collate Class
The latest version of this topic can be found at collate Class.
A template class that describes an object that can serve as a locale facet to control the ordering and grouping of characters within a string, comparisons between them and the hashing of strings.
Syntax
template <class CharType>
class collate : public locale::facet;
Parameters
CharType
The type used within a program to encode characters.
Remarks
As with any locale facet, the static object ID has an initial stored value of zero. The first attempt to access its stored value stores a unique positive value in id. In some languages, characters are grouped and treated as a single character, and in others, individual characters are treated as if they were two characters. The collating services provided by the collate class provide the way to sort these cases.
Constructors
| collate | The constructor for objects of class collate that serves as a locale facet to handle string sorting conventions. |
Typedefs
| char_type | A type that describes a character of type CharType. |
| string_type | A type that describes a string of type basic_string containing characters of type CharType. |
Member Functions
| compare | Compares two character sequences according to their facet-specific rules for equality or inequality. |
| do_compare | A virtual function called to compare two character sequences according to their facet-specific rules for equality or inequality. |
| do_hash | A virtual function called to determine the hash value of sequences according to their facet-specific rules. |
| do_transform | A virtual function called to convert a character sequence from a locale to a string that may be used in lexicographical comparisons with other character sequences similarly converted from the same locale. |
| hash | Determines the hash value of sequence according to their facet-specific rules. |
| transform | Converts a character sequence from a locale to a string that may be used in lexicographical comparisons with other character sequences similarly converted from the same locale. |
Requirements
Header: <locale>
Namespace: std
collate::char_type
A type that describes a character of type CharType.
typedef CharType char_type;
Remarks
The type is a synonym for the template parameter CharType.
collate::collate
The constructor for objects of class collate that serves as a locale facet to handle string sorting conventions.
public:
explicit collate(
size_t_Refs = 0);
protected:
collate(
const char* _Locname,
size_t _Refs = 0);
Parameters
_Refs
Integer value used to specify the type of memory management for the object.
_Locname
The name of the locale.
Remarks
The possible values for the _Refs parameter and their significance are:
0: The lifetime of the object is managed by the locales that contain it.
1: The lifetime of the object must be manually managed.
> 0: These values are not defined.
The constructor initializes its base object with locale::facet( _Refs).
collate::compare
Compares two character sequences according to their facet-specific rules for equality or inequality.
int compare(const CharType* first1,
const CharType* last1,
const CharType* first2,
const CharType* last2) const;
Parameters
first1
Pointer to the first element in the first sequence to be compared.
last1
Pointer to the last element in the first sequence to be compared.
first2
Pointer to the first element in the second sequence to be compared.
last2
Pointer to the last element in the second sequence to be compared.
Return Value
The member function returns:
–1 if the first sequence compares less than the second sequence.
+1 if the second sequence compares less than the first sequence.
0 if the sequences are equivalent.
Remarks
The first sequence compares less if it has the smaller element in the earliest unequal pair in the sequences, or, if no unequal pairs exist, but the first sequence is shorter.
The member function returns do_compare( first1, last1, first2, last2).
Example
// collate_compare.cpp
// compile with: /EHsc
#include <locale>
#include <iostream>
#include <tchar.h>
using namespace std;
int main() {
locale loc ( "German_germany" );
_TCHAR * s1 = _T("Das ist wei\x00dfzz."); // \x00df is the German sharp-s, it comes before z in the German alphabet
_TCHAR * s2 = _T("Das ist weizzz.");
int result1 = use_facet<collate<_TCHAR> > ( loc ).
compare ( s1, &s1[_tcslen( s1 )-1 ], s2, &s2[_tcslen( s2 )-1 ] );
cout << result1 << endl;
locale loc2 ( "C" );
int result2 = use_facet<collate<_TCHAR> > ( loc2 ).
compare (s1, &s1[_tcslen( s1 )-1 ], s2, &s2[_tcslen( s2 )-1 ] );
cout << result2 << endl;
}
collate::do_compare
A virtual function called to compare two character sequences according to their facet-specific rules for equality or inequality.
virtual int do_compare(const CharType* first1,
const CharType* last1,
const CharType* first2,
const CharType* last2) const;
Parameters
first1
Pointer to the first element in the first sequence to be compared.
last1
Pointer to the last element in the first sequence to be compared.
first2
Pointer to the first element in the second sequence to be compared.
last2
Pointer to the last element in the second sequence to be compared.
Return Value
The member function returns:
-1 if the first sequence compares less than the second sequence.
+1 if the second sequence compares less than the first sequence.
0 if the sequences are equivalent.
Remarks
The protected virtual member function compares the sequence at [ * first1, Last1)* with the sequence at [ first2, last2). It compares values by applying operator< between pairs of corresponding elements of type CharType. The first sequence compares less if it has the smaller element in the earliest unequal pair in the sequences or if no unequal pairs exist but the first sequence is shorter.
Example
See the example for collate::compare, which calls do_compare.
collate::do_hash
A virtual function called to determine the hash value of sequences according to their facet-specific rules.
virtual long do_hash(const CharType* first, const CharType* last) const;
Parameters
first
A pointer to the first character in the sequence whose has value is to be determined.
last
A pointer to the last character in the sequence whose has value is to be determined.
Return Value
A hash value of type long for the sequence.
Remarks
A hash value can be useful, for example, in distributing sequences pseudo-randomly across an array of lists.
Example
See the example for hash, which calls do_hash.
collate::do_transform
A virtual function called to convert a character sequence from a locale to a string that may be used in lexicographical comparisons with other character sequences similarly converted from the same locale.
virtual string_type do_transform(const CharType* first, const CharType* last) const;
Parameters
first
A pointer to the first character in the sequence to be converted.
last
A pointer to the last character in the sequence to be converted.
Return Value
A string that is the transformed character sequence.
Remarks
The protected virtual member function returns an object of class string_type whose controlled sequence is a copy of the sequence [ first, last). If a class derived from collate< CharType> overrides do_compare, it should also override do_transform to match. When passed to collate::compare, two transformed strings should yield the same result that you would get from passing the untransformed strings to compare in the derived class.
Example
See the example for transform, which calls do_transform.
collate::hash
Determines the hash value of sequence according to their facet-specific rules.
long hash(const CharType* first, const CharType* last) const;
Parameters
first
A pointer to the first character in the sequence whose has value is to be determined.
last
A pointer to the last character in the sequence whose has value is to be determined.
Return Value
A hash value of type long for the sequence.
Remarks
The member function returns do_hash( first, last).
A hash value can be useful, for example, in distributing sequences pseudo-randomly across an array of lists.
Example
// collate_hash.cpp
// compile with: /EHsc
#include <locale>
#include <iostream>
#include <tchar.h>
using namespace std;
int main( )
{
locale loc ( "German_germany" );
_TCHAR * s1 = _T("\x00dfzz abc."); // \x00df is the German sharp-s (looks like beta), it comes before z in the alphabet
_TCHAR * s2 = _T("zzz abc."); // \x00df is the German sharp-s (looks like beta), it comes before z in the alphabet
long r1 = use_facet< collate<_TCHAR> > ( loc ).
hash (s1, &s1[_tcslen( s1 )-1 ]);
long r2 = use_facet< collate<_TCHAR> > ( loc ).
hash (s2, &s2[_tcslen( s2 )-1 ] );
cout << r1 << " " << r2 << endl;
}
541187293 551279837
collate::string_type
A type that describes a string of type basic_string containing characters of type CharType.
typedef basic_string<CharType> string_type;
Remarks
The type describes a specialization of template class basic_string whose objects can store copies of the source sequence.
Example
For an example of how to declare and use string_type, see transform.
collate::transform
Converts a character sequence from a locale to a string that may be used in lexicographical comparisons with other character sequences similarly converted from the same locale.
string_type transform(const CharType* first, const CharType* last) const;
Parameters
first
A pointer to the first character in the sequence to be converted.
last
A pointer to the last character in the sequence to be converted.
Return Value
A string that contains the transformed character sequence.
Remarks
The member function returns do_transform( first, last).
Example
// collate_transform.cpp
// compile with: /EHsc
#include <locale>
#include <iostream>
#include <tchar.h>
using namespace std;
int main( )
{
locale loc ( "German_Germany" );
_TCHAR* s1 = _T("\x00dfzz abc.");
// \x00df is the German sharp-s (looks like beta),
// it comes before z in the alphabet
_TCHAR* s2 = _T("zzz abc.");
collate<_TCHAR>::string_type r1; // OK for typedef
r1 = use_facet< collate<_TCHAR> > ( loc ).
transform (s1, &s1[_tcslen( s1 )-1 ]);
cout << r1 << endl;
basic_string<_TCHAR> r2 = use_facet< collate<_TCHAR> > ( loc ).
transform (s2, &s2[_tcslen( s2 )-1 ]);
cout << r2 << endl;
int result1 = use_facet<collate<_TCHAR> > ( loc ).compare
(s1, &s1[_tcslen( s1 )-1 ], s2, &s2[_tcslen( s2 )-1 ] );
cout << _tcscmp(r1.c_str( ),r2.c_str( )) << result1
<< _tcscmp(s1,s2) <<endl;
}
-1-11