E-MailRelay

gconvert.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file gconvert.h
19///
20
21#ifndef G_CONVERT_H
22#define G_CONVERT_H
23
24#include "gdef.h"
25#include "gexception.h"
26#include <string>
27
28 namespace G
29{
30 class Convert ;
31}
32
33//| \class G::Convert
34/// A static class which provides string encoding conversion functions. Supported
35/// encodings are ISO-8859-15 eight-bit char, UTF-16 wchar, and UTF-8 multi-byte char.
36///
37/// On Windows the eight-bit char encoding uses the 'active code page', typically
38/// CP-1252, rather than ISO-8859-15. Note that the active code page is also used
39/// by the Win32 API "A()" functions when they have to convert from 'ansi' to UTF-16
40/// (UCS-2) wide characters (see GetACP()).
41///
42/// Conversions that can fail take a ThrowOnError parameter which is used to add
43/// context information to the G::Convert::Error exception that is thrown.
44///
45/// Eg:
46/// \code
47/// std::string to_utf8( const std::wstring & wide_input )
48/// {
49/// G::Convert::utf8 utf8_result ;
50/// G::Convert::convert( utf8_result , wide_input ) ;
51/// return utf8_result.s ;
52/// }
53/// std::string to_ansi( const std::wstring & wide_input )
54/// {
55/// std::string ansi_result ;
56/// G::Convert::convert( ansi_result , wide_input , G::Convert::ThrowOnError("to_ansi") ) ;
57/// return ansi_result ;
58/// }
59/// \endcode
60///
61 class G::Convert
62{
63 public:
64 G_EXCEPTION_CLASS( Error , "string character-set conversion error" ) ;
65 using tstring = std::basic_string<TCHAR> ;
66
67 struct utf8 /// A string wrapper that indicates UTF-8 encoding.
68 {
69 utf8() = default;
70 explicit utf8( const std::string & s_ ) : s(s_) {}
71 std::string s ;
72 } ;
73
74 struct ThrowOnError /// Holds context information which convert() adds to the exception when it fails.
75 {
76 ThrowOnError() = default;
77 explicit ThrowOnError( const std::string & context_ ) : context(context_) {}
78 std::string context ;
79 } ;
80
81 static void convert( utf8 & utf_out , const std::string & in_ ) ;
82 ///< Converts between string types/encodings:
83 ///< ansi to utf8.
84
85 static void convert( utf8 & utf_out , const utf8 & in_ ) ;
86 ///< Converts between string types/encodings:
87 ///< utf8 to utf8.
88
89 static void convert( utf8 & utf_out , const std::wstring & in_ ) ;
90 ///< Converts between string types/encodings:
91 ///< utf16 to utf8.
92
93 static void convert( std::string & ansi_out , const std::string & in_ ) ;
94 ///< Converts between string types/encodings:
95 ///< ansi to ansi.
96
97 static void convert( std::string & ansi_out , const utf8 & in_ , const ThrowOnError & ) ;
98 ///< Converts between string types/encodings:
99 ///< utf8 to ansi.
100
101 static void convert( std::string & ansi_out , const std::wstring & in_ , const ThrowOnError & ) ;
102 ///< Converts between string types/encodings:
103 ///< utf16 to ansi.
104
105 static void convert( std::wstring & wide_out , const std::string & ansi_in ) ;
106 ///< Converts between string types/encodings:
107 ///< ansi to utf16.
108
109 static void convert( std::wstring & wide_out , const utf8 & utf_in ) ;
110 ///< Converts between string types/encodings:
111 ///< utf8 to utf16.
112
113 static void convert( std::wstring & wide_out , const std::wstring & wide_in ) ;
114 ///< Converts between string types/encodings:
115 ///< utf16 to utf16.
116
117 static void convert( std::string & ansi_out , const std::string & in_ , const ThrowOnError & ) ;
118 ///< An overload for TCHAR shenanigans on windows. Note that
119 ///< a TCHAR can sometimes be a char, depending on the build
120 ///< options, so this three-parameter overload allows for the
121 ///< input to be a basic_string<TCHAR>, whatever the build.
122 ///<
123 ///< Converts between string types/encodings:
124 ///< ansi to ansi.
125
126 public:
127 Convert() = delete ;
128
129 private:
130 static std::string narrow( const std::wstring & s , bool is_utf8 , const std::string & = std::string() ) ;
131 static std::wstring widen( const std::string & s , bool is_utf8 , const std::string & = std::string() ) ;
132} ;
133
134#endif
G::Convert
A static class which provides string encoding conversion functions.
Definition: gconvert.h:62
G::Convert::convert
static void convert(utf8 &utf_out, const std::string &in_)
Converts between string types/encodings: ansi to utf8.
Definition: gconvert.cpp:44
gexception.h
G
Low-level classes.
Definition: galign.h:28
G::Convert::ThrowOnError
Holds context information which convert() adds to the exception when it fails.
Definition: gconvert.h:75
G::Convert::utf8
A string wrapper that indicates UTF-8 encoding.
Definition: gconvert.h:68