]>
Commit | Line | Data |
---|---|---|
1 | // | |
2 | // Copyright (c) 2009-2011 Artyom Beilis (Tonkikh) | |
3 | // | |
4 | // Distributed under the Boost Software License, Version 1.0. (See | |
5 | // accompanying file LICENSE_1_0.txt or copy at | |
6 | // http://www.boost.org/LICENSE_1_0.txt) | |
7 | // | |
8 | ||
9 | // vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 filetype=cpp.doxygen | |
10 | /*! | |
11 | \page localized_text_formatting Localized Text Formatting | |
12 | ||
13 | The \c iostream manipulators are very useful, but when we create a messages for the user, sometimes we need something | |
14 | like good old \c printf or \c boost::format. | |
15 | ||
16 | Unfortunately \c boost::format has several limitations in context of localization: | |
17 | ||
18 | -# It renders all parameters using global locale rather than target \c ostream locale. For example: | |
19 | \n | |
20 | \code | |
21 | std::locale::global(std::locale("en_US.UTF-8")); | |
22 | output.imbue(std::locale("de_DE.UTF-8")) | |
23 | output << boost::format("%1%") % 1234.345; | |
24 | \endcode | |
25 | \n | |
26 | This would write "1,234.235" to output, instead of the "1.234,234" that is expected for "de_DE" locale | |
27 | -# It knows nothing about the new Boost.Locale manipulators. | |
28 | -# The \c printf-like syntax is very limited for formatting complex localized data, not allowing | |
29 | the formatting of dates, times, or currencies | |
30 | ||
31 | Thus a new class, boost::locale::format, was introduced. For example: | |
32 | ||
33 | \code | |
34 | wcout << wformat(L"Today {1,date} I would meet {2} at home") % time(0) % name <<endl; | |
35 | \endcode | |
36 | ||
37 | Each format specifier is enclosed within \c {} brackets, is separated with a comma "," and | |
38 | may have an additional option after an equals symbol '='. This option may be simple ASCII text or single-quoted localized text. | |
39 | If a single-quote should be inserted within the text, it may be represented with a pair of single-quote characters. | |
40 | ||
41 | Here is an example of a format string: | |
42 | ||
43 | \verbatim | |
44 | "Ms. {1} had arrived at {2,ftime='%I o''clock'} at home. The exact time is {2,time=full}" | |
45 | \endverbatim | |
46 | ||
47 | The syntax is described by following grammar: | |
48 | ||
49 | \verbatim | |
50 | format : '{' parameters '}' | |
51 | parameters: parameter | parameter ',' parameters; | |
52 | parameter : key ["=" value] ; | |
53 | key : [0-9a-zA-Z<>]+ ; | |
54 | value : ascii-string-excluding-"}"-and="," | local-string ; | |
55 | local-string : quoted-text | quoted-text local-string; | |
56 | quoted-text : '[^']*' ; | |
57 | \endverbatim | |
58 | ||
59 | ||
60 | You can include literal '{' and '}' by inserting double "{{" or "}}" | |
61 | to the text. | |
62 | ||
63 | \code | |
64 | cout << format(translate("Unexpected `{{' in line {1} in file {2}")) % pos % file; | |
65 | \endcode | |
66 | ||
67 | Would display something like | |
68 | ||
69 | \verbatim | |
70 | Unexpected `{' in line 5 in file source.cpp | |
71 | \endverbatim | |
72 | ||
73 | The following format key-value pairs are supported: | |
74 | ||
75 | - <tt>[0-9]+</tt> -- digits, the index of the formatted parameter -- required. | |
76 | - \c num or \c number -- format a number. Options are: | |
77 | \n | |
78 | - \c hex -- display in hexadecimal format | |
79 | - \c oct -- display in octal format | |
80 | - \c sci or \c scientific -- display in scientific format | |
81 | - \c fix or \c fixed -- display in fixed format | |
82 | \n | |
83 | For example, \c number=sci | |
84 | - \c cur or \c currency -- format currency. Options are: | |
85 | \n | |
86 | - \c iso -- display using ISO currency symbol. | |
87 | - \c nat or \c national -- display using national currency symbol. | |
88 | \n | |
89 | - \c per or \c percent -- format a percentage value. | |
90 | - \c date, \c time, \c datetime or \c dt -- format a date, a time, or a date and time. Options are: | |
91 | \n | |
92 | - \c s or \c short -- display in short format. | |
93 | - \c m or \c medium -- display in medium format. | |
94 | - \c l or \c long -- display in long format. | |
95 | - \c f or \c full -- display in full format. | |
96 | - \c ftime with string (quoted) parameter -- display as with \c strftime. See \c as::ftime manipulator. | |
97 | - \c spell or \c spellout -- spell the number. | |
98 | - \c ord or \c ordinal -- format an ordinal number (1st, 2nd... etc) | |
99 | - \c left or \c < -- align-left. | |
100 | - \c right or \c > -- align-right. | |
101 | - \c width or \c w -- set field width (requires parameter). | |
102 | - \c precision or \c p -- set precision (requires parameter). | |
103 | - \c locale -- with parameter -- switch locales for the current operation. This command generates a locale | |
104 | with formatting facets, giving more fine grained control of formatting. For example: | |
105 | \n | |
106 | \code | |
107 | cout << format("This article was published at {1,date=l} (Gregorian) {1,locale=he_IL@calendar=hebrew,date=l} (Hebrew)") % date; | |
108 | \endcode | |
109 | - \c timezone or \c tz -- the name of the timezone to display the time in. For example:\n | |
110 | \code | |
111 | cout << format("Time is: Local {1,time}, ({1,time,tz=EET} Eastern European Time)") % date; | |
112 | \endcode | |
113 | - \c local - display the time in local time | |
114 | - \c gmt - display the time in UTC time scale | |
115 | \code | |
116 | cout << format("Local time is: {1,time,local}, universal time is {1,time,gmt}") % time; | |
117 | \endcode | |
118 | ||
119 | The constructor for the \ref boost::locale::format "format" class can take an object of type \ref boost::locale::message "message", simplifying integration with message translation code. | |
120 | ||
121 | For example: | |
122 | ||
123 | \code | |
124 | cout<< format(translate("Adding {1} to {2}, we get {3}")) % a % b % (a+b) << endl; | |
125 | \endcode | |
126 | ||
127 | A formatted string can be fetched directly by using the \ref boost::locale::format::str() "str(std::locale const &loc=std::locale())" member function. For example: | |
128 | ||
129 | \code | |
130 | std::wstring de = (wformat(translate("Adding {1} to {2}, we get {3}")) % a % b % (a+b)).str(de_locale); | |
131 | std::wstring fr = (wformat(translate("Adding {1} to {2}, we get {3}")) % a % b % (a+b)).str(fr_locale); | |
132 | \endcode | |
133 | ||
134 | ||
135 | \note There is one significant difference between \c boost::format and \c boost::locale::format: Boost.Locale's format converts its | |
136 | parameters only when written to an \c ostream or when the `str()` member function is called. It only saves references to the objects that | |
137 | can be written to a stream. | |
138 | ||
139 | This is generally not a problem when all operations are done in one statement, such as: | |
140 | ||
141 | \code | |
142 | cout << format("Adding {1} to {2}, we get {3}") % a % b % (a+b); | |
143 | \endcode | |
144 | ||
145 | Because the temporary value of \c (a+b) exists until the formatted data is actually written to the stream. But following code is wrong: | |
146 | ||
147 | \code | |
148 | format fmt("Adding {1} to {2}, we get {3}"); | |
149 | fmt % a; | |
150 | fmt % b; | |
151 | fmt % (a+b); | |
152 | cout << fmt; | |
153 | \endcode | |
154 | ||
155 | Because the temporary value of \c (a+b) no longer exists when \c fmt is written to the stream. A correct solution would be: | |
156 | ||
157 | \code | |
158 | format fmt("Adding {1} to {2}, we get {3}"); | |
159 | fmt % a; | |
160 | fmt % b; | |
161 | int a_plus_b = a+b; | |
162 | fmt % a_plus_b; | |
163 | cout << fmt; | |
164 | \endcode | |
165 | ||
166 | */ | |
167 | ||
168 |