collate(3C++) - collate(3C++)
Standard C++ Library Copyright 1998, Rogue Wave Software, Inc.
NAME
collate, collate_byname
- A string collation, comparison, and hashing facet.
SYNOPSIS
#include <locale>
template <class charT> class collate;
template <class charT> class collate_byname;
DESCRIPTION
The collate and collate_byname facets allow for string collation, com‐
parison, and hashing. Use the collate facet for the "C" locale, and use
the collate_byname for named locales.
INTERFACE
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:
~collate(); // virtual
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:
~collate_byname(); // virtual
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;
};
TYPES
char_type
Type of character the facet is instantiated on.
string_type
Type of character string returned by member functions.
CONSTRUCTORS
explicit collate(size_t refs = 0)
Construct a collate facet. If the refs argument is 0, 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 refs
is 1, the object must be explicitly deleted: the locale does not do so.
explicit collate_byname(const char* name, size_t refs = 0);
Construct a collate_byname facet. Use the named locale specified by the
name argument. The refs argument serves the same purpose as it does for the
collate constructor.
DESTRUCTORS
~collate(); // virtual and protected
~collate_byname(); // virtual and protected
Destroy the facet.
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PUBLIC MEMBER FUNCTIONS
The public members of the collate facet include an interface to pro‐
tected members. Each public member xxx has a corresponding virtual pro‐
tected member do_xxx. All work is delegated to these protected members.
For instance, the long version of the public compare function simply
calls its protected cousin do_compare.
int
compare(const charT* low1, const charT* high1,
const charT* low2, const charT* high2) const;
longhash(const charT* low, const charT* high) const;
string_typetransform(const charT* low, const charT* high) const;
Each of these public member functions xxx simply call the corresponding
protected do_xxx function.
PROTECTED MEMBER FUNCTIONS
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 first string is less than the second, or 0 if the two are equal. The
default instantiations, collate<char> and collate<wchar_t>, perform a lexi‐
cographical comparison.
virtual longdo_hash( const charT* low, const charT* high)
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_com‐
pare 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()virtual string_typedo_transform(const charT* low, const charT* high) const;
Returns a string that yields the same result in a lexicographical compari‐
son 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 trans‐
form is the same as applying do_compare to the original strings passed to
transform.
EXAMPLE
//
// collate.cpp
//
#include <iostream>
int main ()
{
using namespace std;
locale loc;
string s1("blue");
string s2("blues");
// Get a reference to the collate<char> facet
const collate<char>& co =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<collate<char> >(loc);
#else
use_facet(loc,(collate<char>*)0);
#endif
// Compare two strings
cout << co.compare(s1.begin(),s1.end(),
s2.begin(),s2.end()-1) << endl;
cout << co.compare(s1.begin(),s1.end(),
s2.begin(),s2.end()) << endl;
// Retrieve hash values for two strings
cout << co.hash(s1.begin(),s1.end()) << endl;
cout << co.hash(s2.begin(),s2.end()) << endl;
return 0;
}
SEE ALSO
locale, facets, ctype
Rogue Wave Software 02 Apr 1998 collate(3C++)