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.

Public Member Functions
	String () noexcept
	Creates an empty string.

	String (const String &) noexcept
	Creates a copy of another string.

	String (String &&) noexcept
	Move constructor.

	String (const char *text)
	Creates a string from a zero-terminated ascii text string.

	String (const char *text, size_t maxChars)
	Creates a string from a string of 8-bit ascii characters.

	String (const wchar_t *text)
	Creates a string from a wchar_t character string.

	String (const wchar_t *text, size_t maxChars)
	Creates a string from a wchar_t character string.

	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.

	String (StringRef)
	Creates a string from a StringRef.

	~String () noexcept
	Destructor.

int	hashCode () const noexcept
	Generates a probably-unique 32-bit hashcode from this string.

int64	hashCode64 () const noexcept
	Generates a probably-unique 64-bit hashcode from this string.

size_t	hash () const noexcept
	Generates a probably-unique hashcode from this string.

int	length () const noexcept
	Returns the number of characters in the string.

String &	operator= (const String &other) noexcept
	Replaces this string's contents with another string.

String &	operator= (String &&other) noexcept
	Moves the contents of another string to the receiver.

String &	operator+= (const String &stringToAppend)
	Appends another string at the end of this one.

String &	operator+= (const char *textToAppend)
	Appends another string at the end of this one.

String &	operator+= (const wchar_t *textToAppend)
	Appends another string at the end of this one.

String &	operator+= (StringRef textToAppend)
	Appends another string at the end of this one.

String &	operator+= (int numberToAppend)
	Appends a decimal number at the end of this string.

String &	operator+= (long numberToAppend)
	Appends a decimal number at the end of this string.

String &	operator+= (int64 numberToAppend)
	Appends a decimal number at the end of this string.

String &	operator+= (uint64 numberToAppend)
	Appends a decimal number at the end of this string.

String &	operator+= (char characterToAppend)
	Appends a character at the end of this string.

String &	operator+= (wchar_t characterToAppend)
	Appends a character at the end of this string.

String &	operator+= (juce_wchar characterToAppend)
	Appends a character at the end of this string.

void	append (const String &textToAppend, size_t maxCharsToTake)
	Appends a string to the end of this one.

void	appendCharPointer (CharPointerType startOfTextToAppend, CharPointerType endOfTextToAppend)
	Appends a string to the end of this one.

template<class CharPointer >
void	appendCharPointer (CharPointer startOfTextToAppend, CharPointer endOfTextToAppend)
	Appends a string to the end of this one.

void	appendCharPointer (CharPointerType textToAppend)
	Appends a string to the end of this one.

template<class CharPointer >
void	appendCharPointer (CharPointer textToAppend, size_t maxCharsToTake)
	Appends a string to the end of this one.

template<class CharPointer >
void	appendCharPointer (CharPointer textToAppend)
	Appends a string to the end of this one.

bool	isEmpty () const noexcept
	Returns true if the string contains no characters.

bool	isNotEmpty () const noexcept
	Returns true if the string contains at least one character.

void	clear () noexcept
	Resets this string to be empty.

bool	equalsIgnoreCase (const String &other) const noexcept
	Case-insensitive comparison with another string.

bool	equalsIgnoreCase (StringRef other) const noexcept
	Case-insensitive comparison with another string.

bool	equalsIgnoreCase (const wchar_t *other) const noexcept
	Case-insensitive comparison with another string.

bool	equalsIgnoreCase (const char *other) const noexcept
	Case-insensitive comparison with another string.

int	compare (const String &other) const noexcept
	Case-sensitive comparison with another string.

int	compare (const char *other) const noexcept
	Case-sensitive comparison with another string.

int	compare (const wchar_t *other) const noexcept
	Case-sensitive comparison with another string.

int	compareIgnoreCase (const String &other) const noexcept
	Case-insensitive comparison with another string.

int	compareNatural (StringRef other, bool isCaseSensitive=false) const noexcept
	Compares two strings, taking into account textual characteristics like numbers and spaces.

bool	startsWith (StringRef text) const noexcept
	Tests whether the string begins with another string.

bool	startsWithChar (juce_wchar character) const noexcept
	Tests whether the string begins with a particular character.

bool	startsWithIgnoreCase (StringRef text) const noexcept
	Tests whether the string begins with another string.

bool	endsWith (StringRef text) const noexcept
	Tests whether the string ends with another string.

bool	endsWithChar (juce_wchar character) const noexcept
	Tests whether the string ends with a particular character.

bool	endsWithIgnoreCase (StringRef text) const noexcept
	Tests whether the string ends with another string.

bool	contains (StringRef text) const noexcept
	Tests whether the string contains another substring.

bool	containsChar (juce_wchar character) const noexcept
	Tests whether the string contains a particular character.

bool	containsIgnoreCase (StringRef text) const noexcept
	Tests whether the string contains another substring.

bool	containsWholeWord (StringRef wordToLookFor) const noexcept
	Tests whether the string contains another substring as a distinct word.

bool	containsWholeWordIgnoreCase (StringRef wordToLookFor) const noexcept
	Tests whether the string contains another substring as a distinct word.

int	indexOfWholeWord (StringRef wordToLookFor) const noexcept
	Finds an instance of another substring if it exists as a distinct word.

int	indexOfWholeWordIgnoreCase (StringRef wordToLookFor) const noexcept
	Finds an instance of another substring if it exists as a distinct word.

bool	containsAnyOf (StringRef charactersItMightContain) const noexcept
	Looks for any of a set of characters in the string.

bool	containsOnly (StringRef charactersItMightContain) const noexcept
	Looks for a set of characters in the string.

bool	containsNonWhitespaceChars () const noexcept
	Returns true if this string contains any non-whitespace characters.

bool	matchesWildcard (StringRef wildcard, bool ignoreCase) const noexcept
	Returns true if the string matches this simple wildcard expression.

int	indexOfChar (juce_wchar characterToLookFor) const noexcept
	Searches for a character inside this string.

int	indexOfChar (int startIndex, juce_wchar characterToLookFor) const noexcept
	Searches for a character inside this string.

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.

int	indexOf (StringRef textToLookFor) const noexcept
	Searches for a substring within this string.

int	indexOf (int startIndex, StringRef textToLookFor) const noexcept
	Searches for a substring within this string.

int	indexOfIgnoreCase (StringRef textToLookFor) const noexcept
	Searches for a substring within this string.

int	indexOfIgnoreCase (int startIndex, StringRef textToLookFor) const noexcept
	Searches for a substring within this string.

int	lastIndexOfChar (juce_wchar character) const noexcept
	Searches for a character inside this string (working backwards from the end of the string).

int	lastIndexOf (StringRef textToLookFor) const noexcept
	Searches for a substring inside this string (working backwards from the end of the string).

int	lastIndexOfIgnoreCase (StringRef textToLookFor) const noexcept
	Searches for a substring inside this string (working backwards from the end of the string).

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.

juce_wchar	operator[] (int index) const noexcept
	Returns the character at this index in the string.

juce_wchar	getLastCharacter () const noexcept
	Returns the final character of the string.

String	substring (int startIndex, int endIndex) const
	Returns a subsection of the string.

String	substring (int startIndex) const
	Returns a section of the string, starting from a given position.

String	dropLastCharacters (int numberToDrop) const
	Returns a version of this string with a number of characters removed from the end.

String	getLastCharacters (int numCharacters) const
	Returns a number of characters from the end of the string.

String	fromFirstOccurrenceOf (StringRef substringToStartFrom, bool includeSubStringInResult, bool ignoreCase) const
	Returns a section of the string starting from a given substring.

String	fromLastOccurrenceOf (StringRef substringToFind, bool includeSubStringInResult, bool ignoreCase) const
	Returns a section of the string starting from the last occurrence of a given substring.

String	upToFirstOccurrenceOf (StringRef substringToEndWith, bool includeSubStringInResult, bool ignoreCase) const
	Returns the start of this string, up to the first occurrence of a substring.

String	upToLastOccurrenceOf (StringRef substringToFind, bool includeSubStringInResult, bool ignoreCase) const
	Returns the start of this string, up to the last occurrence of a substring.

String	trim () const
	Returns a copy of this string with any whitespace characters removed from the start and end.

String	trimStart () const
	Returns a copy of this string with any whitespace characters removed from the start.

String	trimEnd () const
	Returns a copy of this string with any whitespace characters removed from the end.

String	trimCharactersAtStart (StringRef charactersToTrim) const
	Returns a copy of this string, having removed a specified set of characters from its start.

String	trimCharactersAtEnd (StringRef charactersToTrim) const
	Returns a copy of this string, having removed a specified set of characters from its end.

String	toUpperCase () const
	Returns an upper-case version of this string.

String	toLowerCase () const
	Returns an lower-case version of this string.

String	replaceSection (int startIndex, int numCharactersToReplace, StringRef stringToInsert) const
	Replaces a sub-section of the string with another string.

String	replace (StringRef stringToReplace, StringRef stringToInsertInstead, bool ignoreCase=false) const
	Replaces all occurrences of a substring with another string.

String	replaceFirstOccurrenceOf (StringRef stringToReplace, StringRef stringToInsertInstead, bool ignoreCase=false) const
	Replaces the first occurrence of a substring with another string.

String	replaceCharacter (juce_wchar characterToReplace, juce_wchar characterToInsertInstead) const
	Returns a string with all occurrences of a character replaced with a different one.

String	replaceCharacters (StringRef charactersToReplace, StringRef charactersToInsertInstead) const
	Replaces a set of characters with another set.

String	retainCharacters (StringRef charactersToRetain) const
	Returns a version of this string that only retains a fixed set of characters.

String	removeCharacters (StringRef charactersToRemove) const
	Returns a version of this string with a set of characters removed.

String	initialSectionContainingOnly (StringRef permittedCharacters) const
	Returns a section from the start of the string that only contains a certain set of characters.

String	initialSectionNotContaining (StringRef charactersToStopAt) const
	Returns a section from the start of the string that only contains a certain set of characters.

bool	isQuotedString () const
	Checks whether the string might be in quotation marks.

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

String	quoted (juce_wchar quoteCharacter='"') const
	Adds quotation marks around a string.

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.

CharPointerType	begin () const
	Returns an iterator pointing at the beginning of the string.

CharPointerType	end () const
	Returns an iterator pointing at the terminating null of the string.

	String (int decimalInteger)
	Creates a string containing this signed 32-bit integer as a decimal number.

	String (unsigned int decimalInteger)
	Creates a string containing this unsigned 32-bit integer as a decimal number.

	String (short decimalInteger)
	Creates a string containing this signed 16-bit integer as a decimal number.

	String (unsigned short decimalInteger)
	Creates a string containing this unsigned 16-bit integer as a decimal number.

	String (int64 largeIntegerValue)
	Creates a string containing this signed 64-bit integer as a decimal number.

	String (uint64 largeIntegerValue)
	Creates a string containing this unsigned 64-bit integer as a decimal number.

	String (long decimalInteger)
	Creates a string containing this signed long integer as a decimal number.

	String (unsigned long decimalInteger)
	Creates a string containing this unsigned long integer as a decimal number.

	String (float floatValue)
	Creates a string representing this floating-point number.

	String (double doubleValue)
	Creates a string representing this floating-point number.

	String (float floatValue, int numberOfDecimalPlaces, bool useScientificNotation=false)
	Creates a string representing this floating-point number.

	String (double doubleValue, int numberOfDecimalPlaces, bool useScientificNotation=false)
	Creates a string representing this floating-point number.

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

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

int	getTrailingIntValue () const noexcept
	Parses a decimal number from the end of the string.

float	getFloatValue () const noexcept
	Parses this string as a floating point number.

double	getDoubleValue () const noexcept
	Parses this string as a floating point number.

int	getHexValue32 () const noexcept
	Parses the string as a hexadecimal number.

int64	getHexValue64 () const noexcept
	Parses the string as a hexadecimal number.

CharPointerType	getCharPointer () const noexcept
	Returns the character pointer currently being used to store this string.

CharPointer_UTF8	toUTF8 () const
	Returns a pointer to a UTF-8 version of this string.

const char *	toRawUTF8 () const
	Returns a pointer to a UTF-8 version of this string.

CharPointer_UTF16	toUTF16 () const
	Returns a pointer to a UTF-16 version of this string.

CharPointer_UTF32	toUTF32 () const
	Returns a pointer to a UTF-32 version of this string.

const wchar_t *	toWideCharPointer () const
	Returns a pointer to a wchar_t version of this string.

std::string	toStdString () const

size_t	getNumBytesAsUTF8 () const noexcept
	Returns the number of bytes required to represent this string as UTF8.

size_t	copyToUTF8 (CharPointer_UTF8::CharType *destBuffer, size_t maxBufferSizeBytes) const noexcept
	Copies the string to a buffer as UTF-8 characters.

size_t	copyToUTF16 (CharPointer_UTF16::CharType *destBuffer, size_t maxBufferSizeBytes) const noexcept
	Copies the string to a buffer as UTF-16 characters.

size_t	copyToUTF32 (CharPointer_UTF32::CharType *destBuffer, size_t maxBufferSizeBytes) const noexcept
	Copies the string to a buffer as UTF-32 characters.

void	preallocateBytes (size_t numBytesNeeded)
	Increases the string's internally allocated storage.

void	swapWith (String &other) noexcept
	Swaps the contents of this string with another one.

CFStringRef	toCFString () const
	OSX ONLY - Converts this string to a CFString.

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

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.

static String	repeatedString (StringRef stringToRepeat, int numberOfTimesToRepeat)
	Creates a string which is a version of a string repeated and joined together.

static String	createStringFromData (const void *data, int size)
	Creates a string from data in an unknown format.

template<typename... Args>
static String	formatted (const String &formatStr, Args... args)
	Creates a String from a printf-style parameter list.

template<typename IntegerType >
static String	toHexString (IntegerType number)
	Returns a string representing this numeric value in hexadecimal.

static String	toHexString (const void *data, int size, int groupSize=1)
	Returns a string containing a hex dump of a block of binary data.

template<typename DecimalType >
static String	toDecimalStringWithSignificantFigures (DecimalType number, int numberOfSignificantFigures)
	Returns a string containing a decimal with a set number of significant figures.

static String	fromUTF8 (const char *utf8buffer, int bufferSizeBytes=-1)
	Creates a String from a UTF-8 encoded buffer.

static String	fromCFString (CFStringRef cfString)
	OSX ONLY - Creates a String from an OSX CFString.

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

@tags{Core}

Definition at line 52 of file juce_String.h.

Member Typedef Documentation

◆ CharPointerType

using juce::String::CharPointerType = CharPointer_UTF8

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 174 of file juce_String.h.

Constructor & Destructor Documentation

◆ String() [1/31]

juce::String::String ( )

noexcept

Creates an empty string.

See also: empty

Definition at line 234 of file juce_String.cpp.

◆ String() [2/31]

juce::String::String ( const String & other )

noexcept

Creates a copy of another string.

Definition at line 243 of file juce_String.cpp.

◆ String() [3/31]

juce::String::String ( String && other )

noexcept

Move constructor.

Definition at line 266 of file juce_String.cpp.

◆ String() [4/31]

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 295 of file juce_String.cpp.

◆ String() [5/31]

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 318 of file juce_String.cpp.

◆ String() [6/31]

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 341 of file juce_String.cpp.

◆ String() [7/31]

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 350 of file juce_String.cpp.

◆ String() [8/31]

juce::String::String ( CharPointer_UTF8 text )

Creates a string from a UTF-8 character string.

Definition at line 342 of file juce_String.cpp.

◆ String() [9/31]

juce::String::String	(	CharPointer_UTF8	text,
		size_t	maxChars
	)

Creates a string from a UTF-8 character string.

Definition at line 347 of file juce_String.cpp.

◆ String() [10/31]

juce::String::String	(	CharPointer_UTF8	start,
		CharPointer_UTF8	end
	)

Creates a string from a UTF-8 character string.

Definition at line 352 of file juce_String.cpp.

◆ String() [11/31]

juce::String::String ( CharPointer_UTF16 text )

Creates a string from a UTF-16 character string.

Definition at line 343 of file juce_String.cpp.

◆ String() [12/31]

juce::String::String	(	CharPointer_UTF16	text,
		size_t	maxChars
	)

Creates a string from a UTF-16 character string.

Definition at line 348 of file juce_String.cpp.

◆ String() [13/31]

juce::String::String	(	CharPointer_UTF16	start,
		CharPointer_UTF16	end
	)

Creates a string from a UTF-16 character string.

Definition at line 353 of file juce_String.cpp.

◆ String() [14/31]

juce::String::String ( CharPointer_UTF32 text )

Creates a string from a UTF-32 character string.

Definition at line 344 of file juce_String.cpp.

◆ String() [15/31]

juce::String::String	(	CharPointer_UTF32	text,
		size_t	maxChars
	)

Creates a string from a UTF-32 character string.

Definition at line 349 of file juce_String.cpp.

◆ String() [16/31]

juce::String::String	(	CharPointer_UTF32	start,
		CharPointer_UTF32	end
	)

Creates a string from a UTF-32 character string.

Definition at line 354 of file juce_String.cpp.

◆ String() [17/31]

juce::String::String ( CharPointer_ASCII text )

Creates a string from an ASCII character string.

Definition at line 345 of file juce_String.cpp.

◆ String() [18/31]

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

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

Definition at line 356 of file juce_String.cpp.

◆ String() [19/31]

juce::String::String ( StringRef s )

Creates a string from a StringRef.

Definition at line 357 of file juce_String.cpp.

◆ ~String()

juce::String::~String ( )

noexcept

Destructor.

Definition at line 238 of file juce_String.cpp.

◆ String() [20/31]

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 496 of file juce_String.cpp.

◆ String() [21/31]

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 497 of file juce_String.cpp.

◆ String() [22/31]

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 498 of file juce_String.cpp.

◆ String() [23/31]

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 499 of file juce_String.cpp.

◆ String() [24/31]

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 500 of file juce_String.cpp.

◆ String() [25/31]

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 501 of file juce_String.cpp.

◆ String() [26/31]

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 502 of file juce_String.cpp.

◆ String() [27/31]

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 503 of file juce_String.cpp.

◆ String() [28/31]

juce::String::String ( float floatValue )

explicit

Creates a string representing this floating-point number.

Parameters

floatValue the value to convert to a string

See also: getDoubleValue, getIntValue

Definition at line 505 of file juce_String.cpp.

◆ String() [29/31]

juce::String::String ( double doubleValue )

explicit

Creates a string representing this floating-point number.

Parameters

doubleValue the value to convert to a string

See also: getFloatValue, getIntValue

Definition at line 506 of file juce_String.cpp.

◆ String() [30/31]

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

Creates a string representing this floating-point number.

Parameters

floatValue	the value to convert to a string
numberOfDecimalPlaces	if 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.
useScientificNotation	if the number should be formatted using scientific notation

See also: getDoubleValue, getIntValue

Definition at line 507 of file juce_String.cpp.

◆ String() [31/31]

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

Creates a string representing this floating-point number.

Parameters

doubleValue	the value to convert to a string
numberOfDecimalPlaces	if 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.
useScientificNotation	if the number should be formatted using scientific notation

See also: getFloatValue, getIntValue

Definition at line 508 of file juce_String.cpp.

Member Function Documentation

◆ append()

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

Appends a string to the end of this one.

Parameters

textToAppend	the string to add
maxCharsToTake	the maximum number of characters to take from the string passed in

Definition at line 706 of file juce_String.cpp.

◆ appendCharPointer() [1/5]

template<class CharPointer >

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

Appends a string to the end of this one.

Parameters

startOfTextToAppend	the start of the string to add. This must not be a nullptr
endOfTextToAppend	the end of the string to add. This must not be a nullptr

Definition at line 247 of file juce_String.h.

◆ appendCharPointer() [2/5]

template<class CharPointer >

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

Appends a string to the end of this one.

Definition at line 298 of file juce_String.h.

◆ appendCharPointer() [3/5]

template<class CharPointer >

void juce::String::appendCharPointer	(	CharPointer	textToAppend,
		size_t	maxCharsToTake
	)

Appends a string to the end of this one.

Parameters

textToAppend	the string to add
maxCharsToTake	the maximum number of characters to take from the string passed in

Definition at line 276 of file juce_String.h.

◆ appendCharPointer() [4/5]

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

Appends a string to the end of this one.

Parameters

startOfTextToAppend	the start of the string to add. This must not be a nullptr
endOfTextToAppend	the end of the string to add. This must not be a nullptr

Definition at line 717 of file juce_String.cpp.

◆ appendCharPointer() [5/5]

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

Appends a string to the end of this one.

Definition at line 712 of file juce_String.cpp.

◆ begin()

CharPointerType juce::String::begin ( ) const

Returns an iterator pointing at the beginning of the string.

Definition at line 923 of file juce_String.h.

◆ charToString()

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

static

Creates a string from a single character.

Definition at line 359 of file juce_String.cpp.

◆ clear()

void juce::String::clear ( )

noexcept

Resets this string to be empty.

Definition at line 253 of file juce_String.cpp.

◆ compare() [1/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 597 of file juce_String.cpp.

◆ compare() [2/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 596 of file juce_String.cpp.

◆ 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 598 of file juce_String.cpp.

◆ compareIgnoreCase()

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

noexcept

Case-insensitive 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 599 of file juce_String.cpp.

◆ 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 700 of file juce_String.cpp.

◆ 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 1035 of file juce_String.cpp.

◆ 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 1805 of file juce_String.cpp.

◆ containsChar()

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

noexcept

Tests whether the string contains a particular character.

Uses a case-sensitive comparison.

Definition at line 1040 of file juce_String.cpp.

◆ containsIgnoreCase()

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

noexcept

Tests whether the string contains another substring.

Uses a case-insensitive comparison.

Definition at line 1045 of file juce_String.cpp.

◆ 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 1814 of file juce_String.cpp.

◆ 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 1796 of file juce_String.cpp.

◆ 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 1094 of file juce_String.cpp.

◆ 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 1099 of file juce_String.cpp.

◆ 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

destBuffer	the 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).
maxBufferSizeBytes	the 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 2109 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

destBuffer	the 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).
maxBufferSizeBytes	the 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 2114 of file juce_String.cpp.

◆ 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

destBuffer	the 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).
maxBufferSizeBytes	the 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 2104 of file juce_String.cpp.

◆ 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 1968 of file juce_String.cpp.

◆ dropLastCharacters()

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

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

Parameters

numberToDrop the 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 1555 of file juce_String.cpp.

◆ end()

CharPointerType juce::String::end ( ) const

Returns an iterator pointing at the terminating null of the string.

Note that this has to find the terminating null before returning it, so prefer to call this once before looping and then reuse the result, rather than calling 'end()' each time through the loop.

String str = ...;
 
// BEST
for (auto c : str)
    DBG (c);
 
// GOOD
for (auto ptr = str.begin(), end = str.end(); ptr != end; ++ptr)
    DBG (*ptr);
 
std::for_each (str.begin(), str.end(), [] (juce_wchar c) { DBG (c); });
 
// BAD
for (auto ptr = str.begin(); ptr != str.end(); ++ptr)
    DBG (*ptr);

Definition at line 949 of file juce_String.h.

◆ 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 1421 of file juce_String.cpp.

◆ 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 1410 of file juce_String.cpp.

◆ 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 1438 of file juce_String.cpp.

◆ equalsIgnoreCase() [1/4]

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

noexcept

Case-insensitive comparison with another string.

Definition at line 579 of file juce_String.cpp.

◆ equalsIgnoreCase() [2/4]

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

noexcept

Case-insensitive comparison with another string.

Definition at line 590 of file juce_String.cpp.

◆ equalsIgnoreCase() [3/4]

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

noexcept

Case-insensitive comparison with another string.

Definition at line 573 of file juce_String.cpp.

◆ equalsIgnoreCase() [4/4]

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

noexcept

Case-insensitive comparison with another string.

Definition at line 585 of file juce_String.cpp.

◆ formatted()

template<typename... Args>

static String juce::String::formatted	(	const String &	formatStr,
		Args...	args
	)

static

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 920 of file juce_String.h.

◆ 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 1565 of file juce_String.cpp.

◆ 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 1575 of file juce_String.cpp.

◆ 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 2125 of file juce_String.cpp.

◆ getCharPointer()

CharPointerType juce::String::getCharPointer ( ) const

noexcept

Returns the character pointer currently being used to store 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.

Definition at line 1153 of file juce_String.h.

◆ 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 1874 of file juce_String.cpp.

◆ 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 1873 of file juce_String.cpp.

◆ 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 1953 of file juce_String.cpp.

◆ 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 1954 of file juce_String.cpp.

◆ 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 1871 of file juce_String.cpp.

◆ 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 1872 of file juce_String.cpp.

◆ 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 1493 of file juce_String.cpp.

◆ 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 1560 of file juce_String.cpp.

◆ 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 2120 of file juce_String.cpp.

◆ getReferenceCount()

int juce::String::getReferenceCount ( ) const

noexcept

Returns the number of String objects which are currently sharing the same internal data as this one.

Definition at line 289 of file juce_String.cpp.

◆ 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.

If the string ends with a hyphen followed by numeric characters, the return value will be negative.

See also: getIntValue

Definition at line 1876 of file juce_String.cpp.

◆ hash()

size_t juce::String::hash ( ) const

noexcept

Generates a probably-unique hashcode from this string.

Definition at line 551 of file juce_String.cpp.

◆ hashCode()

int juce::String::hashCode ( ) const

noexcept

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

Definition at line 549 of file juce_String.cpp.

◆ hashCode64()

int64 juce::String::hashCode64 ( ) const

noexcept

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

Definition at line 550 of file juce_String.cpp.

◆ indexOf() [1/2]

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

noexcept

Searches for a substring within this string.

Uses a case-sensitive comparison.

Parameters

startIndex	the index from which the search should proceed
textToLookFor	the 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 941 of file juce_String.cpp.

◆ indexOf() [2/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 931 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 911 of file juce_String.cpp.

◆ indexOfChar() [1/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

startIndex	the index from which the search should proceed
characterToLookFor	the 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 879 of file juce_String.cpp.

◆ indexOfChar() [2/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 874 of file juce_String.cpp.

◆ indexOfIgnoreCase() [1/2]

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

noexcept

Searches for a substring within this string.

Uses a case-insensitive comparison.

Parameters

startIndex	the index from which the search should proceed
textToLookFor	the 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 960 of file juce_String.cpp.

◆ indexOfIgnoreCase() [2/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 936 of file juce_String.cpp.

◆ 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 1050 of file juce_String.cpp.

◆ 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 1072 of file juce_String.cpp.

◆ 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 1778 of file juce_String.cpp.

◆ 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 1787 of file juce_String.cpp.

◆ isEmpty()

bool juce::String::isEmpty ( ) const

noexcept

Returns true if the string contains no characters.

Note that there's also an isNotEmpty() method to help write readable code.

See also: containsNonWhitespaceChars()

Definition at line 310 of file juce_String.h.

◆ isNotEmpty()

bool juce::String::isNotEmpty ( ) const

noexcept

Returns true if the string contains at least one character.

Note that there's also an isEmpty() method to help write readable code.

See also: containsNonWhitespaceChars()

Definition at line 316 of file juce_String.h.

◆ 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 1610 of file juce_String.cpp.

◆ 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 979 of file juce_String.cpp.

◆ 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 1023 of file juce_String.cpp.

◆ 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 899 of file juce_String.cpp.

◆ 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 1001 of file juce_String.cpp.

◆ length()

int juce::String::length ( ) const

noexcept

Returns the number of characters in the string.

Definition at line 511 of file juce_String.cpp.

◆ 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 1141 of file juce_String.cpp.

◆ operator+=() [1/10]

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

Appends a character at the end of this string.

Definition at line 766 of file juce_String.cpp.

◆ operator+=() [2/10]

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

Appends another string at the end of this one.

Definition at line 743 of file juce_String.cpp.

◆ operator+=() [3/10]

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

Appends another string at the end of this one.

Definition at line 749 of file juce_String.cpp.

◆ operator+=() [4/10]

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

Appends another string at the end of this one.

Definition at line 737 of file juce_String.cpp.

◆ operator+=() [5/10]

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

Appends a decimal number at the end of this string.

Definition at line 806 of file juce_String.cpp.

◆ operator+=() [6/10]

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

Appends a decimal number at the end of this string.

Definition at line 808 of file juce_String.cpp.

◆ operator+=() [7/10]

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

Appends a decimal number at the end of this string.

Definition at line 807 of file juce_String.cpp.

◆ operator+=() [8/10]

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

Appends another string at the end of this one.

Definition at line 761 of file juce_String.cpp.

◆ operator+=() [9/10]

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

Appends a decimal number at the end of this string.

Definition at line 809 of file juce_String.cpp.

◆ operator+=() [10/10]

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

Appends a character at the end of this string.

Definition at line 772 of file juce_String.cpp.

◆ operator=() [1/2]

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

noexcept

Replaces this string's contents with another string.

Definition at line 259 of file juce_String.cpp.

◆ operator=() [2/2]

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

noexcept

Moves the contents of another string to the receiver.

Definition at line 271 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 526 of file juce_String.cpp.

◆ paddedLeft()

String juce::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.

Definition at line 1161 of file juce_String.cpp.

◆ paddedRight()

String juce::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.

Definition at line 1188 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

numBytesNeeded the 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 284 of file juce_String.cpp.

◆ 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

quoteCharacter the character to add at the start and end

See also: isQuotedString, unquoted

Definition at line 1624 of file juce_String.cpp.

◆ 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 1757 of file juce_String.cpp.

◆ 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

stringToRepeat	the string to repeat
numberOfTimesToRepeat	how many times to repeat it

Definition at line 1147 of file juce_String.cpp.

◆ 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 1279 of file juce_String.cpp.

◆ 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 1344 of file juce_String.cpp.

◆ 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 1367 of file juce_String.cpp.

◆ 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 1297 of file juce_String.cpp.

◆ 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

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

Definition at line 1218 of file juce_String.cpp.

◆ 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 1735 of file juce_String.cpp.

◆ 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 1393 of file juce_String.cpp.

◆ 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 1403 of file juce_String.cpp.

◆ 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 1398 of file juce_String.cpp.

◆ substring() [1/2]

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

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

Parameters

startIndex the 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 1537 of file juce_String.cpp.

◆ substring() [2/2]

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

Returns a subsection of the string.

If the range specified is beyond the limits of the string, as much as possible is returned.

Parameters

startIndex	the index of the start of the substring needed
endIndex	all characters from startIndex up to (but not including) this index are returned

See also: fromFirstOccurrenceOf, dropLastCharacters, getLastCharacters, upToFirstOccurrenceOf

Definition at line 1498 of file juce_String.cpp.

◆ 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 248 of file juce_String.cpp.

◆ 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.

◆ toDecimalStringWithSignificantFigures()

template<typename DecimalType >

static String juce::String::toDecimalStringWithSignificantFigures	(	DecimalType	number,
		int	numberOfSignificantFigures
	)

static

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

Parameters

number	the input number
numberOfSignificantFigures	the number of significant figures to use

Definition at line 1116 of file juce_String.h.

◆ toHexString() [1/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

data	the binary data to use as input
size	how many bytes of data to use
groupSize	how 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 1925 of file juce_String.cpp.

◆ toHexString() [2/2]

template<typename IntegerType >

static String juce::String::toHexString ( IntegerType number )

static

Returns a string representing this numeric value in hexadecimal.

Definition at line 1097 of file juce_String.h.

◆ toLowerCase()

String juce::String::toLowerCase ( ) const

Returns an lower-case version of this string.

Definition at line 1474 of file juce_String.cpp.

◆ 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 2074 of file juce_String.cpp.

◆ toStdString()

std::string juce::String::toStdString ( ) const

Definition at line 2084 of file juce_String.cpp.

◆ toUpperCase()

String juce::String::toUpperCase ( ) const

Returns an upper-case version of this string.

Definition at line 1456 of file juce_String.cpp.

◆ 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 2071 of file juce_String.cpp.

◆ 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 2072 of file juce_String.cpp.

◆ 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 2070 of file juce_String.cpp.

◆ 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 2079 of file juce_String.cpp.

◆ trim()

String juce::String::trim ( ) const

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

Definition at line 1656 of file juce_String.cpp.

◆ 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

charactersToTrim the set of characters to remove.

See also: trim, trimEnd, trimCharactersAtStart

Definition at line 1711 of file juce_String.cpp.

◆ 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

charactersToTrim the set of characters to remove.

See also: trim, trimStart, trimCharactersAtEnd

Definition at line 1701 of file juce_String.cpp.

◆ trimEnd()

String juce::String::trimEnd ( ) const

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

Definition at line 1687 of file juce_String.cpp.

◆ trimStart()

String juce::String::trimStart ( ) const

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

Definition at line 1674 of file juce_String.cpp.

◆ 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 1615 of file juce_String.cpp.

◆ 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 1585 of file juce_String.cpp.

◆ 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 1595 of file juce_String.cpp.

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

juce_core/text/juce_String.h
juce_core/text/juce_String.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ CharPointerType

Constructor & Destructor Documentation

◆ String() [1/31]

◆ String() [2/31]

◆ String() [3/31]

◆ String() [4/31]

◆ String() [5/31]

◆ String() [6/31]

◆ String() [7/31]

◆ String() [8/31]

◆ String() [9/31]

◆ String() [10/31]

◆ String() [11/31]

◆ String() [12/31]

◆ String() [13/31]

◆ String() [14/31]

◆ String() [15/31]

◆ String() [16/31]

◆ String() [17/31]

◆ String() [18/31]

◆ String() [19/31]

◆ ~String()

◆ String() [20/31]

◆ String() [21/31]

◆ String() [22/31]

◆ String() [23/31]

◆ String() [24/31]

◆ String() [25/31]

◆ String() [26/31]

◆ String() [27/31]

◆ String() [28/31]

◆ String() [29/31]

◆ String() [30/31]

◆ String() [31/31]

Member Function Documentation

◆ append()

◆ appendCharPointer() [1/5]

◆ appendCharPointer() [2/5]

◆ appendCharPointer() [3/5]

◆ appendCharPointer() [4/5]

◆ appendCharPointer() [5/5]

◆ begin()

◆ charToString()

◆ clear()

◆ compare() [1/3]

◆ compare() [2/3]

◆ compare() [3/3]

◆ compareIgnoreCase()

◆ compareNatural()

◆ contains()

◆ containsAnyOf()

◆ containsChar()

◆ containsIgnoreCase()

◆ containsNonWhitespaceChars()

◆ containsOnly()

◆ containsWholeWord()

◆ containsWholeWordIgnoreCase()

◆ copyToUTF16()

◆ copyToUTF32()

◆ copyToUTF8()

◆ createStringFromData()

◆ dropLastCharacters()

◆ end()

◆ endsWith()

◆ endsWithChar()

◆ endsWithIgnoreCase()

◆ equalsIgnoreCase() [1/4]

◆ equalsIgnoreCase() [2/4]

◆ equalsIgnoreCase() [3/4]

◆ equalsIgnoreCase() [4/4]

◆ formatted()

◆ fromFirstOccurrenceOf()

◆ fromLastOccurrenceOf()

◆ fromUTF8()

◆ getCharPointer()