Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

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:

Currency formatting

These are the manipulators for currency formatting:

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:

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:

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:

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:

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

General recommendations


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.