Apache C++ Standard Library Reference Guide

## messages, messages_byname

Library: Localization

                                messages_base
    messages_byname  messages
                                locale::facet

- Local Index
- Summary
- Synopsis
- Specializations
- Description
- Interface
- Member Types
- Constructors
- Facet ID
- Public Member Functions
- Protected Member Functions
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

char_type close() do_close() | do_get() do_open() get() | messages() messages_byname() open() | string_type

### Summary

Messaging facets

### Synopsis

    #include <locale>

    namespace std {
      class messages_base;
      template <class charT>
      class messages;
    }

### Specializations

    template <> class messages<char>;
    template <> class messages<wchar_t>;
    template <> class messages_byname<char>;
    template <> class messages_byname<wchar_t>;

### Description

The class 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.

### Interface

    namespace std {

      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<char_type>, char_traits<char_type>,
            allocator<char_type> 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:
        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:
      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;
      };
    }

### Member Types

    char_type

Type of the first template argument.

    string_type

Type of `basic_string` specialized on `char_type`.

### Constructors

    explicit messages(size_t refs = 0)

Constructs a messages object. Calls `locale::facet (refs)`.

The `refs` argument is set to the initial value of the object's reference count. A messages object `f` constructed with `(refs == 0)` that is installed in one or more locale objects will be destroyed and the storage it occupies will be deallocated when the last locale object containing the facet is destroyed, as if by calling `delete static_cast<locale::facet*>(&f)`. A messages object constructed with `(refs != 0)` will not be destroyed by any locale objects in which it may have been installed.

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

Constructs a messages_byname object for the locale given by name. Calls `messages<char_type>::messages (refs)`.

### 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 function `xxx()` calls the corresponding protected virtual member `do_xxx()`. For instance, the public member function `open()` function 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 calls 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 &loc)
            const;

Opens a message catalog with the given name. The `loc` argument is used to obtain a reference to the `codecvt<char_type, char, mbstate_t>` facet to perform any necessary codeset conversion from the multibyte text in the catalog to the appropriate representation used by the internal character type, `char_type`. On success, returns a catalog identifier that can be passed to the `get()` function in order to access specific messages. If the provided catalog name does not refer to an existing valid catalog, the function returns `-1`.

### Example

    //
    //  messages.cpp
    //

    #include <string>
    #include <locale>
    #include <iostream>

    #include <rwstdmessages.h>

    #ifndef _WIN32
    #  define CAT_NAME   "./rwstdmessages.cat"
    #else
    #  define CAT_NAME   "rwstdmessages.dll"
    #endif

    int main ()
    {
        std::locale loc;

        // Get a reference to the messages<char> facet
        const std::messages<char>& msgs =
            std::use_facet <std::messages<char> >(loc);

        // Open a catalog and try to grab
        // both some valid messages, and an invalid message
        const std::string def  = "Message Not Found";

        std::messages<char>::catalog cat = msgs.open (CAT_NAME,
                                                      loc);

        if (cat != std::messages<char>::catalog (-1)) {
            std::cout << msgs.get (cat, 1, _RW_MSG_HELLO, def)
                 << '\n' << msgs.get (cat, 1, _RW_MSG_GOODBYE, def)
                 << '\n' << msgs.get (cat, 1, _RW_MSG_NOGOOD, def)
                 << '\n' << msgs.get (cat, 2, _RW_MSG_TREES, def)
                 << '\n';

            msgs.close (cat);
        }
        else
            std::cerr << "Unable to open message catalog"
                      << std::endl;

        return 0;
    }

    Program Output:

    Hello
    Goodbye
    Message Not Found
    Cedar, Hemlock, and Noble Fir

### See Also

locale, Facets

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 22.2.7