[category.collate]

# 28 Text processing library [[text]](./#text)

## 28.3 Localization library [[localization]](localization#category.collate)

### 28.3.4 Standard locale categories [[locale.categories]](locale.categories#category.collate)

#### 28.3.4.5 The collate category [category.collate]

#### [28.3.4.5.1](#locale.collate) Class template collate [[locale.collate]](locale.collate)

#### [28.3.4.5.1.1](#locale.collate.general) General [[locale.collate.general]](locale.collate.general)

[🔗](#lib: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](#locale.collate.general-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3381)

The class collate<charT> provides features
for use in the collation (comparison) and hashing of strings[.](#locale.collate.general-1.sentence-1)

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]](algorithms "26 Algorithms library")) and
containers operating on strings[.](#locale.collate.general-1.sentence-2)

The specializations
required in Table [91](locale.category#tab:locale.category.facets "Table 91: Locale category facets") ([[locale.category]](locale.category "28.3.3.1.2.1 Type locale​::​category")),
namely collate<char> and collate<wchar_t>,
apply lexicographical ordering ([[alg.lex.comparison]](alg.lex.comparison "26.8.11 Lexicographical comparison"))[.](#locale.collate.general-1.sentence-3)

[2](#locale.collate.general-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3393)

Each function compares a string of characters *p in the range [low, high)[.](#locale.collate.general-2.sentence-1)

#### [28.3.4.5.1.2](#locale.collate.members) Members [[locale.collate.members]](locale.collate.members)

[🔗](#lib:collate,compare)

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

[1](#locale.collate.members-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3406)

*Returns*: do_compare(low1, high1, low2, high2)[.](#locale.collate.members-1.sentence-1)

[🔗](#lib:collate,transform)

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

[2](#locale.collate.members-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3417)

*Returns*: do_transform(low, high)[.](#locale.collate.members-2.sentence-1)

[🔗](#lib:collate,hash)

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

[3](#locale.collate.members-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3428)

*Returns*: do_hash(low, high)[.](#locale.collate.members-3.sentence-1)

#### [28.3.4.5.1.3](#locale.collate.virtuals) Virtual functions [[locale.collate.virtuals]](locale.collate.virtuals)

[🔗](#lib:collate,do_compare)

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

[1](#locale.collate.virtuals-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3442)

*Returns*: 1 if the first string is greater than the second,-1 if less,
zero otherwise[.](#locale.collate.virtuals-1.sentence-1)

The specializations
required in Table [91](locale.category#tab:locale.category.facets "Table 91: Locale category facets") ([[locale.category]](locale.category "28.3.3.1.2.1 Type locale​::​category")),
namely collate<char> and collate<wchar_t>,
implement a lexicographical comparison ([[alg.lex.comparison]](alg.lex.comparison "26.8.11 Lexicographical comparison"))[.](#locale.collate.virtuals-1.sentence-2)

[🔗](#lib:collate,do_transform)

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

[2](#locale.collate.virtuals-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3459)

*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[.](#locale.collate.virtuals-2.sentence-1)[226](#footnote-226 "This function is useful when one string is being compared to many other strings.")

[🔗](#lib:collate,do_hash)

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

[3](#locale.collate.virtuals-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3476)

*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[.](#locale.collate.virtuals-3.sentence-1)

[4](#locale.collate.virtuals-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3482)

*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())[.](#locale.collate.virtuals-4.sentence-1)

[226)](#footnote-226)[226)](#footnoteref-226)

This function is useful when one string is being compared to many other strings[.](#footnote-226.sentence-1)

#### [28.3.4.5.2](#locale.collate.byname) Class template collate_byname [[locale.collate.byname]](locale.collate.byname)

[🔗](#lib: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(); };}