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 14All formatting and parsing is performed via the standard I/O streams. Each of the above information types is represented as a number. 15The formatting information is set using iostream manipulators. All manipulators are placed in the boost::locale::as namespace. 16 17For 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 26There is a special manipulator \c as::posix that "unsets" locale-specific settings and returns them to the default \c iostream formatting 27and 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 31Here 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 53These 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 62and number manipulators to use a non-default format. 63 64\section date_and_time_formatting Date and Time formatting 65 66Dates and times are represented as POSIX time. When date-time formatting is turned on in the \c iostream, each number is treated as a 67POSIX time. The number may be an integer or a double. 68 69There 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 77For 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 86More 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 91These manipulators, when used together with the \c as::date, \c as::time, or \c as::datetime manipulators, change the date-time representation. 92The default format is medium. 93 94 95By 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 102For 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 111There 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 140Unsupported \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 151Formatting information is stored in a stream class by using the \c xalloc, \c pword, and \c register_callback member functions 152of \c std::ios_base . All the information is stored and managed using a special object bound to \c iostream, and the manipulators just 153change its state. 154 155When a number is written to or read from the stream, a custom Boost.Locale facet accesses the object and checks the required formatting 156information. Then it creates a special object that actually formats the number and caches it in the \c iostream. The 157next time a number is written to the stream, the same formatter would be used unless some flags had changed and formatter object is 158invalid. 159 160*/ 161 162 163