2 // Copyright (c) 2009-2011 Artyom Beilis (Tonkikh)
4 // Distributed under the Boost Software License, Version 1.0. (See
5 // accompanying file LICENSE_1_0.txt or copy at
6 // http://www.boost.org/LICENSE_1_0.txt)
8 #ifndef BOOST_LOCALE_COLLATOR_HPP_INCLUDED
9 #define BOOST_LOCALE_COLLATOR_HPP_INCLUDED
11 #include <boost/locale/config.hpp>
13 # pragma warning(push)
14 # pragma warning(disable : 4275 4251 4231 4660)
25 /// \defgroup collation Collation
27 /// This module introduces collation related classes
32 /// \brief a base class that includes collation level flags
38 /// Unicode collation level types
41 primary = 0, ///< 1st collation level: base letters
42 secondary = 1, ///< 2nd collation level: letters and accents
43 tertiary = 2, ///< 3rd collation level: letters, accents and case
44 quaternary = 3, ///< 4th collation level: letters, accents, case and punctuation
45 identical = 4 ///< identical collation level: include code-point comparison
50 /// \brief Collation facet.
52 /// It reimplements standard C++ std::collate,
53 /// allowing usage of std::locale for direct string comparison
55 template<typename CharType>
57 public std::collate<CharType>,
62 /// Type of the underlying character
64 typedef CharType char_type;
66 /// Type of string used with this facet
68 typedef std::basic_string<CharType> string_type;
72 /// Compare two strings in rage [b1,e1), [b2,e2) according using a collation level \a level. Calls do_compare
74 /// Returns -1 if the first of the two strings sorts before the seconds, returns 1 if sorts after and 0 if
75 /// they considered equal.
77 int compare(level_type level,
78 char_type const *b1,char_type const *e1,
79 char_type const *b2,char_type const *e2) const
81 return do_compare(level,b1,e1,b2,e2);
84 /// Create a binary string that can be compared to other in order to get collation order. The string is created
85 /// for text in range [b,e). It is useful for collation of multiple strings for text.
87 /// The transformation follows these rules:
89 /// compare(level,b1,e1,b2,e2) == sign( transform(level,b1,e1).compare(transform(level,b2,e2)) );
92 /// Calls do_transform
94 string_type transform(level_type level,char_type const *b,char_type const *e) const
96 return do_transform(level,b,e);
100 /// Calculate a hash of a text in range [b,e). The value can be used for collation sensitive string comparison.
102 /// If compare(level,b1,e1,b2,e2) == 0 then hash(level,b1,e1) == hash(level,b2,e2)
106 long hash(level_type level,char_type const *b,char_type const *e) const
108 return do_hash(level,b,e);
112 /// Compare two strings \a l and \a r using collation level \a level
114 /// Returns -1 if the first of the two strings sorts before the seconds, returns 1 if sorts after and 0 if
115 /// they considered equal.
118 int compare(level_type level,string_type const &l,string_type const &r) const
120 return do_compare(level,l.data(),l.data()+l.size(),r.data(),r.data()+r.size());
124 /// Calculate a hash that can be used for collation sensitive string comparison of a string \a s
126 /// If compare(level,s1,s2) == 0 then hash(level,s1) == hash(level,s2)
129 long hash(level_type level,string_type const &s) const
131 return do_hash(level,s.data(),s.data()+s.size());
134 /// Create a binary string from string \a s, that can be compared to other, useful for collation of multiple
137 /// The transformation follows these rules:
139 /// compare(level,s1,s2) == sign( transform(level,s1).compare(transform(level,s2)) );
142 string_type transform(level_type level,string_type const &s) const
144 return do_transform(level,s.data(),s.data()+s.size());
150 /// constructor of the collator object
152 collator(size_t refs = 0) : std::collate<CharType>(refs)
161 /// This function is used to override default collation function that does not take in account collation level.
162 /// Uses primary level
164 virtual int do_compare( char_type const *b1,char_type const *e1,
165 char_type const *b2,char_type const *e2) const
167 return do_compare(identical,b1,e1,b2,e2);
170 /// This function is used to override default collation function that does not take in account collation level.
171 /// Uses primary level
173 virtual string_type do_transform(char_type const *b,char_type const *e) const
175 return do_transform(identical,b,e);
178 /// This function is used to override default collation function that does not take in account collation level.
179 /// Uses primary level
181 virtual long do_hash(char_type const *b,char_type const *e) const
183 return do_hash(identical,b,e);
187 /// Actual function that performs comparison between the strings. For details see compare member function. Can be overridden.
189 virtual int do_compare( level_type level,
190 char_type const *b1,char_type const *e1,
191 char_type const *b2,char_type const *e2) const = 0;
193 /// Actual function that performs transformation. For details see transform member function. Can be overridden.
195 virtual string_type do_transform(level_type level,char_type const *b,char_type const *e) const = 0;
197 /// Actual function that calculates hash. For details see hash member function. Can be overridden.
199 virtual long do_hash(level_type level,char_type const *b,char_type const *e) const = 0;
205 /// \brief This class can be used in STL algorithms and containers for comparison of strings
206 /// with a level other than primary
211 /// std::map<std::string,std::string,comparator<char,collator_base::secondary> > data;
214 /// Would create a map the keys of which are sorted using secondary collation level
216 template<typename CharType,collator_base::level_type default_level = collator_base::identical>
221 /// Create a comparator class for locale \a l and with collation leval \a level
223 /// \note throws std::bad_cast if l does not have \ref collator facet installed
225 comparator(std::locale const &l=std::locale(),collator_base::level_type level=default_level) :
232 /// Compare two strings -- equivalent to return left < right according to collation rules
234 bool operator()(std::basic_string<CharType> const &left,std::basic_string<CharType> const &right) const
236 return std::use_facet<collator<CharType> >(locale_).compare(level_,left,right) < 0;
240 collator_base::level_type level_;
258 /// \example collate.cpp
259 /// Example of using collation functions
261 // vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4