boost/locale/collator.hpp

0001 //
0002 // Copyright (c) 2009-2011 Artyom Beilis (Tonkikh)
0003 //
0004 // Distributed under the Boost Software License, Version 1.0.
0005 // https://www.boost.org/LICENSE_1_0.txt
0006
0007 #ifndef BOOST_LOCALE_COLLATOR_HPP_INCLUDED
0008 #define BOOST_LOCALE_COLLATOR_HPP_INCLUDED
0009
0010 #include <boost/locale/config.hpp>
0011 #include <boost/locale/detail/facet_id.hpp>
0012 #include <locale>
0013
0014 #ifdef BOOST_MSVC
0015 #    pragma warning(push)
0016 #    pragma warning(disable : 4275 4251 4231 4660)
0017 #endif
0018
0019 namespace boost { namespace locale {
0020
0021     /// \defgroup collation Collation
0022     ///
0023     /// This module introduces collation related classes
0024     /// @{
0025
0026     /// Unicode collation level types
0027     enum class collate_level {
0028         primary = 0,    ///< 1st collation level: base letters
0029         secondary = 1,  ///< 2nd collation level: letters and accents
0030         tertiary = 2,   ///< 3rd collation level: letters, accents and case
0031         quaternary = 3, ///< 4th collation level: letters, accents, case and punctuation
0032         identical = 4   ///< identical collation level: include code-point comparison
0033     };
0034
0035     class BOOST_DEPRECATED("Use collate_level") collator_base {
0036     public:
0037         using level_type = collate_level;
0038         static constexpr auto primary = collate_level::primary;
0039         static constexpr auto secondary = collate_level::secondary;
0040         static constexpr auto tertiary = collate_level::tertiary;
0041         static constexpr auto quaternary = collate_level::quaternary;
0042         static constexpr auto identical = collate_level::identical;
0043     };
0044
0045     /// \brief Collation facet.
0046     ///
0047     /// It reimplements standard C++ std::collate with support for collation levels
0048     template<typename CharType>
0049     class BOOST_SYMBOL_VISIBLE collator : public std::locale::facet, public detail::facet_id<collator<CharType>> {
0050     public:
0051         /// Type of the underlying character
0052         typedef CharType char_type;
0053         /// Type of string used with this facet
0054         typedef std::basic_string<CharType> string_type;
0055
0056         /// Compare two strings in range [b1,e1),  [b2,e2) according to collation level \a level. Calls do_compare
0057         ///
0058         /// Returns -1 if the first of the two strings sorts before the seconds, returns 1 if sorts after and 0 if
0059         /// they considered equal.
0060         int compare(collate_level level,
0061                     const char_type* b1,
0062                     const char_type* e1,
0063                     const char_type* b2,
0064                     const char_type* e2) const
0065         {
0066             return do_compare(level, b1, e1, b2, e2);
0067         }
0068
0069         /// Default compare function as-in std::collate that does not take collation level into account.
0070         /// Uses identical level
0071         int compare(const char_type* b1, const char_type* e1, const char_type* b2, const char_type* e2) const
0072         {
0073             return compare(collate_level::identical, b1, e1, b2, e2);
0074         }
0075
0076         /// Create a binary string that can be compared to other in order to get collation order. The string is created
0077         /// for text in range [b,e). It is useful for collation of multiple strings for text.
0078         ///
0079         /// The transformation follows these rules:
0080         /// \code
0081         ///   compare(level,b1,e1,b2,e2) == sign( transform(level,b1,e1).compare(transform(level,b2,e2)) );
0082         /// \endcode
0083         ///
0084         /// Calls do_transform
0085         string_type transform(collate_level level, const char_type* b, const char_type* e) const
0086         {
0087             return do_transform(level, b, e);
0088         }
0089
0090         /// Default transform function as-in std::collate that does not take collation level into account.
0091         /// Uses identical level
0092         string_type transform(const char_type* b, const char_type* e) const
0093         {
0094             return transform(collate_level::identical, b, e);
0095         }
0096
0097         /// Calculate a hash of a text in range [b,e). The value can be used for collation sensitive string comparison.
0098         ///
0099         /// If compare(level,b1,e1,b2,e2) == 0 then hash(level,b1,e1) == hash(level,b2,e2)
0100         ///
0101         /// Calls do_hash
0102         long hash(collate_level level, const char_type* b, const char_type* e) const { return do_hash(level, b, e); }
0103
0104         /// Default hash function as-in std::collate that does not take collation level into account.
0105         /// Uses identical level
0106         long hash(const char_type* b, const char_type* e) const { return hash(collate_level::identical, b, e); }
0107
0108         /// Compare two strings \a l and \a r using collation level \a level
0109         ///
0110         /// Returns -1 if the first of the two strings sorts before the seconds, returns 1 if sorts after and 0 if
0111         /// they considered equal.
0112         int compare(collate_level level, const string_type& l, const string_type& r) const
0113         {
0114             return do_compare(level, l.data(), l.data() + l.size(), r.data(), r.data() + r.size());
0115         }
0116
0117         /// Calculate a hash that can be used for collation sensitive string comparison of a string \a s
0118         ///
0119         /// If compare(level,s1,s2) == 0 then hash(level,s1) == hash(level,s2)
0120         long hash(collate_level level, const string_type& s) const
0121         {
0122             return do_hash(level, s.data(), s.data() + s.size());
0123         }
0124
0125         /// Create a binary string from string \a s, that can be compared to other, useful for collation of multiple
0126         /// strings.
0127         ///
0128         /// The transformation follows this rule:
0129         /// \code
0130         ///   compare(level,s1,s2) == sign( transform(level,s1).compare(transform(level,s2)) );
0131         /// \endcode
0132         string_type transform(collate_level level, const string_type& s) const
0133         {
0134             return do_transform(level, s.data(), s.data() + s.size());
0135         }
0136
0137     protected:
0138         /// constructor of the collator object
0139         collator(size_t refs = 0) : std::locale::facet(refs) {}
0140
0141         /// Actual function that performs comparison between the strings. For details see compare member function. Can
0142         /// be overridden.
0143         virtual int do_compare(collate_level level,
0144                                const char_type* b1,
0145                                const char_type* e1,
0146                                const char_type* b2,
0147                                const char_type* e2) const = 0;
0148
0149         /// Actual function that performs transformation. For details see transform member function. Can be overridden.
0150         virtual string_type do_transform(collate_level level, const char_type* b, const char_type* e) const = 0;
0151         /// Actual function that calculates hash. For details see hash member function. Can be overridden.
0152         virtual long do_hash(collate_level level, const char_type* b, const char_type* e) const = 0;
0153     };
0154
0155     /// \brief This class can be used in STL algorithms and containers for comparison of strings
0156     /// with a level other than identical
0157     ///
0158     /// For example:
0159     ///
0160     /// \code
0161     ///  std::map<std::string,std::string,comparator<char,collate_level::secondary> > data;
0162     /// \endcode
0163     ///
0164     /// Would create a map the keys of which are sorted using secondary collation level
0165     template<typename CharType, collate_level default_level = collate_level::identical>
0166     struct comparator {
0167     public:
0168         /// Create a comparator class for locale \a l and with collation level \a level
0169         ///
0170         /// \throws std::bad_cast: \a l does not have \ref collator facet installed
0171         comparator(const std::locale& l = std::locale(), collate_level level = default_level) :
0172             locale_(l), collator_(std::use_facet<collator<CharType>>(locale_)), level_(level)
0173         {}
0174
0175         /// Compare two strings -- equivalent to return left < right according to collation rules
0176         bool operator()(const std::basic_string<CharType>& left, const std::basic_string<CharType>& right) const
0177         {
0178             return collator_.compare(level_, left, right) < 0;
0179         }
0180
0181     private:
0182         std::locale locale_;
0183         const collator<CharType>& collator_;
0184         collate_level level_;
0185     };
0186
0187     ///@}
0188 }} // namespace boost::locale
0189
0190 #ifdef BOOST_MSVC
0191 #    pragma warning(pop)
0192 #endif
0193
0194 ///
0195 /// \example collate.cpp
0196 /// Example of using collation functions
0197 ///
0198
0199 #endif