Apache C++ Standard Library Reference Guide

## collate, collate_byname

Library: Localization

    collate_byname  collate  locale::facet

- Local Index
- Summary
- Synopsis
- Specializations
- Description
- Interface
- Member Types
- Constructors
- Destructors
- Facet ID
- Public Member Functions
- Protected Member Functions
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

char_type collate() collate_byname() compare() | do_compare() do_hash() do_transform() hash() | id string_type transform() ~collate() | ~collate_byname()

### Summary

A string collation, comparison, and hashing facet.

### Synopsis

    #include <locale>

    namespace std {
      template <class charT> class collate;
      template <class charT> class collate_byname;
    }

### Specializations

    template<> class collate<char>;
    template<> class collate<wchar_t>;
    template<> class collate_byname<char>;
    template<> class collate_byname<wchar_t>;

### Description

The collate and collate_byname facets allow for string collation, comparison, and hashing. Use the collate facet for the C locale, and use the collate_byname facet for named locales.

### Interface

    namespace std {
      template <class charT>
      class collate : public locale::facet {
      public:
        typedef charT char_type;
        typedef basic_string<charT> string_type;
        explicit collate(size_t refs = 0);
        int compare(const charT*, const charT*,
                    const charT*, const charT*) const;
        string_type transform(const charT*, const charT*) const;
        long hash(const charT*, const charT*) const;
        static locale::id id;
      protected:
        virtual ~collate();
        virtual int do_compare(const charT*, const charT*,
                               const charT*, const charT*) const;
        virtual string_type do_transform(const charT*,
                                         const charT*) const;
        virtual long do_hash (const charT*, const charT*) const;
      };

      template <class charT>
      class collate_byname : public collate<charT>
      {
       public:
        typedef basic_string<charT> string_type;
        explicit collate_byname(const char*, size_t = 0);
       protected:
        virtual ~collate_byname();
        virtual int do_compare(const charT*, const charT*,
                               const charT*, const charT*) const;
        virtual string_type do_transform(const charT*,
                                         const charT*) const;
        virtual long do_hash(const charT*, const charT*) const;
      };
    }

### Member Types

    char_type

Type of character the facet is instantiated on.

    string_type

Type of character string returned by member functions.

### Constructors

    explicit collate(size_t refs = 0)

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

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

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

Constructs a collate_byname object for the locale given by name. Calls `collate<char_type>::collate (refs)`.

### Destructors

    virtual ~collate();
    virtual ~collate_byname();

Destroys the facet.

### Facet ID

    static locale::id id;

Unique identifier for this type of facet.

### Public Member Functions

The public members of the collate facet include an interface to protected members. Each public member `xxx()` calls the corresponding virtual protected member `do_xxx()`. For instance, the public member function `compare()` calls its protected cousin, `do_compare()`.

    int
    compare(const charT* low1, const charT* high1,
            const charT* low2, const charT* high2) const;
    long
    hash(const charT* low, const charT* high) const;
    string_type
    transform(const charT* low, const charT* high) const;

Each of these public member functions `xxx()` simply calls the corresponding protected `do_xxx()` function.

### Protected Member Functions

    virtual int
    do_compare(const charT* low1, const charT* high1,
               const charT* low2, const charT* high2) const;

Returns `1` if the character string represented by the range `[low1,high1)` is greater than the character string represented by the range`[low2,high2)`, `-1` if the first string is less than the second, or `0` if the two are equal. The specializations, collate<char> and collate<wchar_t>, perform a lexicographical comparison.

As an extension of this implementation, the collate<char> and collate_byname<char> facets recognize and correctly interpret sequences of multi-byte characters.

    virtual long
    do_hash( const charT* low, const charT* high) const;

Generates a hash value from a string defined by the range of characters `[low,high)`. Given two strings that compare equal (in other words, `do_compare()` returns `0`), `do_hash()` returns an integer value that is the same for both strings. For differing strings, the probability that the return value is equal is approximately:

`1.0/numeric_limits<unsigned long>::max()`

As an extension of this implementation, the collate<char> and collate_byname<char> facets recognize and correctly interpret sequences of multi-byte characters.

    virtual string_type
    do_transform(const charT* low, const charT* high) const;

Returns a string that yields the same result in a lexicographical comparison with another string returned from `transform()` as does the `do_compare()` function applied to the original strings. In other words, the result of applying a lexicographical comparison to two strings returned from `transform()` is the same as applying `do_compare()` to the original strings passed to `transform()`.

As an extension of this implementation, the collate<char> and collate_byname<char> facets recognize and correctly interpret sequences of multi-byte characters.

### Example

    //
    // collate.cpp
    //

    #include <iostream>   // for cout, endl
    #include <locale>     // for collate

    int main ()
    {
        std::string s1 ("blue");
        std::string s2 ("blues");

        // Obtain a reference to the collate facet in
        // the default locale imbued in cout.
        const std::collate<char>& co =
          std::use_facet<std::collate<char> >(std::cout.getloc());

        // Strings should collate equal.
        std::cout << co.compare (s1.begin (), s1.end (),
                                 s2.begin (), s2.end () - 1)
                  << std::endl;

        // Strings should collate unequal.
        std::cout << co.compare (s1.begin (), s1.end (),
                                 s2.begin (), s2.end ())
                  << std::endl;

        // Retrieve hash values for the two strings.
        std::cout << co.hash (s1.begin (), s1.end ()) << std::endl;
        std::cout << co.hash (s2.begin (), s2.end ()) << std::endl;

        return 0;
    }

    Program Output:

    0
    -1
    431029
    6896579

### See Also

locale, Facets, ctype

### Standards Conformance

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