[category.collate] (original) (raw)

28.3.4.5.1.1 General [locale.collate.general]

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;};}

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 ([algorithms]) and containers operating on strings.

The specializations required in Table 89 ([locale.category]), namely collate<char> and collate<wchar_t>, apply lexicographical ordering ([alg.lex.comparison]).

Each function compares a string of characters *pin the range [low, high).

28.3.4.5.1.2 Members [locale.collate.members]

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

Returns: do_compare(low1, high1, low2, high2).

string_type transform(const charT* low, const charT* high) const;

Returns: do_transform(low, high).

long hash(const charT* low, const charT* high) const;

Returns: do_hash(low, high).

28.3.4.5.1.3 Virtual functions [locale.collate.virtuals]

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

Returns: 1 if the first string is greater than the second,-1 if less, zero otherwise.

The specializations required in Table 89 ([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;

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.227

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

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.

Recommended practice: 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()).