Module: Standard C++ Library Library: Localization
collate_bynamecollate
|
char_type collate() collate_byname() compare() |
do_compare() do_hash() do_transform() hash() |
id string_type transform() ~collate() |
~collate_byname() |
A string collation, comparison, and hashing facet.
#include <locale>
namespace std {
template <class charT> class collate;
template <class charT> class collate_byname;
}
template<> class collate<char>; template<> class collate<wchar_t>; template<> class collate_byname<char>; template<> class collate_byname<wchar_t>;
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 facet for named locales.
namespace std {
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:
virtual ~collate();
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:
virtual ~collate_byname();
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;
};
}
char_type
Type of character the facet is instantiated on.
string_type
Type of character string returned by member functions.
explicit collate(size_t refs = 0)
Constructs a collate object. Calls locale::facet (refs).
The refs argument is set to the initial value of the object's reference count. A collate object f constructed with (refs == 0) that is installed in one or more locale objects will be destroyed and the storage it occupies will be deallocated when the last locale object containing the facet is destroyed, as if by calling delete static_cast<locale::facet*>(&f). A collate object constructed with (refs != 0) will not be destroyed by any locale objects in which it may have been installed.
explicit collate_byname(const char* name, size_t refs = 0);
Constructs a collate_byname object for the locale given by name. Calls collate<char_type>::collate (refs).
virtual ~collate(); virtual ~collate_byname();
Destroys the facet.
static locale::id id;
Unique identifier for this type of facet.
The public members of the collate facet include an interface to protected members. Each public member xxx() calls the corresponding virtual protected member do_xxx(). For instance, the public member function compare() 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 calls the corresponding protected do_xxx() function.
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 the first string is less than the second, or 0 if the two are equal. The specializations, collate<char> and collate<wchar_t>, perform a lexicographical comparison.
As an extension of this implementation, the collate<char> and collate_byname<char> facets recognize and correctly interpret sequences of multi-byte characters.
virtual long do_hash( const charT* low, const charT* high) const;
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()
As an extension of this implementation, the collate<char> and collate_byname<char> facets recognize and correctly interpret sequences of multi-byte characters.
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().
As an extension of this implementation, the collate<char> and collate_byname<char> facets recognize and correctly interpret sequences of multi-byte characters.
//
// collate.cpp
//
#include <iostream> // for cout, endl
#include <locale> // for collate
int main ()
{
std::string s1 ("blue");
std::string s2 ("blues");
// Obtain a reference to the collate facet in
// the default locale imbued in cout.
const std::collate<char>& co =
std::use_facet<std::collate<char> >(std::cout.getloc());
// Strings should collate equal.
std::cout << co.compare (s1.begin (), s1.end (),
s2.begin (), s2.end () - 1)
<< std::endl;
// Strings should collate unequal.
std::cout << co.compare (s1.begin (), s1.end (),
s2.begin (), s2.end ())
<< std::endl;
// Retrieve hash values for the two strings.
std::cout << co.hash (s1.begin (), s1.end ()) << std::endl;
std::cout << co.hash (s2.begin (), s2.end ()) << std::endl;
return 0;
}
Program Output:
0 -1 431029 6896579
ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 22.2.4
Copyright (c) 1994-2006 Rogue Wave Software, a Quovadx Division.
Licensed under the Apache License, Version 2.0.
Contact Rogue Wave about documentation or support issues. You can also seek help from other developers through the Apache stdcxx community (see below).