Boost.Locale: Numbers, Time and Currency formatting and parsing

| Boost.Locale

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files
- Examples

Numbers, Time and Currency formatting and parsing

All formatting and parsing is performed via the standard I/O streams. Each of the above information types is represented as a number. The formatting information is set using iostream manipulators. All manipulators are placed in the boost::locale::as namespace.

For example:

cout << as::currency << 123.45 << endl;
// display 123.45 in local currency representation.
cin >> as::currency >> x ;
// Parse currency representation and store it in x

There is a special manipulator `as::posix` that "unsets" locale-specific settings and returns them to the default `iostream` formatting and parsing methods. Please note, such formats may still be localized by the default `std::num_put` and `std::num_get` facets.

# Numbers and number manipulators

Here are the manipulators for number formatting:

- `as::number` – format number according to local specifications, it takes into account various `std::ios_base` flags like scientific format and precision.
- `as::percent` – format number as "percent" format. For example:
  cout << as::percent << 0.25 <<endl;
  Would create an output that may look like this:

          25%

- `as::spellout` – spell the number. For example, under the English locale, 103 may be displayed as "one hundred three". Note: not all locales provide rules for spelling numbers. In such a case the number would be displayed in decimal format.
- `as::ordinal` – display an order-of element. For example "2" would be displayed as "2nd" under the English locale. As in the above case, not all locales provide ordinal rules.

# Currency formatting

These are the manipulators for currency formatting:

- `as::currency` – set the format to currency mode.
- `as::currency_iso` – change the currency format to international, like "USD" instead of "$". This flag is supported when using ICU 4.2 and above.
- `as::currency_national` – change currency format to national, like "$".
- `as::currency_default` – return to the default (national) currency format.

Note
  `as::currency_XYZ` manipulators have no effect on general formatting, only on the currency format. You must use both currency and number manipulators to use a non-default format.

# Date and Time formatting

Dates and times are represented as POSIX time. When date-time formatting is turned on in the `iostream`, each number is treated as a POSIX time. The number may be an integer or a double.

There are four major manipulators for Date and Time formatting:

- `as::date` – date only
- `as::time` – time only
- `as::datetime` – both date and time
- `as::ftime` – parameterized manipulator that allows specification of time in the format that is used in the `strftime` function. Note: not all formatting flags of `strftime` are supported.

For example:

time_t now=time(0);
cout << "Today is "<< as::date << now << " and tomorrow is " << now+24*3600 << endl;
cout << "Current time is "<< as::time << now << endl;
cout << "The current weekday is "<< as::ftime("%A") << now << endl;

More fine-grained control of date-time formatting is also available:

- `as::time_default` , `as::time_short` , `as::time_medium` , `as::time_long` , `as::time_full` – change time formatting.
- `as::date_default` , `as::date_short` , `as::date_medium` , `as::date_long` , `as::date_full` – change date formatting.

These manipulators, when used together with the `as::date`, `as::time`, or `as::datetime` manipulators, change the date-time representation. The default format is medium.

By default, the date and time are shown in the local time zone. This behavior may be changed with the following manipulators:

- `as::gmt` – display date and time in GMT.
- `as::local_time` – display in local time zone (default).
- `as::time_zone` – parameterized manipulator that sets the time-zone ID for date-time formatting and parsing. It takes a string parameter that represents the time zone ID.

For example:

double now=time(0);
cout << as::datetime << as::local_time << "Local time is: "<< now << endl;
cout << as::gmt << "GMT Time is: "<< now <<endl;
cout << as::time_zone("EST") << "Eastern Standard Time is: "<< now <<endl;

There is a list of supported `strftime` flags by ICU backend:

- `%a` – Abbreviated weekday (Sun.)
- `%A` – Full weekday (Sunday)
- `%b` – Abbreviated month (Jan.)
- `%B` – Full month (January)
- `%c` – Locale date-time format. Note: prefer using `as::datetime`
- `%d` – Day of Month [01,31]
- `%e` – Day of Month [1,31]
- `%h` – Same as `%b`
- `%H` – 24 clock hour [00,23]
- `%I` – 12 clock hour [01,12]
- `%j` – Day of year [1,366]
- `%m` – Month [01,12]
- `%M` – Minute [00,59]
- `%n` – New Line
- `%p` – AM/PM in locale representation
- `%r` – Time with AM/PM, same as `%I:%M:%S` %p
- `%R` – Same as `%H:%M`
- `%S` – Second [00,61]
- `%t` – Tab character
- `%T` – Same as `%H:%M:%S`
- `%x` – Local date representation. Note: prefer using `as::date`
- `%X` – Local time representation. Note: prefer using `as::time`
- `%y` – Year [00,99]
- `%Y` – 4 digits year. (2009)
- `%Z` – Time Zone
- `%%` – Percent symbol

Unsupported `strftime` flags are: `%C` , `%u` , `%U` , `%V` , `%w` , `%W` . Also, the `O` and `E` modifiers are not supported.

General recommendations

- Prefer using generic date-time manipulators rather than specifying the full format using `as::ftime`.
- Remember that current calendars may be not Gregorian.

# Internals

Formatting information is stored in a stream class by using the `xalloc`, `pword`, and `register_callback` member functions of `std::ios_base` . All the information is stored and managed using a special object bound to `iostream`, and the manipulators just change its state.

When a number is written to or read from the stream, a custom Boost.Locale facet accesses the object and checks the required formatting information. Then it creates a special object that actually formats the number and caches it in the `iostream`. The next time a number is written to the stream, the same formatter would be used unless some flags had changed and formatter object is invalid.

- © Copyright 2009-2012 Artyom Beilis, Distributed under the Boost Software License, Version 1.0.