## messages, messages_byname

        messages_base
                                messages_bynamemessages
           locale::facet

- Summary
- Data Type and Member Function Indexes
- Synopsis
- Description
- Interface
- Types
- Constructors
- Destructors
- Facet ID
- Public Member Functions
- Protected Member Functions
- Example
- See Also

### Summary

Messaging facets.

### Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Data Types
char_type string_type

Member Functions
close() do_close() do_get() do_open() get() | open()

### Synopsis

    #include<locale>
    class messages_base;
    template <class charT> class messages;

### Description

messages gives access to a localized messaging facility. The messages facet is used with the "C" locale, while the messages_byname facet is used with named locales.

The messages_base class includes 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 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

    explicit messages(size_t refs = 0)

Constructs 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 because the locale does not do so.

    explicit messages_byname(const char* name,
       size_t refs = 0);

Constructs a messages_byname facet. Uses the named locale specified by the name argument. The `refs` argument serves the same purpose as it does for the messages constructor.

### Destructors

    ~messages();  // virtual and protected

Destroys 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 include an interface to protected members. Each public member `xxx` has a corresponding virtual protected member `do_xxx`. All work is delegated 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 be 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 be obtained by a previous call to `open()`. This function must not be called with a `cat` that has had close called on it after the last call to `open()`. That is, the catalog must be open 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 specified in the `name` argument is invalid. The `loc` argument is 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

Copyright (c) 1998, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.
OEM Release, June 1998