1 /* Copyright (C) 2022 Wildfire Games.
2 * This file is part of 0 A.D.
4 * 0 A.D. 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 2 of the License, or
7 * (at your option) any later version.
9 * 0 A.D. 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.
14 * You should have received a copy of the GNU General Public License
15 * along with 0 A.D. If not, see <http://www.gnu.org/licenses/>.
19 * Description : Contains CStr class which is a versatile class for making string use easy.
20 * : The class implements a series of string manipulation/formatting functions.
27 * Whitespace trim identifier for Trim and Pad functions
31 PS_TRIM_LEFT
, /// Trim all white space from the beginning of the string
32 PS_TRIM_RIGHT
, /// Trim all white space from the end of the string
33 PS_TRIM_BOTH
/// Trim all white space from the beginning and end of the string
37 #define UNIDOUBLER_HEADER "CStr.h"
38 #include "UniDoubler.h"
43 // Include this section when in unidoubler mode, and when this unicode/ascii
44 // version has not already been included.
45 #if defined(IN_UNIDOUBLER) && ( (defined(_UNICODE) && !defined(CSTR_H_U)) || (!defined(_UNICODE) && !defined(CSTR_H_A)) )
53 #include "ps/CStrForward.h"
58 * The base class of all strings
60 class CStr
: public std::tstring
63 using StrBase
= std::tstring
;
64 using Char
= typename
std::tstring::value_type
;
66 CStr(const StrBase
& str
) : StrBase(str
) {}
68 using StrBase::StrBase
;
71 * Repeat: Named constructor, to avoid overload overload.
73 * @param const CStr & str reference to another CStr object to be repeated for initialization
74 * @param size_t Reps number of times to repeat the initialization
75 * @return CStr new CStr object
77 static CStr
Repeat(const CStr
& str
, size_t reps
);
80 * Construction from u16strings.
82 * @param u16string String u16string to be used for initialization.
84 explicit CStr(const std::u16string
& str
) : StrBase(str
.begin(), str
.end()) {}
86 // Conversion to/from UTF-8, encoded in a CStr8.
87 // Invalid bytes/characters (e.g. broken UTF-8, and Unicode characters
88 // above U+FFFF) are silently replaced with U+FFFD.
92 CStrW
FromUTF8() const;
97 static CStr
FromInt(int n
);
98 static CStr
FromUInt(unsigned int n
);
99 static CStr
FromInt64(i64 n
);
100 static CStr
FromDouble(double n
);
103 * Return CStr as Integer.
104 * Conversion is from the beginning of CStr.
106 * @return int CStr represented as an integer.
110 * Return CStr as Unsigned Integer.
111 * Conversion is from the beginning of CStr.
113 * @return unsigned int CStr represented as an unsigned integer.
115 unsigned int ToUInt() const;
117 * Return CStr as Long.
118 * Conversion is from the beginning of CStr.
120 * @return long CStr represented as a long.
124 * Return CStr as Unsigned Long.
125 * Conversion is from the beginning of CStr.
127 * @return unsigned long CStr represented as an unsigned long.
129 unsigned long ToULong() const;
131 * Return CStr as Float.
132 * Conversion is from the beginning of CStr.
134 * @return float CStr represented as a float.
136 float ToFloat() const;
138 * Return CStr as Double.
139 * Conversion is from the beginning of CStr.
141 * @return double CStr represented as a double.
143 double ToDouble() const;
146 * Search the CStr for another string.
147 * The search is case-sensitive.
149 * @param const CStr & str reference to the search string
150 * @return long offset into the CStr of the first occurrence of the search string
151 * -1 if the search string is not found
153 long Find(const CStr
& str
) const;
155 * Search the CStr for another string.
156 * The search is case-sensitive.
158 * @param const {t|w}char_t & chr reference to the search string
159 * @return long offset into the CStr of the first occurrence of the search string
160 * -1 if the search string is not found
162 long Find(const Char chr
) const;
164 * Search the CStr for another string with starting offset.
165 * The search is case-sensitive.
167 * @param const int & start character offset into CStr to begin search
168 * @param const {t|w}char_t & chr reference to the search string
169 * @return long offset into the CStr of the first occurrence of the search string
170 * -1 if the search string is not found
172 long Find(const int start
, const Char chr
) const;
175 * Search the CStr for another string.
176 * The search is case-insensitive.
178 * @param const CStr & str reference to the search string
179 * @return long offset into the CStr of the first occurrence of the search string
180 * -1 if the search string is not found
182 long FindInsensitive(const CStr
& str
) const;
184 * Search the CStr for another string.
185 * The search is case-insensitive.
187 * @param const {t|w}char_t & chr reference to the search string
188 * @return long offset into the CStr of the first occurrence of the search string
189 * -1 if the search string is not found
191 long FindInsensitive(const Char chr
) const;
193 * Search the CStr for another string with starting offset.
194 * The search is case-insensitive.
196 * @param const int & start character offset into CStr to begin search
197 * @param const {t|w}char_t & chr reference to the search string
198 * @return long offset into the CStr of the first occurrence of the search string
199 * -1 if the search string is not found
201 long FindInsensitive(const int start
, const Char chr
) const;
204 * Search the CStr for another string.
205 * The search is case-sensitive.
207 * @param const CStr & str reference to the search string
208 * @return long offset into the CStr of the last occurrence of the search string
209 * -1 if the search string is not found
211 long ReverseFind(const CStr
& str
) const;
214 * Make a copy of the CStr in lower-case.
216 * @return CStr converted copy of CStr.
218 CStr
LowerCase() const;
220 * Make a copy of the CStr in upper-case.
222 * @return CStr converted copy of CStr.
224 CStr
UpperCase() const;
227 * Retrieve first n characters of the CStr.
229 * @param size_t len the number of characters to retrieve.
230 * @return CStr retrieved substring.
232 CStr
Left(size_t len
) const;
235 * Retrieve last n characters of the CStr.
237 * @param size_t len the number of characters to retrieve.
238 * @return CStr retrieved substring.
240 CStr
Right(size_t len
) const;
243 * Retrieve substring of the CStr after last occurrence of a string.
244 * Return substring of the CStr after the last occurrence of the search string.
246 * @param const CStr & str reference to search string
247 * @param size_t startPos character position to start searching from
248 * @return CStr substring remaining after match
249 * the CStr if no match is found
251 CStr
AfterLast(const CStr
& str
, size_t startPos
= npos
) const;
254 * Retrieve substring of the CStr preceding last occurrence of a string.
255 * Return substring of the CStr preceding the last occurrence of the search string.
257 * @param const CStr & str reference to search string
258 * @param size_t startPos character position to start searching from
259 * @return CStr substring preceding before match
260 * the CStr if no match is found
262 CStr
BeforeLast(const CStr
& str
, size_t startPos
= npos
) const;
265 * Retrieve substring of the CStr after first occurrence of a string.
266 * Return substring of the CStr after the first occurrence of the search string.
268 * @param const CStr & str reference to search string
269 * @param size_t startPos character position to start searching from
270 * @return CStr substring remaining after match
271 * the CStr if no match is found
273 CStr
AfterFirst(const CStr
& str
, size_t startPos
= 0) const;
276 * Retrieve substring of the CStr preceding first occurrence of a string.
277 * Return substring of the CStr preceding the first occurrence of the search string.
279 * @param const CStr & str reference to search string
280 * @param size_t startPos character position to start searching from
281 * @return CStr substring preceding before match
282 * the CStr if no match is found
284 CStr
BeforeFirst(const CStr
& str
, size_t startPos
= 0) const;
287 * Remove all occurrences of a string from the CStr.
289 * @param const CStr & str reference to search string to remove.
291 void Remove(const CStr
& str
);
294 * Replace all occurrences of one string by another string in the CStr.
296 * @param const CStr & strToReplace reference to search string.
297 * @param const CStr & replaceWith reference to replace string.
299 void Replace(const CStr
& toReplace
, const CStr
& replaceWith
);
302 * Convert strings to printable ASCII characters with JSON-style escapes.
304 std::string
EscapeToPrintableASCII() const;
307 * Return a trimmed copy of the CStr.
309 * @param PS_TRIM_MODE Mode value from trim mode enumeration.
310 * @return CStr copy of trimmed CStr.
312 CStr
Trim(PS_TRIM_MODE mode
) const;
315 * Return a space padded copy of the CStr.
317 * @param PS_TRIM_MODE Mode value from trim mode enumeration.
318 * @param size_t Length number of pad spaces to add
319 * @return CStr copy of padded CStr.
321 CStr
Pad(PS_TRIM_MODE mode
, size_t len
) const;
323 // Conversion to u16string
324 std::u16string
utf16() const { return std::u16string(begin(), end()); }
326 // Calculates a hash of the string's contents
327 size_t GetHashCode() const;
329 // Serialization functions
330 // (These are not virtual or inherited from ISerializable, to avoid
331 // adding a vtable and making the strings larger than std::string)
332 size_t GetSerializedLength() const;
333 u8
* Serialize(u8
* buffer
) const;
334 const u8
* Deserialize(const u8
* buffer
, const u8
* bufferend
);
342 std::size_t operator()(const CStr
& str
) const
344 return str
.GetHashCode();
349 #endif // INCLUDED_CSTR