Standard C++ LibraryCopyright 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



privacy and legal statement