OpenShot Library | libopenshot-audio  0.1.9
juce::String Class Referencefinal

The JUCE String class! More...

#include <juce_String.h>

Public Types

using CharPointerType = CharPointer_UTF8
 This is the character encoding type used internally to store the string. More...
 

Public Member Functions

 String () noexcept
 Creates an empty string. More...
 
 String (const String &) noexcept
 Creates a copy of another string. More...
 
 String (String &&) noexcept
 Move constructor.
 
 String (const char *text)
 Creates a string from a zero-terminated ascii text string. More...
 
 String (const char *text, size_t maxChars)
 Creates a string from a string of 8-bit ascii characters. More...
 
 String (const wchar_t *text)
 Creates a string from a wchar_t character string. More...
 
 String (const wchar_t *text, size_t maxChars)
 Creates a string from a wchar_t character string. More...
 
 String (CharPointer_UTF8 text)
 Creates a string from a UTF-8 character string.
 
 String (CharPointer_UTF8 text, size_t maxChars)
 Creates a string from a UTF-8 character string.
 
 String (CharPointer_UTF8 start, CharPointer_UTF8 end)
 Creates a string from a UTF-8 character string.
 
 String (CharPointer_UTF16 text)
 Creates a string from a UTF-16 character string.
 
 String (CharPointer_UTF16 text, size_t maxChars)
 Creates a string from a UTF-16 character string.
 
 String (CharPointer_UTF16 start, CharPointer_UTF16 end)
 Creates a string from a UTF-16 character string.
 
 String (CharPointer_UTF32 text)
 Creates a string from a UTF-32 character string.
 
 String (CharPointer_UTF32 text, size_t maxChars)
 Creates a string from a UTF-32 character string.
 
 String (CharPointer_UTF32 start, CharPointer_UTF32 end)
 Creates a string from a UTF-32 character string.
 
 String (CharPointer_ASCII text)
 Creates a string from an ASCII character string.
 
 String (const std::string &)
 Creates a string from a UTF-8 encoded std::string. More...
 
 String (StringRef)
 Creates a string from a StringRef.
 
 ~String () noexcept
 Destructor. More...
 
int hashCode () const noexcept
 Generates a probably-unique 32-bit hashcode from this string. More...
 
int64 hashCode64 () const noexcept
 Generates a probably-unique 64-bit hashcode from this string. More...
 
size_t hash () const noexcept
 Generates a probably-unique hashcode from this string. More...
 
int length () const noexcept
 Returns the number of characters in the string. More...
 
Stringoperator= (const String &other) noexcept
 Replaces this string's contents with another string. More...
 
Stringoperator= (String &&other) noexcept
 Moves the contents of another string to the receiver.
 
Stringoperator+= (const String &stringToAppend)
 Appends another string at the end of this one. More...
 
Stringoperator+= (const char *textToAppend)
 Appends another string at the end of this one. More...
 
Stringoperator+= (const wchar_t *textToAppend)
 Appends another string at the end of this one. More...
 
Stringoperator+= (StringRef textToAppend)
 Appends another string at the end of this one. More...
 
Stringoperator+= (int numberToAppend)
 Appends a decimal number at the end of this string. More...
 
Stringoperator+= (long numberToAppend)
 Appends a decimal number at the end of this string. More...
 
Stringoperator+= (int64 numberToAppend)
 Appends a decimal number at the end of this string. More...
 
Stringoperator+= (uint64 numberToAppend)
 Appends a decimal number at the end of this string. More...
 
Stringoperator+= (char characterToAppend)
 Appends a character at the end of this string. More...
 
Stringoperator+= (wchar_t characterToAppend)
 Appends a character at the end of this string. More...
 
Stringoperator+= (juce_wchar characterToAppend)
 Appends a character at the end of this string. More...
 
void append (const String &textToAppend, size_t maxCharsToTake)
 Appends a string to the end of this one. More...
 
void appendCharPointer (CharPointerType startOfTextToAppend, CharPointerType endOfTextToAppend)
 Appends a string to the end of this one. More...
 
template<class CharPointer >
void appendCharPointer (CharPointer startOfTextToAppend, CharPointer endOfTextToAppend)
 Appends a string to the end of this one. More...
 
void appendCharPointer (CharPointerType textToAppend)
 Appends a string to the end of this one. More...
 
template<class CharPointer >
void appendCharPointer (CharPointer textToAppend, size_t maxCharsToTake)
 Appends a string to the end of this one. More...
 
template<class CharPointer >
void appendCharPointer (CharPointer textToAppend)
 Appends a string to the end of this one. More...
 
bool isEmpty () const noexcept
 Returns true if the string contains no characters. More...
 
bool isNotEmpty () const noexcept
 Returns true if the string contains at least one character. More...
 
void clear () noexcept
 Resets this string to be empty. More...
 
bool equalsIgnoreCase (const String &other) const noexcept
 Case-insensitive comparison with another string. More...
 
bool equalsIgnoreCase (StringRef other) const noexcept
 Case-insensitive comparison with another string. More...
 
bool equalsIgnoreCase (const wchar_t *other) const noexcept
 Case-insensitive comparison with another string. More...
 
bool equalsIgnoreCase (const char *other) const noexcept
 Case-insensitive comparison with another string. More...
 
int compare (const String &other) const noexcept
 Case-sensitive comparison with another string. More...
 
int compare (const char *other) const noexcept
 Case-sensitive comparison with another string. More...
 
int compare (const wchar_t *other) const noexcept
 Case-sensitive comparison with another string. More...
 
int compareIgnoreCase (const String &other) const noexcept
 Case-insensitive comparison with another string. More...
 
int compareNatural (StringRef other, bool isCaseSensitive=false) const noexcept
 Compares two strings, taking into account textual characteristics like numbers and spaces. More...
 
bool startsWith (StringRef text) const noexcept
 Tests whether the string begins with another string. More...
 
bool startsWithChar (juce_wchar character) const noexcept
 Tests whether the string begins with a particular character. More...
 
bool startsWithIgnoreCase (StringRef text) const noexcept
 Tests whether the string begins with another string. More...
 
bool endsWith (StringRef text) const noexcept
 Tests whether the string ends with another string. More...
 
bool endsWithChar (juce_wchar character) const noexcept
 Tests whether the string ends with a particular character. More...
 
bool endsWithIgnoreCase (StringRef text) const noexcept
 Tests whether the string ends with another string. More...
 
bool contains (StringRef text) const noexcept
 Tests whether the string contains another substring. More...
 
bool containsChar (juce_wchar character) const noexcept
 Tests whether the string contains a particular character. More...
 
bool containsIgnoreCase (StringRef text) const noexcept
 Tests whether the string contains another substring. More...
 
bool containsWholeWord (StringRef wordToLookFor) const noexcept
 Tests whether the string contains another substring as a distinct word. More...
 
bool containsWholeWordIgnoreCase (StringRef wordToLookFor) const noexcept
 Tests whether the string contains another substring as a distinct word. More...
 
int indexOfWholeWord (StringRef wordToLookFor) const noexcept
 Finds an instance of another substring if it exists as a distinct word. More...
 
int indexOfWholeWordIgnoreCase (StringRef wordToLookFor) const noexcept
 Finds an instance of another substring if it exists as a distinct word. More...
 
bool containsAnyOf (StringRef charactersItMightContain) const noexcept
 Looks for any of a set of characters in the string. More...
 
bool containsOnly (StringRef charactersItMightContain) const noexcept
 Looks for a set of characters in the string. More...
 
bool containsNonWhitespaceChars () const noexcept
 Returns true if this string contains any non-whitespace characters. More...
 
bool matchesWildcard (StringRef wildcard, bool ignoreCase) const noexcept
 Returns true if the string matches this simple wildcard expression. More...
 
int indexOfChar (juce_wchar characterToLookFor) const noexcept
 Searches for a character inside this string. More...
 
int indexOfChar (int startIndex, juce_wchar characterToLookFor) const noexcept
 Searches for a character inside this string. More...
 
int indexOfAnyOf (StringRef charactersToLookFor, int startIndex=0, bool ignoreCase=false) const noexcept
 Returns the index of the first character that matches one of the characters passed-in to this method. More...
 
int indexOf (StringRef textToLookFor) const noexcept
 Searches for a substring within this string. More...
 
int indexOf (int startIndex, StringRef textToLookFor) const noexcept
 Searches for a substring within this string. More...
 
int indexOfIgnoreCase (StringRef textToLookFor) const noexcept
 Searches for a substring within this string. More...
 
int indexOfIgnoreCase (int startIndex, StringRef textToLookFor) const noexcept
 Searches for a substring within this string. More...
 
int lastIndexOfChar (juce_wchar character) const noexcept
 Searches for a character inside this string (working backwards from the end of the string). More...
 
int lastIndexOf (StringRef textToLookFor) const noexcept
 Searches for a substring inside this string (working backwards from the end of the string). More...
 
int lastIndexOfIgnoreCase (StringRef textToLookFor) const noexcept
 Searches for a substring inside this string (working backwards from the end of the string). More...
 
int lastIndexOfAnyOf (StringRef charactersToLookFor, bool ignoreCase=false) const noexcept
 Returns the index of the last character in this string that matches one of the characters passed-in to this method. More...
 
juce_wchar operator[] (int index) const noexcept
 Returns the character at this index in the string. More...
 
juce_wchar getLastCharacter () const noexcept
 Returns the final character of the string. More...
 
String substring (int startIndex, int endIndex) const
 Returns a subsection of the string. More...
 
String substring (int startIndex) const
 Returns a section of the string, starting from a given position. More...
 
String dropLastCharacters (int numberToDrop) const
 Returns a version of this string with a number of characters removed from the end. More...
 
String getLastCharacters (int numCharacters) const
 Returns a number of characters from the end of the string. More...
 
String fromFirstOccurrenceOf (StringRef substringToStartFrom, bool includeSubStringInResult, bool ignoreCase) const
 Returns a section of the string starting from a given substring. More...
 
String fromLastOccurrenceOf (StringRef substringToFind, bool includeSubStringInResult, bool ignoreCase) const
 Returns a section of the string starting from the last occurrence of a given substring. More...
 
String upToFirstOccurrenceOf (StringRef substringToEndWith, bool includeSubStringInResult, bool ignoreCase) const
 Returns the start of this string, up to the first occurrence of a substring. More...
 
String upToLastOccurrenceOf (StringRef substringToFind, bool includeSubStringInResult, bool ignoreCase) const
 Returns the start of this string, up to the last occurrence of a substring. More...
 
String trim () const
 Returns a copy of this string with any whitespace characters removed from the start and end. More...
 
String trimStart () const
 Returns a copy of this string with any whitespace characters removed from the start. More...
 
String trimEnd () const
 Returns a copy of this string with any whitespace characters removed from the end. More...
 
String trimCharactersAtStart (StringRef charactersToTrim) const
 Returns a copy of this string, having removed a specified set of characters from its start. More...
 
String trimCharactersAtEnd (StringRef charactersToTrim) const
 Returns a copy of this string, having removed a specified set of characters from its end. More...
 
String toUpperCase () const
 Returns an upper-case version of this string. More...
 
String toLowerCase () const
 Returns an lower-case version of this string. More...
 
String replaceSection (int startIndex, int numCharactersToReplace, StringRef stringToInsert) const
 Replaces a sub-section of the string with another string. More...
 
String replace (StringRef stringToReplace, StringRef stringToInsertInstead, bool ignoreCase=false) const
 Replaces all occurrences of a substring with another string. More...
 
String replaceFirstOccurrenceOf (StringRef stringToReplace, StringRef stringToInsertInstead, bool ignoreCase=false) const
 Replaces the first occurrence of a substring with another string. More...
 
String replaceCharacter (juce_wchar characterToReplace, juce_wchar characterToInsertInstead) const
 Returns a string with all occurrences of a character replaced with a different one. More...
 
String replaceCharacters (StringRef charactersToReplace, StringRef charactersToInsertInstead) const
 Replaces a set of characters with another set. More...
 
String retainCharacters (StringRef charactersToRetain) const
 Returns a version of this string that only retains a fixed set of characters. More...
 
String removeCharacters (StringRef charactersToRemove) const
 Returns a version of this string with a set of characters removed. More...
 
String initialSectionContainingOnly (StringRef permittedCharacters) const
 Returns a section from the start of the string that only contains a certain set of characters. More...
 
String initialSectionNotContaining (StringRef charactersToStopAt) const
 Returns a section from the start of the string that only contains a certain set of characters. More...
 
bool isQuotedString () const
 Checks whether the string might be in quotation marks. More...
 
String unquoted () const
 Removes quotation marks from around the string, (if there are any). More...
 
String quoted (juce_wchar quoteCharacter='"') const
 Adds quotation marks around a string. More...
 
String paddedLeft (juce_wchar padCharacter, int minimumLength) const
 Returns a copy of this string with the specified character repeatedly added to its beginning until the total length is at least the minimum length specified.
 
String paddedRight (juce_wchar padCharacter, int minimumLength) const
 Returns a copy of this string with the specified character repeatedly added to its end until the total length is at least the minimum length specified.
 
 String (int decimalInteger)
 Creates a string containing this signed 32-bit integer as a decimal number. More...
 
 String (unsigned int decimalInteger)
 Creates a string containing this unsigned 32-bit integer as a decimal number. More...
 
 String (short decimalInteger)
 Creates a string containing this signed 16-bit integer as a decimal number. More...
 
 String (unsigned short decimalInteger)
 Creates a string containing this unsigned 16-bit integer as a decimal number. More...
 
 String (int64 largeIntegerValue)
 Creates a string containing this signed 64-bit integer as a decimal number. More...
 
 String (uint64 largeIntegerValue)
 Creates a string containing this unsigned 64-bit integer as a decimal number. More...
 
 String (long decimalInteger)
 Creates a string containing this signed long integer as a decimal number. More...
 
 String (unsigned long decimalInteger)
 Creates a string containing this unsigned long integer as a decimal number. More...
 
 String (float floatValue)
 Creates a string representing this floating-point number. More...
 
 String (double doubleValue)
 Creates a string representing this floating-point number. More...
 
 String (float floatValue, int numberOfDecimalPlaces, bool useScientificNotation=false)
 Creates a string representing this floating-point number. More...
 
 String (double doubleValue, int numberOfDecimalPlaces, bool useScientificNotation=false)
 Creates a string representing this floating-point number. More...
 
 String (bool)=delete
 
int getIntValue () const noexcept
 Reads the value of the string as a decimal number (up to 32 bits in size). More...
 
int64 getLargeIntValue () const noexcept
 Reads the value of the string as a decimal number (up to 64 bits in size). More...
 
int getTrailingIntValue () const noexcept
 Parses a decimal number from the end of the string. More...
 
float getFloatValue () const noexcept
 Parses this string as a floating point number. More...
 
double getDoubleValue () const noexcept
 Parses this string as a floating point number. More...
 
int getHexValue32 () const noexcept
 Parses the string as a hexadecimal number. More...
 
int64 getHexValue64 () const noexcept
 Parses the string as a hexadecimal number. More...
 
CharPointerType getCharPointer () const noexcept
 Returns the character pointer currently being used to store this string. More...
 
CharPointer_UTF8 toUTF8 () const
 Returns a pointer to a UTF-8 version of this string. More...
 
const char * toRawUTF8 () const
 Returns a pointer to a UTF-8 version of this string. More...
 
CharPointer_UTF16 toUTF16 () const
 Returns a pointer to a UTF-16 version of this string. More...
 
CharPointer_UTF32 toUTF32 () const
 Returns a pointer to a UTF-32 version of this string. More...
 
const wchar_t * toWideCharPointer () const
 Returns a pointer to a wchar_t version of this string. More...
 
std::string toStdString () const
 
size_t getNumBytesAsUTF8 () const noexcept
 Returns the number of bytes required to represent this string as UTF8. More...
 
size_t copyToUTF8 (CharPointer_UTF8::CharType *destBuffer, size_t maxBufferSizeBytes) const noexcept
 Copies the string to a buffer as UTF-8 characters. More...
 
size_t copyToUTF16 (CharPointer_UTF16::CharType *destBuffer, size_t maxBufferSizeBytes) const noexcept
 Copies the string to a buffer as UTF-16 characters. More...
 
size_t copyToUTF32 (CharPointer_UTF32::CharType *destBuffer, size_t maxBufferSizeBytes) const noexcept
 Copies the string to a buffer as UTF-32 characters. More...
 
void preallocateBytes (size_t numBytesNeeded)
 Increases the string's internally allocated storage. More...
 
void swapWith (String &other) noexcept
 Swaps the contents of this string with another one. More...
 
CFStringRef toCFString () const
 OSX ONLY - Converts this string to a CFString. More...
 
String convertToPrecomposedUnicode () const
 OSX ONLY - Returns a copy of this string in which any decomposed unicode characters have been converted to their precomposed equivalents. More...
 
int getReferenceCount () const noexcept
 Returns the number of String objects which are currently sharing the same internal data as this one.
 

Static Public Member Functions

static String charToString (juce_wchar character)
 Creates a string from a single character. More...
 
static String repeatedString (StringRef stringToRepeat, int numberOfTimesToRepeat)
 Creates a string which is a version of a string repeated and joined together. More...
 
static String createStringFromData (const void *data, int size)
 Creates a string from data in an unknown format. More...
 
template<typename... Args>
static String formatted (const String &formatStr, Args... args)
 Creates a String from a printf-style parameter list. More...
 
template<typename IntegerType >
static String toHexString (IntegerType number)
 Returns a string representing this numeric value in hexadecimal. More...
 
static String toHexString (const void *data, int size, int groupSize=1)
 Returns a string containing a hex dump of a block of binary data. More...
 
template<typename DecimalType >
static String toDecimalStringWithSignificantFigures (DecimalType number, int numberOfSignificantFigures)
 Returns a string containing a decimal with a set number of significant figures. More...
 
static String fromUTF8 (const char *utf8buffer, int bufferSizeBytes=-1)
 Creates a String from a UTF-8 encoded buffer. More...
 
static String fromCFString (CFStringRef cfString)
 OSX ONLY - Creates a String from an OSX CFString. More...
 

Detailed Description

The JUCE String class!

Using a reference-counted internal representation, these strings are fast and efficient, and there are methods to do just about any operation you'll ever dream of.

See also
StringArray, StringPairArray

Definition at line 42 of file juce_String.h.

Member Typedef Documentation

◆ CharPointerType

This is the character encoding type used internally to store the string.

By setting the value of JUCE_STRING_UTF_TYPE to 8, 16, or 32, you can change the internal storage format of the String class. UTF-8 uses the least space (if your strings contain few extended characters), but call operator[] involves iterating the string to find the required index. UTF-32 provides instant random access to its characters, but uses 4 bytes per character to store them. UTF-16 uses more space than UTF-8 and is also slow to index, but is the native wchar_t format used in Windows.

It doesn't matter too much which format you pick, because the toUTF8(), toUTF16() and toUTF32() methods let you access the string's content in any of the other formats.

Definition at line 164 of file juce_String.h.

Constructor & Destructor Documentation

◆ String() [1/19]

juce::String::String ( )
noexcept

◆ String() [2/19]

juce::String::String ( const String other)
noexcept

Creates a copy of another string.

Definition at line 250 of file juce_String.cpp.

◆ String() [3/19]

juce::String::String ( const char *  text)

Creates a string from a zero-terminated ascii text string.

The string passed-in must not contain any characters with a value above 127, because these can't be converted to unicode without knowing the original encoding that was used to create the string. If you attempt to pass-in values above 127, you'll get an assertion.

To create strings with extended characters from UTF-8, you should explicitly call String (CharPointer_UTF8 ("my utf8 string..")). It's highly recommended that you use UTF-8 with escape characters in your source code to represent extended characters, because there's no other way to represent unicode strings in a way that isn't dependent on the compiler, source code editor and platform.

Definition at line 302 of file juce_String.cpp.

References juce::CharPointer_ASCII::isValidString().

◆ String() [4/19]

juce::String::String ( const char *  text,
size_t  maxChars 
)

Creates a string from a string of 8-bit ascii characters.

The string passed-in must not contain any characters with a value above 127, because these can't be converted to unicode without knowing the original encoding that was used to create the string. If you attempt to pass-in values above 127, you'll get an assertion.

To create strings with extended characters from UTF-8, you should explicitly call String (CharPointer_UTF8 ("my utf8 string..")). It's highly recommended that you use UTF-8 with escape characters in your source code to represent extended characters, because there's no other way to represent unicode strings in a way that isn't dependent on the compiler, source code editor and platform.

This will use up to the first maxChars characters of the string (or less if the string is actually shorter).

Definition at line 325 of file juce_String.cpp.

References juce::CharPointer_ASCII::isValidString().

◆ String() [5/19]

juce::String::String ( const wchar_t *  text)

Creates a string from a wchar_t character string.

Depending on the platform, this may be treated as either UTF-32 or UTF-16.

Definition at line 348 of file juce_String.cpp.

◆ String() [6/19]

juce::String::String ( const wchar_t *  text,
size_t  maxChars 
)

Creates a string from a wchar_t character string.

Depending on the platform, this may be treated as either UTF-32 or UTF-16.

Definition at line 357 of file juce_String.cpp.

◆ String() [7/19]

juce::String::String ( const std::string &  s)

Creates a string from a UTF-8 encoded std::string.

Definition at line 363 of file juce_String.cpp.

◆ ~String()

juce::String::~String ( )
noexcept

Destructor.

Definition at line 245 of file juce_String.cpp.

◆ String() [8/19]

juce::String::String ( int  decimalInteger)
explicit

Creates a string containing this signed 32-bit integer as a decimal number.

See also
getIntValue, getFloatValue, getDoubleValue, toHexString

Definition at line 503 of file juce_String.cpp.

◆ String() [9/19]

juce::String::String ( unsigned int  decimalInteger)
explicit

Creates a string containing this unsigned 32-bit integer as a decimal number.

See also
getIntValue, getFloatValue, getDoubleValue, toHexString

Definition at line 504 of file juce_String.cpp.

◆ String() [10/19]

juce::String::String ( short  decimalInteger)
explicit

Creates a string containing this signed 16-bit integer as a decimal number.

See also
getIntValue, getFloatValue, getDoubleValue, toHexString

Definition at line 505 of file juce_String.cpp.

◆ String() [11/19]

juce::String::String ( unsigned short  decimalInteger)
explicit

Creates a string containing this unsigned 16-bit integer as a decimal number.

See also
getIntValue, getFloatValue, getDoubleValue, toHexString

Definition at line 506 of file juce_String.cpp.

◆ String() [12/19]

juce::String::String ( int64  largeIntegerValue)
explicit

Creates a string containing this signed 64-bit integer as a decimal number.

See also
getLargeIntValue, getFloatValue, getDoubleValue, toHexString

Definition at line 507 of file juce_String.cpp.

◆ String() [13/19]

juce::String::String ( uint64  largeIntegerValue)
explicit

Creates a string containing this unsigned 64-bit integer as a decimal number.

See also
getLargeIntValue, getFloatValue, getDoubleValue, toHexString

Definition at line 508 of file juce_String.cpp.

◆ String() [14/19]

juce::String::String ( long  decimalInteger)
explicit

Creates a string containing this signed long integer as a decimal number.

See also
getIntValue, getFloatValue, getDoubleValue, toHexString

Definition at line 509 of file juce_String.cpp.

◆ String() [15/19]

juce::String::String ( unsigned long  decimalInteger)
explicit

Creates a string containing this unsigned long integer as a decimal number.

See also
getIntValue, getFloatValue, getDoubleValue, toHexString

Definition at line 510 of file juce_String.cpp.

◆ String() [16/19]

juce::String::String ( float  floatValue)
explicit

Creates a string representing this floating-point number.

Parameters
floatValuethe value to convert to a string
See also
getDoubleValue, getIntValue

Definition at line 512 of file juce_String.cpp.

◆ String() [17/19]

juce::String::String ( double  doubleValue)
explicit

Creates a string representing this floating-point number.

Parameters
doubleValuethe value to convert to a string
See also
getFloatValue, getIntValue

Definition at line 513 of file juce_String.cpp.

◆ String() [18/19]

juce::String::String ( float  floatValue,
int  numberOfDecimalPlaces,
bool  useScientificNotation = false 
)

Creates a string representing this floating-point number.

Parameters
floatValuethe value to convert to a string
numberOfDecimalPlacesif this is > 0 the number will be formatted using that many decimal places, adding trailing zeros as required. If 0 or less the number will be formatted using the C++ standard library default format, which uses scientific notation for large and small numbers.
useScientificNotationif the number should be formatted using scientific notation
See also
getDoubleValue, getIntValue

Definition at line 514 of file juce_String.cpp.

◆ String() [19/19]

juce::String::String ( double  doubleValue,
int  numberOfDecimalPlaces,
bool  useScientificNotation = false 
)

Creates a string representing this floating-point number.

Parameters
doubleValuethe value to convert to a string
numberOfDecimalPlacesif this is > 0, it will format the number using that many decimal places, adding trailing zeros as required, and will not use exponent notation. If 0 or less, it will use exponent notation if necessary.
useScientificNotationif the number should be formatted using scientific notation
See also
getFloatValue, getIntValue

Definition at line 515 of file juce_String.cpp.

Member Function Documentation

◆ charToString()

String juce::String::charToString ( juce_wchar  character)
static

◆ hashCode()

int juce::String::hashCode ( ) const
noexcept

Generates a probably-unique 32-bit hashcode from this string.

Definition at line 556 of file juce_String.cpp.

Referenced by juce::File::hashCode(), and juce::StringRef::StringRef().

◆ hashCode64()

int64 juce::String::hashCode64 ( ) const
noexcept

Generates a probably-unique 64-bit hashcode from this string.

Definition at line 557 of file juce_String.cpp.

Referenced by juce::URLInputSource::hashCode(), juce::File::hashCode64(), and juce::StringRef::StringRef().

◆ hash()

size_t juce::String::hash ( ) const
noexcept

Generates a probably-unique hashcode from this string.

Definition at line 558 of file juce_String.cpp.

References compare(), juce::CharPointer_UTF8::compare(), getCharPointer(), JUCE_API, and juce::StringRef::text.

Referenced by getCharPointer().

◆ length()

◆ operator=()

String & juce::String::operator= ( const String other)
noexcept

Replaces this string's contents with another string.

Definition at line 266 of file juce_String.cpp.

Referenced by operator+=().

◆ operator+=() [1/11]

String & juce::String::operator+= ( const String stringToAppend)

Appends another string at the end of this one.

Definition at line 756 of file juce_String.cpp.

References appendCharPointer(), isEmpty(), and operator=().

Referenced by operator+=().

◆ operator+=() [2/11]

String & juce::String::operator+= ( const char *  textToAppend)

Appends another string at the end of this one.

Definition at line 750 of file juce_String.cpp.

References appendCharPointer().

◆ operator+=() [3/11]

String & juce::String::operator+= ( const wchar_t *  textToAppend)

Appends another string at the end of this one.

Definition at line 744 of file juce_String.cpp.

References appendCharPointer().

◆ operator+=() [4/11]

String & juce::String::operator+= ( StringRef  textToAppend)

Appends another string at the end of this one.

Definition at line 768 of file juce_String.cpp.

References operator+=().

◆ operator+=() [5/11]

String & juce::String::operator+= ( int  numberToAppend)

Appends a decimal number at the end of this string.

Definition at line 813 of file juce_String.cpp.

◆ operator+=() [6/11]

String& juce::String::operator+= ( long  numberToAppend)

Appends a decimal number at the end of this string.

◆ operator+=() [7/11]

String & juce::String::operator+= ( int64  numberToAppend)

Appends a decimal number at the end of this string.

Definition at line 814 of file juce_String.cpp.

◆ operator+=() [8/11]

String & juce::String::operator+= ( uint64  numberToAppend)

◆ operator+=() [9/11]

String & juce::String::operator+= ( char  characterToAppend)

Appends a character at the end of this string.

Definition at line 773 of file juce_String.cpp.

References operator+=().

◆ operator+=() [10/11]

String & juce::String::operator+= ( wchar_t  characterToAppend)

Appends a character at the end of this string.

Definition at line 779 of file juce_String.cpp.

References appendCharPointer(), and operator+=().

◆ operator+=() [11/11]

String& juce::String::operator+= ( juce_wchar  characterToAppend)

Appends a character at the end of this string.

◆ append()

void juce::String::append ( const String textToAppend,
size_t  maxCharsToTake 
)

Appends a string to the end of this one.

Parameters
textToAppendthe string to add
maxCharsToTakethe maximum number of characters to take from the string passed in

Definition at line 713 of file juce_String.cpp.

References appendCharPointer().

◆ appendCharPointer() [1/5]

void juce::String::appendCharPointer ( CharPointerType  startOfTextToAppend,
CharPointerType  endOfTextToAppend 
)

Appends a string to the end of this one.

Parameters
startOfTextToAppendthe start of the string to add. This must not be a nullptr
endOfTextToAppendthe end of the string to add. This must not be a nullptr

Definition at line 724 of file juce_String.cpp.

References juce::CharPointer_UTF8::getAddress(), preallocateBytes(), and juce::CharPointer_UTF8::writeNull().

Referenced by append(), appendCharPointer(), juce::File::getChildFile(), juce::XmlDocument::getLastParseError(), and operator+=().

◆ appendCharPointer() [2/5]

template<class CharPointer >
void juce::String::appendCharPointer ( CharPointer  startOfTextToAppend,
CharPointer  endOfTextToAppend 
)
inline

Appends a string to the end of this one.

Parameters
startOfTextToAppendthe start of the string to add. This must not be a nullptr
endOfTextToAppendthe end of the string to add. This must not be a nullptr

Definition at line 237 of file juce_String.h.

References juce::CharPointer_ASCII::getAddress().

◆ appendCharPointer() [3/5]

void juce::String::appendCharPointer ( CharPointerType  textToAppend)

Appends a string to the end of this one.

Definition at line 719 of file juce_String.cpp.

References appendCharPointer(), and juce::CharPointer_UTF8::findTerminatingNull().

◆ appendCharPointer() [4/5]

template<class CharPointer >
void juce::String::appendCharPointer ( CharPointer  textToAppend,
size_t  maxCharsToTake 
)
inline

Appends a string to the end of this one.

Parameters
textToAppendthe string to add
maxCharsToTakethe maximum number of characters to take from the string passed in

Definition at line 266 of file juce_String.h.

References juce::CharPointer_ASCII::getAddress().

◆ appendCharPointer() [5/5]

template<class CharPointer >
void juce::String::appendCharPointer ( CharPointer  textToAppend)
inline

Appends a string to the end of this one.

Definition at line 288 of file juce_String.h.

◆ isEmpty()

◆ isNotEmpty()

◆ clear()

void juce::String::clear ( )
noexcept

Resets this string to be empty.

Definition at line 260 of file juce_String.cpp.

Referenced by juce::AudioDeviceManager::getAudioDeviceSetup(), and juce::XmlDocument::getLastParseError().

◆ equalsIgnoreCase() [1/4]

bool juce::String::equalsIgnoreCase ( const String other) const
noexcept

Case-insensitive comparison with another string.

Definition at line 597 of file juce_String.cpp.

References juce::CharPointer_UTF8::compareIgnoreCase().

Referenced by juce::XmlDocument::getLastParseError(), juce::Time::operator-=(), and juce::StringRef::StringRef().

◆ equalsIgnoreCase() [2/4]

bool juce::String::equalsIgnoreCase ( StringRef  other) const
noexcept

Case-insensitive comparison with another string.

Definition at line 592 of file juce_String.cpp.

References juce::CharPointer_UTF8::compareIgnoreCase().

◆ equalsIgnoreCase() [3/4]

bool juce::String::equalsIgnoreCase ( const wchar_t *  other) const
noexcept

Case-insensitive comparison with another string.

Definition at line 580 of file juce_String.cpp.

References juce::CharPointer_UTF8::compareIgnoreCase(), and isEmpty().

◆ equalsIgnoreCase() [4/4]

bool juce::String::equalsIgnoreCase ( const char *  other) const
noexcept

Case-insensitive comparison with another string.

Definition at line 586 of file juce_String.cpp.

References juce::CharPointer_UTF8::compareIgnoreCase(), and isEmpty().

◆ compare() [1/3]

int juce::String::compare ( const String other) const
noexcept

Case-sensitive comparison with another string.

Returns
0 if the two strings are identical; negative if this string comes before the other one alphabetically, or positive if it comes after it.

Definition at line 603 of file juce_String.cpp.

References juce::CharPointer_UTF8::compare().

Referenced by juce::File::areFileNamesCaseSensitive(), hash(), juce::var::hasSameTypeAs(), and juce::StringRef::StringRef().

◆ compare() [2/3]

int juce::String::compare ( const char *  other) const
noexcept

Case-sensitive comparison with another string.

Returns
0 if the two strings are identical; negative if this string comes before the other one alphabetically, or positive if it comes after it.

Definition at line 604 of file juce_String.cpp.

References juce::CharPointer_UTF8::compare().

◆ compare() [3/3]

int juce::String::compare ( const wchar_t *  other) const
noexcept

Case-sensitive comparison with another string.

Returns
0 if the two strings are identical; negative if this string comes before the other one alphabetically, or positive if it comes after it.

Definition at line 605 of file juce_String.cpp.

References juce::CharPointer_UTF8::compare().

◆ compareIgnoreCase()

int juce::String::compareIgnoreCase ( const String other) const
noexcept

◆ compareNatural()

int juce::String::compareNatural ( StringRef  other,
bool  isCaseSensitive = false 
) const
noexcept

Compares two strings, taking into account textual characteristics like numbers and spaces.

This comparison is case-insensitive and can detect words and embedded numbers in the strings, making it good for sorting human-readable lists of things like filenames.

Returns
0 if the two strings are identical; negative if this string comes before the other one alphabetically, or positive if it comes after it.

Definition at line 707 of file juce_String.cpp.

References getCharPointer().

Referenced by juce::StringArray::sortNatural().

◆ startsWith()

bool juce::String::startsWith ( StringRef  text) const
noexcept

Tests whether the string begins with another string.

If the parameter is an empty string, this will always return true. Uses a case-sensitive comparison.

Definition at line 1399 of file juce_String.cpp.

Referenced by juce::PropertiesFile::Options::getDefaultFile(), juce::URL::getScheme(), juce::ChildProcessSlave::initialiseFromCommandLine(), juce::File::isRoot(), juce::URL::operator==(), juce::JUCEApplicationBase::quit(), juce::StringRef::StringRef(), and juce::URL::URL().

◆ startsWithChar()

bool juce::String::startsWithChar ( juce_wchar  character) const
noexcept

Tests whether the string begins with a particular character.

If the character is 0, this will always return false. Uses a case-sensitive comparison.

Definition at line 1409 of file juce_String.cpp.

Referenced by juce::AudioFormatManager::findFormatForFileExtension(), juce::PropertiesFile::Options::getDefaultFile(), juce::XmlDocument::getLastParseError(), juce::File::isRoot(), juce::URL::operator==(), quoted(), juce::StringRef::StringRef(), and juce::URL::URL().

◆ startsWithIgnoreCase()

bool juce::String::startsWithIgnoreCase ( StringRef  text) const
noexcept

Tests whether the string begins with another string.

If the parameter is an empty string, this will always return true. Uses a case-insensitive comparison.

Definition at line 1404 of file juce_String.cpp.

Referenced by juce::URL::isProbablyAWebsiteURL(), and juce::StringRef::StringRef().

◆ endsWith()

bool juce::String::endsWith ( StringRef  text) const
noexcept

Tests whether the string ends with another string.

If the parameter is an empty string, this will always return true. Uses a case-sensitive comparison.

Definition at line 1427 of file juce_String.cpp.

References juce::CharPointer_UTF8::findTerminatingNull(), and juce::StringRef::text.

Referenced by juce::StringRef::StringRef().

◆ endsWithChar()

bool juce::String::endsWithChar ( juce_wchar  character) const
noexcept

Tests whether the string ends with a particular character.

If the character is 0, this will always return false. Uses a case-sensitive comparison.

Definition at line 1416 of file juce_String.cpp.

References juce::StringRef::isEmpty().

Referenced by juce::File::addTrailingSeparator(), juce::URL::isProbablyAnEmailAddress(), juce::File::isRoot(), juce::URL::operator==(), quoted(), and juce::StringRef::StringRef().

◆ endsWithIgnoreCase()

bool juce::String::endsWithIgnoreCase ( StringRef  text) const
noexcept

Tests whether the string ends with another string.

If the parameter is an empty string, this will always return true. Uses a case-insensitive comparison.

Definition at line 1444 of file juce_String.cpp.

References juce::CharPointer_UTF8::findTerminatingNull(), and juce::StringRef::text.

Referenced by juce::File::hasFileExtension(), and juce::StringRef::StringRef().

◆ contains()

bool juce::String::contains ( StringRef  text) const
noexcept

Tests whether the string contains another substring.

If the parameter is an empty string, this will always return true. Uses a case-sensitive comparison.

Definition at line 1041 of file juce_String.cpp.

References indexOf().

Referenced by juce::IPAddress::getFormattedAddress(), juce::Time::getTimeZone(), juce::File::operator=(), and juce::StringRef::StringRef().

◆ containsChar()

bool juce::String::containsChar ( juce_wchar  character) const
noexcept

◆ containsIgnoreCase()

bool juce::String::containsIgnoreCase ( StringRef  text) const
noexcept

Tests whether the string contains another substring.

Uses a case-insensitive comparison.

Definition at line 1051 of file juce_String.cpp.

References indexOfIgnoreCase().

Referenced by juce::URL::getChildURL(), juce::Time::getTimeZone(), and juce::StringRef::StringRef().

◆ containsWholeWord()

bool juce::String::containsWholeWord ( StringRef  wordToLookFor) const
noexcept

Tests whether the string contains another substring as a distinct word.

Returns
true if the string contains this word, surrounded by non-alphanumeric characters
See also
indexOfWholeWord, containsWholeWordIgnoreCase

Definition at line 1100 of file juce_String.cpp.

References indexOfWholeWord().

Referenced by juce::StringRef::StringRef().

◆ containsWholeWordIgnoreCase()

bool juce::String::containsWholeWordIgnoreCase ( StringRef  wordToLookFor) const
noexcept

Tests whether the string contains another substring as a distinct word.

Returns
true if the string contains this word, surrounded by non-alphanumeric characters
See also
indexOfWholeWordIgnoreCase, containsWholeWord

Definition at line 1105 of file juce_String.cpp.

References indexOfWholeWordIgnoreCase().

Referenced by juce::StringRef::StringRef().

◆ indexOfWholeWord()

int juce::String::indexOfWholeWord ( StringRef  wordToLookFor) const
noexcept

Finds an instance of another substring if it exists as a distinct word.

Returns
if the string contains this word, surrounded by non-alphanumeric characters, then this will return the index of the start of the substring. If it isn't found, then it will return -1
See also
indexOfWholeWordIgnoreCase, containsWholeWord

Definition at line 1056 of file juce_String.cpp.

References juce::StringRef::length().

Referenced by containsWholeWord(), and juce::StringRef::StringRef().

◆ indexOfWholeWordIgnoreCase()

int juce::String::indexOfWholeWordIgnoreCase ( StringRef  wordToLookFor) const
noexcept

Finds an instance of another substring if it exists as a distinct word.

Returns
if the string contains this word, surrounded by non-alphanumeric characters, then this will return the index of the start of the substring. If it isn't found, then it will return -1
See also
indexOfWholeWord, containsWholeWordIgnoreCase

Definition at line 1078 of file juce_String.cpp.

References juce::StringRef::length().

Referenced by containsWholeWordIgnoreCase(), and juce::StringRef::StringRef().

◆ containsAnyOf()

bool juce::String::containsAnyOf ( StringRef  charactersItMightContain) const
noexcept

Looks for any of a set of characters in the string.

Uses a case-sensitive comparison.

Returns
true if the string contains any of the characters from the string that is passed in.

Definition at line 1811 of file juce_String.cpp.

References juce::StringRef::isEmpty().

Referenced by juce::IPAddress::isNull(), and juce::StringRef::StringRef().

◆ containsOnly()

bool juce::String::containsOnly ( StringRef  charactersItMightContain) const
noexcept

Looks for a set of characters in the string.

Uses a case-sensitive comparison.

Returns
Returns false if any of the characters in this string do not occur in the parameter string. If this string is empty, the return value will always be true.

Definition at line 1802 of file juce_String.cpp.

References juce::StringRef::isEmpty().

Referenced by juce::DirectoryIterator::next(), juce::StringRef::StringRef(), and juce::Expression::withRenamedSymbol().

◆ containsNonWhitespaceChars()

bool juce::String::containsNonWhitespaceChars ( ) const
noexcept

Returns true if this string contains any non-whitespace characters.

This will return false if the string contains only whitespace characters, or if it's empty.

It is equivalent to calling "myString.trim().isNotEmpty()".

Definition at line 1820 of file juce_String.cpp.

References juce::HeapBlock< ElementType, throwOnFailure >::get(), juce::StringRef::isEmpty(), String(), and toWideCharPointer().

Referenced by juce::XmlDocument::getLastParseError(), and juce::StringRef::StringRef().

◆ matchesWildcard()

bool juce::String::matchesWildcard ( StringRef  wildcard,
bool  ignoreCase 
) const
noexcept

Returns true if the string matches this simple wildcard expression.

So for example String ("abcdef").matchesWildcard ("*DEF", true) would return true.

This isn't a full-blown regex though! The only wildcard characters supported are "*" and "?". It's mainly intended for filename pattern matching.

Definition at line 1147 of file juce_String.cpp.

Referenced by juce::StringRef::StringRef(), and juce::DirectoryIterator::~DirectoryIterator().

◆ indexOfChar() [1/2]

int juce::String::indexOfChar ( juce_wchar  characterToLookFor) const
noexcept

Searches for a character inside this string.

Uses a case-sensitive comparison.

Returns
the index of the first occurrence of the character in this string, or -1 if it's not found.

Definition at line 880 of file juce_String.cpp.

Referenced by juce::XmlDocument::getLastParseError(), juce::ArgumentList::Argument::getLongOptionValue(), juce::URL::isProbablyAnEmailAddress(), juce::File::isRoot(), juce::URL::operator==(), juce::StringRef::StringRef(), and juce::URL::URL().

◆ indexOfChar() [2/2]

int juce::String::indexOfChar ( int  startIndex,
juce_wchar  characterToLookFor 
) const
noexcept

Searches for a character inside this string.

Uses a case-sensitive comparison.

Parameters
startIndexthe index from which the search should proceed
characterToLookForthe character to look for
Returns
the index of the first occurrence of the character in this string, or -1 if it's not found.

Definition at line 885 of file juce_String.cpp.

◆ indexOfAnyOf()

int juce::String::indexOfAnyOf ( StringRef  charactersToLookFor,
int  startIndex = 0,
bool  ignoreCase = false 
) const
noexcept

Returns the index of the first character that matches one of the characters passed-in to this method.

This scans the string, beginning from the startIndex supplied, and if it finds a character that appears in the string charactersToLookFor, it returns its index.

If none of these characters are found, it returns -1.

If ignoreCase is true, the comparison will be case-insensitive.

See also
indexOfChar, lastIndexOfAnyOf

Definition at line 917 of file juce_String.cpp.

Referenced by juce::StringRef::StringRef().

◆ indexOf() [1/2]

int juce::String::indexOf ( StringRef  textToLookFor) const
noexcept

Searches for a substring within this string.

Uses a case-sensitive comparison.

Returns
the index of the first occurrence of this substring, or -1 if it's not found. If textToLookFor is an empty string, this will always return 0.

Definition at line 937 of file juce_String.cpp.

Referenced by contains(), fromFirstOccurrenceOf(), juce::XmlDocument::getLastParseError(), juce::IPAddress::isNull(), replace(), replaceFirstOccurrenceOf(), juce::StringRef::StringRef(), and upToFirstOccurrenceOf().

◆ indexOf() [2/2]

int juce::String::indexOf ( int  startIndex,
StringRef  textToLookFor 
) const
noexcept

Searches for a substring within this string.

Uses a case-sensitive comparison.

Parameters
startIndexthe index from which the search should proceed
textToLookForthe string to search for
Returns
the index of the first occurrence of this substring, or -1 if it's not found. If textToLookFor is an empty string, this will always return -1.

Definition at line 947 of file juce_String.cpp.

◆ indexOfIgnoreCase() [1/2]

int juce::String::indexOfIgnoreCase ( StringRef  textToLookFor) const
noexcept

Searches for a substring within this string.

Uses a case-insensitive comparison.

Returns
the index of the first occurrence of this substring, or -1 if it's not found. If textToLookFor is an empty string, this will always return 0.

Definition at line 942 of file juce_String.cpp.

References juce::CharacterFunctions::indexOfIgnoreCase(), and juce::StringRef::text.

Referenced by containsIgnoreCase(), fromFirstOccurrenceOf(), replace(), replaceFirstOccurrenceOf(), juce::StringRef::StringRef(), and upToFirstOccurrenceOf().

◆ indexOfIgnoreCase() [2/2]

int juce::String::indexOfIgnoreCase ( int  startIndex,
StringRef  textToLookFor 
) const
noexcept

Searches for a substring within this string.

Uses a case-insensitive comparison.

Parameters
startIndexthe index from which the search should proceed
textToLookForthe string to search for
Returns
the index of the first occurrence of this substring, or -1 if it's not found. If textToLookFor is an empty string, this will always return -1.

Definition at line 966 of file juce_String.cpp.

References juce::CharacterFunctions::indexOfIgnoreCase().

◆ lastIndexOfChar()

int juce::String::lastIndexOfChar ( juce_wchar  character) const
noexcept

Searches for a character inside this string (working backwards from the end of the string).

Uses a case-sensitive comparison.

Returns
the index of the last occurrence of the character in this string, or -1 if it's not found.

Definition at line 905 of file juce_String.cpp.

Referenced by juce::File::copyDirectoryTo(), juce::File::getChildFile(), juce::File::getFileExtension(), juce::File::getFileName(), juce::File::getFileNameWithoutExtension(), juce::File::getNonexistentChildFile(), juce::File::hasFileExtension(), and juce::URL::isProbablyAnEmailAddress().

◆ lastIndexOf()

int juce::String::lastIndexOf ( StringRef  textToLookFor) const
noexcept

Searches for a substring inside this string (working backwards from the end of the string).

Uses a case-sensitive comparison.

Returns
the index of the start of the last occurrence of the substring within this string, or -1 if it's not found. If textToLookFor is an empty string, this will always return -1.

Definition at line 985 of file juce_String.cpp.

References length().

Referenced by fromLastOccurrenceOf(), juce::IPAddress::isNull(), and upToLastOccurrenceOf().

◆ lastIndexOfIgnoreCase()

int juce::String::lastIndexOfIgnoreCase ( StringRef  textToLookFor) const
noexcept

Searches for a substring inside this string (working backwards from the end of the string).

Uses a case-insensitive comparison.

Returns
the index of the start of the last occurrence of the substring within this string, or -1 if it's not found. If textToLookFor is an empty string, this will always return -1.

Definition at line 1007 of file juce_String.cpp.

References length().

Referenced by fromLastOccurrenceOf(), and upToLastOccurrenceOf().

◆ lastIndexOfAnyOf()

int juce::String::lastIndexOfAnyOf ( StringRef  charactersToLookFor,
bool  ignoreCase = false 
) const
noexcept

Returns the index of the last character in this string that matches one of the characters passed-in to this method.

This scans the string backwards, starting from its end, and if it finds a character that appears in the string charactersToLookFor, it returns its index.

If none of these characters are found, it returns -1.

If ignoreCase is true, the comparison will be case-insensitive.

See also
lastIndexOf, indexOfAnyOf

Definition at line 1029 of file juce_String.cpp.

◆ operator[]()

juce_wchar juce::String::operator[] ( int  index) const
noexcept

Returns the character at this index in the string.

In a release build, no checks are made to see if the index is within a valid range, so be careful! In a debug build, the index is checked and an assertion fires if it's out-of-range.

Also beware that depending on the encoding format that the string is using internally, this method may execute in either O(1) or O(n) time, so be careful when using it in your algorithms. If you're scanning through a string to inspect its characters, you should never use this operator for random access, it's far more efficient to call getCharPointer() to return a pointer, and then to use that to iterate the string.

See also
getCharPointer

Definition at line 533 of file juce_String.cpp.

References juce::CharPointer_UTF8::lengthUpTo().

◆ getLastCharacter()

juce_wchar juce::String::getLastCharacter ( ) const
noexcept

Returns the final character of the string.

If the string is empty this will return 0.

Definition at line 1499 of file juce_String.cpp.

References isEmpty(), and length().

Referenced by juce::StringRef::StringRef().

◆ substring() [1/2]

String juce::String::substring ( int  startIndex,
int  endIndex 
) const

◆ substring() [2/2]

String juce::String::substring ( int  startIndex) const

Returns a section of the string, starting from a given position.

Parameters
startIndexthe first character to include. If this is beyond the end of the string, an empty string is returned. If it is zero or less, the whole string is returned.
Returns
the substring from startIndex up to the end of the string
See also
dropLastCharacters, getLastCharacters, fromFirstOccurrenceOf, upToFirstOccurrenceOf, fromLastOccurrenceOf

Definition at line 1543 of file juce_String.cpp.

References String().

◆ dropLastCharacters()

String juce::String::dropLastCharacters ( int  numberToDrop) const

Returns a version of this string with a number of characters removed from the end.

Parameters
numberToDropthe number of characters to drop from the end of the string. If this is greater than the length of the string, an empty string will be returned. If zero or less, the original string will be returned.
See also
substring, fromFirstOccurrenceOf, upToFirstOccurrenceOf, fromLastOccurrenceOf, getLastCharacter

Definition at line 1561 of file juce_String.cpp.

References length(), and String().

Referenced by juce::IPAddress::getFormattedAddress(), juce::File::getRelativePathFrom(), juce::File::isRoot(), and juce::StringRef::StringRef().

◆ getLastCharacters()

String juce::String::getLastCharacters ( int  numCharacters) const

Returns a number of characters from the end of the string.

This returns the last numCharacters characters from the end of the string. If the string is shorter than numCharacters, the whole string is returned.

See also
substring, dropLastCharacters, getLastCharacter

Definition at line 1566 of file juce_String.cpp.

References length(), and String().

Referenced by juce::StringRef::StringRef().

◆ fromFirstOccurrenceOf()

String juce::String::fromFirstOccurrenceOf ( StringRef  substringToStartFrom,
bool  includeSubStringInResult,
bool  ignoreCase 
) const

Returns a section of the string starting from a given substring.

This will search for the first occurrence of the given substring, and return the section of the string starting from the point where this is found (optionally not including the substring itself).

e.g. for the string "123456", fromFirstOccurrenceOf ("34", true) would return "3456", and fromFirstOccurrenceOf ("34", false) would return "56".

If the substring isn't found, the method will return an empty string.

If ignoreCase is true, the comparison will be case-insensitive.

See also
upToFirstOccurrenceOf, fromLastOccurrenceOf

Definition at line 1571 of file juce_String.cpp.

References indexOf(), indexOfIgnoreCase(), juce::StringRef::length(), and substring().

Referenced by juce::WebInputStream::connect(), juce::IPAddress::getFormattedAddress(), juce::XmlDocument::getLastParseError(), juce::ChildProcessSlave::initialiseFromCommandLine(), juce::IPAddress::isNull(), juce::File::isRoot(), juce::StringRef::StringRef(), and juce::URL::URL().

◆ fromLastOccurrenceOf()

String juce::String::fromLastOccurrenceOf ( StringRef  substringToFind,
bool  includeSubStringInResult,
bool  ignoreCase 
) const

Returns a section of the string starting from the last occurrence of a given substring.

Similar to fromFirstOccurrenceOf(), but using the last occurrence of the substring, and unlike fromFirstOccurrenceOf(), if the substring isn't found, this method will return the whole of the original string.

See also
fromFirstOccurrenceOf, upToLastOccurrenceOf

Definition at line 1581 of file juce_String.cpp.

References lastIndexOf(), lastIndexOfIgnoreCase(), juce::StringRef::length(), and substring().

Referenced by juce::URL::getScheme(), juce::XmlElement::getTagNameWithoutNamespace(), juce::URL::isProbablyAWebsiteURL(), juce::ConsoleApplication::printCommandList(), and juce::StringRef::StringRef().

◆ upToFirstOccurrenceOf()

String juce::String::upToFirstOccurrenceOf ( StringRef  substringToEndWith,
bool  includeSubStringInResult,
bool  ignoreCase 
) const

Returns the start of this string, up to the first occurrence of a substring.

This will search for the first occurrence of a given substring, and then return a copy of the string, up to the position of this substring, optionally including or excluding the substring itself in the result.

e.g. for the string "123456", upTo ("34", false) would return "12", and upTo ("34", true) would return "1234".

If the substring isn't found, this will return the whole of the original string.

See also
upToLastOccurrenceOf, fromFirstOccurrenceOf

Definition at line 1591 of file juce_String.cpp.

References indexOf(), indexOfIgnoreCase(), juce::StringRef::length(), and substring().

Referenced by juce::WebInputStream::connect(), juce::XmlDocument::getLastParseError(), juce::XmlElement::getNamespace(), juce::ChildProcessSlave::initialiseFromCommandLine(), juce::ArgumentList::Argument::isLongOption(), juce::URL::isProbablyAWebsiteURL(), juce::File::isRoot(), juce::StringRef::StringRef(), and juce::URL::URL().

◆ upToLastOccurrenceOf()

String juce::String::upToLastOccurrenceOf ( StringRef  substringToFind,
bool  includeSubStringInResult,
bool  ignoreCase 
) const

Returns the start of this string, up to the last occurrence of a substring.

Similar to upToFirstOccurrenceOf(), but this finds the last occurrence rather than the first. If the substring isn't found, this will return the whole of the original string.

See also
upToFirstOccurrenceOf, fromFirstOccurrenceOf

Definition at line 1601 of file juce_String.cpp.

References lastIndexOf(), lastIndexOfIgnoreCase(), juce::StringRef::length(), and substring().

Referenced by juce::IPAddress::isNull(), and juce::StringRef::StringRef().

◆ trim()

◆ trimStart()

String juce::String::trimStart ( ) const

Returns a copy of this string with any whitespace characters removed from the start.

Definition at line 1680 of file juce_String.cpp.

References isNotEmpty(), and String().

Referenced by juce::StringRef::StringRef().

◆ trimEnd()

String juce::String::trimEnd ( ) const

Returns a copy of this string with any whitespace characters removed from the end.

Definition at line 1693 of file juce_String.cpp.

References isNotEmpty(), and String().

Referenced by juce::ChannelRemappingAudioSource::createXml(), juce::RelativeTime::getDescription(), juce::File::hasFileExtension(), juce::StringRef::StringRef(), and juce::Time::toString().

◆ trimCharactersAtStart()

String juce::String::trimCharactersAtStart ( StringRef  charactersToTrim) const

Returns a copy of this string, having removed a specified set of characters from its start.

Characters are removed from the start of the string until it finds one that is not in the specified set, and then it stops.

Parameters
charactersToTrimthe set of characters to remove.
See also
trim, trimStart, trimCharactersAtEnd

Definition at line 1707 of file juce_String.cpp.

References juce::CharPointer_UTF8::indexOf(), String(), and juce::StringRef::text.

◆ trimCharactersAtEnd()

String juce::String::trimCharactersAtEnd ( StringRef  charactersToTrim) const

Returns a copy of this string, having removed a specified set of characters from its end.

Characters are removed from the end of the string until it finds one that is not in the specified set, and then it stops.

Parameters
charactersToTrimthe set of characters to remove.
See also
trim, trimEnd, trimCharactersAtStart

Definition at line 1717 of file juce_String.cpp.

References juce::CharPointer_UTF8::indexOf(), isNotEmpty(), String(), and juce::StringRef::text.

Referenced by juce::File::createDirectory(), and juce::XmlDocument::getLastParseError().

◆ toUpperCase()

String juce::String::toUpperCase ( ) const

Returns an upper-case version of this string.

Definition at line 1462 of file juce_String.cpp.

References juce::CharPointer_UTF8::toUpperCase().

◆ toLowerCase()

String juce::String::toLowerCase ( ) const

Returns an lower-case version of this string.

Definition at line 1480 of file juce_String.cpp.

References juce::CharPointer_UTF8::toLowerCase().

Referenced by juce::Expression::withRenamedSymbol().

◆ replaceSection()

String juce::String::replaceSection ( int  startIndex,
int  numCharactersToReplace,
StringRef  stringToInsert 
) const

Replaces a sub-section of the string with another string.

This will return a copy of this string, with a set of characters from startIndex to startIndex + numCharsToReplace removed, and with a new string inserted in their place.

Note that this is a const method, and won't alter the string itself.

Parameters
startIndexthe first character to remove. If this is beyond the bounds of the string, it will be constrained to a valid range.
numCharactersToReplacethe number of characters to remove. If zero or less, no characters will be taken out.
stringToInsertthe new string to insert at startIndex after the characters have been removed.

Definition at line 1224 of file juce_String.cpp.

References juce::CharPointer_UTF8::getAddress(), juce::StringRef::isEmpty(), juce::StringRef::text, and juce::CharPointer_UTF8::writeNull().

Referenced by replace(), and replaceFirstOccurrenceOf().

◆ replace()

String juce::String::replace ( StringRef  stringToReplace,
StringRef  stringToInsertInstead,
bool  ignoreCase = false 
) const

Replaces all occurrences of a substring with another string.

Returns a copy of this string, with any occurrences of stringToReplace swapped for stringToInsertInstead.

Note that this is a const method, and won't alter the string itself.

Definition at line 1285 of file juce_String.cpp.

References indexOf(), indexOfIgnoreCase(), juce::StringRef::length(), and replaceSection().

Referenced by juce::IPAddress::getFormattedAddress(), juce::StringRef::StringRef(), and juce::LocalisedStrings::translate().

◆ replaceFirstOccurrenceOf()

String juce::String::replaceFirstOccurrenceOf ( StringRef  stringToReplace,
StringRef  stringToInsertInstead,
bool  ignoreCase = false 
) const

Replaces the first occurrence of a substring with another string.

Returns a copy of this string, with the first occurrence of stringToReplace swapped for stringToInsertInstead.

Note that this is a const method, and won't alter the string itself.

Definition at line 1303 of file juce_String.cpp.

References indexOf(), indexOfIgnoreCase(), juce::StringRef::length(), and replaceSection().

◆ replaceCharacter()

String juce::String::replaceCharacter ( juce_wchar  characterToReplace,
juce_wchar  characterToInsertInstead 
) const

Returns a string with all occurrences of a character replaced with a different one.

Definition at line 1350 of file juce_String.cpp.

References containsChar(), and juce::CharPointer_UTF8::getAndAdvance().

Referenced by juce::File::getChildFile(), juce::File::isRoot(), juce::URL::removeEscapeChars(), and juce::StringRef::StringRef().

◆ replaceCharacters()

String juce::String::replaceCharacters ( StringRef  charactersToReplace,
StringRef  charactersToInsertInstead 
) const

Replaces a set of characters with another set.

Returns a string in which each character from charactersToReplace has been replaced by the character at the equivalent position in newCharacters (so the two strings passed in must be the same length).

e.g. replaceCharacters ("abc", "def") replaces 'a' with 'd', 'b' with 'e', etc.

Note that this is a const method, and won't affect the string itself.

Definition at line 1373 of file juce_String.cpp.

References juce::CharPointer_UTF8::indexOf(), juce::StringRef::length(), and juce::StringRef::text.

Referenced by juce::StringRef::StringRef().

◆ retainCharacters()

String juce::String::retainCharacters ( StringRef  charactersToRetain) const

Returns a version of this string that only retains a fixed set of characters.

This will return a copy of this string, omitting any characters which are not found in the string passed-in.

e.g. for "1122334455", retainCharacters ("432") would return "223344"

Note that this is a const method, and won't alter the string itself.

Definition at line 1741 of file juce_String.cpp.

References juce::CharPointer_UTF8::getAndAdvance(), juce::CharPointer_UTF8::indexOf(), isEmpty(), and juce::StringRef::text.

Referenced by juce::StringRef::StringRef().

◆ removeCharacters()

String juce::String::removeCharacters ( StringRef  charactersToRemove) const

Returns a version of this string with a set of characters removed.

This will return a copy of this string, omitting any characters which are found in the string passed-in.

e.g. for "1122334455", removeCharacters ("432") would return "1155"

Note that this is a const method, and won't alter the string itself.

Definition at line 1763 of file juce_String.cpp.

References juce::CharPointer_UTF8::getAndAdvance(), juce::CharPointer_UTF8::indexOf(), isEmpty(), and juce::StringRef::text.

Referenced by juce::File::createLegalFileName(), juce::File::createLegalPathName(), and juce::StringRef::StringRef().

◆ initialSectionContainingOnly()

String juce::String::initialSectionContainingOnly ( StringRef  permittedCharacters) const

Returns a section from the start of the string that only contains a certain set of characters.

This returns the leftmost section of the string, up to (and not including) the first character that doesn't appear in the string passed in.

Definition at line 1784 of file juce_String.cpp.

References juce::CharPointer_UTF8::indexOf(), juce::StringRef::isEmpty(), and juce::StringRef::text.

Referenced by juce::StringRef::StringRef().

◆ initialSectionNotContaining()

String juce::String::initialSectionNotContaining ( StringRef  charactersToStopAt) const

Returns a section from the start of the string that only contains a certain set of characters.

This returns the leftmost section of the string, up to (and not including) the first character that occurs in the string passed in. (If none of the specified characters are found in the string, the return value will just be the original string).

Definition at line 1793 of file juce_String.cpp.

References juce::CharPointer_UTF8::indexOf(), juce::StringRef::isEmpty(), and juce::StringRef::text.

Referenced by juce::StringRef::StringRef().

◆ isQuotedString()

bool juce::String::isQuotedString ( ) const

Checks whether the string might be in quotation marks.

Returns
true if the string begins with a quote character (either a double or single quote). It is also true if there is whitespace before the quote, but it doesn't check the end of the string.
See also
unquoted, quoted

Definition at line 1616 of file juce_String.cpp.

Referenced by juce::JUCEApplicationBase::getCommandLineParameters(), and juce::StringRef::StringRef().

◆ unquoted()

String juce::String::unquoted ( ) const

Removes quotation marks from around the string, (if there are any).

Returns a copy of this string with any quotes removed from its ends. Quotes that aren't at the ends of the string are not affected. If there aren't any quotes, the original string is returned.

Note that this is a const method, and won't alter the string itself.

See also
isQuotedString, quoted

Definition at line 1621 of file juce_String.cpp.

References length(), and substring().

Referenced by juce::XmlDocument::getLastParseError(), and juce::StringRef::StringRef().

◆ quoted()

String juce::String::quoted ( juce_wchar  quoteCharacter = '"') const

Adds quotation marks around a string.

This will return a copy of the string with a quote at the start and end, (but won't add the quote if there's already one there, so it's safe to call this on strings that may already have quotes around them).

Note that this is a const method, and won't alter the string itself.

Parameters
quoteCharacterthe character to add at the start and end
See also
isQuotedString, unquoted

Definition at line 1630 of file juce_String.cpp.

References charToString(), endsWithChar(), isEmpty(), and startsWithChar().

Referenced by juce::JUCEApplicationBase::getCommandLineParameters(), and juce::StringRef::StringRef().

◆ repeatedString()

String juce::String::repeatedString ( StringRef  stringToRepeat,
int  numberOfTimesToRepeat 
)
static

Creates a string which is a version of a string repeated and joined together.

Parameters
stringToRepeatthe string to repeat
numberOfTimesToRepeathow many times to repeat it

Definition at line 1153 of file juce_String.cpp.

References juce::StringRef::text, and juce::CharPointer_UTF8::writeAll().

Referenced by juce::IPAddress::getFormattedAddress(), juce::File::getRelativePathFrom(), juce::ConsoleApplication::printCommandList(), and juce::StringRef::StringRef().

◆ createStringFromData()

String juce::String::createStringFromData ( const void *  data,
int  size 
)
static

Creates a string from data in an unknown format.

This looks at some binary data and tries to guess whether it's Unicode or 8-bit characters, then returns a string that represents it correctly.

Should be able to handle Unicode endianness correctly, by looking at the first two bytes.

Definition at line 1966 of file juce_String.cpp.

References charToString(), juce::CharPointer_UTF8::isByteOrderMark(), juce::CharPointer_UTF16::isByteOrderMarkBigEndian(), juce::CharPointer_UTF16::isByteOrderMarkLittleEndian(), juce::CharPointer_UTF8::isValidString(), juce::ByteOrder::swapIfBigEndian(), and juce::ByteOrder::swapIfLittleEndian().

Referenced by juce::MemoryOutputStream::toString().

◆ formatted()

template<typename... Args>
static String juce::String::formatted ( const String formatStr,
Args...  args 
)
inlinestatic

Creates a String from a printf-style parameter list.

I don't like this method. I don't use it myself, and I recommend avoiding it and using the operator<< methods or pretty much anything else instead. It's only provided here because of the popular unrest that was stirred-up when I tried to remove it...

If you're really determined to use it, at least make sure that you never, ever, pass any String objects to it as parameters. And bear in mind that internally, depending on the platform, it may be using wchar_t or char character types, so that even string literals can't be safely used as parameters if you're writing portable code.

Definition at line 910 of file juce_String.h.

References toRawUTF8().

Referenced by juce::Time::getUTCOffsetString(), and juce::Time::toISO8601().

◆ getIntValue()

int juce::String::getIntValue ( ) const
noexcept

Reads the value of the string as a decimal number (up to 32 bits in size).

Returns
the value of the string as a 32 bit signed base-10 integer.
See also
getTrailingIntValue, getHexValue32, getHexValue64

Definition at line 1869 of file juce_String.cpp.

Referenced by juce::MemoryBlock::fromBase64Encoding(), juce::AudioChannelSet::getChannelTypeFromAbbreviation(), juce::XmlDocument::getLastParseError(), and juce::StringRef::StringRef().

◆ getLargeIntValue()

int64 juce::String::getLargeIntValue ( ) const
noexcept

Reads the value of the string as a decimal number (up to 64 bits in size).

Returns
the value of the string as a 64 bit signed base-10 integer.

Definition at line 1870 of file juce_String.cpp.

Referenced by juce::StringRef::StringRef().

◆ getTrailingIntValue()

int juce::String::getTrailingIntValue ( ) const
noexcept

Parses a decimal number from the end of the string.

This will look for a value at the end of the string. e.g. for "321 xyz654" it will return 654; for "2 3 4" it'll return 4.

Negative numbers are not handled, so "xyz-5" returns 5.

See also
getIntValue

Definition at line 1874 of file juce_String.cpp.

References String().

◆ getFloatValue()

float juce::String::getFloatValue ( ) const
noexcept

Parses this string as a floating point number.

Returns
the value of the string as a 32-bit floating point value.
See also
getDoubleValue

Definition at line 1871 of file juce_String.cpp.

References getDoubleValue().

Referenced by juce::StringRef::StringRef().

◆ getDoubleValue()

double juce::String::getDoubleValue ( ) const
noexcept

Parses this string as a floating point number.

Returns
the value of the string as a 64-bit floating point value.
See also
getFloatValue

Definition at line 1872 of file juce_String.cpp.

Referenced by getFloatValue(), and juce::StringRef::StringRef().

◆ getHexValue32()

int juce::String::getHexValue32 ( ) const
noexcept

Parses the string as a hexadecimal number.

Non-hexadecimal characters in the string are ignored.

If the string contains too many characters, then the lowest significant digits are returned, e.g. "ffff12345678" would produce 0x12345678.

Returns
a 32-bit number which is the value of the string in hex.

Definition at line 1951 of file juce_String.cpp.

Referenced by juce::XmlDocument::getLastParseError(), and juce::StringRef::StringRef().

◆ getHexValue64()

int64 juce::String::getHexValue64 ( ) const
noexcept

Parses the string as a hexadecimal number.

Non-hexadecimal characters in the string are ignored.

If the string contains too many characters, then the lowest significant digits are returned, e.g. "ffff1234567812345678" would produce 0x1234567812345678.

Returns
a 64-bit number which is the value of the string in hex.

Definition at line 1952 of file juce_String.cpp.

References juce::CharacterFunctions::getUnicodeCharFromWindows1252Codepage().

Referenced by juce::StringRef::StringRef().

◆ toHexString() [1/2]

◆ toHexString() [2/2]

String juce::String::toHexString ( const void *  data,
int  size,
int  groupSize = 1 
)
static

Returns a string containing a hex dump of a block of binary data.

Parameters
datathe binary data to use as input
sizehow many bytes of data to use
groupSizehow many bytes are grouped together before inserting a space into the output. e.g. group size 0 has no spaces, group size 1 looks like: "be a1 c2 ff", group size 2 looks like "bea1 c2ff".

Definition at line 1923 of file juce_String.cpp.

References juce::CharPointer_UTF8::write().

◆ toDecimalStringWithSignificantFigures()

template<typename DecimalType >
static String juce::String::toDecimalStringWithSignificantFigures ( DecimalType  number,
int  numberOfSignificantFigures 
)
inlinestatic

Returns a string containing a decimal with a set number of significant figures.

Parameters
numberthe intput number
numberOfSignificantFiguresthe number of significant figures to use

Definition at line 1074 of file juce_String.h.

Referenced by juce::StringRef::StringRef().

◆ getCharPointer()

CharPointerType juce::String::getCharPointer ( ) const
inlinenoexcept

◆ toUTF8()

CharPointer_UTF8 juce::String::toUTF8 ( ) const

Returns a pointer to a UTF-8 version of this string.

Because it returns a reference to the string's internal data, the pointer that is returned must not be stored anywhere, as it can be deleted whenever the string changes.

To find out how many bytes you need to store this string as UTF-8, you can call CharPointer_UTF8::getBytesRequiredFor (myString.getCharPointer())

See also
toRawUTF8, getCharPointer, toUTF16, toUTF32

Definition at line 2068 of file juce_String.cpp.

Referenced by juce::StringRef::StringRef(), and toRawUTF8().

◆ toRawUTF8()

const char * juce::String::toRawUTF8 ( ) const

Returns a pointer to a UTF-8 version of this string.

Because it returns a reference to the string's internal data, the pointer that is returned must not be stored anywhere, as it can be deleted whenever the string changes.

To find out how many bytes you need to store this string as UTF-8, you can call CharPointer_UTF8::getBytesRequiredFor (myString.getCharPointer())

See also
getCharPointer, toUTF8, toUTF16, toUTF32

Definition at line 2072 of file juce_String.cpp.

References juce::CharPointer_UTF8::getAddress(), and toUTF8().

Referenced by juce::URL::addEscapeChars(), juce::File::createSymbolicLink(), formatted(), juce::StringRef::StringRef(), juce::Base64::toBase64(), toWideCharPointer(), juce::URL::withPOSTData(), juce::OutputStream::writeString(), and juce::OutputStream::writeText().

◆ toUTF16()

CharPointer_UTF16 juce::String::toUTF16 ( ) const

Returns a pointer to a UTF-16 version of this string.

Because it returns a reference to the string's internal data, the pointer that is returned must not be stored anywhere, as it can be deleted whenever the string changes.

To find out how many bytes you need to store this string as UTF-16, you can call CharPointer_UTF16::getBytesRequiredFor (myString.getCharPointer())

See also
getCharPointer, toUTF8, toUTF32

Definition at line 2069 of file juce_String.cpp.

Referenced by juce::StringRef::StringRef().

◆ toUTF32()

CharPointer_UTF32 juce::String::toUTF32 ( ) const

Returns a pointer to a UTF-32 version of this string.

Because it returns a reference to the string's internal data, the pointer that is returned must not be stored anywhere, as it can be deleted whenever the string changes.

See also
getCharPointer, toUTF8, toUTF16

Definition at line 2070 of file juce_String.cpp.

Referenced by juce::StringRef::StringRef().

◆ toWideCharPointer()

const wchar_t * juce::String::toWideCharPointer ( ) const

Returns a pointer to a wchar_t version of this string.

Because it returns a reference to the string's internal data, the pointer that is returned must not be stored anywhere, as it can be deleted whenever the string changes.

Bear in mind that the wchar_t type is different on different platforms, so on Windows, this will be equivalent to calling toUTF16(), on unix it'll be the same as calling toUTF32(), etc.

See also
getCharPointer, toUTF8, toUTF16, toUTF32

Definition at line 2077 of file juce_String.cpp.

References toRawUTF8().

Referenced by containsNonWhitespaceChars(), and juce::File::createSymbolicLink().

◆ fromUTF8()

String juce::String::fromUTF8 ( const char *  utf8buffer,
int  bufferSizeBytes = -1 
)
static

Creates a String from a UTF-8 encoded buffer.

If the size is < 0, it'll keep reading until it hits a zero.

Definition at line 2123 of file juce_String.cpp.

References juce::CharPointer_UTF8::isValidString(), and String().

Referenced by juce::URL::addEscapeChars(), juce::BufferedInputStream::readString(), juce::URL::removeEscapeChars(), and juce::MemoryBlock::toString().

◆ getNumBytesAsUTF8()

size_t juce::String::getNumBytesAsUTF8 ( ) const
noexcept

Returns the number of bytes required to represent this string as UTF8.

The number returned does NOT include the trailing zero.

See also
toUTF8, copyToUTF8

Definition at line 2118 of file juce_String.cpp.

References juce::CharPointer_UTF8::getBytesRequiredFor().

Referenced by juce::URL::addEscapeChars(), juce::URL::withPOSTData(), juce::OutputStream::writeString(), and juce::OutputStream::writeText().

◆ copyToUTF8()

size_t juce::String::copyToUTF8 ( CharPointer_UTF8::CharType *  destBuffer,
size_t  maxBufferSizeBytes 
) const
noexcept

Copies the string to a buffer as UTF-8 characters.

Returns the number of bytes copied to the buffer, including the terminating null character.

To find out how many bytes you need to store this string as UTF-8, you can call CharPointer_UTF8::getBytesRequiredFor (myString.getCharPointer())

Parameters
destBufferthe place to copy it to; if this is a null pointer, the method just returns the number of bytes required (including the terminating null character).
maxBufferSizeBytesthe size of the destination buffer, in bytes. If the string won't fit, it'll put in as many as it can while still allowing for a terminating null char at the end, and will return the number of bytes that were actually used.
See also
CharPointer_UTF8::writeWithDestByteLimit

Definition at line 2102 of file juce_String.cpp.

Referenced by juce::OutputStream::writeString().

◆ copyToUTF16()

size_t juce::String::copyToUTF16 ( CharPointer_UTF16::CharType *  destBuffer,
size_t  maxBufferSizeBytes 
) const
noexcept

Copies the string to a buffer as UTF-16 characters.

Returns the number of bytes copied to the buffer, including the terminating null character.

To find out how many bytes you need to store this string as UTF-16, you can call CharPointer_UTF16::getBytesRequiredFor (myString.getCharPointer())

Parameters
destBufferthe place to copy it to; if this is a null pointer, the method just returns the number of bytes required (including the terminating null character).
maxBufferSizeBytesthe size of the destination buffer, in bytes. If the string won't fit, it'll put in as many as it can while still allowing for a terminating null char at the end, and will return the number of bytes that were actually used.
See also
CharPointer_UTF16::writeWithDestByteLimit

Definition at line 2107 of file juce_String.cpp.

◆ copyToUTF32()

size_t juce::String::copyToUTF32 ( CharPointer_UTF32::CharType *  destBuffer,
size_t  maxBufferSizeBytes 
) const
noexcept

Copies the string to a buffer as UTF-32 characters.

Returns the number of bytes copied to the buffer, including the terminating null character.

To find out how many bytes you need to store this string as UTF-32, you can call CharPointer_UTF32::getBytesRequiredFor (myString.getCharPointer())

Parameters
destBufferthe place to copy it to; if this is a null pointer, the method just returns the number of bytes required (including the terminating null character).
maxBufferSizeBytesthe size of the destination buffer, in bytes. If the string won't fit, it'll put in as many as it can while still allowing for a terminating null char at the end, and will return the number of bytes that were actually used.
See also
CharPointer_UTF32::writeWithDestByteLimit

Definition at line 2112 of file juce_String.cpp.

◆ preallocateBytes()

void juce::String::preallocateBytes ( size_t  numBytesNeeded)

Increases the string's internally allocated storage.

Although the string's contents won't be affected by this call, it will increase the amount of memory allocated internally for the string to grow into.

If you're about to make a large number of calls to methods such as += or <<, it's more efficient to preallocate enough extra space beforehand, so that these methods won't have to keep resizing the string to append the extra characters.

Parameters
numBytesNeededthe number of bytes to allocate storage for. If this value is less than the currently allocated size, it will have no effect.

Definition at line 291 of file juce_String.cpp.

Referenced by appendCharPointer(), juce::RelativeTime::getDescription(), juce::StringArray::joinIntoString(), juce::MemoryBlock::toBase64Encoding(), and juce::Decibels::toString().

◆ swapWith()

void juce::String::swapWith ( String other)
noexcept

Swaps the contents of this string with another one.

This is a very fast operation, as no allocation or copying needs to be done.

Definition at line 255 of file juce_String.cpp.

◆ fromCFString()

static String juce::String::fromCFString ( CFStringRef  cfString)
static

OSX ONLY - Creates a String from an OSX CFString.

◆ toCFString()

CFStringRef juce::String::toCFString ( ) const

OSX ONLY - Converts this string to a CFString.

Remember that you must use CFRelease() to free the returned string when you're finished with it.

◆ convertToPrecomposedUnicode()

String juce::String::convertToPrecomposedUnicode ( ) const

OSX ONLY - Returns a copy of this string in which any decomposed unicode characters have been converted to their precomposed equivalents.


The documentation for this class was generated from the following files: