25 Localization library [localization]

25.4 Standard locale categories [locale.categories]

25.4.4 The collate category [category.collate]

25.4.4.1 Class template collate [locale.collate]

namespace std {
  template <class charT>
    class collate : public locale::facet {
    public:
      using char_type   = charT;
      using string_type = basic_string<charT>;

      explicit collate(size_t refs = 0);

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

      static locale::id id;

    protected:
      ~collate();
      virtual int do_compare(const charT* low1, const charT* high1,
                             const charT* low2, const charT* high2) const;
      virtual string_type do_transform(const charT* low, const charT* high) const;
      virtual long do_hash (const charT* low, const charT* high) const;
    };
}
1
#
The class collate<charT> provides features for use in the collation (comparison) and hashing of strings.
A locale member function template, operator(), uses the collate facet to allow a locale to act directly as the predicate argument for standard algorithms (Clause [algorithms]) and containers operating on strings.
The specializations required in Table 64 ([locale.category]), namely collate<char> and collate<wchar_­t>, apply lexicographic ordering ([alg.lex.comparison]).
2
#
Each function compares a string of characters *p in the range [low, high).

25.4.4.1.1 collate members [locale.collate.members]

int compare(const charT* low1, const charT* high1, const charT* low2, const charT* high2) const;
1
#
Returns: do_­compare(low1, high1, low2, high2).
string_type transform(const charT* low, const charT* high) const;
2
#
Returns: do_­transform(low, high).
long hash(const charT* low, const charT* high) const;
3
#
Returns: do_­hash(low, high).

25.4.4.1.2 collate virtual functions [locale.collate.virtuals]

int do_compare(const charT* low1, const charT* high1, const charT* low2, const charT* high2) const;
1
#
Returns: 1 if the first string is greater than the second, -1 if less, zero otherwise.
The specializations required in Table 64 ([locale.category]), namely collate<char> and collate<wchar_­t>, implement a lexicographical comparison ([alg.lex.comparison]).
string_type do_transform(const charT* low, const charT* high) const;
2
#
Returns: A basic_­string<charT> value that, compared lexicographically with the result of calling transform() on another string, yields the same result as calling do_­compare() on the same two strings.242
long do_hash(const charT* low, const charT* high) const;
3
#
Returns: An integer value equal to the result of calling hash() on any other string for which do_­compare() returns 0 (equal) when passed the two strings.
[ Note
:
The probability that the result equals that for another string which does not compare equal should be very small, approaching (1.0/numeric_­limits<unsigned long>​::​max()).
— end note
 ]
242)
This function is useful when one string is being compared to many other strings.

25.4.4.2 Class template collate_­byname [locale.collate.byname]

namespace std {
  template <class charT>
    class collate_byname : public collate<charT> {
    public:
      using string_type = basic_string<charT>;

      explicit collate_byname(const char*, size_t refs = 0);
      explicit collate_byname(const string&, size_t refs = 0);
    protected:
      ~collate_byname();
    };
}