1/**************************************************************************/
2/* ustring.h */
3/**************************************************************************/
4/* This file is part of: */
5/* GODOT ENGINE */
6/* https://godotengine.org */
7/**************************************************************************/
8/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
9/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */
10/* */
11/* Permission is hereby granted, free of charge, to any person obtaining */
12/* a copy of this software and associated documentation files (the */
13/* "Software"), to deal in the Software without restriction, including */
14/* without limitation the rights to use, copy, modify, merge, publish, */
15/* distribute, sublicense, and/or sell copies of the Software, and to */
16/* permit persons to whom the Software is furnished to do so, subject to */
17/* the following conditions: */
18/* */
19/* The above copyright notice and this permission notice shall be */
20/* included in all copies or substantial portions of the Software. */
21/* */
22/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */
23/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */
24/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
25/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */
26/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */
27/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */
28/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
29/**************************************************************************/
30
31#ifndef USTRING_GODOT_H
32#define USTRING_GODOT_H
33
34// Note: _GODOT suffix added to header guard to avoid conflict with ICU header.
35
36#include "core/string/char_utils.h"
37#include "core/templates/cowdata.h"
38#include "core/templates/vector.h"
39#include "core/typedefs.h"
40#include "core/variant/array.h"
41
42/*************************************************************************/
43/* CharProxy */
44/*************************************************************************/
45
46template <class T>
47class CharProxy {
48 friend class Char16String;
49 friend class CharString;
50 friend class String;
51
52 const int _index;
53 CowData<T> &_cowdata;
54 static const T _null = 0;
55
56 _FORCE_INLINE_ CharProxy(const int &p_index, CowData<T> &p_cowdata) :
57 _index(p_index),
58 _cowdata(p_cowdata) {}
59
60public:
61 _FORCE_INLINE_ CharProxy(const CharProxy<T> &p_other) :
62 _index(p_other._index),
63 _cowdata(p_other._cowdata) {}
64
65 _FORCE_INLINE_ operator T() const {
66 if (unlikely(_index == _cowdata.size())) {
67 return _null;
68 }
69
70 return _cowdata.get(_index);
71 }
72
73 _FORCE_INLINE_ const T *operator&() const {
74 return _cowdata.ptr() + _index;
75 }
76
77 _FORCE_INLINE_ void operator=(const T &p_other) const {
78 _cowdata.set(_index, p_other);
79 }
80
81 _FORCE_INLINE_ void operator=(const CharProxy<T> &p_other) const {
82 _cowdata.set(_index, p_other.operator T());
83 }
84};
85
86/*************************************************************************/
87/* Char16String */
88/*************************************************************************/
89
90class Char16String {
91 CowData<char16_t> _cowdata;
92 static const char16_t _null;
93
94public:
95 _FORCE_INLINE_ char16_t *ptrw() { return _cowdata.ptrw(); }
96 _FORCE_INLINE_ const char16_t *ptr() const { return _cowdata.ptr(); }
97 _FORCE_INLINE_ int size() const { return _cowdata.size(); }
98 Error resize(int p_size) { return _cowdata.resize(p_size); }
99
100 _FORCE_INLINE_ char16_t get(int p_index) const { return _cowdata.get(p_index); }
101 _FORCE_INLINE_ void set(int p_index, const char16_t &p_elem) { _cowdata.set(p_index, p_elem); }
102 _FORCE_INLINE_ const char16_t &operator[](int p_index) const {
103 if (unlikely(p_index == _cowdata.size())) {
104 return _null;
105 }
106
107 return _cowdata.get(p_index);
108 }
109 _FORCE_INLINE_ CharProxy<char16_t> operator[](int p_index) { return CharProxy<char16_t>(p_index, _cowdata); }
110
111 _FORCE_INLINE_ Char16String() {}
112 _FORCE_INLINE_ Char16String(const Char16String &p_str) { _cowdata._ref(p_str._cowdata); }
113 _FORCE_INLINE_ void operator=(const Char16String &p_str) { _cowdata._ref(p_str._cowdata); }
114 _FORCE_INLINE_ Char16String(const char16_t *p_cstr) { copy_from(p_cstr); }
115
116 void operator=(const char16_t *p_cstr);
117 bool operator<(const Char16String &p_right) const;
118 Char16String &operator+=(char16_t p_char);
119 int length() const { return size() ? size() - 1 : 0; }
120 const char16_t *get_data() const;
121 operator const char16_t *() const { return get_data(); };
122
123protected:
124 void copy_from(const char16_t *p_cstr);
125};
126
127/*************************************************************************/
128/* CharString */
129/*************************************************************************/
130
131class CharString {
132 CowData<char> _cowdata;
133 static const char _null;
134
135public:
136 _FORCE_INLINE_ char *ptrw() { return _cowdata.ptrw(); }
137 _FORCE_INLINE_ const char *ptr() const { return _cowdata.ptr(); }
138 _FORCE_INLINE_ int size() const { return _cowdata.size(); }
139 Error resize(int p_size) { return _cowdata.resize(p_size); }
140
141 _FORCE_INLINE_ char get(int p_index) const { return _cowdata.get(p_index); }
142 _FORCE_INLINE_ void set(int p_index, const char &p_elem) { _cowdata.set(p_index, p_elem); }
143 _FORCE_INLINE_ const char &operator[](int p_index) const {
144 if (unlikely(p_index == _cowdata.size())) {
145 return _null;
146 }
147
148 return _cowdata.get(p_index);
149 }
150 _FORCE_INLINE_ CharProxy<char> operator[](int p_index) { return CharProxy<char>(p_index, _cowdata); }
151
152 _FORCE_INLINE_ CharString() {}
153 _FORCE_INLINE_ CharString(const CharString &p_str) { _cowdata._ref(p_str._cowdata); }
154 _FORCE_INLINE_ void operator=(const CharString &p_str) { _cowdata._ref(p_str._cowdata); }
155 _FORCE_INLINE_ CharString(const char *p_cstr) { copy_from(p_cstr); }
156
157 void operator=(const char *p_cstr);
158 bool operator<(const CharString &p_right) const;
159 bool operator==(const CharString &p_right) const;
160 CharString &operator+=(char p_char);
161 int length() const { return size() ? size() - 1 : 0; }
162 const char *get_data() const;
163 operator const char *() const { return get_data(); };
164
165protected:
166 void copy_from(const char *p_cstr);
167};
168
169/*************************************************************************/
170/* String */
171/*************************************************************************/
172
173struct StrRange {
174 const char32_t *c_str;
175 int len;
176
177 StrRange(const char32_t *p_c_str = nullptr, int p_len = 0) {
178 c_str = p_c_str;
179 len = p_len;
180 }
181};
182
183class String {
184 CowData<char32_t> _cowdata;
185 static const char32_t _null;
186 static const char32_t _replacement_char;
187
188 void copy_from(const char *p_cstr);
189 void copy_from(const char *p_cstr, const int p_clip_to);
190 void copy_from(const wchar_t *p_cstr);
191 void copy_from(const wchar_t *p_cstr, const int p_clip_to);
192 void copy_from(const char32_t *p_cstr);
193 void copy_from(const char32_t *p_cstr, const int p_clip_to);
194
195 void copy_from(const char32_t &p_char);
196
197 void copy_from_unchecked(const char32_t *p_char, const int p_length);
198
199 bool _base_is_subsequence_of(const String &p_string, bool case_insensitive) const;
200 int _count(const String &p_string, int p_from, int p_to, bool p_case_insensitive) const;
201 String _camelcase_to_underscore() const;
202
203public:
204 enum {
205 npos = -1 ///<for "some" compatibility with std::string (npos is a huge value in std::string)
206 };
207
208 _FORCE_INLINE_ char32_t *ptrw() { return _cowdata.ptrw(); }
209 _FORCE_INLINE_ const char32_t *ptr() const { return _cowdata.ptr(); }
210
211 void remove_at(int p_index) { _cowdata.remove_at(p_index); }
212
213 _FORCE_INLINE_ void clear() { resize(0); }
214
215 _FORCE_INLINE_ char32_t get(int p_index) const { return _cowdata.get(p_index); }
216 _FORCE_INLINE_ void set(int p_index, const char32_t &p_elem) { _cowdata.set(p_index, p_elem); }
217 _FORCE_INLINE_ int size() const { return _cowdata.size(); }
218 Error resize(int p_size) { return _cowdata.resize(p_size); }
219
220 _FORCE_INLINE_ const char32_t &operator[](int p_index) const {
221 if (unlikely(p_index == _cowdata.size())) {
222 return _null;
223 }
224
225 return _cowdata.get(p_index);
226 }
227 _FORCE_INLINE_ CharProxy<char32_t> operator[](int p_index) { return CharProxy<char32_t>(p_index, _cowdata); }
228
229 bool operator==(const String &p_str) const;
230 bool operator!=(const String &p_str) const;
231 String operator+(const String &p_str) const;
232 String operator+(char32_t p_char) const;
233
234 String &operator+=(const String &);
235 String &operator+=(char32_t p_char);
236 String &operator+=(const char *p_str);
237 String &operator+=(const wchar_t *p_str);
238 String &operator+=(const char32_t *p_str);
239
240 /* Compatibility Operators */
241
242 void operator=(const char *p_str);
243 void operator=(const wchar_t *p_str);
244 void operator=(const char32_t *p_str);
245
246 bool operator==(const char *p_str) const;
247 bool operator==(const wchar_t *p_str) const;
248 bool operator==(const char32_t *p_str) const;
249 bool operator==(const StrRange &p_str_range) const;
250
251 bool operator!=(const char *p_str) const;
252 bool operator!=(const wchar_t *p_str) const;
253 bool operator!=(const char32_t *p_str) const;
254
255 bool operator<(const char32_t *p_str) const;
256 bool operator<(const char *p_str) const;
257 bool operator<(const wchar_t *p_str) const;
258
259 bool operator<(const String &p_str) const;
260 bool operator<=(const String &p_str) const;
261 bool operator>(const String &p_str) const;
262 bool operator>=(const String &p_str) const;
263
264 signed char casecmp_to(const String &p_str) const;
265 signed char nocasecmp_to(const String &p_str) const;
266 signed char naturalcasecmp_to(const String &p_str) const;
267 signed char naturalnocasecmp_to(const String &p_str) const;
268
269 const char32_t *get_data() const;
270 /* standard size stuff */
271
272 _FORCE_INLINE_ int length() const {
273 int s = size();
274 return s ? (s - 1) : 0; // length does not include zero
275 }
276
277 bool is_valid_string() const;
278
279 /* debug, error messages */
280 void print_unicode_error(const String &p_message, bool p_critical = false) const;
281
282 /* complex helpers */
283 String substr(int p_from, int p_chars = -1) const;
284 int find(const String &p_str, int p_from = 0) const; ///< return <0 if failed
285 int find(const char *p_str, int p_from = 0) const; ///< return <0 if failed
286 int find_char(const char32_t &p_char, int p_from = 0) const; ///< return <0 if failed
287 int findn(const String &p_str, int p_from = 0) const; ///< return <0 if failed, case insensitive
288 int rfind(const String &p_str, int p_from = -1) const; ///< return <0 if failed
289 int rfindn(const String &p_str, int p_from = -1) const; ///< return <0 if failed, case insensitive
290 int findmk(const Vector<String> &p_keys, int p_from = 0, int *r_key = nullptr) const; ///< return <0 if failed
291 bool match(const String &p_wildcard) const;
292 bool matchn(const String &p_wildcard) const;
293 bool begins_with(const String &p_string) const;
294 bool begins_with(const char *p_string) const;
295 bool ends_with(const String &p_string) const;
296 bool is_enclosed_in(const String &p_string) const;
297 bool is_subsequence_of(const String &p_string) const;
298 bool is_subsequence_ofn(const String &p_string) const;
299 bool is_quoted() const;
300 Vector<String> bigrams() const;
301 float similarity(const String &p_string) const;
302 String format(const Variant &values, String placeholder = "{_}") const;
303 String replace_first(const String &p_key, const String &p_with) const;
304 String replace(const String &p_key, const String &p_with) const;
305 String replace(const char *p_key, const char *p_with) const;
306 String replacen(const String &p_key, const String &p_with) const;
307 String repeat(int p_count) const;
308 String reverse() const;
309 String insert(int p_at_pos, const String &p_string) const;
310 String erase(int p_pos, int p_chars = 1) const;
311 String pad_decimals(int p_digits) const;
312 String pad_zeros(int p_digits) const;
313 String trim_prefix(const String &p_prefix) const;
314 String trim_suffix(const String &p_suffix) const;
315 String lpad(int min_length, const String &character = " ") const;
316 String rpad(int min_length, const String &character = " ") const;
317 String sprintf(const Array &values, bool *error) const;
318 String quote(String quotechar = "\"") const;
319 String unquote() const;
320 static String num(double p_num, int p_decimals = -1);
321 static String num_scientific(double p_num);
322 static String num_real(double p_num, bool p_trailing = true);
323 static String num_int64(int64_t p_num, int base = 10, bool capitalize_hex = false);
324 static String num_uint64(uint64_t p_num, int base = 10, bool capitalize_hex = false);
325 static String chr(char32_t p_char);
326 static String md5(const uint8_t *p_md5);
327 static String hex_encode_buffer(const uint8_t *p_buffer, int p_len);
328 Vector<uint8_t> hex_decode() const;
329
330 bool is_numeric() const;
331
332 double to_float() const;
333 int64_t hex_to_int() const;
334 int64_t bin_to_int() const;
335 int64_t to_int() const;
336
337 static int64_t to_int(const char *p_str, int p_len = -1);
338 static int64_t to_int(const wchar_t *p_str, int p_len = -1);
339 static int64_t to_int(const char32_t *p_str, int p_len = -1, bool p_clamp = false);
340
341 static double to_float(const char *p_str);
342 static double to_float(const wchar_t *p_str, const wchar_t **r_end = nullptr);
343 static double to_float(const char32_t *p_str, const char32_t **r_end = nullptr);
344 static uint32_t num_characters(int64_t p_int);
345
346 String capitalize() const;
347 String to_camel_case() const;
348 String to_pascal_case() const;
349 String to_snake_case() const;
350
351 String get_with_code_lines() const;
352 int get_slice_count(String p_splitter) const;
353 String get_slice(String p_splitter, int p_slice) const;
354 String get_slicec(char32_t p_splitter, int p_slice) const;
355
356 Vector<String> split(const String &p_splitter = "", bool p_allow_empty = true, int p_maxsplit = 0) const;
357 Vector<String> rsplit(const String &p_splitter = "", bool p_allow_empty = true, int p_maxsplit = 0) const;
358 Vector<String> split_spaces() const;
359 Vector<double> split_floats(const String &p_splitter, bool p_allow_empty = true) const;
360 Vector<float> split_floats_mk(const Vector<String> &p_splitters, bool p_allow_empty = true) const;
361 Vector<int> split_ints(const String &p_splitter, bool p_allow_empty = true) const;
362 Vector<int> split_ints_mk(const Vector<String> &p_splitters, bool p_allow_empty = true) const;
363
364 String join(Vector<String> parts) const;
365
366 static char32_t char_uppercase(char32_t p_char);
367 static char32_t char_lowercase(char32_t p_char);
368 String to_upper() const;
369 String to_lower() const;
370
371 int count(const String &p_string, int p_from = 0, int p_to = 0) const;
372 int countn(const String &p_string, int p_from = 0, int p_to = 0) const;
373
374 String left(int p_len) const;
375 String right(int p_len) const;
376 String indent(const String &p_prefix) const;
377 String dedent() const;
378 String strip_edges(bool left = true, bool right = true) const;
379 String strip_escapes() const;
380 String lstrip(const String &p_chars) const;
381 String rstrip(const String &p_chars) const;
382 String get_extension() const;
383 String get_basename() const;
384 String path_join(const String &p_file) const;
385 char32_t unicode_at(int p_idx) const;
386
387 CharString ascii(bool p_allow_extended = false) const;
388 CharString utf8() const;
389 Error parse_utf8(const char *p_utf8, int p_len = -1, bool p_skip_cr = false);
390 static String utf8(const char *p_utf8, int p_len = -1);
391
392 Char16String utf16() const;
393 Error parse_utf16(const char16_t *p_utf16, int p_len = -1);
394 static String utf16(const char16_t *p_utf16, int p_len = -1);
395
396 static uint32_t hash(const char32_t *p_cstr, int p_len); /* hash the string */
397 static uint32_t hash(const char32_t *p_cstr); /* hash the string */
398 static uint32_t hash(const wchar_t *p_cstr, int p_len); /* hash the string */
399 static uint32_t hash(const wchar_t *p_cstr); /* hash the string */
400 static uint32_t hash(const char *p_cstr, int p_len); /* hash the string */
401 static uint32_t hash(const char *p_cstr); /* hash the string */
402 uint32_t hash() const; /* hash the string */
403 uint64_t hash64() const; /* hash the string */
404 String md5_text() const;
405 String sha1_text() const;
406 String sha256_text() const;
407 Vector<uint8_t> md5_buffer() const;
408 Vector<uint8_t> sha1_buffer() const;
409 Vector<uint8_t> sha256_buffer() const;
410
411 _FORCE_INLINE_ bool is_empty() const { return length() == 0; }
412 _FORCE_INLINE_ bool contains(const char *p_str) const { return find(p_str) != -1; }
413 _FORCE_INLINE_ bool contains(const String &p_str) const { return find(p_str) != -1; }
414
415 // path functions
416 bool is_absolute_path() const;
417 bool is_relative_path() const;
418 bool is_resource_file() const;
419 String path_to(const String &p_path) const;
420 String path_to_file(const String &p_path) const;
421 String get_base_dir() const;
422 String get_file() const;
423 static String humanize_size(uint64_t p_size);
424 String simplify_path() const;
425 bool is_network_share_path() const;
426
427 String xml_escape(bool p_escape_quotes = false) const;
428 String xml_unescape() const;
429 String uri_encode() const;
430 String uri_decode() const;
431 String c_escape() const;
432 String c_escape_multiline() const;
433 String c_unescape() const;
434 String json_escape() const;
435 Error parse_url(String &r_scheme, String &r_host, int &r_port, String &r_path) const;
436
437 String property_name_encode() const;
438
439 // node functions
440 static String get_invalid_node_name_characters();
441 String validate_node_name() const;
442 String validate_identifier() const;
443 String validate_filename() const;
444
445 bool is_valid_identifier() const;
446 bool is_valid_int() const;
447 bool is_valid_float() const;
448 bool is_valid_hex_number(bool p_with_prefix) const;
449 bool is_valid_html_color() const;
450 bool is_valid_ip_address() const;
451 bool is_valid_filename() const;
452
453 /**
454 * The constructors must not depend on other overloads
455 */
456
457 _FORCE_INLINE_ String() {}
458 _FORCE_INLINE_ String(const String &p_str) { _cowdata._ref(p_str._cowdata); }
459 _FORCE_INLINE_ void operator=(const String &p_str) { _cowdata._ref(p_str._cowdata); }
460
461 Vector<uint8_t> to_ascii_buffer() const;
462 Vector<uint8_t> to_utf8_buffer() const;
463 Vector<uint8_t> to_utf16_buffer() const;
464 Vector<uint8_t> to_utf32_buffer() const;
465 Vector<uint8_t> to_wchar_buffer() const;
466
467 String(const char *p_str);
468 String(const wchar_t *p_str);
469 String(const char32_t *p_str);
470 String(const char *p_str, int p_clip_to_len);
471 String(const wchar_t *p_str, int p_clip_to_len);
472 String(const char32_t *p_str, int p_clip_to_len);
473 String(const StrRange &p_range);
474};
475
476bool operator==(const char *p_chr, const String &p_str);
477bool operator==(const wchar_t *p_chr, const String &p_str);
478bool operator!=(const char *p_chr, const String &p_str);
479bool operator!=(const wchar_t *p_chr, const String &p_str);
480
481String operator+(const char *p_chr, const String &p_str);
482String operator+(const wchar_t *p_chr, const String &p_str);
483String operator+(char32_t p_chr, const String &p_str);
484
485String itos(int64_t p_val);
486String uitos(uint64_t p_val);
487String rtos(double p_val);
488String rtoss(double p_val); //scientific version
489
490struct NoCaseComparator {
491 bool operator()(const String &p_a, const String &p_b) const {
492 return p_a.nocasecmp_to(p_b) < 0;
493 }
494};
495
496struct NaturalNoCaseComparator {
497 bool operator()(const String &p_a, const String &p_b) const {
498 return p_a.naturalnocasecmp_to(p_b) < 0;
499 }
500};
501
502template <typename L, typename R>
503_FORCE_INLINE_ bool is_str_less(const L *l_ptr, const R *r_ptr) {
504 while (true) {
505 const char32_t l = *l_ptr;
506 const char32_t r = *r_ptr;
507
508 if (l == 0 && r == 0) {
509 return false;
510 } else if (l == 0) {
511 return true;
512 } else if (r == 0) {
513 return false;
514 } else if (l < r) {
515 return true;
516 } else if (l > r) {
517 return false;
518 }
519
520 l_ptr++;
521 r_ptr++;
522 }
523}
524
525/* end of namespace */
526
527// Tool translate (TTR and variants) for the editor UI,
528// and doc translate for the class reference (DTR).
529#ifdef TOOLS_ENABLED
530// Gets parsed.
531String TTR(const String &p_text, const String &p_context = "");
532String TTRN(const String &p_text, const String &p_text_plural, int p_n, const String &p_context = "");
533String DTR(const String &p_text, const String &p_context = "");
534String DTRN(const String &p_text, const String &p_text_plural, int p_n, const String &p_context = "");
535// Use for C strings.
536#define TTRC(m_value) (m_value)
537// Use to avoid parsing (for use later with C strings).
538#define TTRGET(m_value) TTR(m_value)
539
540#else
541#define TTRC(m_value) (m_value)
542#define TTRGET(m_value) (m_value)
543#endif
544
545// Use this to mark property names for editor translation.
546// Often for dynamic properties defined in _get_property_list().
547// Property names defined directly inside EDITOR_DEF, GLOBAL_DEF, and ADD_PROPERTY macros don't need this.
548#define PNAME(m_value) (m_value)
549
550// Similar to PNAME, but to mark groups, i.e. properties with PROPERTY_USAGE_GROUP.
551// Groups defined directly inside ADD_GROUP macros don't need this.
552// The arguments are the same as ADD_GROUP. m_prefix is only used for extraction.
553#define GNAME(m_value, m_prefix) (m_value)
554
555// Runtime translate for the public node API.
556String RTR(const String &p_text, const String &p_context = "");
557String RTRN(const String &p_text, const String &p_text_plural, int p_n, const String &p_context = "");
558
559bool select_word(const String &p_s, int p_col, int &r_beg, int &r_end);
560
561_FORCE_INLINE_ void sarray_add_str(Vector<String> &arr) {
562}
563
564_FORCE_INLINE_ void sarray_add_str(Vector<String> &arr, const String &p_str) {
565 arr.push_back(p_str);
566}
567
568template <class... P>
569_FORCE_INLINE_ void sarray_add_str(Vector<String> &arr, const String &p_str, P... p_args) {
570 arr.push_back(p_str);
571 sarray_add_str(arr, p_args...);
572}
573
574template <class... P>
575_FORCE_INLINE_ Vector<String> sarray(P... p_args) {
576 Vector<String> arr;
577 sarray_add_str(arr, p_args...);
578 return arr;
579}
580
581#endif // USTRING_GODOT_H
582