StringArray Class Reference

A special array for holding a list of strings. More...

List of all members.

Public Member Functions
	StringArray () throw ()
	Creates an empty string array.
	StringArray (const StringArray &other)
	Creates a copy of another string array.
	StringArray (const String &firstValue)
	Creates an array containing a single string.
	StringArray (const juce_wchar **strings, int numberOfStrings)
	Creates a copy of an array of string literals.
	StringArray (const char **strings, int numberOfStrings)
	Creates a copy of an array of string literals.
	StringArray (const juce_wchar **strings)
	Creates a copy of a null-terminated array of string literals.
	StringArray (const char **strings)
	Creates a copy of a null-terminated array of string literals.
	~StringArray ()
	Destructor.
StringArray &	operator= (const StringArray &other)
	Copies the contents of another string array into this one.
bool	operator== (const StringArray &other) const throw ()
	Compares two arrays.
bool	operator!= (const StringArray &other) const throw ()
	Compares two arrays.
int	size () const throw ()
	Returns the number of strings in the array.
const String &	operator[] (int index) const throw ()
	Returns one of the strings from the array.
String &	getReference (int index) throw ()
	Returns a reference to one of the strings in the array.
bool	contains (const String &stringToLookFor, bool ignoreCase=false) const
	Searches for a string in the array.
int	indexOf (const String &stringToLookFor, bool ignoreCase=false, int startIndex=0) const
	Searches for a string in the array.
void	add (const String &stringToAdd)
	Appends a string at the end of the array.
void	insert (int index, const String &stringToAdd)
	Inserts a string into the array.
void	addIfNotAlreadyThere (const String &stringToAdd, bool ignoreCase=false)
	Adds a string to the array as long as it's not already in there.
void	set (int index, const String &newString)
	Replaces one of the strings in the array with another one.
void	addArray (const StringArray &other, int startIndex=0, int numElementsToAdd=-1)
	Appends some strings from another array to the end of this one.
int	addTokens (const String &stringToTokenise, bool preserveQuotedStrings)
	Breaks up a string into tokens and adds them to this array.
int	addTokens (const String &stringToTokenise, const String &breakCharacters, const String &quoteCharacters)
	Breaks up a string into tokens and adds them to this array.
int	addLines (const String &stringToBreakUp)
	Breaks up a string into lines and adds them to this array.
void	clear ()
	Removes all elements from the array.
void	remove (int index)
	Removes a string from the array.
void	removeString (const String &stringToRemove, bool ignoreCase=false)
	Finds a string in the array and removes it.
void	removeDuplicates (bool ignoreCase)
	Removes any duplicated elements from the array.
void	removeEmptyStrings (bool removeWhitespaceStrings=true)
	Removes empty strings from the array.
void	move (int currentIndex, int newIndex) throw ()
	Moves one of the strings to a different position.
void	trim ()
	Deletes any whitespace characters from the starts and ends of all the strings.
void	appendNumbersToDuplicates (bool ignoreCaseWhenComparing, bool appendNumberToFirstInstance, const juce_wchar *preNumberString=0, const juce_wchar *postNumberString=0)
	Adds numbers to the strings in the array, to make each string unique.
const String	joinIntoString (const String &separatorString, int startIndex=0, int numberOfElements=-1) const
	Joins the strings in the array together into one string.
void	sort (bool ignoreCase)
	Sorts the array into alphabetical order.
void	minimiseStorageOverheads ()
	Reduces the amount of storage being used by the array.

---

Detailed Description

A special array for holding a list of strings.

See also:

String, StringPairArray

---

Constructor & Destructor Documentation

StringArray::StringArray

(

)

throw ()

Creates an empty string array.

StringArray::StringArray

(

const StringArray &

other

)

Creates a copy of another string array.

StringArray::StringArray

(

const String &

firstValue

)

[explicit]

Creates an array containing a single string.

StringArray::StringArray	(	const juce_wchar **	strings,
		int	numberOfStrings
	)

Creates a copy of an array of string literals.

Parameters:

	strings	an array of strings to add. Null pointers in the array will be treated as empty strings
	numberOfStrings	how many items there are in the array

StringArray::StringArray	(	const char **	strings,
		int	numberOfStrings
	)

Creates a copy of an array of string literals.

Parameters:

	strings	an array of strings to add. Null pointers in the array will be treated as empty strings
	numberOfStrings	how many items there are in the array

StringArray::StringArray

(

const juce_wchar **

strings

)

[explicit]

Creates a copy of a null-terminated array of string literals.

Each item from the array passed-in is added, until it encounters a null pointer, at which point it stops.

StringArray::StringArray

(

const char **

strings

)

[explicit]

Creates a copy of a null-terminated array of string literals.

Each item from the array passed-in is added, until it encounters a null pointer, at which point it stops.

StringArray::~StringArray

(

)

Destructor.

---

Member Function Documentation

StringArray& StringArray::operator=

(

const StringArray &

other

)

Copies the contents of another string array into this one.

bool StringArray::operator==

(

const StringArray &

other

)

const throw ()

Compares two arrays.

Comparisons are case-sensitive.

Returns:

true only if the other array contains exactly the same strings in the same order

bool StringArray::operator!=

(

const StringArray &

other

)

const throw ()

Compares two arrays.

Comparisons are case-sensitive.

Returns:

false if the other array contains exactly the same strings in the same order

int StringArray::size

(

)

const throw ()

Returns the number of strings in the array.

const String& StringArray::operator[]

(

int

index

)

const throw ()

Returns one of the strings from the array.

If the index is out-of-range, an empty string is returned.

Obviously the reference returned shouldn't be stored for later use, as the string it refers to may disappear when the array changes.

String& StringArray::getReference

(

int

index

)

throw ()

Returns a reference to one of the strings in the array.

This lets you modify a string in-place in the array, but you must be sure that the index is in-range.

bool StringArray::contains	(	const String &	stringToLookFor,
		bool	ignoreCase = false
	)			const

Searches for a string in the array.

The comparison will be case-insensitive if the ignoreCase parameter is true.

Returns:

true if the string is found inside the array

int StringArray::indexOf	(	const String &	stringToLookFor,
		bool	ignoreCase = false,
		int	startIndex = 0
	)			const

Searches for a string in the array.

The comparison will be case-insensitive if the ignoreCase parameter is true.

Parameters:

	stringToLookFor	the string to try to find
	ignoreCase	whether the comparison should be case-insensitive
	startIndex	the first index to start searching from

Returns:

the index of the first occurrence of the string in this array, or -1 if it isn't found.

void StringArray::add

(

const String &

stringToAdd

)

Appends a string at the end of the array.

void StringArray::insert	(	int	index,
		const String &	stringToAdd
	)

Inserts a string into the array.

This will insert a string into the array at the given index, moving up the other elements to make room for it. If the index is less than zero or greater than the size of the array, the new string will be added to the end of the array.

void StringArray::addIfNotAlreadyThere	(	const String &	stringToAdd,
		bool	ignoreCase = false
	)

Adds a string to the array as long as it's not already in there.

The search can optionally be case-insensitive.

void StringArray::set	(	int	index,
		const String &	newString
	)

Replaces one of the strings in the array with another one.

If the index is higher than the array's size, the new string will be added to the end of the array; if it's less than zero nothing happens.

void StringArray::addArray	(	const StringArray &	other,
		int	startIndex = 0,
		int	numElementsToAdd = -1
	)

Appends some strings from another array to the end of this one.

Parameters:

	other	the array to add
	startIndex	the first element of the other array to add
	numElementsToAdd	the maximum number of elements to add (if this is less than zero, they are all added)

int StringArray::addTokens	(	const String &	stringToTokenise,
		bool	preserveQuotedStrings
	)

Breaks up a string into tokens and adds them to this array.

This will tokenise the given string using whitespace characters as the token delimiters, and will add these tokens to the end of the array.

Returns:

the number of tokens added

Referenced by Rectangle< int >::fromString().

int StringArray::addTokens	(	const String &	stringToTokenise,
		const String &	breakCharacters,
		const String &	quoteCharacters
	)

Breaks up a string into tokens and adds them to this array.

This will tokenise the given string (using the string passed in to define the token delimiters), and will add these tokens to the end of the array.

Parameters:

	stringToTokenise	the string to tokenise
	breakCharacters	a string of characters, any of which will be considered to be a token delimiter.
	quoteCharacters	if this string isn't empty, it defines a set of characters which are treated as quotes. Any text occurring between quotes is not broken up into tokens.

Returns:

the number of tokens added

int StringArray::addLines

(

const String &

stringToBreakUp

)

Breaks up a string into lines and adds them to this array.

This breaks a string down into lines separated by \n or \r\n, and adds each line to the array. Line-break characters are omitted from the strings that are added to the array.

void StringArray::clear

(

)

Removes all elements from the array.

void StringArray::remove

(

int

index

)

Removes a string from the array.

If the index is out-of-range, no action will be taken.

void StringArray::removeString	(	const String &	stringToRemove,
		bool	ignoreCase = false
	)

Finds a string in the array and removes it.

This will remove the first occurrence of the given string from the array. The comparison may be case-insensitive depending on the ignoreCase parameter.

void StringArray::removeDuplicates

(

bool

ignoreCase

)

Removes any duplicated elements from the array.

If any string appears in the array more than once, only the first occurrence of it will be retained.

Parameters:

ignoreCase

whether to use a case-insensitive comparison

void StringArray::removeEmptyStrings

(

bool

removeWhitespaceStrings = true

)

Removes empty strings from the array.

Parameters:

removeWhitespaceStrings

if true, strings that only contain whitespace characters will also be removed

void StringArray::move	(	int	currentIndex,
		int	newIndex
	)			throw ()

Moves one of the strings to a different position.

This will move the string to a specified index, shuffling along any intervening elements as required.

So for example, if you have the array { 0, 1, 2, 3, 4, 5 } then calling move (2, 4) would result in { 0, 1, 3, 4, 2, 5 }.

Parameters:

	currentIndex	the index of the value to be moved. If this isn't a valid index, then nothing will be done
	newIndex	the index at which you'd like this value to end up. If this is less than zero, the value will be moved to the end of the array

void StringArray::trim

(

)

Deletes any whitespace characters from the starts and ends of all the strings.

void StringArray::appendNumbersToDuplicates	(	bool	ignoreCaseWhenComparing,
		bool	appendNumberToFirstInstance,
		const juce_wchar *	preNumberString = 0,
		const juce_wchar *	postNumberString = 0
	)

Adds numbers to the strings in the array, to make each string unique.

This will add numbers to the ends of groups of similar strings. e.g. if there are two "moose" strings, they will become "moose (1)" and "moose (2)"

Parameters:

	ignoreCaseWhenComparing	whether the comparison used is case-insensitive
	appendNumberToFirstInstance	whether the first of a group of similar strings also has a number appended to it.
	preNumberString	when adding a number, this string is added before the number. If you pass 0, a default string will be used, which adds brackets around the number.
	postNumberString	this string is appended after any numbers that are added. If you pass 0, a default string will be used, which adds brackets around the number.

const String StringArray::joinIntoString	(	const String &	separatorString,
		int	startIndex = 0,
		int	numberOfElements = -1
	)			const

Joins the strings in the array together into one string.

This will join a range of elements from the array into a string, separating them with a given string.

e.g. joinIntoString (",") will turn an array of "a" "b" and "c" into "a,b,c".

Parameters:

	separatorString	the string to insert between all the strings
	startIndex	the first element to join
	numberOfElements	how many elements to join together. If this is less than zero, all available elements will be used.

void StringArray::sort

(

bool

ignoreCase

)

Sorts the array into alphabetical order.

Parameters:

ignoreCase

if true, the comparisons used will be case-sensitive.

void StringArray::minimiseStorageOverheads

(

)

Reduces the amount of storage being used by the array.

Arrays typically allocate slightly more storage than they need, and after removing elements, they may have quite a lot of unused space allocated. This method will reduce the amount of allocated storage to a minimum.

---

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

• juce_StringArray.h