Standard library header <locale>

From cppreference.com
< cpp‎ | header

This header is part of the localization library.


Classes

set of polymorphic facets that encapsulate cultural differences
(class)
String and stream conversions
(C++11)(deprecated in C++17)
performs conversions between a wide string and a byte string
(class template)
(C++11)(deprecated in C++17)
performs conversion between a byte stream buffer and a wide stream buffer
(class template)
Facet category base classes
defines character classification categories
(class)
defines character conversion errors
(class)
defines messages catalog type
(class)
defines date format constants
(class)
defines monetary formatting patterns
(class)
Facet categories
defines character classification tables
(class template)
specialization of std::ctype for type char
(class template specialization)
converts between character encodings, including UTF-8, UTF-16, UTF-32
(class template)
defines lexicographical comparison and hashing of strings
(class template)
implements retrieval of strings from message catalogs
(class template)
parses time/date values from an input character sequence into struct std::tm
(class template)
formats contents of struct std::tm for output as character sequence
(class template)
parses numeric values from an input character sequence
(class template)
formats numeric values for output as character sequence
(class template)
defines numeric punctuation rules
(class template)
parses and constructs a monetary value from an input character sequence
(class template)
formats a monetary value for output as a character sequence
(class template)
defines monetary formatting parameters used by std::money_get and std::money_put
(class template)
Locale-specific facet categories
represents the system-supplied std::ctype for the named locale
(class template)
represents the system-supplied std::codecvt for the named locale
(class template)
represents the system-supplied std::messages for the named locale
(class template)
represents the system-supplied std::collate for the named locale
(class template)
represents the system-supplied std::time_get for the named locale
(class template)
represents the system-supplied std::time_put for the named locale
(class template)
represents the system-supplied std::numpunct for the named locale
(class template)
represents the system-supplied std::moneypunct for the named locale
(class template)

Functions

Locales and facets
obtains a facet from a locale
(function template)
checks if a locale implements a specific facet
(function template)
Character classification
checks if a character is classified as whitespace by a locale
(function template)
checks if a character is classified as a blank character by a locale
(function template)
checks if a character is classified as a control character by a locale
(function template)
checks if a character is classified as uppercase by a locale
(function template)
checks if a character is classified as lowercase by a locale
(function template)
checks if a character is classified as alphabetic by a locale
(function template)
checks if a character is classified as a digit by a locale
(function template)
checks if a character is classified as punctuation by a locale
(function template)
checks if a character is classified as a hexadecimal digit by a locale
(function template)
checks if a character is classified as alphanumeric by a locale
(function template)
checks if a character is classified as printable by a locale
(function template)
checks if a character is classfied as graphical by a locale
(function template)
Character conversions
converts a character to uppercase using the ctype facet of a locale
(function template)
converts a character to lowercase using the ctype facet of a locale
(function template)

Synospis

namespace std {
 
    // locale:
    class locale;
    template <class Facet> const Facet& use_facet(const locale&);
    template <class Facet> bool has_facet(const locale&) noexcept;
 
    // convenience interfaces:
    template <class charT> bool isspace (charT c, const locale& loc);
    template <class charT> bool isprint (charT c, const locale& loc);
    template <class charT> bool iscntrl (charT c, const locale& loc);
    template <class charT> bool isupper (charT c, const locale& loc);
    template <class charT> bool islower (charT c, const locale& loc);
    template <class charT> bool isalpha (charT c, const locale& loc);
    template <class charT> bool isdigit (charT c, const locale& loc);
    template <class charT> bool ispunct (charT c, const locale& loc);
    template <class charT> bool isxdigit(charT c, const locale& loc);
    template <class charT> bool isalnum (charT c, const locale& loc);
    template <class charT> bool isgraph (charT c, const locale& loc);
    template <class charT> charT toupper(charT c, const locale& loc);
    template <class charT> charT tolower(charT c, const locale& loc);
    template <class Codecvt, class Elem = wchar_t,
              class Wide_alloc = std::allocator<Elem>,
        class Byte_alloc = std::allocator<char> > class wstring_convert;
    template <class Codecvt, class Elem = wchar_t,
              class Tr = char_traits<Elem>> class wbuffer_convert;
 
    // ctype:
    class ctype_base;
    template <class charT> class ctype;
    template <>            class ctype<char>; // specialization
    template <class charT> class ctype_byname;
    class codecvt_base;
    template <class internT, class externT, class stateT> class codecvt;
    template <class internT, class externT, class stateT> class codecvt_byname;
 
    // numeric:
    template <class charT,	class	InputIterator = istreambuf_iterator<charT> > class num_get;
    template <class charT,	class	OutputIterator = osterambuf_iterator<charT> > class num_put;
    template <class charT>	class	numpunct;
    template <class charT>	class	numpunct_byname;
 
    // collation:
    template <class charT> class collate;
    template <class charT> class collate_byname;
 
    // date and time:
    class time_base;	
    template <class charT, class InputIterator = istreambuf_iterator<charT> >
        class time_get;	
    template <class charT, class InputIterator> = istreambuf_iterator<charT> >
        class time_get_byname;	
    template <class charT, class OutputIterator> = ostreambuf_iterator<charT> >
        class time_put;	
    template <class charT, class OutputIterator> = ostreambuf_iterator<charT> >
        class time_put_byname;	
 
    // money:	
    class money_base;	
    template <class charT, class InputIterator = istreambuf_iterator<charT> > > 
        class money_get;
    template <class charT, class OutputIterator = ostreambuf_iterator<charT> > > 
        class money_put;
    template <class charT, bool Intl = false> class moneypunct;
    template <class charT, bool Intl = false> class moneypunct_byname;
 
    // message retrieval:
    class messages_base;
    template <class charT> class messages;
    template <class charT> class messages_byname;
}


Class std::locale

class locale
{
public:
    // types:
    class facet;
    class id;
    typedef int category;
    static const category // values assigned here are for exposition only
        none    = 0,
        collate = 0x010, 
        ctype   = 0x020,
        monetary= 0x040, 
        numeric = 0x080,
        time    = 0x100, 
        messages= 0x200,
        all = collate | ctype | monetary | numeric | time | messages;
 
    // construct/copy/destroy:
    locale() noexcept;
    locale(const locale& other) noexcept;
    explicit locale(const char* std_name);
    explicit locale(const string& std_name);
    locale(const locale& other, const char* std_name, category);
    locale(const locale& other, const string& std_name, category);
    template <class Facet> locale(const locale& other, Facet* f);
    locale(const locale& other, const locale& one, category);
    ~locale();
 
    // not virtual
    const locale& operator=(const locale& other) noexcept;
    template <class Facet> locale combine(const locale& other) const;
 
    // locale operations:
    basic_string<char>
    name() const;
    bool operator==(const locale& other) const;
    bool operator!=(const locale& other) const;
    template <class charT, class traits, class Allocator>
    bool operator()(const basic_string<charT,traits,Allocator>& s1,
                    const basic_string<charT,traits,Allocator>& s2) const;
 
    // global locale objects:
    static
    locale global(const locale&);
    static const locale& classic();
};

Class std::ctype_base

class ctype_base {
public:
    typedef /*T*/ mask;
 
    // numeric values are for exposition only.
    static const mask space = 1 << 0;
    static const mask print = 1 << 1;
    static const mask cntrl = 1 << 2;
    static const mask upper = 1 << 3;
    static const mask lower = 1 << 4;
    static const mask alpha = 1 << 5;
    static const mask digit = 1 << 6;
    static const mask punct = 1 << 7;
    static const mask xdigit= 1 << 8;
    static const mask blank = 1 << 9;
    static const mask alnum = alpha | digit;
    static const mask graph = alnum | punct;
 
};

Class std::ctype

template <class charT>
class ctype : public locale::facet, public ctype_base
{
public:
    typedef charT char_type;
 
    explicit ctype(size_t refs = 0);
 
    bool is(mask m, charT c) const;
    const charT* is(const charT* low, const charT* high, mask* vec) const;
    const charT* scan_is(mask m,
                         const charT* low, const charT* high) const;
    const charT* scan_not(mask m,
                          const charT* low, const charT* high) const;
 
    charT           toupper(charT c) const;
    const charT*    toupper(charT* low, const charT* high) const;
    charT           tolower(charT c) const;
    const charT*    tolower(charT* low, const charT* high) const;
 
    charT       widen(char c) const;
    const char* widen(const char* low, const char* high, charT* to) const;
    char        narrow(charT c, char dfault) const;
    const charT*narrow(const charT* low, const charT*, char dfault,
                        char* to) const;
 
    static locale::id id;
 
protected:
    ~ctype();
    virtual bool do_is(mask m, charT c) const;
    virtual const charT* do_is(const charT* low, const charT* high,
                               mask* vec) const;
    virtual const charT* do_scan_is(mask m,
                                    const charT* low, const charT* high) const;
    virtual const charT* do_scan_not(mask m,
                                     const charT* low, const charT* high) const;
 
    virtual charT do_toupper(charT) const;
    virtual const charT* do_toupper(charT* low, const charT* high) const;
    virtual charT do_tolower(charT) const;
    virtual const charT* do_tolower(charT* low, const charT* high) const;
    virtual charT do_widen(char) const;
    virtual const char*  do_widen(const char* low, const char* high,
                                  charT* dest) const;
    virtual char do_narrow(charT, char dfault) const;
    virtual const charT* do_narrow(const charT* low, const charT* high,
                                   char dfault, char* dest) const;
};


Class std::ctype_byname

template <class charT>
class ctype_byname : public ctype<charT> {
public:
    typedef typename ctype<charT>::mask mask;
    explicit ctype_byname(const char*, size_t refs = 0);
    explicit ctype_byname(const string&, size_t refs = 0);
    protected:
    ~ctype_byname();
};

Class std::ctype<char>

template <> class ctype<char>
    : public locale::facet, public ctype_base
{
public:
    typedef char char_type;
    explicit ctype(const mask* tab = 0, bool del = false,
                   size_t refs = 0);
    bool is(mask m, char c) const;
    const char* is(const char* low, const char* high, mask* vec) const;
    const char* scan_is (mask m,
                         const char* low, const char* high) const;
    const char* scan_not(mask m,
                         const char* low, const char* high) const;
    char        toupper(char c) const;
    const char* toupper(char* low, const char* high) const;
    char        tolower(char c) const;
    const char* tolower(char* low, const char* high) const;
    char        widen(char c) const;
    const char* widen(const char* low, const char* high, char* to) const;
    char        narrow(char c, char dfault) const;
    const char* narrow(const char* low, const char* high, char dfault,
                       char* to) const;
 
    static locale::id id;
 
    static const size_t table_size = implementation-defined;
    const mask* table() const noexcept;
    static const mask* classic_table() noexcept;
 
protected:
    ~ctype();
    virtual char        do_toupper(char c) const;
    virtual const char* do_toupper(char* low, const char* high) const;
    virtual char        do_tolower(char c) const;
    virtual const char* do_tolower(char* low, const char* high) const;
    virtual char        do_widen(char c) const;
    virtual const char* do_widen(const char* low,
                                 const char* high,
                                 char* to) const;
    virtual char        do_narrow(char c, char dfault) const;
    virtual const char* do_narrow(const char* low,
                                  const char* high,
                                  char dfault, char* to) const;
};

Class std::codecvt_base

class codecvt_base
{
public:
    enum result { ok, partial, error, noconv };
};

Class std::codecvt

template <class internT, class externT, class stateT>
class codecvt : public locale::facet, public codecvt_base
{
public:
        typedef internT intern_type;
        typedef externT extern_type;
        typedef stateT state_type;
        explicit codecvt(size_t refs = 0);
        result out(stateT& state,
                   const internT* from, const internT* from_end, 
                   const internT*& from_next,
                   externT* to, externT* to_end, externT*& to_next) const;
        result unshift(stateT& state, externT* to,
                       externT* to_end, externT*& to_next) const;
        result in(stateT& state,
                  const externT* from, const externT* from_end, 
                  const externT*& from_next,
                  internT* to,
                  internT* to_end, internT*& to_next) const;
        int encoding() const noexcept;
        bool always_noconv() const noexcept;
        int length(stateT&, const externT* from, const externT* end,
                   size_t max) const;
        int max_length() const noexcept;
        static locale::id id;
protected:
        ~codecvt();
        virtual result do_out(stateT& state,
                              const internT* from, const internT* from_end, 
                              const internT*& from_next,
                              externT* to,
                              externT* to_end, externT*& to_next) const;
        virtual result do_in(stateT& state,
                             const externT* from, const externT* from_end, 
                             const externT*& from_next,
                             internT* to,
                             internT* to_end, internT*& to_next) const;
        virtual result do_unshift(stateT& state,
                                  externT* to,
                                  externT* to_end, externT*& to_next) const;
        virtual int do_encoding() const noexcept;
        virtual bool do_always_noconv() const noexcept;
        virtual int do_length(stateT&, const externT* from,
                              const externT* end, size_t max) const;
        virtual int do_max_length() const noexcept;
};

Class std::codecvt_byname

template <class internT, class externT, class stateT>
class codecvt_byname : public codecvt<internT, externT, stateT> {
public:
    explicit codecvt_byname(const char*, size_t refs = 0);
    explicit codecvt_byname(const string&, size_t refs = 0);
protected:
    ~codecvt_byname();
};


Class std::num_get

template <class charT, class InputIterator = istreambuf_iterator<charT> >
class num_get : public locale::facet
{
public:
    typedef charT           char_type;
    typedef InputIterator   iter_type;
    explicit num_get(size_t refs = 0);
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, bool& v) const;
    iter_type get(iter_type in, iter_type end, ios_base& ,
                  ios_base::iostate& err, long& v) const;
    iter_type get(iter_type in, iter_type end, ios_base& ,
                  ios_base::iostate& err, long long& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, unsigned short& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, unsigned int& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, unsigned long& v) const;
    iter_type get(iter_type in, iter_type end, ios_base& ,
                  ios_base::iostate& err, unsigned long long& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, float& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, double& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, long double& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, void*& v) const;
 
    static locale::id id;
 
 
protected:
    ~num_get();
 
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, bool& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, long& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, long long& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, unsigned short& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, unsigned int& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, unsigned long& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, unsigned long long& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, float& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, double& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, long double& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, void*& v) const;
};