| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>messages</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , messages " /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="facets.html" title="Chapter 15. Facets aka Categories" /><link rel="prev" href="codecvt.html" title="codecvt" /><link rel="next" href="containers.html" title="Part VII. Containers" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">messages</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="codecvt.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Facets aka Categories</th><td width="20%" align="right"> <a accesskey="n" href="containers.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.localization.facet.messages"></a>messages</h2></div></div></div><p> |
| The std::messages facet implements message retrieval functionality |
| equivalent to Java's java.text.MessageFormat .using either GNU gettext |
| or IEEE 1003.1-200 functions. |
| </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="facet.messages.req"></a>Requirements</h3></div></div></div><p> |
| The std::messages facet is probably the most vaguely defined facet in |
| the standard library. It's assumed that this facility was built into |
| the standard library in order to convert string literals from one |
| locale to the other. For instance, converting the "C" locale's |
| <code class="code">const char* c = "please"</code> to a German-localized <code class="code">"bitte"</code> |
| during program execution. |
| </p><div class="blockquote"><blockquote class="blockquote"><p> |
| 22.2.7.1 - Template class messages [lib.locale.messages] |
| </p></blockquote></div><p> |
| This class has three public member functions, which directly |
| correspond to three protected virtual member functions. |
| </p><p> |
| The public member functions are: |
| </p><p> |
| <code class="code">catalog open(const string&, const locale&) const</code> |
| </p><p> |
| <code class="code">string_type get(catalog, int, int, const string_type&) const</code> |
| </p><p> |
| <code class="code">void close(catalog) const</code> |
| </p><p> |
| While the virtual functions are: |
| </p><p> |
| <code class="code">catalog do_open(const string&, const locale&) const</code> |
| </p><div class="blockquote"><blockquote class="blockquote"><p> |
| <span class="emphasis"><em> |
| -1- Returns: A value that may be passed to get() to retrieve a |
| message, from the message catalog identified by the string name |
| according to an implementation-defined mapping. The result can be used |
| until it is passed to close(). Returns a value less than 0 if no such |
| catalog can be opened. |
| </em></span> |
| </p></blockquote></div><p> |
| <code class="code">string_type do_get(catalog, int, int, const string_type&) const</code> |
| </p><div class="blockquote"><blockquote class="blockquote"><p> |
| <span class="emphasis"><em> |
| -3- Requires: A catalog cat obtained from open() and not yet closed. |
| -4- Returns: A message identified by arguments set, msgid, and dfault, |
| according to an implementation-defined mapping. If no such message can |
| be found, returns dfault. |
| </em></span> |
| </p></blockquote></div><p> |
| <code class="code">void do_close(catalog) const</code> |
| </p><div class="blockquote"><blockquote class="blockquote"><p> |
| <span class="emphasis"><em> |
| -5- Requires: A catalog cat obtained from open() and not yet closed. |
| -6- Effects: Releases unspecified resources associated with cat. |
| -7- Notes: The limit on such resources, if any, is implementation-defined. |
| </em></span> |
| </p></blockquote></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="facet.messages.design"></a>Design</h3></div></div></div><p> |
| A couple of notes on the standard. |
| </p><p> |
| First, why is <code class="code">messages_base::catalog</code> specified as a typedef |
| to int? This makes sense for implementations that use |
| <code class="code">catopen</code>, but not for others. Fortunately, it's not heavily |
| used and so only a minor irritant. |
| </p><p> |
| Second, by making the member functions <code class="code">const</code>, it is |
| impossible to save state in them. Thus, storing away information used |
| in the 'open' member function for use in 'get' is impossible. This is |
| unfortunate. |
| </p><p> |
| The 'open' member function in particular seems to be oddly |
| designed. The signature seems quite peculiar. Why specify a <code class="code">const |
| string& </code> argument, for instance, instead of just <code class="code">const |
| char*</code>? Or, why specify a <code class="code">const locale&</code> argument that is |
| to be used in the 'get' member function? How, exactly, is this locale |
| argument useful? What was the intent? It might make sense if a locale |
| argument was associated with a given default message string in the |
| 'open' member function, for instance. Quite murky and unclear, on |
| reflection. |
| </p><p> |
| Lastly, it seems odd that messages, which explicitly require code |
| conversion, don't use the codecvt facet. Because the messages facet |
| has only one template parameter, it is assumed that ctype, and not |
| codecvt, is to be used to convert between character sets. |
| </p><p> |
| It is implicitly assumed that the locale for the default message |
| string in 'get' is in the "C" locale. Thus, all source code is assumed |
| to be written in English, so translations are always from "en_US" to |
| other, explicitly named locales. |
| </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="facet.messages.impl"></a>Implementation</h3></div></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="messages.impl.models"></a>Models</h4></div></div></div><p> |
| This is a relatively simple class, on the face of it. The standard |
| specifies very little in concrete terms, so generic |
| implementations that are conforming yet do very little are the |
| norm. Adding functionality that would be useful to programmers and |
| comparable to Java's java.text.MessageFormat takes a bit of work, |
| and is highly dependent on the capabilities of the underlying |
| operating system. |
| </p><p> |
| Three different mechanisms have been provided, selectable via |
| configure flags: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| generic |
| </p><p> |
| This model does very little, and is what is used by default. |
| </p></li><li><p> |
| gnu |
| </p><p> |
| The gnu model is complete and fully tested. It's based on the |
| GNU gettext package, which is part of glibc. It uses the |
| functions <code class="code">textdomain, bindtextdomain, gettext</code> to |
| implement full functionality. Creating message catalogs is a |
| relatively straight-forward process and is lightly documented |
| below, and fully documented in gettext's distributed |
| documentation. |
| </p></li><li><p> |
| ieee_1003.1-200x |
| </p><p> |
| This is a complete, though untested, implementation based on |
| the IEEE standard. The functions <code class="code">catopen, catgets, |
| catclose</code> are used to retrieve locale-specific messages |
| given the appropriate message catalogs that have been |
| constructed for their use. Note, the script <code class="code"> |
| po2msg.sed</code> that is part of the gettext distribution can |
| convert gettext catalogs into catalogs that |
| <code class="code">catopen</code> can use. |
| </p></li></ul></div><p> |
| A new, standards-conformant non-virtual member function signature was |
| added for 'open' so that a directory could be specified with a given |
| message catalog. This simplifies calling conventions for the gnu |
| model. |
| </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="messages.impl.gnu"></a>The GNU Model</h4></div></div></div><p> |
| The messages facet, because it is retrieving and converting |
| between characters sets, depends on the ctype and perhaps the |
| codecvt facet in a given locale. In addition, underlying "C" |
| library locale support is necessary for more than just the |
| <code class="code">LC_MESSAGES</code> mask: <code class="code">LC_CTYPE</code> is also |
| necessary. To avoid any unpleasantness, all bits of the "C" mask |
| (i.e. <code class="code">LC_ALL</code>) are set before retrieving messages. |
| </p><p> |
| Making the message catalogs can be initially tricky, but become |
| quite simple with practice. For complete info, see the gettext |
| documentation. Here's an idea of what is required: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| Make a source file with the required string literals that need |
| to be translated. See <code class="code">intl/string_literals.cc</code> for |
| an example. |
| </p></li><li><p> |
| Make initial catalog (see "4 Making the PO Template File" from |
| the gettext docs).</p><p> |
| <code class="code"> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code> |
| </p></li><li><p>Make language and country-specific locale catalogs.</p><p> |
| <code class="code">cp libstdc++.pot fr_FR.po</code> |
| </p><p> |
| <code class="code">cp libstdc++.pot de_DE.po</code> |
| </p></li><li><p> |
| Edit localized catalogs in emacs so that strings are |
| translated. |
| </p><p> |
| <code class="code">emacs fr_FR.po</code> |
| </p></li><li><p>Make the binary mo files.</p><p> |
| <code class="code">msgfmt fr_FR.po -o fr_FR.mo</code> |
| </p><p> |
| <code class="code">msgfmt de_DE.po -o de_DE.mo</code> |
| </p></li><li><p>Copy the binary files into the correct directory structure.</p><p> |
| <code class="code">cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++.mo</code> |
| </p><p> |
| <code class="code">cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++.mo</code> |
| </p></li><li><p>Use the new message catalogs.</p><p> |
| <code class="code">locale loc_de("de_DE");</code> |
| </p><p> |
| <code class="code"> |
| use_facet<messages<char> >(loc_de).open("libstdc++", locale(), dir); |
| </code> |
| </p></li></ul></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="facet.messages.use"></a>Use</h3></div></div></div><p> |
| A simple example using the GNU model of message conversion. |
| </p><pre class="programlisting"> |
| #include <iostream> |
| #include <locale> |
| using namespace std; |
| |
| void test01() |
| { |
| typedef messages<char>::catalog catalog; |
| const char* dir = |
| "/mnt/egcs/build/i686-pc-linux-gnu/libstdc++/po/share/locale"; |
| const locale loc_de("de_DE"); |
| const messages<char>& mssg_de = use_facet<messages<char> >(loc_de); |
| |
| catalog cat_de = mssg_de.open("libstdc++", loc_de, dir); |
| string s01 = mssg_de.get(cat_de, 0, 0, "please"); |
| string s02 = mssg_de.get(cat_de, 0, 0, "thank you"); |
| cout << "please in german:" << s01 << '\n'; |
| cout << "thank you in german:" << s02 << '\n'; |
| mssg_de.close(cat_de); |
| } |
| </pre></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="facet.messages.future"></a>Future</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| Things that are sketchy, or remain unimplemented: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| _M_convert_from_char, _M_convert_to_char are in flux, |
| depending on how the library ends up doing character set |
| conversions. It might not be possible to do a real character |
| set based conversion, due to the fact that the template |
| parameter for messages is not enough to instantiate the |
| codecvt facet (1 supplied, need at least 2 but would prefer |
| 3). |
| </p></li><li><p> |
| There are issues with gettext needing the global locale set |
| to extract a message. This dependence on the global locale |
| makes the current "gnu" model non MT-safe. Future versions |
| of glibc, i.e. glibc 2.3.x will fix this, and the C++ library |
| bits are already in place. |
| </p></li></ul></div></li><li><p> |
| Development versions of the GNU "C" library, glibc 2.3 will allow |
| a more efficient, MT implementation of std::messages, and will |
| allow the removal of the _M_name_messages data member. If this is |
| done, it will change the library ABI. The C++ parts to support |
| glibc 2.3 have already been coded, but are not in use: once this |
| version of the "C" library is released, the marked parts of the |
| messages implementation can be switched over to the new "C" |
| library functionality. |
| </p></li><li><p> |
| At some point in the near future, std::numpunct will probably use |
| std::messages facilities to implement truename/falsename |
| correctly. This is currently not done, but entries in |
| libstdc++.pot have already been made for "true" and "false" string |
| literals, so all that remains is the std::numpunct coding and the |
| configure/make hassles to make the installed library search its |
| own catalog. Currently the libstdc++.mo catalog is only searched |
| for the testsuite cases involving messages members. |
| </p></li><li><p> The following member functions:</p><p> |
| <code class="code"> |
| catalog |
| open(const basic_string<char>& __s, const locale& __loc) const |
| </code> |
| </p><p> |
| <code class="code"> |
| catalog |
| open(const basic_string<char>&, const locale&, const char*) const; |
| </code> |
| </p><p> |
| Don't actually return a "value less than 0 if no such catalog |
| can be opened" as required by the standard in the "gnu" |
| model. As of this writing, it is unknown how to query to see |
| if a specified message catalog exists using the gettext |
| package. |
| </p></li></ul></div></div><div class="bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="facet.messages.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id427517"></a><p><span class="title"><i> |
| The GNU C Library |
| </i>. </span><span class="author"><span class="firstname">Roland</span> <span class="surname">McGrath</span>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2007 FSF. </span><span class="pagenums">Chapters 6 Character Set Handling, and 7 Locales and Internationalization |
| . </span></p></div><div class="biblioentry"><a id="id391329"></a><p><span class="title"><i> |
| Correspondence |
| </i>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2002 . </span></p></div><div class="biblioentry"><a id="id391358"></a><p><span class="title"><i> |
| ISO/IEC 14882:1998 Programming languages - C++ |
| </i>. </span><span class="copyright">Copyright © 1998 ISO. </span></p></div><div class="biblioentry"><a id="id514997"></a><p><span class="title"><i> |
| ISO/IEC 9899:1999 Programming languages - C |
| </i>. </span><span class="copyright">Copyright © 1999 ISO. </span></p></div><div class="biblioentry"><a id="id515015"></a><p><span class="title"><i> |
| System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) |
| </i>. </span><span class="copyright">Copyright © 1999 |
| The Open Group/The Institute of Electrical and Electronics Engineers, Inc.. </span><span class="biblioid"> |
| <a class="ulink" href="http://www.opennc.org/austin/docreg.html" target="_top"> |
| </a> |
| . </span></p></div><div class="biblioentry"><a id="id427733"></a><p><span class="title"><i> |
| The C++ Programming Language, Special Edition |
| </i>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley, Inc.. </span><span class="pagenums">Appendix D. </span><span class="publisher"><span class="publishername"> |
| Addison Wesley |
| . </span></span></p></div><div class="biblioentry"><a id="id427774"></a><p><span class="title"><i> |
| Standard C++ IOStreams and Locales |
| </i>. </span><span class="subtitle"> |
| Advanced Programmer's Guide and Reference |
| . </span><span class="author"><span class="firstname">Angelika</span> <span class="surname">Langer</span>. </span><span class="author"><span class="firstname">Klaus</span> <span class="surname">Kreft</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley Longman, Inc.. </span><span class="publisher"><span class="publishername"> |
| Addison Wesley Longman |
| . </span></span></p></div><div class="biblioentry"><a id="id402618"></a><p><span class="title"><i> |
| Java 2 Platform, Standard Edition, v 1.3.1 API Specification |
| </i>. </span><span class="pagenums">java.util.Properties, java.text.MessageFormat, |
| java.util.Locale, java.util.ResourceBundle. </span><span class="biblioid"> |
| <a class="ulink" href="http://java.sun.com/j2se/1.3/docs/api" target="_top"> |
| </a> |
| . </span></p></div><div class="biblioentry"><a id="id404627"></a><p><span class="title"><i> |
| GNU gettext tools, version 0.10.38, Native Language Support |
| Library and Tools. |
| </i>. </span><span class="biblioid"> |
| <a class="ulink" href="http://sources.redhat.com/gettext" target="_top"> |
| </a> |
| . </span></p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="codecvt.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="facets.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="containers.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">codecvt </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part VII. |
| Containers |
| |
| </td></tr></table></div></body></html> |