String Class Reference

The JUCE String class! More...

List of all members.

Classes

struct  InternalRefCountedStringHolder

Public Member Functions

 String () throw ()
 Creates an empty string.
 String (const String &other) throw ()
 Creates a copy of another string.
 String (const char *const text) throw ()
 Creates a string from a zero-terminated text string.
 String (const char *const text, const int maxChars) throw ()
 Creates a string from an string of characters.
 String (const juce_wchar *const unicodeText) throw ()
 Creates a string from a zero-terminated unicode text string.
 String (const juce_wchar *const unicodeText, const int maxChars) throw ()
 Creates a string from a unicode text string.
 ~String () throw ()
 Destructor.
int hashCode () const throw ()
 Generates a probably-unique 32-bit hashcode from this string.
int64 hashCode64 () const throw ()
 Generates a probably-unique 64-bit hashcode from this string.
int length () const throw ()
 Returns the number of characters in the string.
const String & operator= (const tchar *const other) throw ()
 Replaces this string's contents with another string.
const String & operator= (const String &other) throw ()
 Replaces this string's contents with another string.
const String & operator+= (const tchar *const textToAppend) throw ()
 Appends another string at the end of this one.
const String & operator+= (const String &stringToAppend) throw ()
 Appends another string at the end of this one.
const String & operator+= (const char characterToAppend) throw ()
 Appends a character at the end of this string.
const String & operator+= (const juce_wchar characterToAppend) throw ()
 Appends a character at the end of this string.
void append (const tchar *const textToAppend, const int maxCharsToTake) throw ()
 Appends a string at the end of this one.
const String operator+ (const String &stringToAppend) const throw ()
 Appends a string at the end of this one.
const String operator+ (const tchar *const textToAppend) const throw ()
 Appends a string at the end of this one.
const String operator+ (const tchar characterToAppend) const throw ()
 Appends a character at the end of this one.
String & operator<< (const char n) throw ()
 Appends a character at the end of this string.
String & operator<< (const juce_wchar n) throw ()
 Appends a character at the end of this string.
String & operator<< (const char *const text) throw ()
 Appends another string at the end of this one.
String & operator<< (const juce_wchar *const text) throw ()
 Appends another string at the end of this one.
String & operator<< (const String &text) throw ()
 Appends another string at the end of this one.
String & operator<< (const short number) throw ()
 Appends a decimal number at the end of this string.
String & operator<< (const int number) throw ()
 Appends a decimal number at the end of this string.
String & operator<< (const unsigned int number) throw ()
 Appends a decimal number at the end of this string.
String & operator<< (const float number) throw ()
 Appends a decimal number at the end of this string.
String & operator<< (const double number) throw ()
 Appends a decimal number at the end of this string.
bool isEmpty () const throw ()
 Returns true if the string contains no characters.
bool isNotEmpty () const throw ()
 Returns true if the string contains at least one character.
bool operator== (const String &other) const throw ()
 Case-sensitive comparison with another string.
bool operator== (const tchar *const other) const throw ()
 Case-sensitive comparison with another string.
bool operator!= (const String &other) const throw ()
 Case-sensitive comparison with another string.
bool operator!= (const tchar *const other) const throw ()
 Case-sensitive comparison with another string.
bool equalsIgnoreCase (const String &other) const throw ()
 Case-insensitive comparison with another string.
bool equalsIgnoreCase (const tchar *const other) const throw ()
 Case-insensitive comparison with another string.
bool operator> (const String &other) const throw ()
 Case-sensitive comparison with another string.
bool operator< (const tchar *const other) const throw ()
 Case-sensitive comparison with another string.
bool operator>= (const String &other) const throw ()
 Case-sensitive comparison with another string.
bool operator<= (const tchar *const other) const throw ()
 Case-sensitive comparison with another string.
int compare (const tchar *const other) const throw ()
 Case-sensitive comparison with another string.
int compareIgnoreCase (const tchar *const other) const throw ()
 Case-insensitive comparison with another string.
int compareLexicographically (const tchar *const other) const throw ()
 Lexicographic comparison with another string.
bool startsWith (const tchar *const text) const throw ()
 Tests whether the string begins with another string.
bool startsWithChar (const tchar character) const throw ()
 Tests whether the string begins with a particular character.
bool startsWithIgnoreCase (const tchar *const text) const throw ()
 Tests whether the string begins with another string.
bool endsWith (const tchar *const text) const throw ()
 Tests whether the string ends with another string.
bool endsWithChar (const tchar character) const throw ()
 Tests whether the string ends with a particular character.
bool endsWithIgnoreCase (const tchar *const text) const throw ()
 Tests whether the string ends with another string.
bool contains (const tchar *const text) const throw ()
 Tests whether the string contains another substring.
bool containsChar (const tchar character) const throw ()
 Tests whether the string contains a particular character.
bool containsIgnoreCase (const tchar *const text) const throw ()
 Tests whether the string contains another substring.
bool containsWholeWord (const tchar *const wordToLookFor) const throw ()
 Tests whether the string contains another substring as a distict word.
bool containsWholeWordIgnoreCase (const tchar *const wordToLookFor) const throw ()
 Tests whether the string contains another substring as a distict word.
int indexOfWholeWord (const tchar *const wordToLookFor) const throw ()
 Finds an instance of another substring if it exists as a distict word.
int indexOfWholeWordIgnoreCase (const tchar *const wordToLookFor) const throw ()
 Finds an instance of another substring if it exists as a distict word.
bool containsAnyOf (const tchar *const charactersItMightContain) const throw ()
 Looks for any of a set of characters in the string.
bool containsOnly (const tchar *const charactersItMightContain) const throw ()
 Looks for a set of characters in the string.
bool containsNonWhitespaceChars () const throw ()
 Returns true if this string contains any non-whitespace characters.
bool matchesWildcard (const tchar *wildcard, const bool ignoreCase) const throw ()
 Returns true if the string matches this simple wildcard expression.
int indexOfChar (const tchar characterToLookFor) const throw ()
 Searches for a character inside this string.
int indexOfChar (const int startIndex, const tchar characterToLookFor) const throw ()
 Searches for a character inside this string.
int indexOfAnyOf (const tchar *const charactersToLookFor, const int startIndex=0, const bool ignoreCase=false) const throw ()
 Returns the index of the first character that matches one of the characters passed-in to this method.
int indexOf (const tchar *const text) const throw ()
 Searches for a substring within this string.
int indexOf (const int startIndex, const tchar *const textToLookFor) const throw ()
 Searches for a substring within this string.
int indexOfIgnoreCase (const tchar *const textToLookFor) const throw ()
 Searches for a substring within this string.
int indexOfIgnoreCase (const int startIndex, const tchar *const textToLookFor) const throw ()
 Searches for a substring within this string.
int lastIndexOfChar (const tchar character) const throw ()
 Searches for a character inside this string (working backwards from the end of the string).
int lastIndexOf (const tchar *const textToLookFor) const throw ()
 Searches for a substring inside this string (working backwards from the end of the string).
int lastIndexOfIgnoreCase (const tchar *const textToLookFor) const throw ()
 Searches for a substring inside this string (working backwards from the end of the string).
int lastIndexOfAnyOf (const tchar *const charactersToLookFor, const bool ignoreCase=false) const throw ()
 Returns the index of the last character in this string that matches one of the characters passed-in to this method.
const tchar & operator[] (const int index) const throw ()
 Returns the character at this index in the string.
tchar & operator[] (const int index) throw ()
 Returns a character from the string such that it can also be altered.
tchar getLastCharacter () const throw ()
 Returns the final character of the string.
const String substring (int startIndex, int endIndex) const throw ()
 Returns a subsection of the string.
const String substring (const int startIndex) const throw ()
 Returns a section of the string, starting from a given position.
const String dropLastCharacters (const int numberToDrop) const throw ()
 Returns a version of this string with a number of characters removed from the end.
const String getLastCharacters (const int numCharacters) const throw ()
 Returns a number of characters from the end of the string.
const String fromFirstOccurrenceOf (const tchar *const substringToStartFrom, const bool includeSubStringInResult, const bool ignoreCase) const throw ()
 Returns a section of the string starting from a given substring.
const String fromLastOccurrenceOf (const tchar *const substringToFind, const bool includeSubStringInResult, const bool ignoreCase) const throw ()
 Returns a section of the string starting from the last occurrence of a given substring.
const String upToFirstOccurrenceOf (const tchar *const substringToEndWith, const bool includeSubStringInResult, const bool ignoreCase) const throw ()
 Returns the start of this string, up to the first occurrence of a substring.
const String upToLastOccurrenceOf (const tchar *substringToFind, const bool includeSubStringInResult, const bool ignoreCase) const throw ()
 Returns the start of this string, up to the last occurrence of a substring.
const String trim () const throw ()
 Returns a copy of this string with any whitespace characters removed from the start and end.
const String trimStart () const throw ()
 Returns a copy of this string with any whitespace characters removed from the start.
const String trimEnd () const throw ()
 Returns a copy of this string with any whitespace characters removed from the end.
const String trimCharactersAtStart (const tchar *charactersToTrim) const throw ()
 Returns a copy of this string, having removed a specified set of characters from its start.
const String trimCharactersAtEnd (const tchar *charactersToTrim) const throw ()
 Returns a copy of this string, having removed a specified set of characters from its end.
const String toUpperCase () const throw ()
 Returns an upper-case version of this string.
const String toLowerCase () const throw ()
 Returns an lower-case version of this string.
const String replaceSection (int startIndex, int numCharactersToReplace, const tchar *const stringToInsert) const throw ()
 Replaces a sub-section of the string with another string.
const String replace (const tchar *const stringToReplace, const tchar *const stringToInsertInstead, const bool ignoreCase=false) const throw ()
 Replaces all occurrences of a substring with another string.
const String replaceCharacter (const tchar characterToReplace, const tchar characterToInsertInstead) const throw ()
 Returns a string with all occurrences of a character replaced with a different one.
const String replaceCharacters (const String &charactersToReplace, const tchar *const charactersToInsertInstead) const throw ()
 Replaces a set of characters with another set.
const String retainCharacters (const tchar *const charactersToRetain) const throw ()
 Returns a version of this string that only retains a fixed set of characters.
const String removeCharacters (const tchar *const charactersToRemove) const throw ()
 Returns a version of this string with a set of characters removed.
const String initialSectionContainingOnly (const tchar *const permittedCharacters) const throw ()
 Returns a section from the start of the string that only contains a certain set of characters.
const String initialSectionNotContaining (const tchar *const charactersToStopAt) const throw ()
 Returns a section from the start of the string that only contains a certain set of characters.
bool isQuotedString () const throw ()
 Checks whether the string might be in quotation marks.
const String unquoted () const throw ()
 Removes quotation marks from around the string, (if there are any).
const String quoted (const tchar quoteCharacter=JUCE_T('"')) const throw ()
 Adds quotation marks around a string.
void printf (const tchar *const format,...) throw ()
 Writes text into this string, using printf style-arguments.
void vprintf (const tchar *const format, va_list &args) throw ()
 Writes text into this string, using a printf style, but taking a va_list argument.
 String (const int decimalInteger) throw ()
 Creates a string containing this signed 32-bit integer as a decimal number.
 String (const unsigned int decimalInteger) throw ()
 Creates a string containing this unsigned 32-bit integer as a decimal number.
 String (const short decimalInteger) throw ()
 Creates a string containing this signed 16-bit integer as a decimal number.
 String (const unsigned short decimalInteger) throw ()
 Creates a string containing this unsigned 16-bit integer as a decimal number.
 String (const int64 largeIntegerValue) throw ()
 Creates a string containing this signed 64-bit integer as a decimal number.
 String (const uint64 largeIntegerValue) throw ()
 Creates a string containing this unsigned 64-bit integer as a decimal number.
 String (const float floatValue, const int numberOfDecimalPlaces=0) throw ()
 Creates a string representing this floating-point number.
 String (const double doubleValue, const int numberOfDecimalPlaces=0) throw ()
 Creates a string representing this floating-point number.
int getIntValue () const throw ()
 Reads the value of the string as a decimal number (up to 32 bits in size).
int64 getLargeIntValue () const throw ()
 Reads the value of the string as a decimal number (up to 64 bits in size).
int getTrailingIntValue () const throw ()
 Parses a decimal number from the end of the string.
float getFloatValue () const throw ()
 Parses this string as a floating point number.
double getDoubleValue () const throw ()
 Parses this string as a floating point number.
int getHexValue32 () const throw ()
 Parses the string as a hexadecimal number.
int64 getHexValue64 () const throw ()
 Parses the string as a hexadecimal number.
 operator const char * () const throw ()
 Returns a version of this string using the default 8-bit system encoding.
 operator const juce_wchar * () const throw ()
 Returns a unicode version of this string.
void copyToBuffer (char *const destBuffer, const int maxCharsToCopy) const throw ()
 Copies the string to a buffer.
void copyToBuffer (juce_wchar *const destBuffer, const int maxCharsToCopy) const throw ()
 Copies the string to a unicode buffer.
int copyToUTF8 (uint8 *const destBuffer, const int maxBufferSizeBytes=0x7fffffff) const throw ()
 Copies the string to a buffer as UTF-8 characters.
const char * toUTF8 () const throw ()
 Returns a pointer to a UTF-8 version of this string.
void preallocateStorage (const int numCharsNeeded) throw ()
 Increases the string's internally allocated storage.

Static Public Member Functions

static const String charToString (const tchar character) throw ()
 Creates a string from a single character.
static const String formatted (const tchar *const format,...) throw ()
 Returns a string, created using arguments in the style of printf.
static const String repeatedString (const tchar *const stringToRepeat, int numberOfTimesToRepeat) throw ()
 Creates a string which is a version of a string repeated and joined together.
static const String createStringFromData (const void *const data, const int size) throw ()
 Creates a string from data in an unknown format.
static const String toHexString (const int number) throw ()
 Creates a string representing this 32-bit value in hexadecimal.
static const String toHexString (const int64 number) throw ()
 Creates a string representing this 64-bit value in hexadecimal.
static const String toHexString (const short number) throw ()
 Creates a string representing this 16-bit value in hexadecimal.
static const String toHexString (const unsigned char *data, const int size, const int groupSize=1) throw ()
 Creates a string containing a hex dump of a block of binary data.
static const String fromUTF8 (const uint8 *const utf8buffer, int bufferSizeBytes=-1) throw ()
 Creates a String from a UTF-8 encoded buffer.

Static Public Attributes

static const String empty
 This is an empty string that can be used whenever one is needed.

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

Constructor & Destructor Documentation

String::String (  )  throw ()

Creates an empty string.

See also:
empty

String::String ( const String &  other  )  throw ()

Creates a copy of another string.

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

Creates a string from a zero-terminated text string.

The string is assumed to be stored in the default system encoding.

String::String ( const char *const   text,
const int  maxChars 
) throw ()

Creates a string from an string of characters.

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

String::String ( const juce_wchar *const   unicodeText  )  throw ()

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

String::String ( const juce_wchar *const   unicodeText,
const int  maxChars 
) throw ()

Creates a string from a unicode text string.

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

String::~String (  )  throw ()

Destructor.

String::String ( const int  decimalInteger  )  throw () [explicit]

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

See also:
getIntValue, getFloatValue, getDoubleValue, toHexString

String::String ( const unsigned int  decimalInteger  )  throw () [explicit]

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

See also:
getIntValue, getFloatValue, getDoubleValue, toHexString

String::String ( const short  decimalInteger  )  throw () [explicit]

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

See also:
getIntValue, getFloatValue, getDoubleValue, toHexString

String::String ( const unsigned short  decimalInteger  )  throw () [explicit]

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

See also:
getIntValue, getFloatValue, getDoubleValue, toHexString

String::String ( const int64  largeIntegerValue  )  throw () [explicit]

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

See also:
getLargeIntValue, getFloatValue, getDoubleValue, toHexString

String::String ( const uint64  largeIntegerValue  )  throw () [explicit]

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

See also:
getLargeIntValue, getFloatValue, getDoubleValue, toHexString

String::String ( const float  floatValue,
const int  numberOfDecimalPlaces = 0 
) throw () [explicit]

Creates a string representing this floating-point number.

Parameters:
floatValue the value to convert to a string
numberOfDecimalPlaces if this is > 0, it will format the number using that many decimal places, and will not use exponent notation. If 0 or less, it will use exponent notation if necessary.
See also:
getDoubleValue, getIntValue

String::String ( const double  doubleValue,
const int  numberOfDecimalPlaces = 0 
) throw () [explicit]

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, and will not use exponent notation. If 0 or less, it will use exponent notation if necessary.
See also:
getFloatValue, getIntValue

Member Function Documentation

static const String String::charToString ( const tchar  character  )  throw () [static]

Creates a string from a single character.

int String::hashCode (  )  const throw ()

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

int64 String::hashCode64 (  )  const throw ()

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

int String::length (  )  const throw ()

Returns the number of characters in the string.

const String& String::operator= ( const tchar *const   other  )  throw ()

Replaces this string's contents with another string.

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

Replaces this string's contents with another string.

const String& String::operator+= ( const tchar *const   textToAppend  )  throw ()

Appends another string at the end of this one.

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

Appends another string at the end of this one.

const String& String::operator+= ( const char  characterToAppend  )  throw ()

Appends a character at the end of this string.

const String& String::operator+= ( const juce_wchar  characterToAppend  )  throw ()

Appends a character at the end of this string.

void String::append ( const tchar *const   textToAppend,
const int  maxCharsToTake 
) throw ()

Appends a string at the end of this one.

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

const String String::operator+ ( const String &  stringToAppend  )  const throw ()

Appends a string at the end of this one.

Returns:
the concatenated string

const String String::operator+ ( const tchar *const   textToAppend  )  const throw ()

Appends a string at the end of this one.

Returns:
the concatenated string

const String String::operator+ ( const tchar  characterToAppend  )  const throw ()

Appends a character at the end of this one.

Returns:
the concatenated string

String& String::operator<< ( const char  n  )  throw ()

Appends a character at the end of this string.

String& String::operator<< ( const juce_wchar  n  )  throw ()

Appends a character at the end of this string.

String& String::operator<< ( const char *const   text  )  throw ()

Appends another string at the end of this one.

String& String::operator<< ( const juce_wchar *const   text  )  throw ()

Appends another string at the end of this one.

String& String::operator<< ( const String &  text  )  throw ()

Appends another string at the end of this one.

String& String::operator<< ( const short  number  )  throw ()

Appends a decimal number at the end of this string.

String& String::operator<< ( const int  number  )  throw ()

Appends a decimal number at the end of this string.

String& String::operator<< ( const unsigned int  number  )  throw ()

Appends a decimal number at the end of this string.

String& String::operator<< ( const float  number  )  throw ()

Appends a decimal number at the end of this string.

String& String::operator<< ( const double  number  )  throw ()

Appends a decimal number at the end of this string.

bool String::isEmpty (  )  const throw ()

Returns true if the string contains no characters.

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

See also:
containsNonWhitespaceChars()

bool String::isNotEmpty (  )  const throw ()

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()

bool String::operator== ( const String &  other  )  const throw ()

Case-sensitive comparison with another string.

bool String::operator== ( const tchar *const   other  )  const throw ()

Case-sensitive comparison with another string.

bool String::operator!= ( const String &  other  )  const throw ()

Case-sensitive comparison with another string.

bool String::operator!= ( const tchar *const   other  )  const throw ()

Case-sensitive comparison with another string.

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

Case-insensitive comparison with another string.

bool String::equalsIgnoreCase ( const tchar *const   other  )  const throw ()

Case-insensitive comparison with another string.

bool String::operator> ( const String &  other  )  const throw ()

Case-sensitive comparison with another string.

bool String::operator< ( const tchar *const   other  )  const throw ()

Case-sensitive comparison with another string.

bool String::operator>= ( const String &  other  )  const throw ()

Case-sensitive comparison with another string.

bool String::operator<= ( const tchar *const   other  )  const throw ()

Case-sensitive comparison with another string.

int String::compare ( const tchar *const   other  )  const throw ()

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.

int String::compareIgnoreCase ( const tchar *const   other  )  const throw ()

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.

int String::compareLexicographically ( const tchar *const   other  )  const throw ()

Lexicographic comparison with another string.

The comparison used here is case-insensitive and ignores leading non-alphanumeric characters, making it good for sorting human-readable strings.

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.

bool String::startsWith ( const tchar *const   text  )  const throw ()

Tests whether the string begins with another string.

Uses a case-sensitive comparison.

bool String::startsWithChar ( const tchar  character  )  const throw ()

Tests whether the string begins with a particular character.

Uses a case-sensitive comparison.

bool String::startsWithIgnoreCase ( const tchar *const   text  )  const throw ()

Tests whether the string begins with another string.

Uses a case-insensitive comparison.

bool String::endsWith ( const tchar *const   text  )  const throw ()

Tests whether the string ends with another string.

Uses a case-sensitive comparison.

bool String::endsWithChar ( const tchar  character  )  const throw ()

Tests whether the string ends with a particular character.

Uses a case-sensitive comparison.

bool String::endsWithIgnoreCase ( const tchar *const   text  )  const throw ()

Tests whether the string ends with another string.

Uses a case-insensitive comparison.

bool String::contains ( const tchar *const   text  )  const throw ()

Tests whether the string contains another substring.

Uses a case-sensitive comparison.

bool String::containsChar ( const tchar  character  )  const throw ()

Tests whether the string contains a particular character.

Uses a case-sensitive comparison.

bool String::containsIgnoreCase ( const tchar *const   text  )  const throw ()

Tests whether the string contains another substring.

Uses a case-insensitive comparison.

bool String::containsWholeWord ( const tchar *const   wordToLookFor  )  const throw ()

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

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

bool String::containsWholeWordIgnoreCase ( const tchar *const   wordToLookFor  )  const throw ()

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

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

int String::indexOfWholeWord ( const tchar *const   wordToLookFor  )  const throw ()

Finds an instance of another substring if it exists as a distict 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

int String::indexOfWholeWordIgnoreCase ( const tchar *const   wordToLookFor  )  const throw ()

Finds an instance of another substring if it exists as a distict 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

bool String::containsAnyOf ( const tchar *const   charactersItMightContain  )  const throw ()

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.

bool String::containsOnly ( const tchar *const   charactersItMightContain  )  const throw ()

Looks for a set of characters in the string.

Uses a case-sensitive comparison.

Returns:
true if the all the characters in the string are also found in the string that is passed in.

bool String::containsNonWhitespaceChars (  )  const throw ()

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()".

bool String::matchesWildcard ( const tchar *  wildcard,
const bool  ignoreCase 
) const throw ()

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.

int String::indexOfChar ( const tchar  characterToLookFor  )  const throw ()

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.

int String::indexOfChar ( const int  startIndex,
const tchar  characterToLookFor 
) const throw ()

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.

int String::indexOfAnyOf ( const tchar *const   charactersToLookFor,
const int  startIndex = 0,
const bool  ignoreCase = false 
) const throw ()

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

int String::indexOf ( const tchar *const   text  )  const throw ()

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.

int String::indexOf ( const int  startIndex,
const tchar *const   textToLookFor 
) const throw ()

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.

int String::indexOfIgnoreCase ( const tchar *const   textToLookFor  )  const throw ()

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.

int String::indexOfIgnoreCase ( const int  startIndex,
const tchar *const   textToLookFor 
) const throw ()

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.

int String::lastIndexOfChar ( const tchar  character  )  const throw ()

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.

int String::lastIndexOf ( const tchar *const   textToLookFor  )  const throw ()

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.

int String::lastIndexOfIgnoreCase ( const tchar *const   textToLookFor  )  const throw ()

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.

int String::lastIndexOfAnyOf ( const tchar *const   charactersToLookFor,
const bool  ignoreCase = false 
) const throw ()

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

const tchar& String::operator[] ( const int  index  )  const throw ()

Returns the character at this index in the string.

No checks are made to see if the index is within a valid range, so be careful!

References jassert.

tchar& String::operator[] ( const int  index  )  throw ()

Returns a character from the string such that it can also be altered.

This can be used as a way of easily changing characters in the string.

Note that the index passed-in is not checked to see whether it's in-range, so be careful when using this.

tchar String::getLastCharacter (  )  const throw ()

Returns the final character of the string.

If the string is empty this will return 0.

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

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

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

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

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

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

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

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

const String String::fromFirstOccurrenceOf ( const tchar *const   substringToStartFrom,
const bool  includeSubStringInResult,
const bool  ignoreCase 
) const throw ()

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

const String String::fromLastOccurrenceOf ( const tchar *const   substringToFind,
const bool  includeSubStringInResult,
const bool  ignoreCase 
) const throw ()

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

const String String::upToFirstOccurrenceOf ( const tchar *const   substringToEndWith,
const bool  includeSubStringInResult,
const bool  ignoreCase 
) const throw ()

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

const String String::upToLastOccurrenceOf ( const tchar *  substringToFind,
const bool  includeSubStringInResult,
const bool  ignoreCase 
) const throw ()

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 an empty string.

See also:
upToFirstOccurrenceOf, fromFirstOccurrenceOf

const String String::trim (  )  const throw ()

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

const String String::trimStart (  )  const throw ()

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

const String String::trimEnd (  )  const throw ()

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

const String String::trimCharactersAtStart ( const tchar *  charactersToTrim  )  const throw ()

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. This must not be null.
See also:
trim, trimStart, trimCharactersAtEnd

const String String::trimCharactersAtEnd ( const tchar *  charactersToTrim  )  const throw ()

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. This must not be null.
See also:
trim, trimEnd, trimCharactersAtStart

const String String::toUpperCase (  )  const throw ()

Returns an upper-case version of this string.

const String String::toLowerCase (  )  const throw ()

Returns an lower-case version of this string.

const String String::replaceSection ( int  startIndex,
int  numCharactersToReplace,
const tchar *const   stringToInsert 
) const throw ()

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.

const String String::replace ( const tchar *const   stringToReplace,
const tchar *const   stringToInsertInstead,
const bool  ignoreCase = false 
) const throw ()

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.

const String String::replaceCharacter ( const tchar  characterToReplace,
const tchar  characterToInsertInstead 
) const throw ()

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

const String String::replaceCharacters ( const String &  charactersToReplace,
const tchar *const   charactersToInsertInstead 
) const throw ()

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. translate ("abc", "def") replaces 'a' with 'd', 'b' with 'e', etc.

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

const String String::retainCharacters ( const tchar *const   charactersToRetain  )  const throw ()

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.

const String String::removeCharacters ( const tchar *const   charactersToRemove  )  const throw ()

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.

const String String::initialSectionContainingOnly ( const tchar *const   permittedCharacters  )  const throw ()

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.

const String String::initialSectionNotContaining ( const tchar *const   charactersToStopAt  )  const throw ()

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.

bool String::isQuotedString (  )  const throw ()

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

const String String::unquoted (  )  const throw ()

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

const String String::quoted ( const tchar  quoteCharacter = JUCE_T('"')  )  const throw ()

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

void String::printf ( const tchar *const   format,
  ... 
) throw ()

Writes text into this string, using printf style-arguments.

This will replace the contents of the string with the output of this formatted printf.

Note that using the s token with a juce string is probably a bad idea, as this may expect differect encodings on different platforms.

See also:
formatted

static const String String::formatted ( const tchar *const   format,
  ... 
) throw () [static]

Returns a string, created using arguments in the style of printf.

This will return a string which is the result of a sprintf using the arguments passed-in.

Note that using the s token with a juce string is probably a bad idea, as this may expect differect encodings on different platforms.

See also:
printf, vprintf

void String::vprintf ( const tchar *const   format,
va_list &  args 
) throw ()

Writes text into this string, using a printf style, but taking a va_list argument.

This will replace the contents of the string with the output of this formatted printf. Used by other methods, this is public in case it's useful for other purposes where you want to pass a va_list through directly.

Note that using the s token with a juce string is probably a bad idea, as this may expect differect encodings on different platforms.

See also:
printf, formatted

static const String String::repeatedString ( const tchar *const   stringToRepeat,
int  numberOfTimesToRepeat 
) throw () [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

static const String String::createStringFromData ( const void *const   data,
const int  size 
) throw () [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.

int String::getIntValue (  )  const throw ()

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

int64 String::getLargeIntValue (  )  const throw ()

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.

int String::getTrailingIntValue (  )  const throw ()

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

float String::getFloatValue (  )  const throw ()

Parses this string as a floating point number.

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

double String::getDoubleValue (  )  const throw ()

Parses this string as a floating point number.

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

int String::getHexValue32 (  )  const throw ()

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.

int64 String::getHexValue64 (  )  const throw ()

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.

static const String String::toHexString ( const int  number  )  throw () [static]

Creates a string representing this 32-bit value in hexadecimal.

Referenced by juce_getOutputFromCommand().

static const String String::toHexString ( const int64  number  )  throw () [static]

Creates a string representing this 64-bit value in hexadecimal.

static const String String::toHexString ( const short  number  )  throw () [static]

Creates a string representing this 16-bit value in hexadecimal.

static const String String::toHexString ( const unsigned char *  data,
const int  size,
const int  groupSize = 1 
) throw () [static]

Creates 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".

String::operator const char * (  )  const throw ()

Returns a version of this string using the default 8-bit system encoding.

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.

String::operator const juce_wchar * (  )  const throw ()

Returns a unicode 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.

void String::copyToBuffer ( char *const   destBuffer,
const int  maxCharsToCopy 
) const throw ()

Copies the string to a buffer.

Parameters:
destBuffer the place to copy it to
maxCharsToCopy the maximum number of characters to copy to the buffer, not including the tailing zero, so this shouldn't be larger than the size of your destination buffer - 1

void String::copyToBuffer ( juce_wchar *const   destBuffer,
const int  maxCharsToCopy 
) const throw ()

Copies the string to a unicode buffer.

Parameters:
destBuffer the place to copy it to
maxCharsToCopy the maximum number of characters to copy to the buffer, not including the tailing zero, so this shouldn't be larger than the size of your destination buffer - 1

int String::copyToUTF8 ( uint8 *const   destBuffer,
const int  maxBufferSizeBytes = 0x7fffffff 
) const throw ()

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

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

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. If this value is < 0, no limit is used.

const char* String::toUTF8 (  )  const throw ()

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.

Referenced by InterProcessLock::InterProcessLock(), juce_getVolumeLabel(), and juce_runSystemCommand().

static const String String::fromUTF8 ( const uint8 *const   utf8buffer,
int  bufferSizeBytes = -1 
) throw () [static]

Creates a String from a UTF-8 encoded buffer.

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

Referenced by juce_getVolumeLabel().

void String::preallocateStorage ( const int  numCharsNeeded  )  throw ()

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:
numCharsNeeded the number of characters to allocate storage for. If this value is less than the currently allocated size, it will have no effect.

Member Data Documentation

const String String::empty [static]

This is an empty string that can be used whenever one is needed.

It's better to use this than String() because it explains what's going on and is more efficient.

Referenced by AudioProcessorGraph::getParameterName(), AudioProcessorGraph::getParameterText(), AudioProcessorGraph::getProgramName(), and juce_getVolumeLabel().

The documentation for this class was generated from the following file:
Generated on Fri Nov 20 12:00:49 2009 for JUCE by  doxygen 1.5.9