ceph/src/boost/libs/locale/doc/localized_text_formatting.txt

   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