Apache C++ Standard Library Reference Guide

## money_get

Library: Localization

    money_get  locale::facet

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

### Local Index

#### Members

char_type do_get() | get() id | iter_type money_get() | string_type

### Summary

A monetary parsing facet.

### Synopsis

    #include <locale>

    namespace std {
      template <class charT,
                class InputIterator = istreambuf_iterator<charT> >
      class money_get;
    }

### Specializations

The primary template can be implicitly or explicitly specialized on any character type that satisfies the requirements on the type of the character used by iostream class templates, and on any iterator type that satisfies the requirements of Output Iterator.

### Description

The money_get facet includes facilities for parsing sequences of characters and interpreting them as monetary values. The facet is not used by any other C++ Standard Library components.

### Interface

    namespace std {

      template <class charT,
                class InputIterator = istreambuf_iterator<charT> >
      class money_get : public locale::facet
      {
      public:
        typedef charT               char_type;
        typedef InputIterator       iter_type;
        typedef basic_string<charT> string_type;

        explicit money_get(size_t = 0);

        iter_type get(iter_type, iter_type, bool, ios_base&,
                      ios_base::iostate&, long double&) const;
        iter_type get(iter_type, iter_type, bool, ios_base&,
                      ios_base::iostate&, string_type&) const;
        static locale::id id;

      protected:
        virtual iter_type do_get(iter_type, iter_type,
                                 bool, ios_base&,
                                 ios_base::iostate&,
                                 long double&) const;
        virtual iter_type do_get(iter_type, iter_type,
                                 bool, ios_base&,
                                 ios_base::iostate&,
                                 string_type&) const;
      };
    }

### Member Types

    char_type

Type of the first template argument.

    iter_type

Type of the second template argument.

    string_type

The type of `basic_string` specialized on `char_type`.

### Constructor

    explicit money_get(size_t refs = 0)

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

The `refs` argument is set to the initial value of the money_get object's reference count. A money_get 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 money_get object constructed with `(refs != 0)` will not be destroyed by any locale objects in which it may have been installed.

### Static Members

    static locale::id id;

Unique identifier for this type of facet.

### Public Member Functions

The public members of the money_get facet include an interface to protected members. Each public member `get()` calls the corresponding protected virtual protected member `do_get()`.

    iter_type
    get(iter_type s, iter_type end, bool intl, ios_base& f,
        ios_base::iostate& err, long double& units) const;
    iter_type
    get(iter_type s, iter_type end, bool intl, ios_base& f,
        ios_base::iostate& err, string_type& digits) const;

Each of these two overloads of the public member function `get()` calls the corresponding protected virtual `do_get()` function.

### Protected Member Functions

    virtual iter_type
    do_get(iter_type s, iter_type end,
           bool intl, ios_base& io,
           ios_base::iostate& err,
           long double& units) const;
    virtual iter_type
    do_get(iter_type s, iter_type end,
           bool intl, ios_base& io,
           ios_base::iostate& err,
           string_type& digits) const;

Reads a sequence of characters `[s,end)`, and attempts to extract a monetary value. On success, the integral part of the extracted value is stored in `units` or `digits`, respectively, either as a `long double` value, or as a sequence of digits, without modifying `err`; otherwise `units` and `digits` is left unchanged and `ios_base::failbit` is set in `err`. The functions return an iterator pointing just past the last extracted character.

The `io` argument is used to obtain a reference to the `moneypunct<char_type, intl>` facet installed in the object's locale and containing locale-specific punctuation data (the format of the monetary value, the currency symbol, the negative and positive signs, the number of significant digits after the decimal point, the grouping, the thousands separator, and the decimal point), to obtain a reference to the `ctype<char_type>` facet installed in the same locale needed to interpret the parsed characters, and to determine whether the currency symbol is optional or required. If the functions reach the end of the input sequence while attempting to extract additional characters, they set `ios_base::eofbit` in `err`.

The functions use the result of `use_facet<moneypunct<char_type, intl>` `>(io.getloc()).neg_format()` to parse all sequences. Where `money_base::none` or `money_base::space` appears in the format, any optional whitespace characters, as determined by `isspace(c, io.getloc ())`, are extracted from the input sequence after the required space, if any. Trailing whitespace is never extracted, even when followed by the currency symbol, unless the latter is required (see below). Where `money_base::sign` appears in the format, the first character (if any) of either the negative sign or the positive sign, as determined by `use_facet<moneypunct<char_type, intl> >(io.getloc()).negative_sign()` and `positive_sign()`, respectively, is required. Any remaining characters of the sign are extracted only after all other components of the format, including any whitespace, have been successfully extracted. If the first character of the positive sign is equal to the first character of the negative sign, or if both are empty, the extracted value is assumed to be positive. Where `money_base::value` appears in the format, a sequence of digits, as determined by `isdigit(c, io.getloc())`, optionally iterspersed with thousands separators (see below), is extracted. If `(use_facet<moneypunct<char_type, intl> >(io.getloc()).frac_digits() > 0)` is true the sequence of digits may be immediately followed by the decimal point and, optionally, by additional digits (no thousands separators are allowed); in that case the extracted value is multiplied by `10` to the power of `fd`, where `fd` is the number of fractional digits, and truncated to an integer before storing.

If `(io.flags () & ios_base::showbase)` is non-zero, the currency symbol is required; otherwise the currency symbol is optional and is only extracted from the input sequence if other components of the monetary value are necessary to complete it.

If `use_facet<moneypunct<char_type, intl> >(io.getloc()).grouping()` returns a non-empty string, the positions of any characters found in the input sequence prior to the character returned by `use_facet<moneypunct<char_type, intl> >(io.getloc()).decimal_point()`, if any, which match that returned by `use_facet<moneypunct<char_type> >(io.getloc()).thousands_sep()` are checked for consistency with the grouping string. The functions indicate inconsistencies in the placement of thousands speratators by setting `ios_base::failbit` in `err`. If the grouping is empty, the first thousands separator terminates input.

### Example

    #include <locale>     // for locale, money_get, use_facet
    #include <sstream>    // for istringstream
    #include <iostream>   // for cout, endl
    #include <iterator>   // for istreambuf_iterator

    int main (int argc, char *argv[])
    {
        // Get the monetary string and locale from the argument vector.
        const char* const buffer  = 1 < argc ? argv [1] : "$1,234.6789";
        const char* const locname = 2 < argc ? argv [2] : "en_US";
        const bool        intl    = 3 < argc;

        std::string smon;
        long double fmon = 0.0;

        std::ios_base::iostate state = std::ios_base::goodbit;

        // Retrieve the money_get facet from the named locale.
        const std::locale loc (locname);

        typedef std::istreambuf_iterator<char> Iter;
        typedef std::money_get<char, Iter>     MoneyGet;

        const MoneyGet &mgf = std::use_facet<MoneyGet>(loc);

        {
            // Build an istringstream object from the buffer
            // and imbue the locale in it.
            std::istringstream ins (buffer);
            ins.imbue (loc);

            // Get a string representation of the monetary value.
            mgf.get (ins, Iter (), intl, ins, state, smon);
        }
        {
            std::istringstream ins (buffer);
            ins.imbue (loc);

            // Get a floating point representation of the monetary value.
            mgf.get (ins, Iter (), intl, ins, state, fmon);
        }

        // Output the original sequence and its string and floating point
        // representations.
        std::cout << buffer << " --> \"" << smon << "\" --> " << fmon << '\n';

        // Return 0 on success, non-zero on failure.
        return !(std::ios_base::eofbit == state);
    }

    Program Output:
    $1,234.6789 --> "123467" --> 123467

### See Also

locale, Facets, money_put, moneypunct

### Standards Conformance

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

Copyright © 2003-2006, The Apache Software Foundation