Library: Localization
messages_base messages_byname
|
char_type close() do_close() |
do_get() do_open() get() |
messages() messages_byname() open() |
string_type |
Messaging facets
#include <locale>
namespace std {
class messages_base;
template <class charT>
class messages;
}
template <> class messages<char>; template <> class messages<wchar_t>; template <> class messages_byname<char>; template <> class messages_byname<wchar_t>;
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.
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;
};
}
char_type
Type of the first template argument.
string_type
Type of basic_string specialized on char_type.
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).
static locale::id id;
Unique identifier for this type of facet.
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.
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.
//
// 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
ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 22.2.7