boost/locale/conversion.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_CONVERTER_HPP_INCLUDED
0008 #define BOOST_LOCALE_CONVERTER_HPP_INCLUDED
0009
0010 #include <boost/locale/detail/facet_id.hpp>
0011 #include <boost/locale/detail/is_supported_char.hpp>
0012 #include <boost/locale/util/string.hpp>
0013 #include <locale>
0014
0015 #ifdef BOOST_MSVC
0016 #    pragma warning(push)
0017 #    pragma warning(disable : 4275 4251 4231 4660)
0018 #endif
0019
0020 namespace boost { namespace locale {
0021
0022     /// \defgroup convert Text Conversions
0023     ///
0024     ///  This module provides various function for string manipulation like Unicode normalization, case conversion etc.
0025     /// @{
0026
0027     /// \brief This class provides base flags for text manipulation. It is used as base for converter facet.
0028     class converter_base {
0029     public:
0030         /// The flag used for facet - the type of operation to perform
0031         enum conversion_type {
0032             normalization, ///< Apply Unicode normalization on the text
0033             upper_case,    ///< Convert text to upper case
0034             lower_case,    ///< Convert text to lower case
0035             case_folding,  ///< Fold case in the text
0036             title_case     ///< Convert text to title case
0037         };
0038     };
0039
0040     /// \brief The facet that implements text manipulation
0041     ///
0042     /// It is used to perform text conversion operations defined by \ref converter_base::conversion_type.
0043     /// It is implemented for supported character types, at least \c char, \c wchar_t
0044     template<typename Char>
0045     class BOOST_SYMBOL_VISIBLE converter : public converter_base,
0046                                            public std::locale::facet,
0047                                            public detail::facet_id<converter<Char>> {
0048         BOOST_LOCALE_ASSERT_IS_SUPPORTED(Char);
0049
0050     public:
0051         /// Standard constructor
0052         converter(size_t refs = 0) : std::locale::facet(refs) {}
0053         /// Convert text in range [\a begin, \a end) according to conversion method \a how. Parameter
0054         /// \a flags is used for specification of normalization method like nfd, nfc etc.
0055         virtual std::basic_string<Char>
0056         convert(conversion_type how, const Char* begin, const Char* end, int flags = 0) const = 0;
0057     };
0058
0059     /// The type that defined <a href="http://unicode.org/reports/tr15/#Norm_Forms">normalization form</a>
0060     enum norm_type {
0061         norm_nfd,                ///< Canonical decomposition
0062         norm_nfc,                ///< Canonical decomposition followed by canonical composition
0063         norm_nfkd,               ///< Compatibility decomposition
0064         norm_nfkc,               ///< Compatibility decomposition followed by canonical composition.
0065         norm_default = norm_nfc, ///< Default normalization - canonical decomposition followed by canonical composition
0066     };
0067
0068     /// Normalize Unicode string in range [begin,end) according to \ref norm_type "normalization form" \a n
0069     ///
0070     /// Note: This function receives only Unicode strings, i.e.: UTF-8, UTF-16 or UTF-32. It does not take
0071     /// in account the locale encoding, because Unicode decomposition and composition are meaningless outside
0072     /// of a Unicode character set.
0073     ///
0074     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0075     template<typename CharType>
0076     std::basic_string<CharType> normalize(const CharType* begin,
0077                                           const CharType* end,
0078                                           norm_type n = norm_default,
0079                                           const std::locale& loc = std::locale())
0080     {
0081         return std::use_facet<converter<CharType>>(loc).convert(converter_base::normalization, begin, end, n);
0082     }
0083
0084     /// Normalize Unicode string \a str according to \ref norm_type "normalization form" \a n
0085     ///
0086     /// Note: This function receives only Unicode strings, i.e.: UTF-8, UTF-16 or UTF-32. It does not take
0087     /// in account the locale encoding, because Unicode decomposition and composition are meaningless outside
0088     /// of a Unicode character set.
0089     ///
0090     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0091     template<typename CharType>
0092     std::basic_string<CharType> normalize(const std::basic_string<CharType>& str,
0093                                           norm_type n = norm_default,
0094                                           const std::locale& loc = std::locale())
0095     {
0096         return normalize(str.data(), str.data() + str.size(), n, loc);
0097     }
0098
0099     /// Normalize NULL terminated Unicode string \a str according to \ref norm_type "normalization form" \a n
0100     ///
0101     /// Note: This function receives only Unicode strings, i.e.: UTF-8, UTF-16 or UTF-32. It does not take
0102     /// in account the locale encoding, because Unicode decomposition and composition are meaningless outside
0103     /// of a Unicode character set.
0104     ///
0105     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0106     template<typename CharType>
0107     std::basic_string<CharType>
0108     normalize(const CharType* str, norm_type n = norm_default, const std::locale& loc = std::locale())
0109     {
0110         return normalize(str, util::str_end(str), n, loc);
0111     }
0112
0113     ///////////////////////////////////////////////////
0114
0115     /// Convert a string in range [begin,end) to upper case according to locale \a loc
0116     ///
0117     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0118     template<typename CharType>
0119     std::basic_string<CharType>
0120     to_upper(const CharType* begin, const CharType* end, const std::locale& loc = std::locale())
0121     {
0122         return std::use_facet<converter<CharType>>(loc).convert(converter_base::upper_case, begin, end);
0123     }
0124
0125     /// Convert a string \a str to upper case according to locale \a loc
0126     ///
0127     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0128     template<typename CharType>
0129     std::basic_string<CharType> to_upper(const std::basic_string<CharType>& str, const std::locale& loc = std::locale())
0130     {
0131         return to_upper(str.data(), str.data() + str.size(), loc);
0132     }
0133
0134     /// Convert a NULL terminated string \a str to upper case according to locale \a loc
0135     ///
0136     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0137     template<typename CharType>
0138     std::basic_string<CharType> to_upper(const CharType* str, const std::locale& loc = std::locale())
0139     {
0140         return to_upper(str, util::str_end(str), loc);
0141     }
0142
0143     ///////////////////////////////////////////////////
0144
0145     /// Convert a string in range [begin,end) to lower case according to locale \a loc
0146     ///
0147     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0148     template<typename CharType>
0149     std::basic_string<CharType>
0150     to_lower(const CharType* begin, const CharType* end, const std::locale& loc = std::locale())
0151     {
0152         return std::use_facet<converter<CharType>>(loc).convert(converter_base::lower_case, begin, end);
0153     }
0154
0155     /// Convert a string \a str to lower case according to locale \a loc
0156     ///
0157     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0158     template<typename CharType>
0159     std::basic_string<CharType> to_lower(const std::basic_string<CharType>& str, const std::locale& loc = std::locale())
0160     {
0161         return to_lower(str.data(), str.data() + str.size(), loc);
0162     }
0163
0164     /// Convert a NULL terminated string \a str to lower case according to locale \a loc
0165     ///
0166     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0167     template<typename CharType>
0168     std::basic_string<CharType> to_lower(const CharType* str, const std::locale& loc = std::locale())
0169     {
0170         return to_lower(str, util::str_end(str), loc);
0171     }
0172
0173     ///////////////////////////////////////////////////
0174
0175     /// Convert a string in range [begin,end) to title case according to locale \a loc
0176     ///
0177     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0178     template<typename CharType>
0179     std::basic_string<CharType>
0180     to_title(const CharType* begin, const CharType* end, const std::locale& loc = std::locale())
0181     {
0182         return std::use_facet<converter<CharType>>(loc).convert(converter_base::title_case, begin, end);
0183     }
0184
0185     /// Convert a string \a str to title case according to locale \a loc
0186     ///
0187     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0188     template<typename CharType>
0189     std::basic_string<CharType> to_title(const std::basic_string<CharType>& str, const std::locale& loc = std::locale())
0190     {
0191         return to_title(str.data(), str.data() + str.size(), loc);
0192     }
0193
0194     /// Convert a NULL terminated string \a str to title case according to locale \a loc
0195     ///
0196     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0197     template<typename CharType>
0198     std::basic_string<CharType> to_title(const CharType* str, const std::locale& loc = std::locale())
0199     {
0200         return to_title(str, util::str_end(str), loc);
0201     }
0202
0203     ///////////////////////////////////////////////////
0204
0205     /// Fold case of a string in range [begin,end) according to locale \a loc
0206     ///
0207     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0208     template<typename CharType>
0209     std::basic_string<CharType>
0210     fold_case(const CharType* begin, const CharType* end, const std::locale& loc = std::locale())
0211     {
0212         return std::use_facet<converter<CharType>>(loc).convert(converter_base::case_folding, begin, end);
0213     }
0214
0215     /// Fold case of a string \a str according to locale \a loc
0216     ///
0217     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0218     template<typename CharType>
0219     std::basic_string<CharType> fold_case(const std::basic_string<CharType>& str,
0220                                           const std::locale& loc = std::locale())
0221     {
0222         return fold_case(str.data(), str.data() + str.size(), loc);
0223     }
0224
0225     /// Fold case of a NULL terminated string \a str according to locale \a loc
0226     ///
0227     /// \throws std::bad_cast: \a loc does not have \ref converter facet installed
0228     template<typename CharType>
0229     std::basic_string<CharType> fold_case(const CharType* str, const std::locale& loc = std::locale())
0230     {
0231         return fold_case(str, util::str_end(str), loc);
0232     }
0233
0234     ///@}
0235 }} // namespace boost::locale
0236
0237 #ifdef BOOST_MSVC
0238 #    pragma warning(pop)
0239 #endif
0240
0241 /// \example conversions.cpp
0242 ///
0243 /// Example of using various text conversion functions.
0244 ///
0245 /// \example wconversions.cpp
0246 ///
0247 /// Example of using various text conversion functions with wide strings.
0248
0249 #endif