## collate, collate_byname

    collate_bynamecollatelocale::facet

- Summary
- Data Type and Member Function Indexes
- Synopsis
- Description
- Interface
- Types
- Constructors
- Destructors
- Facet ID
- Public Member Functions
- Protected Member Functions
- Example
- See Also

### Summary

A string collation, comparison, and hashing facet.

### Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Data Types
char_type id string_type

Member Functions
compare() do_compare() do_hash() do_transform() hash() transform() |

### Synopsis

    #include <locale>
    template <class charT> class collate;
    template <class charT> class collate_byname;

### 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 for named locales.

### Interface

    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:
      ~collate();  // virtual
      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:
      ~collate_byname();  // virtual
      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;
    };

### 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)

Construct a collate facet. If the `refs` argument is `0`, destruction of the object is delegated to the locale, or locales, containing it. This allows the user to ignore lifetime management issues. On the other hand, if `refs` is `1`, the object must be explicitly deleted: the locale does not do so.

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

Construct a collate_byname facet. Use the named locale specified by the name argument. The `refs` argument serves the same purpose as it does for the collate constructor.

### Destructors

    ~collate();  // virtual and protected
    ~collate_byname();  // virtual and protected

Destroy 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` has a corresponding virtual protected member `do_xxx`. All work is delegated to these protected members. For instance, the long version of the public `compare` function simply 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 call 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 first string is less than the second, or `0` if the two are equal. The default instantiations, `collate<char>` and `collate<wchar_t>`, perform a lexicographical comparison.

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

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()`

    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.

### Example

    //
    // collate.cpp
    //
    #include <iostream>

    int main ()
    {
      using namespace std;
      locale loc;
      string s1("blue");
      string s2("blues");
      // Get a reference to the collate<char> facet
      const collate<char>& co =
    #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
          use_facet<collate<char> >(loc);
    #else
          use_facet(loc,(collate<char>*)0);
    #endif
      // Compare two strings
      cout << co.compare(s1.begin(),s1.end(),
                         s2.begin(),s2.end()-1) << endl;
      cout << co.compare(s1.begin(),s1.end(),
                         s2.begin(),s2.end()) << endl;
      // Retrieve hash values for two strings
      cout << co.hash(s1.begin(),s1.end()) << endl;
      cout << co.hash(s2.begin(),s2.end()) << endl;
      return 0;
    }

### See Also

locale, facets, ctype

Copyright (c) 1998, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.
OEM Release, June 1998