ceph/src/boost/libs/locale/doc/formatting_and_parsing.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
  12 \page formatting_and_parsing Numbers, Time and Currency formatting and parsing
  13
  14 All formatting and parsing is performed via the standard I/O streams. Each of the above information types is represented as a number.
  15 The formatting information is set using iostream manipulators. All manipulators are placed in the boost::locale::as namespace.
  16
  17 For example:
  18
  19 \code
  20     cout << as::currency << 123.45 << endl;
  21     // display 123.45 in local currency representation.
  22     cin >> as::currency >> x ;
  23     // Parse currency representation and store it in x
  24 \endcode
  25
  26 There is a special manipulator \c as::posix that "unsets" locale-specific settings and returns them to the default \c iostream formatting
  27 and parsing methods. Please note, such formats may still be localized by the default \c std::num_put and \c std::num_get facets.
  28
  29 \section numbers_formatting Numbers and number manipulators
  30
  31 Here are the manipulators for number formatting:
  32
  33 -   \c as::number -- format number according to local specifications, it takes into account various \c std::ios_base flags like scientific
  34     format and precision.
  35     \n
  36 -   \c as::percent -- format number as "percent" format. For example:
  37     \code
  38         cout << as::percent << 0.25 <<endl;
  39     \endcode
  40     Would create an output that may look like this:
  41     \verbatim
  42     25%
  43     \endverbatim
  44     \n
  45 -   \c as::spellout -- spell the number. For example, under the English locale, 103 may be displayed as "one hundred three".
  46     \b Note: not all locales provide rules for spelling numbers. In such a case the number would be displayed in decimal format.
  47     \n
  48 -   \c as::ordinal -- display an order-of element. For example "2" would be displayed as "2nd" under the English locale. As in
  49     the above case, not all locales provide ordinal rules.
  50
  51 \section currency_formatting Currency formatting
  52
  53 These are the manipulators for currency formatting:
  54
  55 -   \c as::currency -- set the format to currency mode.
  56 -   \c as::currency_iso -- change the currency format to international, like "USD" instead of "$". This flag is supported
  57     when using ICU 4.2 and above.
  58 -   \c as::currency_national -- change currency format to national, like "$".
  59 -   \c as::currency_default -- return to the default (national) currency format.
  60
  61 \note \c as::currency_XYZ  manipulators have no effect on general formatting, only on the currency format. You must use both currency
  62 and number manipulators to use a non-default format.
  63
  64 \section date_and_time_formatting Date and Time formatting
  65
  66 Dates and times are represented as POSIX time. When date-time formatting is turned on in the \c iostream, each number is treated as a
  67 POSIX time. The number may be an integer or a double.
  68
  69 There are four major manipulators for Date and Time formatting:
  70
  71 -   \c as::date -- date only
  72 -   \c as::time -- time only
  73 -   \c as::datetime -- both date and time
  74 -   \c as::ftime -- parameterized manipulator that allows specification of time in the format that is used in the \c strftime function.
  75     \b Note: not all formatting flags of \c strftime are supported.
  76
  77 For example:
  78
  79 \code
  80     time_t now=time(0);
  81     cout << "Today is "<< as::date << now << " and tomorrow is " << now+24*3600 << endl;
  82     cout << "Current time is "<< as::time << now << endl;
  83     cout << "The current weekday is "<< as::ftime("%A") << now << endl;
  84 \endcode
  85
  86 More fine-grained control of date-time formatting is also available:
  87
  88 -   \c as::time_default , \c as::time_short , \c as::time_medium , \c as::time_long , \c as::time_full  -- change time formatting.
  89 -   \c as::date_default , \c as::date_short , \c as::date_medium , \c as::date_long , \c as::date_full  -- change date formatting.
  90
  91 These manipulators, when used together with the \c as::date, \c as::time, or \c as::datetime manipulators, change the date-time representation.
  92 The default format is medium.
  93
  94
  95 By default, the date and time are shown in the local time zone. This behavior may be changed with the following manipulators:
  96
  97 -   \c as::gmt -- display date and time in GMT.
  98 -   \c as::local_time  -- display in local time zone (default).
  99 -   \c as::time_zone  -- parameterized manipulator that sets the time-zone ID for date-time formatting and parsing. It
 100     takes a string parameter that represents the time zone ID.
 101
 102 For example:
 103
 104 \code
 105     double now=time(0);
 106     cout << as::datetime << as::local_time << "Local time is: "<< now << endl;
 107     cout << as::gmt << "GMT Time is: "<< now <<endl;
 108     cout << as::time_zone("EST") << "Eastern Standard Time is: "<< now <<endl;
 109 \endcode
 110
 111 There is a list of supported \c strftime flags by ICU backend:
 112
 113 -   \c \%a  -- Abbreviated  weekday (Sun.)
 114 -   \c \%A  -- Full weekday (Sunday)
 115 -   \c \%b  -- Abbreviated month (Jan.)
 116 -   \c \%B  -- Full month (January)
 117 -   \c \%c  -- Locale date-time format. \b Note: prefer using \c as::datetime
 118 -   \c \%d  -- Day of Month [01,31]
 119 -   \c \%e  -- Day of Month [1,31]
 120 -   \c \%h  -- Same as \c \%b
 121 -   \c \%H  -- 24 clock hour [00,23]
 122 -   \c \%I  -- 12 clock hour [01,12]
 123 -   \c \%j  -- Day of year [1,366]
 124 -   \c \%m  -- Month [01,12]
 125 -   \c \%M  -- Minute [00,59]
 126 -   \c \%n  -- New Line
 127 -   \c \%p  -- AM/PM in locale representation
 128 -   \c \%r  -- Time with AM/PM, same as \c \%I:\%M:\%S \%p
 129 -   \c \%R  -- Same as \c \%H:\%M
 130 -   \c \%S  -- Second [00,61]
 131 -   \c \%t  -- Tab character
 132 -   \c \%T  -- Same as \c \%H:\%M:\%S
 133 -   \c \%x  -- Local date representation. **Note:** prefer using \c as::date
 134 -   \c \%X  -- Local time representation. **Note:** prefer using \c as::time
 135 -   \c \%y  -- Year [00,99]
 136 -   \c \%Y  -- 4 digits year. (2009)
 137 -   \c \%Z  -- Time Zone
 138 -   \c \%\%  -- Percent symbol
 139
 140 Unsupported \c strftime flags are: \c \%C , \c \%u , \c \%U , \c \%V , \c \%w , \c \%W . Also, the \c O and \c E modifiers are not supported.
 141
 142
 143 \b General \b recommendations
 144
 145 - Prefer using generic date-time manipulators rather than specifying the full format using \c as::ftime.
 146 - Remember that current calendars may be not Gregorian.
 147
 148
 149 \section formatting_internals Internals
 150
 151 Formatting information is stored in a stream class by using the \c xalloc, \c pword, and \c register_callback  member functions
 152 of \c std::ios_base . All the information is stored and managed using a special object bound to \c iostream, and the manipulators just
 153 change its state.
 154
 155 When a number is written to or read from the stream, a custom Boost.Locale facet accesses the object and checks the required formatting
 156 information. Then it creates a special object that actually formats the number and caches it in the \c iostream. The
 157 next time a number is written to the stream, the same formatter would be used unless some flags had changed and formatter object is
 158 invalid.
 159
 160 */
 161
 162