2 // Copyright (c) 2009-2011 Artyom Beilis (Tonkikh)
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)
9 // vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 filetype=cpp.doxygen
12 \page formatting_and_parsing Numbers, Time and Currency formatting and parsing
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.
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
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.
29 \section numbers_formatting Numbers and number manipulators
31 Here are the manipulators for number formatting:
33 - \c as::number -- format number according to local specifications, it takes into account various \c std::ios_base flags like scientific
36 - \c as::percent -- format number as "percent" format. For example:
38 cout << as::percent << 0.25 <<endl;
40 Would create an output that may look like this:
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.
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.
51 \section currency_formatting Currency formatting
53 These are the manipulators for currency formatting:
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.
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.
64 \section date_and_time_formatting Date and Time formatting
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.
69 There are four major manipulators for Date and Time formatting:
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.
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;
86 More fine-grained control of date-time formatting is also available:
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.
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.
95 By default, the date and time are shown in the local time zone. This behavior may be changed with the following manipulators:
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.
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;
111 There is a list of supported \c strftime flags by ICU backend:
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]
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
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.
143 \b General \b recommendations
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.
149 \section formatting_internals Internals
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
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