.\" ident @(#)collate.3 .\" Standard Template Library .\" $$RW_INSERT_HEADER "slyrs.man" .TH collate 3C++ "02 Apr 1998" "Rogue Wave Software" "-" .ce2 Standard C++ Library Copyright 1998, Rogue Wave Software, Inc. .SH NAME \f2collate\fP, \f2collate_byname\fP \ - A string collation, comparison, and hashing facet. .SH SYNOPSIS .br #include .br template class collate; .br template class collate_byname; .SH 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. .SH INTERFACE .br template .br class collate : public locale::facet { .br public: .RE .RS 1 typedef charT char_type; .br typedef basic_string string_type; .br explicit collate(size_t refs = 0); .br int compare(const charT*, const charT*, .RE .RS 13 const charT*, const charT*) const; .RE .RS 1 string_type transform(const charT*, const charT*) const; .br long hash(const charT*, const charT*) const; .br static locale::id id; .RE .RS 0 protected: .RE .RS 2 ~collate(); // virtual .RE .RS 1 virtual int do_compare(const charT*, const charT*, .RE .RS 24 const charT*, const charT*) const; .RE .RS 1 virtual string_type do_transform(const charT*, .RE .RS 29 const charT*) const; .RE .RS 1 virtual long do_hash (const charT*, const charT*) const; .RE .RS 0 }; .br .br template .br class collate_byname : public collate { .br public: .RE .RS 1 typedef basic_string string_type; .br explicit collate_byname(const char*, size_t = 0); .RE .RS 0 protected: .RE .RS 2 ~collate_byname(); // virtual .RE .RS 1 virtual int do_compare(const charT*, const charT*, .RE .RS 24 const charT*, const charT*) const; .RE .RS 1 virtual string_type do_transform(const charT*, .RE .RS 29 const charT*) const; .RE .RS 1 virtual long do_hash(const charT*, const charT*) const; .RE .RS 0 }; .SH TYPES .br char_type .RE .RS 3 Type of character the facet is instantiated on. .RE .br string_type .RE .RS 3 Type of character string returned by member functions. .RE .SH CONSTRUCTORS .br explicit collate(size_t refs = 0) .RE .RS 3 Construct a collate facet. If the \f2refs\fP argument is \f20\fP, 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 \f2refs\fP is \f21\fP, the object must be explicitly deleted: the locale does not do so. .RE .br explicit collate_byname(const char* name, size_t refs = 0); .RE .RS 3 Construct a collate_byname facet. Use the named locale specified by the name argument. The \f2refs\fP argument serves the same purpose as it does for the collate constructor. .RE .SH DESTRUCTORS .br ~collate(); // virtual and protected .br ~collate_byname(); // virtual and protected .RE .RS 3 Destroy the facet. .RE .SH FACET ID .br static locale::id id; .RE .RS 3 Unique identifier for this type of facet. .RE .SH PUBLIC MEMBER FUNCTIONS The public members of the collate facet include an interface to protected members. Each public member \f2xxx\fP has a corresponding virtual protected member \f2do_xxx\fP. All work is delegated to these protected members. For instance, the long version of the public \f2compare\fP function simply calls its protected cousin \f2do_compare\fP. .br int .br compare(const charT* low1, const charT* high1, .RE .RS 7 const charT* low2, const charT* high2) const; .RE .RS 0 long .br hash(const charT* low, const charT* high) const; .br string_type .br transform(const charT* low, const charT* high) const; .RE .RS 3 Each of these public member functions \f2xxx\fP simply call the corresponding protected \f2do_xxx\fP function. .RE .SH PROTECTED MEMBER FUNCTIONS .br virtual int .br do_compare(const charT* low1, const charT* high1, .RE .RS 10 const charT* low2, const charT* high2) const; .RE .RS 3 Returns \f21\fP if the character string represented by the range\f2 [low1,high1)\fP is greater than the character string represented by the range\f2 [low2,high2)\fP, \f2-1\fP if first string is less than the second, or \f20\fP if the two are equal. The default instantiations, \f2collate\fP and \f2collate\fP, perform a lexicographical comparison. .RE .RE .RS 0 virtual long .br do_hash( const charT* low, const charT* high) .RE .RS 3 Generates a hash value from a string defined by the range of characters \f2[low,high)\fP. Given two strings that compare equal (in other words, \f2do_compare\fP returns \f20\fP), \f2do_hash\fP returns an integer value that is the same for both strings. For differing strings the probability that the return value is equal is approximately: \f21.0/numeric_limits::max()\fP .RE .br virtual string_type .br do_transform(const charT* low, const charT* high) const; .RE .RS 3 Returns a string that yields the same result in a lexicographical comparison with another string returned from transform as does the \f2do_compare\fP function applied to the original strings. In other words, the result of applying a lexicographical comparison to two strings returned from \f2transform\fP is the same as applying \f2do_compare\fP to the original strings passed to transform. .RE .SH EXAMPLE .br // .br // collate.cpp .br // .br #include .br .br int main () .br { .RE .RS 1 using namespace std; .br locale loc; .br string s1("blue"); .br string s2("blues"); .RE .RS 2 // Get a reference to the collate facet .RE .RS 1 const collate& co = .RE .RS 0 #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE .RE .RS 5 use_facet >(loc); .RE .RS 0 #else .RE .RS 5 use_facet(loc,(collate*)0); .RE .RS 0 #endif .RE .RS 2 // Compare two strings .RE .RS 1 cout << co.compare(s1.begin(),s1.end(), .RE .RS 20 s2.begin(),s2.end()-1) << endl; .RE .RS 1 cout << co.compare(s1.begin(),s1.end(), .RE .RS 20 s2.begin(),s2.end()) << endl; .RE .RS 2 // Retrieve hash values for two strings .RE .RS 1 cout << co.hash(s1.begin(),s1.end()) << endl; .br cout << co.hash(s2.begin(),s2.end()) << endl; .br return 0; .RE .RS 0 } .SH SEE ALSO locale, facets, ctype