OpenShot Audio Library | OpenShotAudio 0.3.2
Loading...
Searching...
No Matches
juce_String.h
1/*
2 ==============================================================================
3
4 This file is part of the JUCE library.
5 Copyright (c) 2017 - ROLI Ltd.
6
7 JUCE is an open source library subject to commercial or open-source
8 licensing.
9
10 The code included in this file is provided under the terms of the ISC license
11 http://www.isc.org/downloads/software-support-policy/isc-license. Permission
12 To use, copy, modify, and/or distribute this software for any purpose with or
13 without fee is hereby granted provided that the above copyright notice and
14 this permission notice appear in all copies.
15
16 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
17 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
18 DISCLAIMED.
19
20 ==============================================================================
21*/
22
23namespace juce
24{
25
26//==============================================================================
38class JUCE_API String final
39{
40public:
41 //==============================================================================
45 String() noexcept;
46
48 String (const String&) noexcept;
49
51 String (String&&) noexcept;
52
66 String (const char* text);
67
84 String (const char* text, size_t maxChars);
85
89 String (const wchar_t* text);
90
94 String (const wchar_t* text, size_t maxChars);
95
96 //==============================================================================
99
101 String (CharPointer_UTF8 text, size_t maxChars);
102
105
106 //==============================================================================
109
111 String (CharPointer_UTF16 text, size_t maxChars);
112
115
116 //==============================================================================
119
121 String (CharPointer_UTF32 text, size_t maxChars);
122
125
126 //==============================================================================
129
131 String (const std::string&);
132
135
136 //==============================================================================
138 static String charToString (juce_wchar character);
139
141 ~String() noexcept;
142
155 #if (JUCE_STRING_UTF_TYPE == 32)
156 using CharPointerType = CharPointer_UTF32;
157 #elif (JUCE_STRING_UTF_TYPE == 16)
158 using CharPointerType = CharPointer_UTF16;
159 #elif (DOXYGEN || JUCE_STRING_UTF_TYPE == 8)
160 using CharPointerType = CharPointer_UTF8;
161 #else
162 #error "You must set the value of JUCE_STRING_UTF_TYPE to be either 8, 16, or 32!"
163 #endif
164
165 //==============================================================================
167 int hashCode() const noexcept;
168
170 int64 hashCode64() const noexcept;
171
173 size_t hash() const noexcept;
174
176 int length() const noexcept;
177
178 //==============================================================================
179 // Assignment and concatenation operators..
180
182 String& operator= (const String& other) noexcept;
183
185 String& operator= (String&& other) noexcept;
186
190 String& operator+= (const char* textToAppend);
192 String& operator+= (const wchar_t* textToAppend);
207 #if ! JUCE_NATIVE_WCHAR_IS_UTF32
210 #endif
211
217 void append (const String& textToAppend, size_t maxCharsToTake);
218
224 void appendCharPointer (CharPointerType startOfTextToAppend,
225 CharPointerType endOfTextToAppend);
226
232 template <class CharPointer>
235 {
236 jassert (startOfTextToAppend.getAddress() != nullptr && endOfTextToAppend.getAddress() != nullptr);
237
238 size_t extraBytesNeeded = 0, numChars = 1;
239
240 for (auto t = startOfTextToAppend; t != endOfTextToAppend && ! t.isEmpty(); ++numChars)
241 extraBytesNeeded += CharPointerType::getBytesRequiredFor (t.getAndAdvance());
242
243 if (extraBytesNeeded > 0)
244 {
245 auto byteOffsetOfNull = getByteOffsetOfEnd();
246
247 preallocateBytes (byteOffsetOfNull + extraBytesNeeded);
248 CharPointerType (addBytesToPointer (text.getAddress(), (int) byteOffsetOfNull))
249 .writeWithCharLimit (startOfTextToAppend, (int) numChars);
250 }
251 }
252
254 void appendCharPointer (CharPointerType textToAppend);
255
261 template <class CharPointer>
263 {
264 if (textToAppend.getAddress() != nullptr)
265 {
266 size_t extraBytesNeeded = 0, numChars = 1;
267
268 for (auto t = textToAppend; numChars <= maxCharsToTake && ! t.isEmpty(); ++numChars)
269 extraBytesNeeded += CharPointerType::getBytesRequiredFor (t.getAndAdvance());
270
271 if (extraBytesNeeded > 0)
272 {
273 auto byteOffsetOfNull = getByteOffsetOfEnd();
274
275 preallocateBytes (byteOffsetOfNull + extraBytesNeeded);
276 CharPointerType (addBytesToPointer (text.getAddress(), (int) byteOffsetOfNull))
277 .writeWithCharLimit (textToAppend, (int) numChars);
278 }
279 }
280 }
281
283 template <class CharPointer>
285 {
286 appendCharPointer (textToAppend, std::numeric_limits<size_t>::max());
287 }
288
289 //==============================================================================
290 // Comparison methods..
291
296 inline bool isEmpty() const noexcept { return text.isEmpty(); }
297
302 inline bool isNotEmpty() const noexcept { return ! text.isEmpty(); }
303
305 void clear() noexcept;
306
308 bool equalsIgnoreCase (const String& other) const noexcept;
309
311 bool equalsIgnoreCase (StringRef other) const noexcept;
312
314 bool equalsIgnoreCase (const wchar_t* other) const noexcept;
315
317 bool equalsIgnoreCase (const char* other) const noexcept;
318
323 int compare (const String& other) const noexcept;
324
329 int compare (const char* other) const noexcept;
330
335 int compare (const wchar_t* other) const noexcept;
336
341 int compareIgnoreCase (const String& other) const noexcept;
342
351 int compareNatural (StringRef other, bool isCaseSensitive = false) const noexcept;
352
357 bool startsWith (StringRef text) const noexcept;
358
363 bool startsWithChar (juce_wchar character) const noexcept;
364
369 bool startsWithIgnoreCase (StringRef text) const noexcept;
370
375 bool endsWith (StringRef text) const noexcept;
376
381 bool endsWithChar (juce_wchar character) const noexcept;
382
387 bool endsWithIgnoreCase (StringRef text) const noexcept;
388
393 bool contains (StringRef text) const noexcept;
394
398 bool containsChar (juce_wchar character) const noexcept;
399
403 bool containsIgnoreCase (StringRef text) const noexcept;
404
411 bool containsWholeWord (StringRef wordToLookFor) const noexcept;
412
419 bool containsWholeWordIgnoreCase (StringRef wordToLookFor) const noexcept;
420
428 int indexOfWholeWord (StringRef wordToLookFor) const noexcept;
429
437 int indexOfWholeWordIgnoreCase (StringRef wordToLookFor) const noexcept;
438
446
455
463 bool containsNonWhitespaceChars() const noexcept;
464
472 bool matchesWildcard (StringRef wildcard, bool ignoreCase) const noexcept;
473
474 //==============================================================================
475 // Substring location methods..
476
482 int indexOfChar (juce_wchar characterToLookFor) const noexcept;
483
491 int indexOfChar (int startIndex, juce_wchar characterToLookFor) const noexcept;
492
505 int indexOfAnyOf (StringRef charactersToLookFor,
506 int startIndex = 0,
507 bool ignoreCase = false) const noexcept;
508
515
523 int indexOf (int startIndex, StringRef textToLookFor) const noexcept;
524
530 int indexOfIgnoreCase (StringRef textToLookFor) const noexcept;
531
539 int indexOfIgnoreCase (int startIndex, StringRef textToLookFor) const noexcept;
540
545 int lastIndexOfChar (juce_wchar character) const noexcept;
546
552 int lastIndexOf (StringRef textToLookFor) const noexcept;
553
559 int lastIndexOfIgnoreCase (StringRef textToLookFor) const noexcept;
560
573 int lastIndexOfAnyOf (StringRef charactersToLookFor,
574 bool ignoreCase = false) const noexcept;
575
576
577 //==============================================================================
578 // Substring extraction and manipulation methods..
579
591 juce_wchar operator[] (int index) const noexcept;
592
596 juce_wchar getLastCharacter() const noexcept;
597
598 //==============================================================================
609 String substring (int startIndex, int endIndex) const;
610
619 String substring (int startIndex) const;
620
630 String dropLastCharacters (int numberToDrop) const;
631
639 String getLastCharacters (int numCharacters) const;
640
641 //==============================================================================
657 String fromFirstOccurrenceOf (StringRef substringToStartFrom,
659 bool ignoreCase) const;
660
669 String fromLastOccurrenceOf (StringRef substringToFind,
671 bool ignoreCase) const;
672
686 String upToFirstOccurrenceOf (StringRef substringToEndWith,
688 bool ignoreCase) const;
689
697 String upToLastOccurrenceOf (StringRef substringToFind,
699 bool ignoreCase) const;
700
701 //==============================================================================
703 String trim() const;
704
706 String trimStart() const;
707
709 String trimEnd() const;
710
717 String trimCharactersAtStart (StringRef charactersToTrim) const;
718
725 String trimCharactersAtEnd (StringRef charactersToTrim) const;
726
727 //==============================================================================
729 String toUpperCase() const;
730
732 String toLowerCase() const;
733
734 //==============================================================================
750 String replaceSection (int startIndex,
753
763 bool ignoreCase = false) const;
764
772 String replaceFirstOccurrenceOf (StringRef stringToReplace,
774 bool ignoreCase = false) const;
775
777 String replaceCharacter (juce_wchar characterToReplace,
779
790 String replaceCharacters (StringRef charactersToReplace,
792
802 String retainCharacters (StringRef charactersToRetain) const;
803
813 String removeCharacters (StringRef charactersToRemove) const;
814
820 String initialSectionContainingOnly (StringRef permittedCharacters) const;
821
828 String initialSectionNotContaining (StringRef charactersToStopAt) const;
829
830 //==============================================================================
837 bool isQuotedString() const;
838
849 String unquoted() const;
850
862 String quoted (juce_wchar quoteCharacter = '"') const;
863
864
865 //==============================================================================
871 static String repeatedString (StringRef stringToRepeat,
873
877 String paddedLeft (juce_wchar padCharacter, int minimumLength) const;
878
882 String paddedRight (juce_wchar padCharacter, int minimumLength) const;
883
892 static String createStringFromData (const void* data, int size);
893
905 template <typename... Args>
906 static String formatted (const String& formatStr, Args... args) { return formattedRaw (formatStr.toRawUTF8(), args...); }
907
908 //==============================================================================
909 // Numeric conversions..
910
914 explicit String (int decimalInteger);
915
919 explicit String (unsigned int decimalInteger);
920
924 explicit String (short decimalInteger);
925
929 explicit String (unsigned short decimalInteger);
930
934 explicit String (int64 largeIntegerValue);
935
939 explicit String (uint64 largeIntegerValue);
940
944 explicit String (long decimalInteger);
945
949 explicit String (unsigned long decimalInteger);
950
955 explicit String (float floatValue);
956
961 explicit String (double doubleValue);
962
974
984 String (double doubleValue, int numberOfDecimalPlaces, bool useScientificNotation = false);
985
986 #ifndef DOXYGEN
987 // Automatically creating a String from a bool opens up lots of nasty type conversion edge cases.
988 // If you want a String representation of a bool you can cast the bool to an int first.
989 explicit String (bool) = delete;
990 #endif
991
997 int getIntValue() const noexcept;
998
1002 int64 getLargeIntValue() const noexcept;
1003
1013 int getTrailingIntValue() const noexcept;
1014
1020 float getFloatValue() const noexcept;
1021
1027 double getDoubleValue() const noexcept;
1028
1038 int getHexValue32() const noexcept;
1039
1049 int64 getHexValue64() const noexcept;
1050
1053 static String toHexString (IntegerType number) { return createHex (number); }
1054
1064 static String toHexString (const void* data, int size, int groupSize = 1);
1065
1071 template <typename DecimalType>
1073 {
1074 jassert (numberOfSignificantFigures > 0);
1075
1076 if (number == 0)
1077 {
1079 {
1080 String result ("0.0");
1081
1082 for (int i = 2; i < numberOfSignificantFigures; ++i)
1083 result += "0";
1084
1085 return result;
1086 }
1087
1088 return "0";
1089 }
1090
1091 auto numDigitsBeforePoint = (int) std::ceil (std::log10 (number < 0 ? -number : number));
1092
1093 #if JUCE_PROJUCER_LIVE_BUILD
1094 auto doubleNumber = (double) number;
1095 constexpr int bufferSize = 311;
1096 char buffer[bufferSize];
1097 auto* ptr = &(buffer[0]);
1098 auto* const safeEnd = ptr + (bufferSize - 1);
1099 auto numSigFigsParsed = 0;
1100
1101 auto writeToBuffer = [safeEnd] (char* destination, char data)
1102 {
1103 *destination++ = data;
1104
1105 if (destination == safeEnd)
1106 {
1107 *destination = '\0';
1108 return true;
1109 }
1110
1111 return false;
1112 };
1113
1115 {
1116 return (sigFigsParsed == numberOfSignificantFigures - 1) ? (int) std::round (fractional)
1117 : (int) fractional;
1118 };
1119
1120 if (doubleNumber < 0)
1121 {
1122 doubleNumber *= -1;
1123 *ptr++ = '-';
1124 }
1125
1126 if (numDigitsBeforePoint > 0)
1127 {
1128 doubleNumber /= std::pow (10.0, numDigitsBeforePoint);
1129
1130 while (numDigitsBeforePoint-- > 0)
1131 {
1133 {
1134 if (writeToBuffer (ptr++, '0'))
1135 return buffer;
1136
1137 continue;
1138 }
1139
1140 doubleNumber *= 10;
1142
1143 if (writeToBuffer (ptr++, (char) ('0' + digit)))
1144 return buffer;
1145
1148 }
1149
1151 {
1152 *ptr++ = '\0';
1153 return buffer;
1154 }
1155 }
1156 else
1157 {
1158 *ptr++ = '0';
1159 }
1160
1161 if (writeToBuffer (ptr++, '.'))
1162 return buffer;
1163
1165 {
1166 doubleNumber *= 10;
1168
1169 if (writeToBuffer (ptr++, (char) ('0' + digit)))
1170 return buffer;
1171
1172 if (numSigFigsParsed != 0 || digit != 0)
1174
1176 }
1177
1178 *ptr++ = '\0';
1179 return buffer;
1180 #else
1182 auto factor = std::pow (10.0, shift);
1183 auto rounded = std::round (number * factor) / factor;
1184
1185 std::stringstream ss;
1186 ss << std::fixed << std::setprecision (std::max (shift, 0)) << rounded;
1187 return ss.str();
1188 #endif
1189 }
1190
1191 //==============================================================================
1198 inline CharPointerType getCharPointer() const noexcept { return text; }
1199
1211 CharPointer_UTF8 toUTF8() const;
1212
1224 const char* toRawUTF8() const;
1225
1237 CharPointer_UTF16 toUTF16() const;
1238
1247 CharPointer_UTF32 toUTF32() const;
1248
1261 const wchar_t* toWideCharPointer() const;
1262
1264 std::string toStdString() const;
1265
1266 //==============================================================================
1270 static String fromUTF8 (const char* utf8buffer, int bufferSizeBytes = -1);
1271
1276 size_t getNumBytesAsUTF8() const noexcept;
1277
1278 //==============================================================================
1294 size_t copyToUTF8 (CharPointer_UTF8::CharType* destBuffer, size_t maxBufferSizeBytes) const noexcept;
1295
1311 size_t copyToUTF16 (CharPointer_UTF16::CharType* destBuffer, size_t maxBufferSizeBytes) const noexcept;
1312
1328 size_t copyToUTF32 (CharPointer_UTF32::CharType* destBuffer, size_t maxBufferSizeBytes) const noexcept;
1329
1330 //==============================================================================
1345 void preallocateBytes (size_t numBytesNeeded);
1346
1350 void swapWith (String& other) noexcept;
1351
1352 //==============================================================================
1353 #if JUCE_MAC || JUCE_IOS || DOXYGEN
1356
1361 CFStringRef toCFString() const;
1362
1366 #endif
1367
1371 int getReferenceCount() const noexcept;
1372
1373 //==============================================================================
1374 /* This was a static empty string object, but is now deprecated as it's too easy to accidentally
1375 use it indirectly during a static constructor, leading to hard-to-find order-of-initialisation
1376 problems.
1377 @deprecated If you need an empty String object, just use String() or {}.
1378 The only time you might miss having String::empty available might be if you need to return an
1379 empty string from a function by reference, but if you need to do that, it's easy enough to use
1380 a function-local static String object and return that, avoiding any order-of-initialisation issues.
1381 */
1382 JUCE_DEPRECATED_STATIC (static const String empty;)
1383
1384private:
1385 //==============================================================================
1386 CharPointerType text;
1387
1388 //==============================================================================
1389 struct PreallocationBytes
1390 {
1391 explicit PreallocationBytes (size_t) noexcept;
1392 size_t numBytes;
1393 };
1394
1395 explicit String (const PreallocationBytes&); // This constructor preallocates a certain amount of memory
1396 size_t getByteOffsetOfEnd() const noexcept;
1397 JUCE_DEPRECATED (String (const String&, size_t));
1398
1399 // This private cast operator should prevent strings being accidentally cast
1400 // to bools (this is possible because the compiler can add an implicit cast
1401 // via a const char*)
1402 operator bool() const noexcept { return false; }
1403
1404 //==============================================================================
1405 static String formattedRaw (const char*, ...);
1406
1407 static String createHex (uint8);
1408 static String createHex (uint16);
1409 static String createHex (uint32);
1410 static String createHex (uint64);
1411
1412 template <typename Type>
1413 static String createHex (Type n) { return createHex (static_cast<typename TypeHelpers::UnsignedTypeWithSize<(int) sizeof (n)>::type> (n)); }
1414};
1415
1416//==============================================================================
1418JUCE_API String JUCE_CALLTYPE operator+ (const char* string1, const String& string2);
1420JUCE_API String JUCE_CALLTYPE operator+ (const wchar_t* string1, const String& string2);
1422JUCE_API String JUCE_CALLTYPE operator+ (char string1, const String& string2);
1424JUCE_API String JUCE_CALLTYPE operator+ (wchar_t string1, const String& string2);
1425#if ! JUCE_NATIVE_WCHAR_IS_UTF32
1427JUCE_API String JUCE_CALLTYPE operator+ (juce_wchar string1, const String& string2);
1428#endif
1429
1431JUCE_API String JUCE_CALLTYPE operator+ (String string1, const String& string2);
1433JUCE_API String JUCE_CALLTYPE operator+ (String string1, const char* string2);
1435JUCE_API String JUCE_CALLTYPE operator+ (String string1, const wchar_t* string2);
1437JUCE_API String JUCE_CALLTYPE operator+ (String string1, const std::string& string2);
1439JUCE_API String JUCE_CALLTYPE operator+ (String string1, char characterToAppend);
1441JUCE_API String JUCE_CALLTYPE operator+ (String string1, wchar_t characterToAppend);
1442#if ! JUCE_NATIVE_WCHAR_IS_UTF32
1444JUCE_API String JUCE_CALLTYPE operator+ (String string1, juce_wchar characterToAppend);
1445#endif
1446
1447//==============================================================================
1449JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, char characterToAppend);
1451JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, wchar_t characterToAppend);
1452#if ! JUCE_NATIVE_WCHAR_IS_UTF32
1454JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, juce_wchar characterToAppend);
1455#endif
1456
1458JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, const char* string2);
1460JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, const wchar_t* string2);
1462JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, const String& string2);
1464JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, StringRef string2);
1466JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, const std::string& string2);
1467
1469JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, uint8 number);
1471JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, short number);
1473JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, int number);
1475JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, long number);
1477JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, unsigned long number);
1479JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, int64 number);
1481JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, uint64 number);
1483JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, float number);
1485JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, double number);
1486
1487#ifndef DOXYGEN
1488// Automatically creating a String from a bool opens up lots of nasty type conversion edge cases.
1489// If you want a String representation of a bool you can cast the bool to an int first.
1490String& JUCE_CALLTYPE operator<< (String&, bool) = delete;
1491#endif
1492
1493//==============================================================================
1495JUCE_API bool JUCE_CALLTYPE operator== (const String& string1, const String& string2) noexcept;
1497JUCE_API bool JUCE_CALLTYPE operator== (const String& string1, const char* string2) noexcept;
1499JUCE_API bool JUCE_CALLTYPE operator== (const String& string1, const wchar_t* string2) noexcept;
1501JUCE_API bool JUCE_CALLTYPE operator== (const String& string1, CharPointer_UTF8 string2) noexcept;
1503JUCE_API bool JUCE_CALLTYPE operator== (const String& string1, CharPointer_UTF16 string2) noexcept;
1505JUCE_API bool JUCE_CALLTYPE operator== (const String& string1, CharPointer_UTF32 string2) noexcept;
1506
1508JUCE_API bool JUCE_CALLTYPE operator!= (const String& string1, const String& string2) noexcept;
1510JUCE_API bool JUCE_CALLTYPE operator!= (const String& string1, const char* string2) noexcept;
1512JUCE_API bool JUCE_CALLTYPE operator!= (const String& string1, const wchar_t* string2) noexcept;
1514JUCE_API bool JUCE_CALLTYPE operator!= (const String& string1, CharPointer_UTF8 string2) noexcept;
1516JUCE_API bool JUCE_CALLTYPE operator!= (const String& string1, CharPointer_UTF16 string2) noexcept;
1518JUCE_API bool JUCE_CALLTYPE operator!= (const String& string1, CharPointer_UTF32 string2) noexcept;
1519
1520//==============================================================================
1524template <class traits>
1525std::basic_ostream <char, traits>& JUCE_CALLTYPE operator<< (std::basic_ostream <char, traits>& stream, const String& stringToWrite)
1526{
1527 return stream << stringToWrite.toRawUTF8();
1528}
1529
1533template <class traits>
1534std::basic_ostream <wchar_t, traits>& JUCE_CALLTYPE operator<< (std::basic_ostream <wchar_t, traits>& stream, const String& stringToWrite)
1535{
1536 return stream << stringToWrite.toWideCharPointer();
1537}
1538
1540JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const String& stringToWrite);
1541
1543JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, StringRef stringToWrite);
1544
1545} // namespace juce
1546
1547#if ! DOXYGEN
1548namespace std
1549{
1550 template <> struct hash<juce::String>
1551 {
1552 size_t operator() (const juce::String& s) const noexcept { return s.hash(); }
1553 };
1554}
1555#endif
bool isEmpty() const noexcept
Definition juce_Array.h:222
CharPointerType getCharPointer() const noexcept
bool isEmpty() const noexcept
static String toDecimalStringWithSignificantFigures(DecimalType number, int numberOfSignificantFigures)
void appendCharPointer(CharPointer startOfTextToAppend, CharPointer endOfTextToAppend)
void appendCharPointer(CharPointer textToAppend, size_t maxCharsToTake)
void appendCharPointer(CharPointer textToAppend)
bool isNotEmpty() const noexcept