Standard C++	Library
 		 Copyright 1996, Rogue Wave Software, Inc.

 NAME

   messages, messages_byname - Messaging	facets.

 SYNOPSIS

   #include<locale>
   class	messages_base;

   template <class charT> class messages;

 DESCRIPTION

   messages  provides access to a localized messaging facility. The
   messages facet	provides facilities based on the "C" locale,
   while the messages_byname facet	provides the same facilities
   for named locales.

   The messages_base class provides a catalog type for use by the
   derived messages	and messages_byname classes.

   Note that the	default	messages facet uses catopen, catclose, etc.,
   to implement the	message	database.  If your platform does not
   support these then you'll need to imbue your own messages facet by
   implementing whatever database is available.

 INTERFACE

   class	messages_base {
   public:
    typedef int catalog;
   };

   template <class charT>
   class	messages : public locale::facet, public	messages_base {
   public:
    typedef charT char_type;
    typedef basic_string<charT> string_type;
    explicit messages(size_t = 0);
    catalog open(const basic_string<char>&, const locale&) const;
    string_type	get(catalog, int, int,
 		    const string_type&)	const;
    void	   close(catalog) const;
    static locale::id id;
   protected:
     ~messages();  // virtual
    virtual catalog do_open(const basic_string<char>&,
 			   const locale&) const;
    virtual string_type	do_get(catalog,	int, int,
 			       const string_type&) const;
    virtual void	   do_close(catalog) const;
   };

   class	messages_byname	: public messages<charT> {
   public:
    explicit messages_byname(const char*, size_t	= 0);
   protected:
     ~messages_byname();	 // virtual
    virtual catalog do_open(const basic_string<char>&,
 			   const locale&) const;
   virtual string_type  do_get(catalog, int, int,
 			     const string_type&) const;
    virtual void	   do_close(catalog) const;
   };

 TYPES

   char_type
      Type of character the facet is instantiated on.

   string_type
      Type of character string returned by member functions.

 CONSTRUCTORS AND DESTRUCTORS

   explicit messages(size_t refs	= 0)
      Construct a messages facet.  If the refs argument is 0 then
      destruction of	the object is delegated	to the locale, or
      locales, containing it. This allows the user to ignore lifetime
      management	issues.	 On the	other hand, if refs is 1	then
      the object	must be	explicitly deleted:  the locale will not do
      so.  In	this case, the object can be maintained across the
      lifetime of multiple locales.

   explicit messages_byname(const char* name, size_t refs = 0);
      Construct a messages_byname facet.	 Use the named locale
      specified	by the name argument.	 The refs argument serves the
      same purpose as it does for the messages constructor.

   ~messages();	// virtual and protected
      Destroy the facet

 FACET ID

   static locale::id id;
      Unique identifier for this	type of	facet.

 PUBLIC MEMBER FUNCTIONS

   The public members of	the messages facet provide an interface	to
   protected members.  Each public	member xxx has a corresponding
   virtual protected member do_xxx.  All work is delagated	to
   these protected members.   For instance, the	long version of	the
   public open	function simply	calls its protected cousin do_open.

   void
   close(catalog	c) const;

   string_type
   get(catalog c, int set, int msgid,
      const string_type&	dfault)	const;

   catalog
   open(const basic_string<char>& fn, const locale&) const;
      Each of these public member functions xxx simply call the
      corresponding protected do_xxx function.

 PROTECTED MEMBER FUNCTIONS

   virtual void
   do_close(catalog cat)	const;
      Closes the	catalog.  The cat argument must	have been obtained by
      a	call to	open().

   virtual string_type
   do_get(catalog cat, int set, int msgid,
 	const string_type& dfault) const;
      Retrieves a specific message.  Returns the	message	identified by
      cat, set, msgid, and dfault.  cat must have been obtained by a
      previous	call to	open() and this	function must not be called
      with a cat that has	had close() called on yet after the
      last call to open().  In other words, the catalog must have been
      opened and not yet closed.

   virtual catalog
   do_open(const	basic_string<char>& name, const	locale&) const;
      Opens a message catalog.  Returns a catalog identifier that can
      be passed to the get() function in order to access specific
      messages. Returns -1	if the catalog name specificed in the
      name argument is invalid.  The loc argument	will be	used
      for codeset conversion if necessary.

 EXAMPLE

   //
   // messages.cpp
   //
   #include <string>
   #include <iostream>

   int main ()
   {
    using namespace std;

    locale loc;

     // Get a reference to the messages<char> facet
    const messages<char>& mess =
   #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
      use_facet<messages<char> >(loc);
   #else
      use_facet(loc,(messages<char>*)0);
   #endif

     // Open a catalog and try to grab
     // both some valid messages, and an	invalid	message
    string def("Message Not Found");
    messages<char>::catalog cat =
 	   mess.open("./rwstdmessages.cat",loc);
    if (cat != -1)
     {
      string msg0 = mess.get(cat,1,1,def);
      string msg1 = mess.get(cat,1,2,def);
      string msg2 = mess.get(cat,1,6,def); // invalid msg #
      string msg3 = mess.get(cat,2,1,def);

      mess.close(cat);
      cout << msg0 << endl << msg1 << endl
 	   << msg2 << endl << msg3 << endl;
     }
    else
      cout << "Unable to	open message catalog" << endl;

    return 0;
   }

 SEE ALSO

   locale, facets

 STANDARDS CONFORMANCE
   ANSI X3J16/ISO WG21 Joint C++	Committee