boost/locale/encoding.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_ENCODING_HPP_INCLUDED
0008 #define BOOST_LOCALE_ENCODING_HPP_INCLUDED
0009
0010 #include <boost/locale/config.hpp>
0011 #include <boost/locale/detail/encoding.hpp>
0012 #include <boost/locale/encoding_errors.hpp>
0013 #include <boost/locale/encoding_utf.hpp>
0014 #include <boost/locale/info.hpp>
0015 #include <boost/locale/util/string.hpp>
0016 #include <memory>
0017
0018 #ifdef BOOST_MSVC
0019 #    pragma warning(push)
0020 #    pragma warning(disable : 4275 4251 4231 4660)
0021 #endif
0022
0023 namespace boost { namespace locale {
0024
0025     /// \brief Namespace that contains all functions related to character set conversion
0026     namespace conv {
0027
0028         /// \defgroup Charset conversion functions
0029         ///
0030         /// @{
0031
0032         /// convert text in range [begin,end) encoded with \a charset to UTF according to policy \a how
0033         ///
0034         /// \throws invalid_charset_error: Character set is not supported
0035         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0036         /// encoded or decoded)
0037         template<typename CharType>
0038         BOOST_LOCALE_DECL std::basic_string<CharType>
0039         to_utf(const char* begin, const char* end, const std::string& charset, method_type how = default_method);
0040
0041         /// convert UTF text in range [begin,end) to text encoded with \a charset according to policy \a how
0042         ///
0043         /// \throws invalid_charset_error: Character set is not supported
0044         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0045         /// encoded or decoded)
0046         template<typename CharType>
0047         BOOST_LOCALE_DECL std::string from_utf(const CharType* begin,
0048                                                const CharType* end,
0049                                                const std::string& charset,
0050                                                method_type how = default_method);
0051
0052         /// convert \a text encoded with \a charset to UTF according to policy \a how
0053         ///
0054         /// \throws invalid_charset_error: Character set is not supported
0055         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0056         /// encoded or decoded)
0057         template<typename CharType>
0058         std::basic_string<CharType>
0059         to_utf(const std::string& text, const std::string& charset, method_type how = default_method)
0060         {
0061             return to_utf<CharType>(text.c_str(), text.c_str() + text.size(), charset, how);
0062         }
0063
0064         /// Convert \a text encoded with \a charset to UTF according to policy \a how
0065         ///
0066         /// \throws invalid_charset_error: Character set is not supported
0067         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0068         /// encoded or decoded)
0069         template<typename CharType>
0070         std::basic_string<CharType>
0071         to_utf(const char* text, const std::string& charset, method_type how = default_method)
0072         {
0073             return to_utf<CharType>(text, util::str_end(text), charset, how);
0074         }
0075
0076         /// convert text in range [begin,end) in locale encoding given by \a loc to UTF according to
0077         /// policy \a how
0078         ///
0079         /// \throws std::bad_cast: \a loc does not have \ref info facet installed
0080         /// \throws invalid_charset_error: Character set is not supported
0081         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0082         /// encoded or decoded)
0083         template<typename CharType>
0084         std::basic_string<CharType>
0085         to_utf(const char* begin, const char* end, const std::locale& loc, method_type how = default_method)
0086         {
0087             return to_utf<CharType>(begin, end, std::use_facet<info>(loc).encoding(), how);
0088         }
0089
0090         /// Convert \a text in locale encoding given by \a loc to UTF according to policy \a how
0091         ///
0092         /// \throws std::bad_cast: \a loc does not have \ref info facet installed
0093         /// \throws invalid_charset_error: Character set is not supported
0094         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0095         /// encoded or decoded)
0096         template<typename CharType>
0097         std::basic_string<CharType>
0098         to_utf(const std::string& text, const std::locale& loc, method_type how = default_method)
0099         {
0100             return to_utf<CharType>(text, std::use_facet<info>(loc).encoding(), how);
0101         }
0102
0103         /// Convert \a text in locale encoding given by \a loc to UTF according to policy \a how
0104         ///
0105         /// \throws std::bad_cast: \a loc does not have \ref info facet installed
0106         /// \throws invalid_charset_error: Character set is not supported
0107         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0108         /// encoded or decoded)
0109         template<typename CharType>
0110         std::basic_string<CharType> to_utf(const char* text, const std::locale& loc, method_type how = default_method)
0111         {
0112             return to_utf<CharType>(text, std::use_facet<info>(loc).encoding(), how);
0113         }
0114
0115         /// convert \a text from UTF to text encoded with \a charset according to policy \a how
0116         ///
0117         /// \throws invalid_charset_error: Character set is not supported
0118         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0119         /// encoded or decoded)
0120         template<typename CharType>
0121         std::string
0122         from_utf(const std::basic_string<CharType>& text, const std::string& charset, method_type how = default_method)
0123         {
0124             return from_utf(text.c_str(), text.c_str() + text.size(), charset, how);
0125         }
0126
0127         /// Convert \a text from UTF to \a charset according to policy \a how
0128         ///
0129         /// \throws invalid_charset_error: Character set is not supported
0130         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0131         /// encoded or decoded)
0132         template<typename CharType>
0133         std::string from_utf(const CharType* text, const std::string& charset, method_type how = default_method)
0134         {
0135             return from_utf(text, util::str_end(text), charset, how);
0136         }
0137
0138         /// Convert UTF text in range [begin,end) to text in locale encoding given by \a loc according to policy \a how
0139         ///
0140         /// \throws std::bad_cast: \a loc does not have \ref info facet installed
0141         /// \throws invalid_charset_error: Character set is not supported
0142         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0143         /// encoded or decoded)
0144         template<typename CharType>
0145         std::string
0146         from_utf(const CharType* begin, const CharType* end, const std::locale& loc, method_type how = default_method)
0147         {
0148             return from_utf(begin, end, std::use_facet<info>(loc).encoding(), how);
0149         }
0150
0151         /// Convert \a text from UTF to locale encoding given by \a loc according to policy \a how
0152         ///
0153         /// \throws std::bad_cast: \a loc does not have \ref info facet installed
0154         /// \throws invalid_charset_error: Character set is not supported
0155         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0156         /// encoded or decoded)
0157         template<typename CharType>
0158         std::string
0159         from_utf(const std::basic_string<CharType>& text, const std::locale& loc, method_type how = default_method)
0160         {
0161             return from_utf(text, std::use_facet<info>(loc).encoding(), how);
0162         }
0163
0164         /// Convert \a text from UTF to locale encoding given by \a loc according to policy \a how
0165         ///
0166         /// \throws std::bad_cast: \a loc does not have \ref info facet installed
0167         /// \throws invalid_charset_error: Character set is not supported
0168         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0169         /// encoded or decoded)
0170         template<typename CharType>
0171         std::string from_utf(const CharType* text, const std::locale& loc, method_type how = default_method)
0172         {
0173             return from_utf(text, std::use_facet<info>(loc).encoding(), how);
0174         }
0175
0176         /// Convert a text in range [begin,end) to \a to_encoding from \a from_encoding according to
0177         /// policy \a how
0178         ///
0179         /// \throws invalid_charset_error: Either character set is not supported
0180         /// \throws conversion_error: when the conversion fails (e.g. \a how is \c stop and any character cannot be
0181         /// encoded or decoded)
0182         BOOST_LOCALE_DECL
0183         std::string between(const char* begin,
0184                             const char* end,
0185                             const std::string& to_encoding,
0186                             const std::string& from_encoding,
0187                             method_type how = default_method);
0188
0189         /// Convert \a text to \a to_encoding from \a from_encoding according to
0190         /// policy \a how
0191         ///
0192         /// \throws invalid_charset_error: Either character set is not supported
0193         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0194         /// encoded or decoded)
0195         inline std::string between(const char* text,
0196                                    const std::string& to_encoding,
0197                                    const std::string& from_encoding,
0198                                    method_type how = default_method)
0199         {
0200             return between(text, util::str_end(text), to_encoding, from_encoding, how);
0201         }
0202
0203         /// Convert \a text to \a to_encoding from \a from_encoding according to
0204         /// policy \a how
0205         ///
0206         /// \throws invalid_charset_error: Either character set is not supported
0207         /// \throws conversion_error: Conversion failed (e.g. \a how is \c stop and any character cannot be
0208         /// encoded or decoded)
0209         inline std::string between(const std::string& text,
0210                                    const std::string& to_encoding,
0211                                    const std::string& from_encoding,
0212                                    method_type how = default_method)
0213         {
0214             return between(text.c_str(), text.c_str() + text.size(), to_encoding, from_encoding, how);
0215         }
0216
0217         /// @}
0218
0219         /// Converter class to decode a narrow string using a local encoding and encode it with UTF
0220         template<typename CharType>
0221         class utf_encoder {
0222             std::unique_ptr<detail::utf_encoder<CharType>> impl_;
0223
0224         public:
0225             using char_type = CharType;
0226             using string_type = std::basic_string<CharType>;
0227
0228             /// Create an instance to convert text encoded with \a charset to UTF according to policy \a how
0229             ///
0230             /// Note: When converting only a single text \ref to_utf is likely faster.
0231             /// \throws invalid_charset_error: Character set is not supported
0232             utf_encoder(const std::string& charset, method_type how = default_method) :
0233                 impl_(detail::make_utf_encoder<CharType>(charset, how))
0234             {}
0235
0236             /// Convert text in range [begin,end) to UTF
0237             ///
0238             /// \throws conversion_error: Conversion failed
0239             string_type convert(const char* begin, const char* end) const { return impl_->convert(begin, end); }
0240             /// Convert \a text to UTF
0241             ///
0242             /// \throws conversion_error: Conversion failed
0243             string_type convert(const boost::string_view& text) const { return impl_->convert(text); }
0244             /// Convert \a text to UTF
0245             ///
0246             /// \throws conversion_error: Conversion failed
0247             string_type operator()(const boost::string_view& text) const { return convert(text); }
0248         };
0249
0250         /// Converter class to decode an UTF string and encode it using a local encoding
0251         template<typename CharType>
0252         class utf_decoder {
0253             std::unique_ptr<detail::utf_decoder<CharType>> impl_;
0254
0255         public:
0256             using char_type = CharType;
0257             using stringview_type = boost::basic_string_view<CharType>;
0258
0259             /// Create an instance to convert UTF text to text encoded with \a charset according to policy \a how
0260             ///
0261             /// Note: When converting only a single text \ref from_utf is likely faster.
0262             /// \throws invalid_charset_error: Character set is not supported
0263             utf_decoder(const std::string& charset, method_type how = default_method) :
0264                 impl_(detail::make_utf_decoder<CharType>(charset, how))
0265             {}
0266
0267             /// Convert UTF text in range [begin,end) to local encoding
0268             ///
0269             /// \throws conversion_error: Conversion failed
0270             std::string convert(const CharType* begin, const CharType* end) const { return impl_->convert(begin, end); }
0271             /// Convert \a text from UTF to local encoding
0272             ///
0273             /// \throws conversion_error: Conversion failed
0274             std::string convert(const stringview_type& text) const { return impl_->convert(text); }
0275             /// Convert \a text from UTF to local encoding
0276             ///
0277             /// \throws conversion_error: Conversion failed
0278             std::string operator()(const stringview_type& text) const { return convert(text); }
0279         };
0280
0281         class narrow_converter {
0282             std::unique_ptr<detail::narrow_converter> impl_;
0283
0284         public:
0285             /// Create converter to convert text from \a src_encoding to \a target_encoding according to policy \a how
0286             ///
0287             /// \throws invalid_charset_error: Either character set is not supported
0288             narrow_converter(const std::string& src_encoding,
0289                              const std::string& target_encoding,
0290                              method_type how = default_method) :
0291                 impl_(detail::make_narrow_converter(src_encoding, target_encoding, how))
0292             {}
0293
0294             /// Convert text in range [begin,end)
0295             ///
0296             /// \throws conversion_error: Conversion failed
0297             std::string convert(const char* begin, const char* end) const { return impl_->convert(begin, end); }
0298             /// Convert \a text
0299             ///
0300             /// \throws conversion_error: Conversion failed
0301             std::string convert(const boost::string_view& text) const { return impl_->convert(text); }
0302             /// Convert \a text
0303             ///
0304             /// \throws conversion_error: Conversion failed
0305             std::string operator()(const boost::string_view& text) const { return convert(text); }
0306         };
0307     } // namespace conv
0308 }}    // namespace boost::locale
0309
0310 #ifdef BOOST_MSVC
0311 #    pragma warning(pop)
0312 #endif
0313
0314 #endif