namespace std
{
// 22.1.1 Class locale
+ /**
+ * @brief Container class for localization functionality.
+ *
+ * The locale class is first a class wrapper for C library locales. It is
+ * also an extensible container for user-defined localization. A locale is
+ * a collection of facets that implement various localization features such
+ * as money, time, and number printing.
+ *
+ * Constructing C++ locales does not change the C library locale.
+ *
+ * This library supports efficient construction and copying of locales
+ * through a reference counting implementation of the locale class.
+ */
class locale
{
public:
// Types:
+ /// Definition of locale::category.
typedef unsigned int category;
// Forward decls and friends:
template<typename _Cache>
friend struct __use_cache;
- // Category values:
- // NB: Order must match _S_facet_categories definition in locale.cc
+ //@{
+ /**
+ * @brief Category values.
+ *
+ * The standard category values are none, ctype, numeric, collate, time,
+ * monetary, and messages. They form a bitmask that supports union and
+ * intersection. The category all is the union of these values.
+ *
+ * @if maint
+ * NB: Order must match _S_facet_categories definition in locale.cc
+ * @endif
+ */
static const category none = 0;
static const category ctype = 1L << 0;
static const category numeric = 1L << 1;
static const category messages = 1L << 5;
static const category all = (ctype | numeric | collate |
time | monetary | messages);
+ //@}
// Construct/copy/destroy:
+
+ /**
+ * @brief Default constructor.
+ *
+ * Constructs a copy of the global locale. If no locale has been
+ * explicitly set, this is the "C" locale.
+ */
locale() throw();
+ /**
+ * @brief Copy constructor.
+ *
+ * Constructs a copy of @a other.
+ *
+ * @param other The locale to copy.
+ */
locale(const locale& __other) throw();
+ /**
+ * @brief Named locale constructor.
+ *
+ * Constructs a copy of the named C library locale.
+ *
+ * @param s Name of the locale to construct.
+ * @throw std::runtime_error if s is null or an undefined locale.
+ */
explicit
locale(const char* __s);
+ /**
+ * @brief Construct locale with facets from another locale.
+ *
+ * Constructs a copy of the locale @a base. The facets specified by @a
+ * cat are replaced with those from the locale named by @a s. If base is
+ * named, this locale instance will also be named.
+ *
+ * @param base The locale to copy.
+ * @param s Name of the locale to use facets from.
+ * @param cat Set of categories defining the facets to use from s.
+ * @throw std::runtime_error if s is null or an undefined locale.
+ */
locale(const locale& __base, const char* __s, category __cat);
+ /**
+ * @brief Construct locale with facets from another locale.
+ *
+ * Constructs a copy of the locale @a base. The facets specified by @a
+ * cat are replaced with those from the locale @a add. If @a base and @a
+ * add are named, this locale instance will also be named.
+ *
+ * @param base The locale to copy.
+ * @param add The locale to use facets from.
+ * @param cat Set of categories defining the facets to use from add.
+ */
locale(const locale& __base, const locale& __add, category __cat);
+ /**
+ * @brief Construct locale with another facet.
+ *
+ * Constructs a copy of the locale @a other. The facet @f is added to
+ * @other, replacing an existing facet of type Facet if there is one. If
+ * @f is null, this locale is a copy of @a other.
+ *
+ * @param other The locale to copy.
+ * @param f The facet to add in.
+ */
template<typename _Facet>
locale(const locale& __other, _Facet* __f);
+ /// Locale destructor.
~locale() throw();
- const locale&
+ /**
+ * @brief Assignment operator.
+ *
+ * Set this locale to be a copy of @a other.
+ *
+ * @param other The locale to copy.
+ * @return A reference to this locale.
+ */
+ const locale&
operator=(const locale& __other) throw();
+ /**
+ * @brief Construct locale with another facet.
+ *
+ * Constructs and returns a new copy of this locale. Adds or replaces an
+ * existing facet of type Facet from the locale @a other into the new
+ * locale.
+ *
+ * @param Facet The facet type to copy from other
+ * @param other The locale to copy from.
+ * @return Newly constructed locale.
+ * @throw std::runtime_error if other has no facet of type Facet.
+ */
template<typename _Facet>
locale
combine(const locale& __other) const;
// Locale operations:
+ /**
+ * @brief Return locale name.
+ * @return Locale name or "*" if unnamed.
+ */
string
name() const;
+ /**
+ * @brief Locale equality.
+ *
+ * @param other The locale to compare against.
+ * @return True if other and this refer to the same locale instance, are
+ * copies, or have the same name. False otherwise.
+ */
bool
operator==(const locale& __other) const throw ();
+ /**
+ * @brief Locale inequality.
+ *
+ * @param other The locale to compare against.
+ * @return ! (*this == other)
+ */
inline bool
operator!=(const locale& __other) const throw ()
{ return !(this->operator==(__other)); }
+ /**
+ * @brief Compare two strings according to collate.
+ *
+ * Template operator to compare two strings using the compare function of
+ * the collate facet in this locale. One use is to provide the locale to
+ * the sort function. For example, a vector v of strings could be sorted
+ * according to locale loc by doing:
+ * @code
+ * std::sort(v.begin(), v.end(), loc);
+ * @endcode
+ *
+ * @param s1 First string to compare.
+ * @param s2 Second string to compare.
+ * @return True if collate<Char> facet compares s1 < s2, else false.
+ */
template<typename _Char, typename _Traits, typename _Alloc>
bool
operator()(const basic_string<_Char, _Traits, _Alloc>& __s1,
const basic_string<_Char, _Traits, _Alloc>& __s2) const;
// Global locale objects:
+ /**
+ * @brief Set global locale
+ *
+ * This function sets the global locale to the argument and returns a
+ * copy of the previous global locale. If the argument has a name, it
+ * will also call std::setlocale(LC_ALL, loc.name()).
+ *
+ * @param locale The new locale to make global.
+ * @return Copy of the old global locale.
+ */
static locale
global(const locale&);
+ /**
+ * @brief Return reference to the "C" locale.
+ */
static const locale&
classic();
// 22.1.1.1.2 Class locale::facet
+ /**
+ * @brief Localization functionality base class.
+ *
+ * The facet class is the base class for a localization feature, such as
+ * money, time, and number printing. It provides common support for facets
+ * and reference management.
+ *
+ * Facets may not be copied or assigned.
+ */
class locale::facet
{
private:
_S_initialize_once();
protected:
+ /**
+ * @brief Facet constructor.
+ *
+ * This is the constructor provided by the standard. If refs is 0, the
+ * facet is destroyed when the last referencing locale is destroyed.
+ * Otherwise the facet will never be destroyed.
+ *
+ * @param refs The initial value for reference count.
+ */
explicit
facet(size_t __refs = 0) throw() : _M_refcount(__refs ? 1 : 0)
{ }
+ /// Facet destructor.
virtual
~facet();
// 22.1.1.1.3 Class locale::id
+ /**
+ * @brief Facet ID class.
+ *
+ * The ID class provides facets with an index used to identify them.
+ * Every facet class must define a public static member locale::id, or be
+ * derived from a facet that provides this member, otherwise the facet
+ * cannot be used in a locale. The locale::id ensures that each class
+ * type gets a unique identifier.
+ */
class locale::id
{
private:
public:
// NB: This class is always a static data member, and thus can be
// counted on to be zero-initialized.
+ /// Constructor.
id() { }
size_t
projects / thirdparty / gcc.git / commitdiff
