messages(3C++) - messages(3C++)
Standard C++ Library Copyright 1998, Rogue Wave Software, Inc.
NAME
messages, messages_byname
- Messaging facets.
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 pro‐
tected members. Each public member xxx has a corresponding virtual pro‐
tected 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;
catalogopen(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_typedo_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 catalogdo_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
Rogue Wave Software 02 Apr 1998 messages(3C++)
