boost/locale/encoding.hpp

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