OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [gcc-4.5.1/] [libstdc++-v3/] [doc/] [html/] [manual/] [messages.html] - Blame information for rev 424

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 424 jeremybenn 
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 
<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.75.2" /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      messages&#10;    " /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    " /><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" title="messages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.localization.facet.messages"></a>messages</h2></div></div></div><p>
4 
The std::messages facet implements message retrieval functionality
5 
equivalent to Java's java.text.MessageFormat .using either GNU gettext
6 
or IEEE 1003.1-200 functions.
7 
</p><div class="sect2" title="Requirements"><div class="titlepage"><div><div><h3 class="title"><a id="facet.messages.req"></a>Requirements</h3></div></div></div><p>
8 
The std::messages facet is probably the most vaguely defined facet in
9 
the standard library. It's assumed that this facility was built into
10 
the standard library in order to convert string literals from one
11 
locale to the other. For instance, converting the "C" locale's
12 
<code class="code">const char* c = "please"</code> to a German-localized <code class="code">"bitte"</code>
13 
during program execution.
14 
</p><div class="blockquote"><blockquote class="blockquote"><p>
15 
22.2.7.1 - Template class messages [lib.locale.messages]
16 
</p></blockquote></div><p>
17 
This class has three public member functions, which directly
18 
correspond to three protected virtual member functions.
19 
</p><p>
20 
The public member functions are:
21 
</p><p>
22 
<code class="code">catalog open(const string&amp;, const locale&amp;) const</code>
23 
</p><p>
24 
<code class="code">string_type get(catalog, int, int, const string_type&amp;) const</code>
25 
</p><p>
26 
<code class="code">void close(catalog) const</code>
27 
</p><p>
28 
While the virtual functions are:
29 
</p><p>
30 
<code class="code">catalog do_open(const string&amp;, const locale&amp;) const</code>
31 
</p><div class="blockquote"><blockquote class="blockquote"><p>
32 
<span class="emphasis"><em>
33 
-1- Returns: A value that may be passed to get() to retrieve a
34 
message, from the message catalog identified by the string name
35 
according to an implementation-defined mapping. The result can be used
36 
until it is passed to close().  Returns a value less than 0 if no such
37 
catalog can be opened.
38 
</em></span>
39 
</p></blockquote></div><p>
40 
<code class="code">string_type do_get(catalog, int, int, const string_type&amp;) const</code>
41 
</p><div class="blockquote"><blockquote class="blockquote"><p>
42 
<span class="emphasis"><em>
43 
-3- Requires: A catalog cat obtained from open() and not yet closed.
44 
-4- Returns: A message identified by arguments set, msgid, and dfault,
45 
according to an implementation-defined mapping. If no such message can
46 
be found, returns dfault.
47 
</em></span>
48 
</p></blockquote></div><p>
49 
<code class="code">void do_close(catalog) const</code>
50 
</p><div class="blockquote"><blockquote class="blockquote"><p>
51 
<span class="emphasis"><em>
52 
-5- Requires: A catalog cat obtained from open() and not yet closed.
53 
-6- Effects: Releases unspecified resources associated with cat.
54 
-7- Notes: The limit on such resources, if any, is implementation-defined.
55 
</em></span>
56 
</p></blockquote></div></div><div class="sect2" title="Design"><div class="titlepage"><div><div><h3 class="title"><a id="facet.messages.design"></a>Design</h3></div></div></div><p>
57 
A couple of notes on the standard.
58 
</p><p>
59 
First, why is <code class="code">messages_base::catalog</code> specified as a typedef
60 
to int? This makes sense for implementations that use
61 
<code class="code">catopen</code>, but not for others. Fortunately, it's not heavily
62 
used and so only a minor irritant.
63 
</p><p>
64 
Second, by making the member functions <code class="code">const</code>, it is
65 
impossible to save state in them. Thus, storing away information used
66 
in the 'open' member function for use in 'get' is impossible. This is
67 
unfortunate.
68 
</p><p>
69 
The 'open' member function in particular seems to be oddly
70 
designed. The signature seems quite peculiar. Why specify a <code class="code">const
71 
string&amp; </code> argument, for instance, instead of just <code class="code">const
72 
char*</code>? Or, why specify a <code class="code">const locale&amp;</code> argument that is
73 
to be used in the 'get' member function? How, exactly, is this locale
74 
argument useful? What was the intent? It might make sense if a locale
75 
argument was associated with a given default message string in the
76 
'open' member function, for instance. Quite murky and unclear, on
77 
reflection.
78 
</p><p>
79 
Lastly, it seems odd that messages, which explicitly require code
80 
conversion, don't use the codecvt facet. Because the messages facet
81 
has only one template parameter, it is assumed that ctype, and not
82 
codecvt, is to be used to convert between character sets.
83 
</p><p>
84 
It is implicitly assumed that the locale for the default message
85 
string in 'get' is in the "C" locale. Thus, all source code is assumed
86 
to be written in English, so translations are always from "en_US" to
87 
other, explicitly named locales.
88 
</p></div><div class="sect2" title="Implementation"><div class="titlepage"><div><div><h3 class="title"><a id="facet.messages.impl"></a>Implementation</h3></div></div></div><div class="sect3" title="Models"><div class="titlepage"><div><div><h4 class="title"><a id="messages.impl.models"></a>Models</h4></div></div></div><p>
89 
    This is a relatively simple class, on the face of it. The standard
90 
    specifies very little in concrete terms, so generic
91 
    implementations that are conforming yet do very little are the
92 
    norm. Adding functionality that would be useful to programmers and
93 
    comparable to Java's java.text.MessageFormat takes a bit of work,
94 
    and is highly dependent on the capabilities of the underlying
95 
    operating system.
96 
  </p><p>
97 
    Three different mechanisms have been provided, selectable via
98 
    configure flags:
99 
  </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
100 
       generic
101 
     </p><p>
102 
       This model does very little, and is what is used by default.
103 
     </p></li><li class="listitem"><p>
104 
       gnu
105 
     </p><p>
106 
       The gnu model is complete and fully tested. It's based on the
107 
       GNU gettext package, which is part of glibc. It uses the
108 
       functions <code class="code">textdomain, bindtextdomain, gettext</code> to
109 
       implement full functionality. Creating message catalogs is a
110 
       relatively straight-forward process and is lightly documented
111 
       below, and fully documented in gettext's distributed
112 
       documentation.
113 
     </p></li><li class="listitem"><p>
114 
       ieee_1003.1-200x
115 
     </p><p>
116 
       This is a complete, though untested, implementation based on
117 
       the IEEE standard. The functions <code class="code">catopen, catgets,
118 
       catclose</code> are used to retrieve locale-specific messages
119 
       given the appropriate message catalogs that have been
120 
       constructed for their use. Note, the script <code class="code">
121 
       po2msg.sed</code> that is part of the gettext distribution can
122 
       convert gettext catalogs into catalogs that
123 
       <code class="code">catopen</code> can use.
124 
   </p></li></ul></div><p>
125 
A new, standards-conformant non-virtual member function signature was
126 
added for 'open' so that a directory could be specified with a given
127 
message catalog. This simplifies calling conventions for the gnu
128 
model.
129 
</p></div><div class="sect3" title="The GNU Model"><div class="titlepage"><div><div><h4 class="title"><a id="messages.impl.gnu"></a>The GNU Model</h4></div></div></div><p>
130 
    The messages facet, because it is retrieving and converting
131 
    between characters sets, depends on the ctype and perhaps the
132 
    codecvt facet in a given locale. In addition, underlying "C"
133 
    library locale support is necessary for more than just the
134 
    <code class="code">LC_MESSAGES</code> mask: <code class="code">LC_CTYPE</code> is also
135 
    necessary. To avoid any unpleasantness, all bits of the "C" mask
136 
    (i.e. <code class="code">LC_ALL</code>) are set before retrieving messages.
137 
  </p><p>
138 
    Making the message catalogs can be initially tricky, but become
139 
    quite simple with practice. For complete info, see the gettext
140 
    documentation. Here's an idea of what is required:
141 
  </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
142 
       Make a source file with the required string literals that need
143 
       to be translated. See <code class="code">intl/string_literals.cc</code> for
144 
       an example.
145 
     </p></li><li class="listitem"><p>
146 
       Make initial catalog (see "4 Making the PO Template File" from
147 
       the gettext docs).</p><p>
148 
   <code class="code"> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code>
149 
   </p></li><li class="listitem"><p>Make language and country-specific locale catalogs.</p><p>
150 
   <code class="code">cp libstdc++.pot fr_FR.po</code>
151 
   </p><p>
152 
   <code class="code">cp libstdc++.pot de_DE.po</code>
153 
   </p></li><li class="listitem"><p>
154 
       Edit localized catalogs in emacs so that strings are
155 
       translated.
156 
     </p><p>
157 
   <code class="code">emacs fr_FR.po</code>
158 
   </p></li><li class="listitem"><p>Make the binary mo files.</p><p>
159 
   <code class="code">msgfmt fr_FR.po -o fr_FR.mo</code>
160 
   </p><p>
161 
   <code class="code">msgfmt de_DE.po -o de_DE.mo</code>
162 
   </p></li><li class="listitem"><p>Copy the binary files into the correct directory structure.</p><p>
163 
   <code class="code">cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++.mo</code>
164 
   </p><p>
165 
   <code class="code">cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++.mo</code>
166 
   </p></li><li class="listitem"><p>Use the new message catalogs.</p><p>
167 
   <code class="code">locale loc_de("de_DE");</code>
168 
   </p><p>
169 
   <code class="code">
170 
   use_facet&lt;messages&lt;char&gt; &gt;(loc_de).open("libstdc++", locale(), dir);
171 
   </code>
172 
   </p></li></ul></div></div></div><div class="sect2" title="Use"><div class="titlepage"><div><div><h3 class="title"><a id="facet.messages.use"></a>Use</h3></div></div></div><p>
173 
   A simple example using the GNU model of message conversion.
174 
 </p><pre class="programlisting">
175 
#include &lt;iostream&gt;
176 
#include &lt;locale&gt;
177 
using namespace std;
178 
 
179 
void test01()
180 
{
181 
  typedef messages&lt;char&gt;::catalog catalog;
182 
  const char* dir =
183 
  "/mnt/egcs/build/i686-pc-linux-gnu/libstdc++/po/share/locale";
184 
  const locale loc_de("de_DE");
185 
  const messages&lt;char&gt;&amp; mssg_de = use_facet&lt;messages&lt;char&gt; &gt;(loc_de);
186 
 
187 
  catalog cat_de = mssg_de.open("libstdc++", loc_de, dir);
188 
  string s01 = mssg_de.get(cat_de, 0, 0, "please");
189 
  string s02 = mssg_de.get(cat_de, 0, 0, "thank you");
190 
  cout &lt;&lt; "please in german:" &lt;&lt; s01 &lt;&lt; '\n';
191 
  cout &lt;&lt; "thank you in german:" &lt;&lt; s02 &lt;&lt; '\n';
192 
  mssg_de.close(cat_de);
193 
}
194 
</pre></div><div class="sect2" title="Future"><div class="titlepage"><div><div><h3 class="title"><a id="facet.messages.future"></a>Future</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
195 
    Things that are sketchy, or remain unimplemented:
196 
  </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>
197 
          _M_convert_from_char, _M_convert_to_char are in flux,
198 
          depending on how the library ends up doing character set
199 
          conversions. It might not be possible to do a real character
200 
          set based conversion, due to the fact that the template
201 
          parameter for messages is not enough to instantiate the
202 
          codecvt facet (1 supplied, need at least 2 but would prefer
203 
          3).
204 
        </p></li><li class="listitem"><p>
205 
          There are issues with gettext needing the global locale set
206 
          to extract a message. This dependence on the global locale
207 
          makes the current "gnu" model non MT-safe. Future versions
208 
          of glibc, i.e. glibc 2.3.x will fix this, and the C++ library
209 
          bits are already in place.
210 
        </p></li></ul></div></li><li class="listitem"><p>
211 
    Development versions of the GNU "C" library, glibc 2.3 will allow
212 
    a more efficient, MT implementation of std::messages, and will
213 
    allow the removal of the _M_name_messages data member. If this is
214 
    done, it will change the library ABI. The C++ parts to support
215 
    glibc 2.3 have already been coded, but are not in use: once this
216 
    version of the "C" library is released, the marked parts of the
217 
    messages implementation can be switched over to the new "C"
218 
    library functionality.
219 
  </p></li><li class="listitem"><p>
220 
    At some point in the near future, std::numpunct will probably use
221 
    std::messages facilities to implement truename/falsename
222 
    correctly. This is currently not done, but entries in
223 
    libstdc++.pot have already been made for "true" and "false" string
224 
    literals, so all that remains is the std::numpunct coding and the
225 
    configure/make hassles to make the installed library search its
226 
    own catalog. Currently the libstdc++.mo catalog is only searched
227 
    for the testsuite cases involving messages members.
228 
  </p></li><li class="listitem"><p> The following member functions:</p><p>
229 
   <code class="code">
230 
        catalog
231 
        open(const basic_string&lt;char&gt;&amp; __s, const locale&amp; __loc) const
232 
   </code>
233 
   </p><p>
234 
   <code class="code">
235 
   catalog
236 
   open(const basic_string&lt;char&gt;&amp;, const locale&amp;, const char*) const;
237 
   </code>
238 
   </p><p>
239 
   Don't actually return a "value less than 0 if no such catalog
240 
   can be opened" as required by the standard in the "gnu"
241 
   model. As of this writing, it is unknown how to query to see
242 
   if a specified message catalog exists using the gettext
243 
   package.
244 
   </p></li></ul></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="facet.messages.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry" title="The GNU C Library"><a id="id612063"></a><p><span class="title"><i>
245 
      The GNU C Library
246 
    </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
247 
    . </span></p></div><div class="biblioentry" title="Correspondence"><a id="id633252"></a><p><span class="title"><i>
248 
      Correspondence
249 
    </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" title="ISO/IEC 14882:1998 Programming languages - C++"><a id="id720940"></a><p><span class="title"><i>
250 
      ISO/IEC 14882:1998 Programming languages - C++
251 
    </i>. </span><span class="copyright">Copyright © 1998 ISO. </span></p></div><div class="biblioentry" title="ISO/IEC 9899:1999 Programming languages - C"><a id="id720958"></a><p><span class="title"><i>
252 
      ISO/IEC 9899:1999 Programming languages - C
253 
    </i>. </span><span class="copyright">Copyright © 1999 ISO. </span></p></div><div class="biblioentry" title="System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)"><a id="id626200"></a><p><span class="title"><i>
254 
      System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
255 
    </i>. </span><span class="copyright">Copyright © 1999
256 
      The Open Group/The Institute of Electrical and Electronics Engineers, Inc.. </span><span class="biblioid">
257 
      <a class="ulink" href="http://www.opengroup.org/austin/" target="_top">
258 
      </a>
259 
    . </span></p></div><div class="biblioentry" title="The C++ Programming Language, Special Edition"><a id="id626228"></a><p><span class="title"><i>
260 
      The C++ Programming Language, Special Edition
261 
    </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">
262 
        Addison Wesley
263 
      . </span></span></p></div><div class="biblioentry" title="Standard C++ IOStreams and Locales"><a id="id706351"></a><p><span class="title"><i>
264 
      Standard C++ IOStreams and Locales
265 
    </i>. </span><span class="subtitle">
266 
      Advanced Programmer's Guide and Reference
267 
    . </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">
268 
        Addison Wesley Longman
269 
      . </span></span></p></div><div class="biblioentry" title="Java 2 Platform, Standard Edition, v 1.3.1 API Specification"><a id="id655088"></a><p><span class="title"><i>
270 
      Java 2 Platform, Standard Edition, v 1.3.1 API Specification
271 
    </i>. </span><span class="pagenums">java.util.Properties, java.text.MessageFormat,
272 
java.util.Locale, java.util.ResourceBundle. </span><span class="biblioid">
273 
      <a class="ulink" href="http://java.sun.com/reference/api/index.html" target="_top">
274 
      </a>
275 
    . </span></p></div><div class="biblioentry" title="GNU gettext tools, version 0.10.38, Native Language Support Library and Tools."><a id="id680363"></a><p><span class="title"><i>
276 
       GNU gettext tools, version 0.10.38, Native Language Support
277 
Library and Tools.
278 
    </i>. </span><span class="biblioid">
279 
      <a class="ulink" href="http://www.gnu.org/software/gettext/" target="_top">
280 
      </a>
281 
    . </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. 
282 
  Containers
283 
 
284 
</td></tr></table></div></body></html>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.