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