2 // Copyright (c) 2009-2011 Artyom Beilis (Tonkikh)
4 // Distributed under the Boost Software License, Version 1.0. (See
5 // accompanying file LICENSE_1_0.txt or copy at
6 // http://www.boost.org/LICENSE_1_0.txt)
8 #ifndef BOOST_LOCALE_CONVERTER_HPP_INCLUDED
9 #define BOOST_LOCALE_CONVERTER_HPP_INCLUDED
11 #include <boost/locale/config.hpp>
13 # pragma warning(push)
14 # pragma warning(disable : 4275 4251 4231 4660)
23 /// \defgroup convert Text Conversions
25 /// This module provides various function for string manipulation like Unicode normalization, case conversion etc.
31 /// \brief This class provides base flags for text manipulation. It is used as base for converter facet.
33 class converter_base {
36 /// The flag used for facet - the type of operation to perform
39 normalization, ///< Apply Unicode normalization on the text
40 upper_case, ///< Convert text to upper case
41 lower_case, ///< Convert text to lower case
42 case_folding, ///< Fold case in the text
43 title_case ///< Convert text to title case
47 template<typename CharType>
50 #ifdef BOOST_LOCALE_DOXYGEN
52 /// \brief The facet that implements text manipulation
54 /// It is used to performs text conversion operations defined by \ref conversion_type. It is specialized
55 /// for four types of characters \c char, \c wchar_t, \c char16_t, \c char32_t
57 template<typename Char>
58 class BOOST_LOCALE_DECL converter: public converter_base, public std::locale::facet {
60 /// Locale identification
61 static std::locale::id id;
63 /// Standard constructor
64 converter(size_t refs = 0) : std::locale::facet(refs)
68 /// Convert text in range [\a begin, \a end) according to conversion method \a how. Parameter
69 /// \a flags is used for specification of normalization method like nfd, nfc etc.
71 virtual std::basic_string<Char> convert(conversion_type how,Char const *begin,Char const *end,int flags = 0) const = 0;
72 #if defined (__SUNPRO_CC) && defined (_RWSTD_VER)
73 std::locale::id& __get_id (void) const { return id; }
79 class BOOST_LOCALE_DECL converter<char> : public converter_base, public std::locale::facet {
81 static std::locale::id id;
83 converter(size_t refs = 0) : std::locale::facet(refs)
86 virtual std::string convert(conversion_type how,char const *begin,char const *end,int flags = 0) const = 0;
87 #if defined (__SUNPRO_CC) && defined (_RWSTD_VER)
88 std::locale::id& __get_id (void) const { return id; }
93 class BOOST_LOCALE_DECL converter<wchar_t> : public converter_base, public std::locale::facet {
95 static std::locale::id id;
96 converter(size_t refs = 0) : std::locale::facet(refs)
99 virtual std::wstring convert(conversion_type how,wchar_t const *begin,wchar_t const *end,int flags = 0) const = 0;
100 #if defined (__SUNPRO_CC) && defined (_RWSTD_VER)
101 std::locale::id& __get_id (void) const { return id; }
105 #ifdef BOOST_LOCALE_ENABLE_CHAR16_T
107 class BOOST_LOCALE_DECL converter<char16_t> : public converter_base, public std::locale::facet {
109 static std::locale::id id;
110 converter(size_t refs = 0) : std::locale::facet(refs)
113 virtual std::u16string convert(conversion_type how,char16_t const *begin,char16_t const *end,int flags = 0) const = 0;
114 #if defined (__SUNPRO_CC) && defined (_RWSTD_VER)
115 std::locale::id& __get_id (void) const { return id; }
120 #ifdef BOOST_LOCALE_ENABLE_CHAR32_T
122 class BOOST_LOCALE_DECL converter<char32_t> : public converter_base, public std::locale::facet {
124 static std::locale::id id;
125 converter(size_t refs = 0) : std::locale::facet(refs)
128 virtual std::u32string convert(conversion_type how,char32_t const *begin,char32_t const *end,int flags = 0) const = 0;
129 #if defined (__SUNPRO_CC) && defined (_RWSTD_VER)
130 std::locale::id& __get_id (void) const { return id; }
138 /// The type that defined <a href="http://unicode.org/reports/tr15/#Norm_Forms">normalization form</a>
142 norm_nfd, ///< Canonical decomposition
143 norm_nfc, ///< Canonical decomposition followed by canonical composition
144 norm_nfkd, ///< Compatibility decomposition
145 norm_nfkc, ///< Compatibility decomposition followed by canonical composition.
146 norm_default = norm_nfc, ///< Default normalization - canonical decomposition followed by canonical composition
150 /// Normalize Unicode string \a str according to \ref norm_type "normalization form" \a n
152 /// Note: This function receives only Unicode strings, i.e.: UTF-8, UTF-16 or UTF-32. It does not take
153 /// in account the locale encoding, because Unicode decomposition and composition are meaningless outside
154 /// of a Unicode character set.
156 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
158 template<typename CharType>
159 std::basic_string<CharType> normalize(std::basic_string<CharType> const &str,norm_type n=norm_default,std::locale const &loc=std::locale())
161 return std::use_facet<converter<CharType> >(loc).convert(converter_base::normalization,str.data(),str.data() + str.size(),n);
165 /// Normalize NUL terminated Unicode string \a str according to \ref norm_type "normalization form" \a n
167 /// Note: This function receives only Unicode strings, i.e.: UTF-8, UTF-16 or UTF-32. It does not take
168 /// in account the locale encoding, because Unicode decomposition and composition are meaningless outside
169 /// of a Unicode character set.
171 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
173 template<typename CharType>
174 std::basic_string<CharType> normalize(CharType const *str,norm_type n=norm_default,std::locale const &loc=std::locale())
176 CharType const *end=str;
179 return std::use_facet<converter<CharType> >(loc).convert(converter_base::normalization,str,end,n);
183 /// Normalize Unicode string in range [begin,end) according to \ref norm_type "normalization form" \a n
185 /// Note: This function receives only Unicode strings, i.e.: UTF-8, UTF-16 or UTF-32. It does not take
186 /// in account the locale encoding, because Unicode decomposition and composition are meaningless outside
187 /// of a Unicode character set.
189 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
191 template<typename CharType>
192 std::basic_string<CharType> normalize( CharType const *begin,
194 norm_type n=norm_default,
195 std::locale const &loc=std::locale())
197 return std::use_facet<converter<CharType> >(loc).convert(converter_base::normalization,begin,end,n);
200 ///////////////////////////////////////////////////
203 /// Convert a string \a str to upper case according to locale \a loc
205 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
208 template<typename CharType>
209 std::basic_string<CharType> to_upper(std::basic_string<CharType> const &str,std::locale const &loc=std::locale())
211 return std::use_facet<converter<CharType> >(loc).convert(converter_base::upper_case,str.data(),str.data()+str.size());
215 /// Convert a NUL terminated string \a str to upper case according to locale \a loc
217 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
219 template<typename CharType>
220 std::basic_string<CharType> to_upper(CharType const *str,std::locale const &loc=std::locale())
222 CharType const *end=str;
225 return std::use_facet<converter<CharType> >(loc).convert(converter_base::upper_case,str,end);
229 /// Convert a string in range [begin,end) to upper case according to locale \a loc
231 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
233 template<typename CharType>
234 std::basic_string<CharType> to_upper(CharType const *begin,CharType const *end,std::locale const &loc=std::locale())
236 return std::use_facet<converter<CharType> >(loc).convert(converter_base::upper_case,begin,end);
239 ///////////////////////////////////////////////////
242 /// Convert a string \a str to lower case according to locale \a loc
244 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
247 template<typename CharType>
248 std::basic_string<CharType> to_lower(std::basic_string<CharType> const &str,std::locale const &loc=std::locale())
250 return std::use_facet<converter<CharType> >(loc).convert(converter_base::lower_case,str.data(),str.data()+str.size());
254 /// Convert a NUL terminated string \a str to lower case according to locale \a loc
256 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
258 template<typename CharType>
259 std::basic_string<CharType> to_lower(CharType const *str,std::locale const &loc=std::locale())
261 CharType const *end=str;
264 return std::use_facet<converter<CharType> >(loc).convert(converter_base::lower_case,str,end);
268 /// Convert a string in range [begin,end) to lower case according to locale \a loc
270 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
272 template<typename CharType>
273 std::basic_string<CharType> to_lower(CharType const *begin,CharType const *end,std::locale const &loc=std::locale())
275 return std::use_facet<converter<CharType> >(loc).convert(converter_base::lower_case,begin,end);
277 ///////////////////////////////////////////////////
280 /// Convert a string \a str to title case according to locale \a loc
282 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
285 template<typename CharType>
286 std::basic_string<CharType> to_title(std::basic_string<CharType> const &str,std::locale const &loc=std::locale())
288 return std::use_facet<converter<CharType> >(loc).convert(converter_base::title_case,str.data(),str.data()+str.size());
292 /// Convert a NUL terminated string \a str to title case according to locale \a loc
294 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
296 template<typename CharType>
297 std::basic_string<CharType> to_title(CharType const *str,std::locale const &loc=std::locale())
299 CharType const *end=str;
302 return std::use_facet<converter<CharType> >(loc).convert(converter_base::title_case,str,end);
306 /// Convert a string in range [begin,end) to title case according to locale \a loc
308 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
310 template<typename CharType>
311 std::basic_string<CharType> to_title(CharType const *begin,CharType const *end,std::locale const &loc=std::locale())
313 return std::use_facet<converter<CharType> >(loc).convert(converter_base::title_case,begin,end);
316 ///////////////////////////////////////////////////
319 /// Fold case of a string \a str according to locale \a loc
321 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
324 template<typename CharType>
325 std::basic_string<CharType> fold_case(std::basic_string<CharType> const &str,std::locale const &loc=std::locale())
327 return std::use_facet<converter<CharType> >(loc).convert(converter_base::case_folding,str.data(),str.data()+str.size());
331 /// Fold case of a NUL terminated string \a str according to locale \a loc
333 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
335 template<typename CharType>
336 std::basic_string<CharType> fold_case(CharType const *str,std::locale const &loc=std::locale())
338 CharType const *end=str;
341 return std::use_facet<converter<CharType> >(loc).convert(converter_base::case_folding,str,end);
345 /// Fold case of a string in range [begin,end) according to locale \a loc
347 /// \note throws std::bad_cast if loc does not have \ref converter facet installed
349 template<typename CharType>
350 std::basic_string<CharType> fold_case(CharType const *begin,CharType const *end,std::locale const &loc=std::locale())
352 return std::use_facet<converter<CharType> >(loc).convert(converter_base::case_folding,begin,end);
370 /// \example conversions.cpp
372 /// Example of using various text conversion functions.
374 /// \example wconversions.cpp
376 /// Example of using various text conversion functions with wide strings.
379 // vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4