ALib C++ Library
Library Version: 2402 R1
Documentation generated by doxygen
Loading...
Searching...
No Matches
std_characters.hpp
Go to the documentation of this file.
1/** ************************************************************************************************
2 * \file
3 * This header file is part of the \aliblong.<br>
4 * With the inclusion of this header compatibility features between \alib and the C++ standard
5 * library are provided.
6 *
7 * \emoji :copyright: 2013-2024 A-Worx GmbH, Germany.
8 * Published under \ref mainpage_license "Boost Software License".
9 **************************************************************************************************/
10#ifndef HPP_ALIB_COMPATIBILITY_STD_CHARACTERS
11#define HPP_ALIB_COMPATIBILITY_STD_CHARACTERS 1
12
13#if !defined(HPP_ALIB) && !defined(ALIB_DOX)
14# include "alib/alib.hpp"
15#endif
16
17#if ALIB_CHARACTERS
18
19#ifndef HPP_ALIB_CHARACTERS_CHARACTERS
20# include "alib/characters/characters.hpp"
21#endif
22
23#if !defined (_GLIBCXX_STRING) && !defined(_STRING_)
24# include <string>
25#endif
26
27#if !defined (_GLIBCXX_STRING_VIEW) && !defined(_STRING_VIEW_)
28# include <string_view>
29#endif
30
31#if !defined (_GLIBCXX_VECTOR) && !defined(_VECTOR_)
32 #include <vector>
33#endif
34
35
36#if ALIB_STRINGS
37# if !defined(HPP_ALIB_STRINGS_FWDS)
38# include "alib/strings/fwds.hpp"
39# endif
40#endif
41
42
43#if !defined(ALIB_DOX)
44namespace alib { namespace characters {
45#else
46namespace alib { namespace characters {
47
48/**
49 * This namespace contains sub-namespaces that provide compatibility of 3rd-party types and
50 * module \alib_characters_nl.<br>
51 * The entities of those namespaces become available with the inclusion of optional "compatibility"
52 * headers found in folder \alibsrcdir{compatibility}.
53 *
54 */
55namespace compatibility {
56
57/**
58 * This namespace documents compatibility features of \alib_characters_nl and the
59 * standard C++ class library found in namespace \c std.
60 */
61namespace std {
62#endif
63
64
65// #################################### std::string_view ######################################
66/**
67 * Specialization of TMP struct \alib{characters;T_CharArray} for type
68 * <c>std::basic_string_view<TChar></c>:
69 * - Character array data (string data) is allowed to be implicitly accessed.
70 * - The type may be implicitly created from character array data.
71 *
72 * @tparam TChar Template parameter providing the underlying character type.
73 * Restricted to types enabled by TMP helper struct \alib{characters;TT_IsChar}.
74 */
75template<typename TChar>
76struct T_CharArray<std::basic_string_view<TChar>, TChar, typename std::enable_if<
77 TT_IsChar<TChar>::value >::type >
78{
79 #if !defined(ALIB_DOX)
80 static constexpr AccessType Access = AccessType::Implicit;
81 static constexpr ConstructionType Construction = ConstructionType::Implicit;
82 static const TChar* Buffer (std::basic_string_view<TChar> const & src) { return src.data () ; }
83 static integer Length (std::basic_string_view<TChar> const & src) { return static_cast<integer>( src.length() ); }
84 static std::basic_string_view<TChar> Construct(const TChar* array, integer length ) { return std::basic_string_view<TChar>( array, static_cast<size_t>(length) ); }
85 #endif
86};
87
88
89/**
90 * Specialization of TMP struct \alib{characters;T_ZTCharArray} for type
91 * <c>std::basic_string_view<TChar></c>:
92 * - Zero-terminated string data is allowed to be explicitly accessed as usually data represented
93 * by type \c std::string_view is not zero-terminated.
94 * - The type may be implicitly created from zero-terminated character arrays.
95 *
96 * @tparam TChar Template parameter providing the underlying character type.
97 * Restricted to types enabled by TMP helper struct \alib{characters;TT_IsChar}.
98 */
99template<typename TChar>
100struct T_ZTCharArray<std::basic_string_view<TChar>, TChar, typename std::enable_if<
101 TT_IsChar<TChar>::value >::type >
102{
103 #if !defined(ALIB_DOX)
104 static constexpr AccessType Access = AccessType::ExplicitOnly;
105 static constexpr ConstructionType Construction = ConstructionType::Implicit;
106 static const TChar* Buffer (std::basic_string_view<TChar> const & src ) { return src.data () ; }
107 static integer Length (std::basic_string_view<TChar> const & src ) { return static_cast<integer>( src.length() ); }
108 static std::basic_string_view<TChar> Construct(const TChar* array, integer length ) { return std::basic_string_view<TChar>( array, static_cast<size_t>(length) ); }
109 #endif
110};
111
112
113// #################################### std::string ######################################
114
115/**
116 * Specialization of TMP struct \alib{characters;T_CharArray} for type
117 * <c>std::basic_string<TChar></c>:
118 * - Character array data (string data) is allowed to be implicitly accessed.
119 * - The construction from character arrays is defined to be allowed in explicit fashion only,
120 * because \c std::string is a heavy-weight string type which will copy the data to an allocated
121 * buffer.
122 *
123 * @tparam TChar Template parameter providing the underlying character type.
124 * Restricted to types enabled by TMP helper struct \alib{characters;TT_IsChar}.
125 */
126template<typename TChar>
127struct T_CharArray<std::basic_string<TChar>, TChar, typename std::enable_if<
128 TT_IsChar<TChar>::value >::type >
129{
130 #if !defined(ALIB_DOX)
131 static constexpr AccessType Access = AccessType::Implicit;
132 static constexpr ConstructionType Construction = ConstructionType::ExplicitOnly;
133 static const TChar* Buffer ( std::basic_string<TChar> const & src ) { return src.data () ; }
134 static integer Length ( std::basic_string<TChar> const & src ) { return static_cast<integer>( src.length() ); }
135 static std::basic_string<TChar> Construct( const TChar* array, integer length ) { return std::basic_string<TChar>( array, static_cast<size_t>(length) ); }
136 #endif
137};
138
139
140/**
141 * Specialization of TMP struct \alib{characters;T_ZTCharArray} for type
142 * <c>std::basic_string<TChar></c>:
143 * - Zero-terminated character string data is allowed to be implicitly accessed, because the
144 * type's buffer access method \c data() returns zero-terminated strings and is defined \c const.
145 * - The type may be created from character array data in an explicit fashion only, because it is a
146 * is a heavy-weight string type which will copy the data to an allocated buffer.
147 *
148 * \note
149 * In combination with classes \alib{strings;TCString;CString} and \alib{strings;TAString;AString},
150 * explicit creation is suppressed using TMP struct \alib{strings;T_SuppressAutoCast}, because
151 * otherwise an ambiguity would occur due to their ability to implicitly cast to
152 * <c>const char*</c>, which implicitly constructs \c std::string in turn.
153 * This leads to the bad situation that an explicit construction like this:
154 *
155 * std::string stdString( cString );
156 *
157 * uses the implicit cast to <c>const char*</c> and with that constructs the \c std::string.
158 * This is of-course very inefficient, as the length of the string has to be determined
159 * internally.
160 *
161 * The most efficient way to create a \c std::string object from an object of type \b CString
162 * or \b AString is to use the explicit constructor:
163 *
164 * std::string stdString( String.Buffer(), String.Length() );
165 *
166 *
167 * @tparam TChar Template parameter providing the underlying character type.
168 * Restricted to types enabled by TMP helper struct \alib{characters;TT_IsChar}.
169 */
170template<typename TChar>
171struct T_ZTCharArray<std::basic_string<TChar>, TChar, typename std::enable_if<
172 TT_IsChar<TChar>::value >::type >
173{
174 #if !defined(ALIB_DOX)
175 static constexpr AccessType Access = AccessType::Implicit;
176 static constexpr ConstructionType Construction = ConstructionType::ExplicitOnly;
177 static const TChar* Buffer ( std::basic_string<TChar> const & src ) { return src.data () ; }
178 static integer Length ( std::basic_string<TChar> const & src ) { return static_cast<integer>( src.length() ); }
179 static std::basic_string<TChar> Construct( const TChar* array, integer length ) { return std::basic_string<TChar>( array, static_cast<size_t>(length) ); }
180 #endif
181};
182
183
184// #################################### std::vector<char> ######################################
185/**
186 * Specialization of TMP struct \alib{characters;T_CharArray} for type <c>std::vector<TChar></c>:
187 * - Character array data (string data) is allowed to be implicitly accessed.
188 * - The construction from character arrays is defined to be allowed in explicit fashion only,
189 * because \c std::vector is a heavy-weight type which will copy the data to an allocated
190 * buffer.
191 *
192 * @tparam TChar Template parameter providing the underlying character type.
193 * Restricted to types enabled by TMP helper struct \alib{characters;TT_IsChar}.
194 */
195template<typename TChar>
196struct T_CharArray<std::vector<TChar>, TChar, typename std::enable_if<
197 TT_IsChar<TChar>::value >::type >
198{
199 #if !defined(ALIB_DOX)
200 static constexpr AccessType Access = AccessType::Implicit;
201 static constexpr ConstructionType Construction = ConstructionType::ExplicitOnly;
202 static const TChar* Buffer (std::vector<TChar> const & src) { return src.data() ; }
203 static integer Length (std::vector<TChar> const & src) { return static_cast<integer>( src.size() ); }
204 ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE
205 static std::vector<TChar> Construct(const TChar* array, integer length )
206 {
207 std::vector<TChar> result;
208 result.reserve( static_cast<size_t>(length) );
209 const TChar* end= array + length;
210 while( array < end )
211 result.push_back( *array++ );
212 return result;
213 }
214 ALIB_WARNINGS_RESTORE
215 #endif
216};
217
218/**
219 * Specialization of TMP struct \alib{characters;T_ZTCharArray} for type <c>std::vector<TChar></c>:
220 * - Character array data (string data) is allowed to be implicitly accessed.
221 * - The construction from zero-terminated character arrays is defined to be allowed in explicit
222 * fashion only, because \c std::vector is a heavy-weight type which will copy the data to an
223 * allocated buffer.<br>
224 * Note that the zero-termination character is not included in the vector when created from
225 * a zero-terminated character array. The length of the vector will have the lengh of the
226 * source string.
227 *
228 * @tparam TChar Template parameter providing the underlying character type.
229 * Restricted to types enabled by TMP helper struct \alib{characters;TT_IsChar}.
230 */
231template<typename TChar>
232struct T_ZTCharArray<std::vector<TChar>, TChar, typename std::enable_if<
233 TT_IsChar<TChar>::value >::type >
234{
235 #if !defined(ALIB_DOX)
236 static constexpr AccessType Access = AccessType::Implicit;
237 static constexpr ConstructionType Construction = ConstructionType::ExplicitOnly;
238 static const TChar* Buffer (std::vector<TChar> const & src) { return src.data() ; }
239 static integer Length (std::vector<TChar> const & src) { return static_cast<integer>( src.size() ); }
240 static std::vector<TChar> Construct(const TChar* array, integer length )
241 {
242 std::vector<TChar> result;
243 result.reserve( static_cast<size_t>(length) );
244 const TChar* end= array + length;
245 while( array < end )
246 result.push_back( *array++ );
247 return result;
248 }
249 #endif
250};
251
252#if !defined(ALIB_DOX)
253}} // namespace [alib::characters]
254#else
255}}}} // namespace [alib::characters::compatibility::std]
256#endif
257
258
259// Suppress conversion of CString and AString to std::string. This rational for this is
260// documented with T_ZTCharArray<std::basic_string> above.
261#if ALIB_STRINGS && !defined(ALIB_DOX)
262
263namespace alib { namespace strings {
264 template<typename TChar> struct T_SuppressAutoCast<TCString<TChar>, characters::ConstructionType::ExplicitOnly, std::basic_string<TChar> > : public std::true_type {};
265 template<typename TChar> struct T_SuppressAutoCast<TAString<TChar>, characters::ConstructionType::ExplicitOnly, std::basic_string<TChar> > : public std::true_type {};
266}}
267
268#endif
269
270
271
272#endif // ALIB_CHARACTERS
273#endif // HPP_ALIB_COMPATIBILITY_STD_CHARACTERS
ALIB_WARNINGS_RESTORE
#define ALIB_WARNINGS_RESTORE
Definition alib.hpp:715
ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE
#define ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE
Definition alib.hpp:644
alib
Definition alib.cpp:57
alib::integer
lang::integer integer
Type alias in namespace alib.
Definition integers.hpp:286
alib::characters::T_CharArray
Definition characters.hpp:265
alib::characters::T_ZTCharArray
Definition characters.hpp:347