E-MailRelay
gconvert.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2023 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
28namespace 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 a 'native' encoding (which might be a SBCS code page, DBCS, or
36/// UTF-8, and possibly related to locale environment variables), UTF-16 wchar,
37/// and UTF-8 multi-byte char.
38///
39/// Conversions that can fail take a ThrowOnError parameter which is used to add
40/// context information to the G::Convert::Error exception that is thrown.
41///
42/// Eg:
43/// \code
44/// std::string to_utf8( const std::wstring & wide_input )
45/// {
46/// G::Convert::utf8 utf8_result ;
47/// G::Convert::convert( utf8_result , wide_input ) ;
48/// return utf8_result.s ;
49/// }
50/// std::string to_native( const std::wstring & wide_input )
51/// {
52/// std::string native_result ;
53/// G::Convert::convert( native_result , wide_input , G::Convert::ThrowOnError("to_native") ) ;
54/// return native_result ;
55/// }
56/// \endcode
57///
59{
60public:
61 G_EXCEPTION_CLASS( Error , tx("string character-set conversion error") ) ;
62 using tstring = std::basic_string<TCHAR> ;
63
64 struct utf8 /// A string wrapper that indicates UTF-8 encoding.
65 {
66 utf8() = default;
67 explicit utf8( const std::string & s_ ) : s(s_) {}
68 std::string s ;
69 } ;
70
71 struct ThrowOnError /// Holds context information which convert() adds to the exception when it fails.
72 {
73 ThrowOnError() = default;
74 explicit ThrowOnError( const std::string & context_ ) : context(context_) {}
75 std::string context ;
76 } ;
77
78 static void convert( utf8 & utf_out , const std::string & in_ ) ;
79 ///< Converts between string types/encodings:
80 ///< native to utf8.
81
82 static void convert( utf8 & utf_out , const utf8 & in_ ) ;
83 ///< Converts between string types/encodings:
84 ///< utf8 to utf8.
85
86 static void convert( utf8 & utf_out , const std::wstring & in_ ) ;
87 ///< Converts between string types/encodings:
88 ///< utf16 to utf8.
89
90 static void convert( std::string & native_out , const std::string & in_ ) ;
91 ///< Converts between string types/encodings:
92 ///< native to native.
93
94 static void convert( std::string & native_out , const utf8 & in_ , const ThrowOnError & ) ;
95 ///< Converts between string types/encodings:
96 ///< utf8 to native.
97
98 static void convert( std::string & native_out , const std::wstring & in_ , const ThrowOnError & ) ;
99 ///< Converts between string types/encodings:
100 ///< utf16 to native.
101
102 static void convert( std::wstring & wide_out , const std::string & native_in ) ;
103 ///< Converts between string types/encodings:
104 ///< native to utf16.
105
106 static void convert( std::wstring & wide_out , const utf8 & utf_in ) ;
107 ///< Converts between string types/encodings:
108 ///< utf8 to utf16.
109
110 static void convert( std::wstring & wide_out , const std::wstring & wide_in ) ;
111 ///< Converts between string types/encodings:
112 ///< utf16 to utf16.
113
114 static void convert( std::string & native_out , const std::string & in_ , const ThrowOnError & ) ;
115 ///< An overload for TCHAR shenanigans on windows. Note that
116 ///< a TCHAR can sometimes be a char, depending on the build
117 ///< options, so this three-parameter overload allows for the
118 ///< input to be a basic_string<TCHAR>, whatever the build.
119 ///<
120 ///< Converts between string types/encodings:
121 ///< native to native.
122
123public:
124 Convert() = delete ;
125
126private:
127 static std::string narrow( const std::wstring & s , bool is_utf8 , const std::string & = {} ) ;
128 static std::wstring widen( const std::string & s , bool is_utf8 , const std::string & = {} ) ;
129} ;
130
131#endif
A static class which provides string encoding conversion functions.
Definition: gconvert.h:59
static void convert(utf8 &utf_out, const std::string &in_)
Converts between string types/encodings: native to utf8.
Definition: gconvert.cpp:44
Low-level classes.
Definition: garg.h:30
constexpr const char * tx(const char *p)
A briefer alternative to G::gettext_noop().
Definition: ggettext.h:84
Holds context information which convert() adds to the exception when it fails.
Definition: gconvert.h:72
A string wrapper that indicates UTF-8 encoding.
Definition: gconvert.h:65