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