Friday, February 7, 2025

money_get,money_put and moneypunct facets

Overview
currency is a numerical values or strings of digits representing money. CRT provides apis for reading and formatting currency with various punctuations. Standard library provides same functionality using money_get, money_put and moneypunct facets. Thes are also used by IO stream manipulatprs money_get and money_put.

Details

money_base
This is a base class for money_get,  money_put and money_punct facets. These are internally used by  methods of the facets.

It defines part enum type  as below. 
enum part { none, space, symbol, sign, value };
NameDescription
none whitespace is permitted but not required except in the last position, where whitespace is not permitted
spaceone or more whitespace characters are required
symbolThe sequence of characters returned by moneypunct::curr_symbol is required
signThe first of the characters returned by moneypunct::positive_sign or moneypunct::negative_sign is required
valueThe absolute numeric monetary value is required

It also declares money format pattern as below.
struct pattern { char field[4]; }
The monetary format is an array of four chars convertible to enum part. 
In that sequence, each of symbol, sign, and value appears exactly once, and either space or none appears in the remaining position. 
The value none, if present, is not first; the value and space, if present, is neither first nor last.
The default format, returned by the standard specializations of moneypunct is {symbol, sign, none, value}.

money_get
This class encapsulates currency parsing rules. The iostream manipulator get_money use the money_get facet of the I/O stream's locale to convert text input to a currency.

Syntax
template<class CharT,class InputIt = std::istreambuf_iterator<CharT>> 
class money_get:public money_base, public facet
CharT can be char and whcar_t. It's aliased as member char_type.  It represents the type of the characters in the sequence to interpret.
InputIt Represents Input iterator type that points to the elements in the character sequence to interpret.
Defaults to istreambuf_iterator, which is an iterator that can be implicitly converted from basic_istream objects.

types
NameDescription
char_type Represents the character type. It's a typedef for CharT .
string_type Represents string type corresponding to the character type. 
It's a typedef for basic_string<charT>
iter_type Represents the iterator type. It's a typedef for InputIt.

Specializations
//narrow string representations of currency
money_get<char>

//wide string representations of currency
money_get<wchar_t>
Fields
NameDescription
locale::id id the identifier of the facet. Represents the monitory category of the facet.
intlboolean value/ Alias of the second class template argument: International.

Constructor
NameDescription
money_get(size_t refs = 0)Creates a money_get facet and forwards the starting reference count refs to the base class constructor, locale::facet::facet()

Methods
NameDegcription
  1. iter_type get
    (iter_type beg, iter_type end,
    bool intl, ios_base& str,
    iostate& err, long double& val)
  2. iter_type get
    (iter_type beg, iter_type end, 
    bool intl, ios_base& str,
    iostate& err, string_type& val)

Reads successive characters from the sequence [beg, 
end] and parses out the currency. 
The parsed number is stored in the val.
intl is used to pull correct format from moneypunct facet.
If the end iterator is reached before a valid number is read, the function sets ios_base::eofbit in err. If a parsing error is encountered, the function sets ios_base::failbit in err.
Example
istringstream ss("USD  1,234.56");
ss.imbue(locale("en_US.UTF-8"));
 
auto& f = use_facet<money_get<char>>(ss.getloc());
ios_base::iostate err;
istreambuf_iterator<char> beg(ss), end;
    
long double val;

//val:123456
f.get(beg, end, true, ss, err, val);

string sval;
ss.str("$1,234.56");
//sval:"123456"
f.get(beg, end, false, ss, err, sval);
This example 7 demonstrates the usage of the money_get facet as seen in its console output.

money_put
This class encapsulates currency formatting rules. The I/O manipulator for currency put_money uses the money_put facet of the I/O stream's locale to generate text representing from numbers.

Syntax
template<class CharT,class OutputIt = std::ostreambuf_iterator<CharT>> 
class money_put:public facet
CharT can be char and whcar_t. It's aliased as member char_type.  It represents the type of the characters in the sequence to interpret.
OutputIt Represents Output iterator type that points to the output stream where text will be written.
Defaults to ostreambuf_iterator, which is an iterator that can be implicitly converted from basic_ostream objects. 

types
NameDescription
char_type Represents the character type. It's a typedef for CharT .
string_type Represents string type corresponding to the character type. 
It's a typedef for basic_string<charT>
iter_type Represents the iterator type. It's a typedef for InputIt.

Specializations
//narrow string representations of currency
money_put<char>

//wide string representations of currency
money_put<wchar_t>

Fields
NameDescription
locale::id id the identifier of the facet. Represents the monitory category of the facet.

Constructor
NameDescription
money_put(size_t refs = 0)Creates a money_put facet and forwards the starting reference count refs to the base class constructor, locale::facet::facet().

Methods
NameDescription
  1. iter_type put
    (iter_type out, bool intl, ios_base& str,
    char_type fill, long double val)
  2. iter_type put
    (iter_type out, bool intl, ios_base& str,
    char_type fill, string val)
Writes currency value in val to the stream pointer out. fill is used for  padding. intl used is formatting in conjunction with moneypunct facet.
The streams io flags are honoured. 
Example
    cout.imbue(locale("en_US.UTF-8"));
    auto& f = use_facet<money_put<char>>(cout.getloc());


    cout << setw(15) << right  << showbase;
    //prints:######$1,234.56
    f.put(cout, false, cout, '#', 123456);
    cout << endl;
    
    cout << setw(15) << right  << showbase;
    //prints:##USD #1,234.56
    f.put(cout, true, cout, '#', "123456");
This example 8 demonstrates the usage of the money_put facet apis as seen in its console output.

moneypunct
The facet moneypunct encapsulates monetary value format preferences. Stream I/O manipulators get_money and put_money use moneypunct through money_get and money_put for parsing monetary value input and formatting monetary value output.

Syntax
template <class charT, bool International = false>
class money_punct:public facet, public money_base
CharT can be char and whcar_t. It's aliased as member char_type.  It represents the type of the characters in the sequence to interpret.
International  If true, the representation uses an international format (such as using the three-letter code USD for the US dollar)
If false (the default value), the representation may use a non-international format (such as using the dollar sign, $, for the US dollar).

types
NameDescription
char_type Represents the character type. It's a typedef for CharT .
string_type Represents string type corresponding to the character type. 
It's a typedef for basic_string<charT>

Specializations
//narrow string representations 
moneypunct<char>


//narrow string representations with international currency symbols
moneypunct<char,true>

//wide string representations with international currency symbols
moneypunct<wchar_t>	


//wide string representations with international currency symbols
moneypunct<wchar_t,true>

Fields
NameDescription
locale::id id the identifier of the facet. Represents the time category of the facet.

Constructor
NameDescription
moneypunct(size_t refs = 0)Creates a moneypunct facet and forwards the starting reference count refs to the base class constructor, locale::facet::facet().

Methods
NameDescription
char_type decimal_point()
Returns the character used to represent the decimal radix separator.
char_type thousands_sep()Returns the character used to represent the digit group separator.
string_type grouping()

Returns a sequence of values indicating the number of digits in each group.

Each char element in the returned sequence is shall be interpreted as an integer value indicating the number of digits in each group. Grouping is considered from right to left, with the first character in the string being used for the rightmost group, and the last character used for any group farther away than the length of the string.

For example, "\03" indicates groups of three digits each, while "\02\03" would indicate that the rightmost group has two digits and all the remaining ones have three digits each.
string_type curr_symbol() Returns the string used to represent the currency identifier symbol.
string_type positive_sign()Returns the string used to represent the indicate a monetary value is positive.
string_type negative_sign()Returns the string used to represent the indicate a monetary value is negative.
int frac_digits()Returns the number of digits after the decimal separator sign, if any.
int frac_digits()Returns the number of digits after the decimal separator sign, if any.
pattern pos_format()Returns the pattern that specifies the format for positive monetary expressions.
pattern neg_format()Returns the pattern that specifies the format for negative monetary expressions.
Example
ostream& operator<< (ostream& os, moneypunct<char>::pattern p)
{
    for (int i=0; i<4; i++)
    switch (p.field[i]) 
    {
      case moneypunct<char>::none: cout << "none "; break;
      case moneypunct<char>::space: cout << "space "; break;
      case moneypunct<char>::symbol: cout << "symbol "; break;
      case moneypunct<char>::sign: cout << "sign "; break;
      case moneypunct<char>::value: cout << "value "; break;
    }
  return os;
}


void printpunct (string loc)
{
  locale l(loc);
  
  cout.imbue(l);
  const moneypunct<char>& mp = use_facet<moneypunct<char> >(l);

  cout << "decimal_point: " << mp.decimal_point() << endl;
  cout << "thousands_sep: " << mp.thousands_sep() << endl;
  cout << "grouping: ";
  for (int c:mp.grouping()) cout << c << " ";
  cout << endl;
  cout << "curr_symbol: " << mp.curr_symbol() << endl;
  cout << "positive_sign: " << mp.positive_sign() << endl;
  cout << "negative_sign: " << mp.negative_sign() << endl;
  cout << "frac_digits: " << mp.frac_digits() << endl;
  cout << "pos_format: " << mp.pos_format() << endl;
  cout << "neg_format: " << mp.neg_format() << endl;
  cout << endl;
}


    /*prints 
    decimal_point: .
    thousands_sep: ,
    grouping: 3 3 
    curr_symbol: $
    positive_sign: 
    negative_sign: -
    frac_digits: 2
    pos_format: sign symbol value none 
    neg_format: sign symbol value none 
    */
    printpunct("en_US.utf8");
    
    /*prints 
    decimal_point: .
    thousands_sep: ,
    grouping: 3 
    curr_symbol: ￥
    positive_sign: 
    negative_sign: -
    frac_digits: 0
    pos_format: symbol sign value none 
    neg_format: symbol sign value none 
    */
    printpunct("ja_JP.utf8");
This example 9  demonstrates the usage of the moneypunct facet for different locales as seen in 
its console output.






at
Labels:

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)