Apache C++ Standard Library Reference Guide

## moneypunct, moneypunct_byname

Library: Localization

                                    locale::facet
    moneypunct_byname  moneypunct
                                    money_base

- Local Index
- Summary
- Synopsis
- Specializations
- Description
- Interface
- Member Types
- Constructors
- Static Members
- Public Member Functions
- Protected Member Functions
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

char_type curr_symbol() decimal_point() do_curr_symbol() do_decimal_point() do_frac_digits() | do_grouping() do_negative_sign() do_neg_format() do_positive_sign() do_pos_format() do_thousands_sep() | frac_digits() grouping() id Intl moneypunct() moneypunct_byname() | negative_sign() neg_format() positive_sign() pos_format() string_type thousands_sep()

### Summary

Monetary punctuation facets

### Synopsis

    #include <locale>

    namespace std {
      class money_base;
      template <class charT, bool International = false>
      class moneypunct;
      template <class charT, bool International = false>
      class moneypunct_byname;
    }

### Specializations

    template<> class moneypunct<char, false>;
    template<> class moneypunct<char, true>;
    template<> class moneypunct<wchar_t, false>;
    template<> class moneypunct<wchar_t, true>;

    template<> class moneypunct_byname<char, false>;
    template<> class moneypunct_byname<char, true>;
    template<> class moneypunct_byname<wchar_t, false>;
    template<> class moneypunct_byname<wchar_t, true>;

### Description

The moneypunct facets include formatting specifications and punctuation character for monetary values. The moneypunct facet is used with the C locale, while the moneypunct_byname facet is used with named locales.

The facet is used by money_put for outputting formatted representations of monetary values and by money_get for reading these strings back in.

money_base defines a structure, `pattern`, that specifies the order of syntactic elements in a monetary value and enumeration values representing those elements. The `pattern` struct includes a simple array of characters, `field`. Each index in `field` is taken up by an enumeration value indicating the location of a syntactic element. The enumeration values are described below:

#### Table 28: Enumeration values of field indexes in the money_base pattern struct

Format Flag | Value | Meaning
`none` | 0 | No grouping separator.
`space` | 1 | Use space for grouping separator.
`symbol` | 2 | Currency symbol.
`sign` | 3 | Sign of monetary value.
`value` | 4 | The monetary value itself.

The `do_pos_format()` and `do_neg_format()` member functions of moneypunct both return values of the `pattern` type. See the description of these functions for further elaboration.

### Interface

    namespace std {

      class money_base {
      public:
        enum part { none, space, symbol, sign, value };
        struct pattern { char field[4]; };
      };

      template <class charT, bool International = false>
      class moneypunct : public locale::facet, public money_base
      {
      public:
        typedef charT char_type;
        typedef basic_string<charT> string_type;
        explicit moneypunct(size_t = 0);
        charT        decimal_point() const;
        charT        thousands_sep() const;
        string       grouping()      const;
        string_type  curr_symbol()   const;
        string_type  positive_sign() const;
        string_type  negative_sign() const;
        int          frac_digits()   const;
        pattern      pos_format()    const;
        pattern      neg_format()    const;
        static locale::id id;
        static const bool intl = International;
      };

      template <class charT, bool Intl = false>
      class moneypunct_byname : public moneypunct<charT, Intl>
      {
      public:
        explicit moneypunct_byname(const char*, size_t = 0);

        };
    }

### Member Types

    char_type

Type of the first template argument.

    string_type

Type of `basic_string` specialized on `char_type`, whose values are returned by some member functions.

### Constructors

    explicit moneypunct(size_t refs = 0)

Constructs a moneypunct object. Calls `locale::facet (refs)`.

The `refs` argument is set to the initial value of the object's reference count. A moneypunct object `f` constructed with `(refs == 0)` that is installed in one or more locale objects will be destroyed and the storage it occupies will be deallocated when the last locale object containing the facet is destroyed, as if by calling `delete static_cast<locale::facet*>(&f)`. A moneypunct object constructed with `(refs != 0)` will not be destroyed by any locale objects in which it may have been installed.

    explicit moneypunct_byname(const char* name,
                                 size_t refs = 0);

Constructs a moneypunct_byname facet. Calls `moneypunct (refs)`.

### Static Members

    static locale::id id;

Unique identifier for this type of facet.

    static const bool intl = Intl;

`true` for international representation, `false` otherwise.

### Public Member Functions

The public members of the moneypunct and moneypunct_byname facets include an interface to protected members. Each public member function `xxx()` calls the corresponding protected virtual protected member function `do_xxx()`. For instance, the public member function `decimal_point()` function calls its protected cousin `do_decimal_point()`.

    string_type  curr_symbol()   const;
    charT        decimal_point() const;
    int          frac_digits()   const;
    string       grouping()      const;
    pattern      neg_format()    const;
    string_type  negative_sign() const;
    pattern      pos_format()    const;
    string_type  positive_sign() const;
    charT        thousands_sep() const;

Each public member function `xxx()` calls the corresponding protected `do_xxx()` function. The result of the call may be cached. Subsequent calls to the public function may return the cached result to avoid the expense of repeatedly calling the virtual function.

### Protected Member Functions

    virtual string_type
    do_curr_symbol() const;

Returns a string to use as the currency symbol. In the C locale, the function returns the empty string. In named locales, the returned international string (in other words, when `intl == true`) typically conforms to the ISO 4217 standard. For example, the standard specifies that the US currency symbol for the Dollar is USD, and that the Japanese currency symbol for the Yen is JPY.

    virtual charT
    do_decimal_point() const;

Returns the radix separator to use if fractional digits are allowed. See `do_frac_digits()`. In the C locale, the function returns the period (`'``.``'` and `L``'``.``'`).

    virtual int
    do_frac_digits() const;

Returns the number of digits in the fractional part of the monetary representation. In the C locale, the function returns `0`.

    virtual string
    do_grouping() const;

Returns a string in which the numeric value of each character is used as an integer value to represent the number of digits in a particular grouping, starting with the rightmost group. A group is simply a sequence of digits between two adjacent thousands separators, or between the decimal point and the first thousands separator. Each group at a position greater than or equal to the size of the string gets the same value as the last element in the string. If a value is less than or equal to zero, or equal to `CHAR_MAX`, then the size of that group is unlimited. In the C locale, the function returns the empty string, indicating no grouping.

    virtual string_type
    do_negative_sign() const;

A string to use as the negative sign. The first character of this string is placed in the position indicated by the format pattern. See `do_neg_format()`. The rest of the characters, if any, are placed after all other parts of the monetary value. In the C locale, the function returns the empty string.

    virtual pattern
    do_neg_format() const;
    virtual pattern
    do_pos_format() const;

Returns a pattern object specifying the location of the various syntactic elements in a monetary representation. The enumeration values `symbol`, `sign`, and `value` appear exactly once in this pattern, with the remaining location taken by either `none` or `space`. `none` never occupies the first position in the pattern and `space` never occupies the first or the last position. Beyond these restrictions, elements may appear in any order. In the C locale, the functions return `{symbol, sign, none, value}`.

    virtual string_type
    do_positive_sign() const;

A string to use as the positive sign for a monetary value. The first character of this string is placed in the position indicated by the format pattern. See `do_pos_format()`. The rest of the characters, if any, are placed after all other parts of the monetary value. In the C locale, the function returns the empty string.

    virtual charT
    do_thousands_sep() const;

Returns the grouping separator. See `do_grouping()`. In the C locale, the function returns the comma (`'``,``'` and `L``'``,``'`).

### Example

    #include <locale>     // for locale
    #include <iostream>   // for cout, endl
    #include <limits>     // for numeric_limits

    int main ()
    {
        // Get a moneypunct facet from the global ("C") locale
        const std::moneypunct<char, false> &mp =
            std::use_facet<std::moneypunct<char, false>
            >(std::locale ());

        // expected values (see 7.11 of C99):
        //     Decimal point        = ''
        //     Thousands seperator  = ''
        //     Negative Sign        = ""
        //     Digits after decimal = CHAR_MAX

        // check to make sure the character returned from
           decimal_point () and
        // thousands_sep() are null characters so that the nulls are
           not printed.
        if ('\0' == mp.decimal_point ())
            std::cout << "Decimal point        = ''";
        else
            std::cout << "Decimal point        = '" <<
            mp.decimal_point () << "'";

        if ('\0' == mp.thousands_sep ())
            std::cout << "\nThousands seperator  = ''";
        else
            std::cout << "\nThousands seperator  = '" <<
            mp.thousands_sep () << "'";

        std::cout << "\nCurrency symbol      = \"" << mp.curr_symbol
            () << "\""
                  << "\nNegative Sign        = \"" <<
                  mp.negative_sign () << "\"";

        // since the value of CHAR_MAX depends on the signedness of
           char,
        // if mp.frac_digits() equals CHAR_MAX print the string
           "CHAR_MAX",
        // otherwise print the actual value

        if (std::numeric_limits<char>::max () == mp.frac_digits ())
            std::cout << "\nDigits after decimal = CHAR_MAX\n";
        else
            std::cout << "\nDigits after decimal = " <<
            mp.frac_digits () << '\n';

        return 0;
    }

    Program Output:
    Decimal point        = ''
    Thousands seperator  = ''
    Currency symbol      = ""
    Negative Sign        = ""
    Digits after decimal = CHAR_MAX

### See Also

locale, Facets, money_put, money_get

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 22.2.6.3