ALib C++ Framework
by
Library Version: 2511 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
chartraits_stdtypes.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of module \alib_characters of the \aliblong.
4///
5/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
6/// Published under #"mainpage_license".
7//==================================================================================================
8ALIB_EXPORT namespace alib::characters {
9
10//##################################################################################################
11//###################################### ArrayTraits<std::xyz> #####################################
12//##################################################################################################
13
14#if DOXYGEN
15/// This namespace contains sub-namespaces that provide compatibility of 3rd-party types and
16/// module \alib_characters_nl.<br>
17/// The entities of those namespaces become available with the inclusion of specific headers
18/// that import a certain C++20 Module or inject the functionality into a namespace in a
19/// traditional fashion, for example, header #"F;ALib.Strings.StdFormatter.H".
20namespace compatibility {
21
22/// This namespace documents compatibility features of \alib_characters_nl and the
23/// standard C++ class library found in namespace \c std.
24namespace std {
25#endif
26
27//######################################### std::string_view #######################################
28/// Specialization of the type trait #"ArrayTraits" for type
29/// <c>std::basic_string_view<TChar></c>:
30/// - Character array data (string data) is allowed to be implicitly accessed.
31/// - The type may be implicitly created from character array data.
32///
33/// @tparam TChar Template parameter providing the underlying character type.
34/// Restricted to types that satisfy the concept #"ch IsCharacter".
35template<typename TChar>
36requires IsCharacter<TChar>
37struct ArrayTraits<std::basic_string_view<TChar>, TChar>
38{
39 #if !DOXYGEN
40 static constexpr Policy Access = Policy::Implicit;
41 static constexpr Policy Construction = Policy::Implicit;
42 static constexpr const TChar* Buffer (std::basic_string_view<TChar> const & src) { return src.data () ; }
43 static constexpr integer Length (std::basic_string_view<TChar> const & src) { return integer( src.length() ); }
44 constexpr static std::basic_string_view<TChar> Construct(const TChar* array, integer length ) { return std::basic_string_view<TChar>( array, size_t(length) ); }
45 #endif
46};
47
48/// Specialization of the type trait #"ArrayTraits" for type
49/// <c>std::basic_string_view<char8_t></c>:
50/// - Character array data (string data) is allowed to be implicitly accessed.
51/// - The type may be implicitly created from character array data.
52template<>
53struct ArrayTraits<std::basic_string_view<char8_t>, nchar>
54{
55 #if !DOXYGEN
56 static constexpr Policy Access = Policy::Implicit;
57 static constexpr Policy Construction = Policy::Implicit;
58 static const nchar* Buffer (std::basic_string_view<char8_t> const & src) { return reinterpret_cast<const nchar*>(src.data ()) ; }
59 static constexpr integer Length (std::basic_string_view<char8_t> const & src) { return integer( src.length() ); }
60 static std::basic_string_view<char8_t> Construct(const nchar* array, integer length )
61 { return std::basic_string_view<char8_t>( reinterpret_cast<const char8_t*>(array), size_t(length) ); }
62 #endif
63};
64
65/// Specialization of the type trait #"ZTArrayTraits" for type
66/// <c>std::basic_string_view<TChar></c>:
67/// - Zero-terminated string data is allowed to be explicitly accessed as usually data represented
68/// by type \c std::string_view is not zero-terminated.
69/// - The type may be implicitly created from zero-terminated character arrays.
70///
71/// @tparam TChar Template parameter providing the underlying character type.
72/// Restricted to types that satisfy the concept #"ch IsCharacter".
73template<typename TChar>
74requires IsCharacter<TChar>
75struct ZTArrayTraits<std::basic_string_view<TChar>, TChar>
76{
77 #if !DOXYGEN
78 static constexpr Policy Access = Policy::ExplicitOnly;
79 static constexpr Policy Construction = Policy::Implicit;
80 static constexpr const TChar* Buffer (std::basic_string_view<TChar> const & src ) { return src.data () ; }
81 static constexpr integer Length (std::basic_string_view<TChar> const & src ) { return integer( src.length() ); }
82 static constexpr std::basic_string_view<TChar> Construct(const TChar* array, integer length ) { return std::basic_string_view<TChar>( array, size_t(length) ); }
83 #endif
84};
85
86/// Specialization of the type trait #"ZTArrayTraits" for type
87/// <c>std::basic_string_view<char8_t></c>:
88/// - Zero-terminated string data is allowed to be explicitly accessed as usually data represented
89/// by type \c std::string_view is not zero-terminated.
90/// - The type may be implicitly created from zero-terminated character arrays.
91template<>
92struct ZTArrayTraits<std::basic_string_view<char8_t>, nchar>
93{
94 #if !DOXYGEN
95 static constexpr Policy Access = Policy::ExplicitOnly;
96 static constexpr Policy Construction = Policy::Implicit;
97 static const nchar* Buffer (std::basic_string_view<char8_t> const & src ) { return reinterpret_cast<const nchar*>(src.data ()) ; }
98 static constexpr integer Length (std::basic_string_view<char8_t> const & src ) { return integer( src.length() ); }
99 static std::basic_string_view<char8_t> Construct(const nchar* array, integer length )
100 { return std::basic_string_view<char8_t>( reinterpret_cast<const char8_t*>(array), size_t(length) ); }
101 #endif
102};
103
104//########################################### std::string ##########################################
105
106/// Specialization of the type trait #"ArrayTraits" for type
107/// <c>std::basic_string<TChar></c>:
108/// - Character array data (string data) is allowed to be implicitly accessed.
109/// - The construction from character arrays is defined to be allowed in explicit fashion only,
110/// because \c std::string is a heavy-weight string type that will copy the data to an allocated
111/// buffer.
112///
113/// @tparam TChar Template parameter providing the underlying character type.
114/// Restricted to types that satisfy the concept #"ch IsCharacter".
115template<typename TChar>
116requires IsCharacter<TChar>
117struct ArrayTraits<std::basic_string<TChar>, TChar>
118{
119 #if !DOXYGEN
120 static constexpr Policy Access = Policy::Implicit;
121 static constexpr Policy Construction = Policy::ExplicitOnly;
122 static constexpr const TChar* Buffer ( std::basic_string<TChar> const & src ) { return src.data () ; }
123 static constexpr integer Length ( std::basic_string<TChar> const & src ) { return integer( src.length() ); }
124 static constexpr std::basic_string<TChar> Construct( const TChar* array, integer length ) { return std::basic_string<TChar>( array, size_t(length) ); }
125 #endif
126};
127
128/// Specialization of the type trait #"ArrayTraits" for type
129/// <c>std::basic_string<char8_t></c>:
130/// - Character array data (string data) is allowed to be implicitly accessed.
131/// - The construction from character arrays is defined to be allowed in explicit fashion only,
132/// because \c std::string is a heavy-weight string type that will copy the data to an allocated
133/// buffer.
134template<>
135struct ArrayTraits<std::basic_string<char8_t>, nchar>
136{
137 #if !DOXYGEN
138 static constexpr Policy Access = Policy::Implicit;
139 static constexpr Policy Construction = Policy::ExplicitOnly;
140 static const nchar* Buffer ( std::basic_string<char8_t> const & src ) { return reinterpret_cast<const nchar*>(src.data()); }
141 static constexpr integer Length ( std::basic_string<char8_t> const & src ) { return integer( src.length() ); }
142 static std::basic_string<char8_t> Construct( const nchar* array, integer length )
143 { return std::basic_string<char8_t>( reinterpret_cast<const char8_t*>(array), size_t(length) ); }
144 #endif
145};
146
147
148/// Specialization of the type trait #"ZTArrayTraits" for type
149/// <c>std::basic_string<TChar></c>:
150/// - Zero-terminated character string data is allowed to be implicitly accessed, because the
151/// type's buffer access method \c data() returns zero-terminated strings and is defined \c const.
152/// - The type may be created from character array data in an explicit fashion only, because it is a
153/// heavy-weight string type that will copy the data to an allocated buffer.
154///
155/// \note
156/// In combination with classes #"TCString;CString" and #"TAString;AString",
157/// explicit creation is suppressed using the type trait #"NoAutoCastTraits", because
158/// otherwise an ambiguity would occur due to their ability to implicitly cast to
159/// <c>const char*</c>, which implicitly constructs \c std::string in turn.
160/// This leads to the bad situation that an explicit construction like this:
161///
162/// std::string stdString( cString );
163///
164/// uses the implicit cast to <c>const char*</c> and with that constructs the \c std::string.
165/// This would be inefficient, as the length of the string has to be determined internally.
166///
167/// The most efficient way to create a \c std::string object from an object of type \b CString
168/// or \b AString is to use the explicit constructor:
169///
170/// std::string stdString( String.Buffer(), String.Length() );
171///
172/// @tparam TChar Template parameter providing the underlying character type.
173/// Restricted to types that satisfy the concept #"ch IsCharacter".
174template<typename TChar>
175requires IsCharacter<TChar>
176struct ZTArrayTraits<std::basic_string<TChar>, TChar>
177{
178 #if !DOXYGEN
179 static constexpr Policy Access = Policy::Implicit;
180 static constexpr Policy Construction = Policy::ExplicitOnly;
181 static constexpr const TChar* Buffer ( std::basic_string<TChar> const & src ) { return src.data () ; }
182 static constexpr integer Length ( std::basic_string<TChar> const & src ) { return integer( src.length() ); }
183 static constexpr std::basic_string<TChar> Construct( const TChar* array, integer length ) { return std::basic_string<TChar>( array, size_t(length) ); }
184 #endif
185};
186
187
188//######################################## std::vector<char> #######################################
189/// Specialization of the type trait #"ArrayTraits" for type <c>std::vector<TChar></c>:
190/// - Character array data (string data) is allowed to be implicitly accessed.
191/// - The construction from character arrays is defined to be allowed in explicit fashion only,
192/// because \c std::vector is a heavy-weight type which will copy the data to an allocated
193/// buffer.
194///
195/// @tparam TChar Template parameter providing the underlying character type.
196/// Restricted to types that satisfy the concept #"ch IsCharacter".
197template<typename TChar>
198requires IsCharacter<TChar>
199struct ArrayTraits<std::vector<TChar>, TChar>
200{
201 #if !DOXYGEN
202 static constexpr Policy Access = Policy::Implicit;
203 static constexpr Policy Construction = Policy::ExplicitOnly;
204 static constexpr const TChar* Buffer (std::vector<TChar> const & src) { return src.data() ; }
205 static constexpr integer Length (std::vector<TChar> const & src) { return integer( src.size() ); }
206 static std::vector<TChar> Construct(const TChar* array, integer length ) {
207 std::vector<TChar> result;
208 result.reserve( size_t(length) );
209 const TChar* end= array + length;
210 while( array < end )
211 result.push_back( *array++ );
212 return result;
213 }
214 #endif
215};
216
217/// Specialization of the type trait #"ZTArrayTraits" for type
218/// <c>std::vector<TChar></c>:
219/// - Character array data (string data) is allowed to be implicitly accessed.
220/// - The construction from zero-terminated character arrays is defined to be allowed in explicit
221/// fashion only, because \c std::vector is a heavy-weight type which will copy the data to an
222/// allocated buffer.<br>
223/// Note that the zero-termination character is not included in the vector when created from
224/// a zero-terminated character array. The length of the vector will have the lengh of the
225/// source string.
226///
227/// @tparam TChar Template parameter providing the underlying character type.
228/// Restricted to types that satisfy the concept #"ch IsCharacter".
229template<typename TChar>
230requires IsCharacter<TChar>
231struct ZTArrayTraits<std::vector<TChar>, TChar >
232{
233 #if !DOXYGEN
234 static constexpr Policy Access = Policy::Implicit;
235 static constexpr Policy Construction = Policy::ExplicitOnly;
236 static constexpr const TChar* Buffer (std::vector<TChar> const & src) { return src.data() ; }
237 static constexpr integer Length (std::vector<TChar> const & src) { return integer( src.size() ); }
238 static constexpr std::vector<TChar> Construct(const TChar* array, integer length ) {
239 std::vector<TChar> result;
240 result.reserve( size_t(length) );
241 const TChar* end= array + length;
242 while( array < end )
243 result.push_back( *array++ );
244 return result;
245 }
246 #endif
247};
248
249//############################################ std::array ##########################################
250/// Specialization of the type trait #"ArrayTraits" for type
251/// <c>std::array<TChar></c>:
252/// - Character array data (string data) is allowed to be implicitly accessed.
253/// - The type may be implicitly created from character array data.
254///
255/// @tparam TChar Template parameter providing the underlying character type.
256/// Restricted to types that satisfy the concept #"ch IsCharacter".
257template<typename TChar, size_t TLength>
258requires IsCharacter<TChar>
259struct ArrayTraits<std::array<TChar,TLength>, TChar>
260{
261 #if !DOXYGEN
262 static constexpr Policy Access = Policy::Implicit;
263 static constexpr Policy Construction = Policy::NONE;
264 static constexpr const TChar* Buffer (std::array<TChar, TLength> const & src) { return src.data () ; }
265 static constexpr integer Length (std::array<TChar, TLength> const & src) { return integer( src.size() ); }
266 #endif
267};
268
269
270/// Specialization of the type trait #"ZTArrayTraits" for type
271/// <c>std::array<TChar></c>:
272/// - Zero-terminated string data is allowed to be explicitly accessed as usually data represented
273/// by type \c std::string_view is not zero-terminated.
274/// - The type may be implicitly created from zero-terminated character arrays.
275///
276/// @tparam TChar Template parameter providing the underlying character type.
277/// Restricted to types that satisfy the concept #"ch IsCharacter".
278template<typename TChar, size_t TLength>
279requires IsCharacter<TChar>
280struct ZTArrayTraits<std::array<TChar, TLength>, TChar>
281{
282 #if !DOXYGEN
283 static constexpr Policy Access = Policy::ExplicitOnly;
284 static constexpr Policy Construction = Policy::NONE;
285 static constexpr const TChar* Buffer (std::array<TChar, TLength> const & src ) { return src.data () ; }
286 static constexpr integer Length (std::array<TChar, TLength> const & src ) { return integer( src.size() ); }
287 #endif
288};
289
290//############################################ std::span ###########################################
291/// Specialization of the type trait #"ArrayTraits" for type
292/// <c>std::span<const TChar></c>:
293/// - Character array data (string data) is allowed to be implicitly accessed.
294/// - The type may be implicitly created from character array data.
295///
296/// @tparam TChar Template parameter providing the underlying character type.
297/// Restricted to types that satisfy the concept #"ch IsCharacter".
298template<typename TChar>
299requires IsCharacter<TChar>
300struct ArrayTraits<std::span<const TChar>, TChar>
301{
302 #if !DOXYGEN
303 static constexpr Policy Access = Policy::Implicit;
304 static constexpr Policy Construction = Policy::Implicit;
305 static constexpr const TChar* Buffer (std::span<const TChar> const & src) { return src.data () ; }
306 static constexpr integer Length (std::span<const TChar> const & src) { return integer( src.size() ); }
307 static std::span<const TChar> Construct(const TChar* array, integer length ) { return std::span<const TChar>( array, size_t(length) ); }
308 #endif
309};
310
311
312/// Specialization of the type trait #"ZTArrayTraits" for type
313/// <c>std::span<const TChar></c>:
314/// - Zero-terminated string data is allowed to be explicitly accessed as usually data represented
315/// by type \c std::span is not zero-terminated.
316/// - The type may be implicitly created from zero-terminated character arrays.
317///
318/// @tparam TChar Template parameter providing the underlying character type.
319/// Restricted to types that satisfy the concept #"ch IsCharacter".
320template<typename TChar>
321requires IsCharacter<TChar>
322struct ZTArrayTraits<std::span<const TChar>, TChar>
323{
324 #if !DOXYGEN
325 static constexpr Policy Access = Policy::ExplicitOnly;
326 static constexpr Policy Construction = Policy::Implicit;
327 static constexpr const TChar* Buffer (std::span<const TChar> const & src ) { return src.data () ; }
328 static constexpr integer Length (std::span<const TChar> const & src ) { return integer( src.size() ); }
329 static std::span<const TChar> Construct(const TChar* array, integer length ) { return std::span<const TChar>( array, size_t(length) ); }
330 #endif
331};
332
333#if DOXYGEN
334}} // namespace alib::characters[::compatibility::std]
335#endif
336
337} // namespace [alib::character]
ALIB_EXPORT
#define ALIB_EXPORT
Definition alib.inl:562
alib::characters::Length
integer Length(const TChar *cstring)
Definition functions.inl:89
alib::integer
lang::integer integer
Type alias in namespace alib.
Definition integers.inl:149