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 13The \c iostream manipulators are very useful, but when we create a messages for the user, sometimes we need something 14like good old \c printf or \c boost::format. 15 16Unfortunately \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 31Thus 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 37Each format specifier is enclosed within \c {} brackets, is separated with a comma "," and 38may have an additional option after an equals symbol '='. This option may be simple ASCII text or single-quoted localized text. 39If a single-quote should be inserted within the text, it may be represented with a pair of single-quote characters. 40 41Here 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 47The 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 60You can include literal '{' and '}' by inserting double "{{" or "}}" 61to the text. 62 63\code 64cout << format(translate("Unexpected `{{' in line {1} in file {2}")) % pos % file; 65\endcode 66 67Would display something like 68 69\verbatim 70Unexpected `{' in line 5 in file source.cpp 71\endverbatim 72 73The 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 119The 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 121For example: 122 123\code 124 cout<< format(translate("Adding {1} to {2}, we get {3}")) % a % b % (a+b) << endl; 125\endcode 126 127A 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 136parameters only when written to an \c ostream or when the `str()` member function is called. It only saves references to the objects that 137can be written to a stream. 138 139This 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 145Because 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 155Because 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 169