StringArray Class Reference

#include <StringArray.h>

Public Member Functions
	StringArray () noexcept
	StringArray (const StringArray &)
	StringArray (const String &firstValue)
	StringArray (const String *strings, int numberOfStrings)
	StringArray (const char *const *strings, int numberOfStrings)
	StringArray (const char *const *strings)
	~StringArray ()
StringArray &	operator= (const StringArray &)
void	swapWith (StringArray &) noexcept
bool	operator== (const StringArray &) const noexcept
bool	operator!= (const StringArray &) const noexcept
int	size () const noexcept
bool	isEmpty () const noexcept
const String &	operator[] (int index) const noexcept
String &	getReference (int index) noexcept
String *	begin () const noexcept
String *	end () const noexcept
bool	contains (StringRef stringToLookFor, bool ignoreCase=false) const
int	indexOf (StringRef stringToLookFor, bool ignoreCase=false, int startIndex=0) const
bool	add (const String &stringToAdd)
bool	insert (int index, const String &stringToAdd)
bool	addIfNotAlreadyThere (const String &stringToAdd, bool ignoreCase=false)
void	set (int index, const String &newString)
void	addArray (const StringArray &other, int startIndex=0, int numElementsToAdd=-1)
void	mergeArray (const StringArray &other, bool ignoreCase=false)
int	addTokens (StringRef stringToTokenise, bool preserveQuotedStrings)
int	addTokens (StringRef stringToTokenise, StringRef breakCharacters, StringRef quoteCharacters)
int	addLines (StringRef stringToBreakUp)
void	clear ()
void	clearQuick ()
void	remove (int index)
void	removeString (StringRef stringToRemove, bool ignoreCase=false)
void	removeRange (int startIndex, int numberToRemove)
void	removeDuplicates (bool ignoreCase)
void	removeEmptyStrings (bool removeWhitespaceStrings=true)
void	trim ()
void	appendNumbersToDuplicates (bool ignoreCaseWhenComparing, bool appendNumberToFirstInstance, CharPointer_UTF8 preNumberString=CharPointer_UTF8(nullptr), CharPointer_UTF8 postNumberString=CharPointer_UTF8(nullptr))
String	joinIntoString (StringRef separatorString, int startIndex=0, int numberOfElements=-1) const
void	sort (bool ignoreCase)
void	sortNatural ()
void	ensureStorageAllocated (int minNumElements)
void	minimiseStorageOverheads ()

Static Public Member Functions
static StringArray	fromTokens (StringRef stringToTokenise, bool preserveQuotedStrings)
static StringArray	fromTokens (StringRef stringToTokenise, StringRef breakCharacters, StringRef quoteCharacters)
static StringArray	fromLines (StringRef stringToBreakUp)

Public Attributes
Array< String >	strings

Detailed Description

A special array for holding a list of strings.

See also

String, StringPairArray

Constructor & Destructor Documentation

StringArray() [1/6]

water::StringArray::StringArray ( )

noexcept

Creates an empty string array

StringArray() [2/6]

water::StringArray::StringArray

(

const StringArray &

other

)

Creates a copy of another string array

StringArray() [3/6]

water::StringArray::StringArray ( const String & firstValue )

explicit

Creates an array containing a single string.

StringArray() [4/6]

water::StringArray::StringArray	(	const String *	strings,
		int	numberOfStrings )

Creates an array from a raw array of strings.

Parameters

strings	an array of strings to add
numberOfStrings	how many items there are in the array

StringArray() [5/6]

water::StringArray::StringArray	(	const char *const *	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() [6/6]

water::StringArray::StringArray ( const char *const * 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()

water::StringArray::~StringArray

(

)

Destructor.

Member Function Documentation

add()

bool water::StringArray::add

(

const String &

stringToAdd

)

Appends a string at the end of the array.

addArray()

void water::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)

addIfNotAlreadyThere()

bool water::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.

Returns

true if the string has been added, false otherwise.

addLines()

int water::StringArray::addLines

(

StringRef

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.

addTokens() [1/2]

int water::StringArray::addTokens	(	StringRef	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

See also

fromTokens

addTokens() [2/2]

int water::StringArray::addTokens	(	StringRef	stringToTokenise,
		StringRef	breakCharacters,
		StringRef	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

See also

fromTokens

appendNumbersToDuplicates()

void water::StringArray::appendNumbersToDuplicates	(	bool	ignoreCaseWhenComparing,
		bool	appendNumberToFirstInstance,
		CharPointer_UTF8	preNumberString = CharPointer_UTF8 (nullptr),
		CharPointer_UTF8	postNumberString = CharPointer_UTF8 (nullptr) )

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 nullptr, 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 nullptr, a default string will be used, which adds brackets around the number.

begin()

String * water::StringArray::begin ( ) const

inlinenoexcept

Returns a pointer to the first String in the array. This method is provided for compatibility with standard C++ iteration mechanisms.

clear()

void water::StringArray::clear

(

)

Removes all elements from the array.

clearQuick()

void water::StringArray::clearQuick

(

)

Removes all elements from the array without freeing the array's allocated storage.

See also

clear

contains()

bool water::StringArray::contains	(	StringRef	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

end()

String * water::StringArray::end ( ) const

inlinenoexcept

Returns a pointer to the String which follows the last element in the array. This method is provided for compatibility with standard C++ iteration mechanisms.

ensureStorageAllocated()

void water::StringArray::ensureStorageAllocated

(

int

minNumElements

)

Increases the array's internal storage to hold a minimum number of elements.

Calling this before adding a large known number of elements means that the array won't have to keep dynamically resizing itself as the elements are added, and it'll therefore be more efficient.

fromLines()

StringArray water::StringArray::fromLines ( StringRef stringToBreakUp )

static

Returns an array containing the lines in a given string.

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

fromTokens() [1/2]

StringArray water::StringArray::fromTokens ( StringRef stringToTokenise, bool preserveQuotedStrings )

static

Returns an array containing the tokens in a given string.

This will tokenise the given string using whitespace characters as the token delimiters, and return the parsed tokens as an array.

See also

addTokens

fromTokens() [2/2]

StringArray water::StringArray::fromTokens ( StringRef stringToTokenise, StringRef breakCharacters, StringRef quoteCharacters )

static

Returns an array containing the tokens in a given string.

This will tokenise the given string using the breakCharacters string to define the token delimiters, and will return the parsed tokens as an 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.

See also

addTokens

getReference()

String & water::StringArray::getReference ( int index )

noexcept

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.

indexOf()

int water::StringArray::indexOf	(	StringRef	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.

insert()

bool water::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.

isEmpty()

bool water::StringArray::isEmpty ( ) const

inlinenoexcept

Returns true if the array is empty, false otherwise.

joinIntoString()

String water::StringArray::joinIntoString	(	StringRef	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.

mergeArray()

void water::StringArray::mergeArray	(	const StringArray &	other,
		bool	ignoreCase = false )

Merges the strings from another array into this one. This will not add a string that already exists.

Parameters

other	the array to add
ignoreCase	ignore case when merging

minimiseStorageOverheads()

void water::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.

operator!=()

bool water::StringArray::operator!= ( const StringArray & other ) const

noexcept

Compares two arrays. Comparisons are case-sensitive.

Returns

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

operator=()

StringArray & water::StringArray::operator=

(

const StringArray &

other

)

Copies the contents of another string array into this one

operator==()

bool water::StringArray::operator== ( const StringArray & other ) const

noexcept

Compares two arrays. Comparisons are case-sensitive.

Returns

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

operator[]()

const String & water::StringArray::operator[] ( int index ) const

noexcept

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.

remove()

void water::StringArray::remove

(

int

index

)

Removes a string from the array. If the index is out-of-range, no action will be taken.

removeDuplicates()

void water::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

removeEmptyStrings()

void water::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

removeRange()

void water::StringArray::removeRange	(	int	startIndex,
		int	numberToRemove )

Removes a range of elements from the array.

This will remove a set of elements, starting from the given index, and move subsequent elements down to close the gap.

If the range extends beyond the bounds of the array, it will be safely clipped to the size of the array.

Parameters

startIndex	the index of the first element to remove
numberToRemove	how many elements should be removed

removeString()

void water::StringArray::removeString	(	StringRef	stringToRemove,
		bool	ignoreCase = false )

Finds a string in the array and removes it. This will remove all occurrences of the given string from the array. The comparison may be case-insensitive depending on the ignoreCase parameter.

set()

void water::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.

size()

int water::StringArray::size ( ) const

inlinenoexcept

Returns the number of strings in the array

sort()

void water::StringArray::sort

(

bool

ignoreCase

)

Sorts the array into alphabetical order.

Parameters

ignoreCase

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

sortNatural()

void water::StringArray::sortNatural

(

)

Sorts the array using extra language-aware rules to do a better job of comparing words containing spaces and numbers.

See also

String::compareNatural()

swapWith()

void water::StringArray::swapWith ( StringArray & other )

noexcept

Swaps the contents of this and another StringArray.

trim()

void water::StringArray::trim

(

)

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

Member Data Documentation

strings

Array<String> water::StringArray::strings

This is the array holding the actual strings. This is public to allow direct access to array methods that may not already be provided by the StringArray class.

---

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

• /home/runner/work/lmms-fork/lmms-fork/plugins/CarlaBase/carla/source/modules/water/text/StringArray.h
• /home/runner/work/lmms-fork/lmms-fork/plugins/CarlaBase/carla/source/modules/water/text/StringArray.cpp