boost::locale::basic_format< CharType > Class Template Reference

a printf like class that allows type-safe and locale aware message formatting More...

#include <boost/locale/format.hpp>

Public Types

typedef CharType char_type
 Underlying character type.
typedef basic_message< char_typemessage_type
typedef std::basic_string< CharType > string_type
 string type for this type of character
typedef std::basic_ostream< CharType > stream_type
 output stream type for this type of character

Public Member Functions

 basic_format (const string_type &format_string)
 Create a format class for format_string.
 basic_format (const message_type &trans)
 basic_format (const basic_format &other)=delete
void operator= (const basic_format &other)=delete
 basic_format (basic_format &&other)
basic_formatoperator= (basic_format &&other)
template<typename Formattible >
basic_formatoperator% (const Formattible &object)
string_type str (const std::locale &loc=std::locale()) const
 Format a string using a locale loc.
void write (stream_type &out) const
 write a formatted string to output stream out using out's locale

Detailed Description

template<typename CharType>
class boost::locale::basic_format< CharType >

a printf like class that allows type-safe and locale aware message formatting

This class creates a formatted message similar to printf or boost::format and receives formatted entries via operator %.

For example

std::cout << format("Hello {1}, you are {2} years old") % name % age << std::endl;
basic_format< char > format
Definition of char based format.
Definition: format.hpp:418

Formatting is enclosed between curly brackets { } and defined by a comma separated list of flags in the format key[=value] value may also be text included between single quotes ' that is used for special purposes where inclusion of non-ASCII text is allowed

Including of literal { and } is possible by specifying double brackets {{ and }} accordingly.

For example:

std::cout << format("The height of water at {1,time} is {2,num=fixed,precision=3}") % time % height;

The special key – a number without a value defines the position of an input parameter. List of keys:

  • [0-9]+ – digits, the index of a formatted parameter – mandatory key.
  • num or number – format a number. Optional values are:
    • hex – display hexadecimal number
    • oct – display in octal format
    • sci or scientific – display in scientific format
    • fix or fixed – display in fixed format
    For example number=sci
  • cur or currency – format currency. Optional values are:
    • iso – display using ISO currency symbol.
    • nat or national – display using national currency symbol.
  • per or percent – format percent value.
  • date, time , datetime or dt – format date, time or date and time. Optional values are:
    • s or short – display in short format
    • m or medium – display in medium format.
    • l or long – display in long format.
    • f or full – display in full format.
  • ftime with string (quoted) parameter – display as with strftime see, as::ftime manipulator
  • spell or spellout – spell the number.
  • ord or ordinal – format ordinal number (1st, 2nd... etc)
  • left or < – align to left.
  • right or > – align to right.
  • width or w – set field width (requires parameter).
  • precision or p – set precision (requires parameter).
  • locale – with parameter – switch locale for current operation. This command generates locale with formatting facets giving more fine grained control of formatting. For example:
    std::cout << format("Today {1,date} ({1,date,locale=he_IL.UTF-8@calendar=hebrew,date} Hebrew Date)") % date;
  • timezone or tz – the name of the timezone to display the time in. For example:
    std::cout << format("Time is: Local {1,time}, ({1,time,tz=EET} Eastern European Time)") % date;
  • local - display the time in local time
  • gmt - display the time in UTC time scale
    std::cout << format("Local time is: {1,time,local}, universal time is {1,time,gmt}") % time;

Invalid formatting strings are silently ignored. This protects against a translator crashing the program in an unexpected location.

calendar.cpp, hello.cpp, and whello.cpp.

Member Typedef Documentation

◆ message_type

template<typename CharType >
typedef basic_message<char_type> boost::locale::basic_format< CharType >::message_type

The translation message type

Constructor & Destructor Documentation

◆ basic_format()

template<typename CharType >
boost::locale::basic_format< CharType >::basic_format ( const message_type trans)

Create a format class using message trans. The message if translated first according to the rules of the target locale and then interpreted as a format string

Member Function Documentation

◆ operator%()

template<typename CharType >
template<typename Formattible >
basic_format & boost::locale::basic_format< CharType >::operator% ( const Formattible &  object)

Add new parameter to the format list. The object should be a type with defined expression out << object where out is std::basic_ostream.

A reference to the object is stored, so do not store the format object longer than the lifetime of the parameter. It is advisable to directly print the result:

basic_format<char> fmt("{0}");
fmt % (5 + 2); // INVALID: Dangling reference
int i = 42;
return fmt % i; // INVALID: Dangling reference
std::cout << fmt % (5 + 2); // OK, print immediately
return (fmt % (5 + 2)).str(); // OK, convert immediately to string
a printf like class that allows type-safe and locale aware message formatting
Definition: format.hpp:181
string_type str(const std::locale &loc=std::locale()) const
Format a string using a locale loc.
Definition: format.hpp:242

The documentation for this class was generated from the following file: