Class to manage a double null-terminated list of strings, such as "one\0two\0three\0". More...

#include <CStringArray.h>

Inheritance diagram for CStringArray:
[legend]
Collaboration diagram for CStringArray:
[legend]

Classes

class  Iterator
 

Public Member Functions

CStringArrayoperator= (const char *cstr)
 
bool add (const char *str, int length=-1)
 Append a new string (or array of strings) to the end of the array. More...
 
bool add (const String &str)
 Append a new string (or array of strings) to the end of the array. More...
 
int indexOf (const char *str, bool ignoreCase=true) const
 Find the given string and return its index. More...
 
int indexOf (const String &str, bool ignoreCase=true) const
 Find the given string and return its index. More...
 
bool contains (const char *str, bool ignoreCase=true) const
 Check if array contains a string. More...
 
bool contains (const String &str, bool ignoreCase=true) const
 Check if array contains a string. More...
 
const char * getValue (unsigned index) const
 Get string at the given position. More...
 
const char * operator[] (unsigned index) const
 Get string at the given position. More...
 
void clear ()
 Empty the array. More...
 
unsigned count () const
 Get quantity of strings in array. More...
 
Constructors
 CStringArray (const String &str)
 
 CStringArray (const char *cstr=nullptr)
 
 CStringArray (const char *cstr, unsigned int length)
 
 CStringArray (flash_string_t pstr, int length=-1)
 
 CStringArray (const FlashString &fstr)
 
Concatenation operators
CStringArrayoperator+= (const String &str)
 
CStringArrayoperator+= (const char *cstr)
 
template<typename T >
CStringArrayoperator+= (T value)
 Append numbers, etc. to the array. More...
 
Iterator support (forward only)
Iterator begin () const
 
Iterator end () const
 

Private Member Functions

void setString (const char *cstr, int length=-1)
 
void setString (flash_string_t pstr, int length=-1)
 
bool reserve (size_t size)
 Pre-allocate String memory. More...
 
bool setLength (size_t length)
 set the string length accordingly, expanding if necessary More...
 
size_t length (void) const
 Obtain the String length in characters, excluding NUL terminator. More...
 
 operator StringIfHelperType () const
 Provides safe bool() operator. More...
 
bool startsWith (const String &prefix) const
 Compare the start of a String Comparison is case-sensitive, must match exactly. More...
 
bool startsWith (const String &prefix, size_t offset) const
 Compare a string portion. More...
 
bool endsWith (const String &suffix) const
 Compare the end of a String. More...
 
char charAt (size_t index) const
 Obtain the character at the given index. More...
 
void setCharAt (size_t index, char c)
 Sets the character at a given index. More...
 
size_t getBytes (unsigned char *buf, size_t bufsize, size_t index=0) const
 Read contents of a String into a buffer. More...
 
void toCharArray (char *buf, size_t bufsize, size_t index=0) const
 Read contents of String into a buffer. More...
 
const char * c_str () const
 Get a constant (un-modifiable) pointer to String content. More...
 
char * begin ()
 Get a modifiable pointer to String content. More...
 
char * end ()
 Get a modifiable pointer to one-past the end of the String. More...
 
void toLowerCase (void)
 Convert the entire String content to lower case. More...
 
void toUpperCase (void)
 Convert the entire String content to upper case. More...
 
void trim (void)
 Remove all leading and trailing whitespace characters from the String. More...
 
long toInt (void) const
 
float toFloat (void) const
 
void invalidate (void)
 
bool isNull () const
 
char * buffer ()
 
const char * cbuffer () const
 
size_t capacity () const
 
void setlen (size_t len)
 
Stringcopy (const char *cstr, size_t length)
 
Stringcopy (flash_string_t pstr, size_t length)
 
void move (String &rhs)
 
Concatenation methods
Return values
booltrue on success, false on failure

Works with built-in types. On failure, the string is left unchanged. If the argument is null or invalid, the concatenation is considered unsucessful.

bool concat (const String &str)
 
bool concat (const FlashString &fstr)
 
bool concat (const char *cstr)
 
bool concat (const char *cstr, size_t length)
 
bool concat (char c)
 
bool concat (unsigned char num)
 
bool concat (int num)
 
bool concat (unsigned int num)
 
bool concat (long num)
 
bool concat (long long num)
 
bool concat (unsigned long num)
 
bool concat (unsigned long long num)
 
bool concat (float num)
 
bool concat (double num)
 
Concatenation operators

If there's not enough memory for the concatenated value, the string will be left unchanged (but this isn't signalled in any way)

Stringoperator+= (const FlashString &rhs)
 
Stringoperator+= (char c)
 
Stringoperator+= (unsigned char num)
 
Stringoperator+= (int num)
 
Stringoperator+= (unsigned int num)
 
Stringoperator+= (long num)
 
Stringoperator+= (long long num)
 
Stringoperator+= (unsigned long num)
 
Stringoperator+= (unsigned long long num)
 
Stringoperator+= (float num)
 
Stringoperator+= (double num)
 
Comparison methods

Works with String and 'c' string

Return values
intReturns < 0 if String is lexically before the argument, > 0 if after or 0 if the same

Comparisons are case-sensitive, binary comparison null strings (including cstr == nullptr) are treated as empty.

int compareTo (const char *cstr, size_t length) const
 
int compareTo (const String &s) const
 
Test for equality

Compares content byte-for-byte using binary comparison

Return values
boolReturns true if strings are identical

null strings (including cstr == nullptr) are treated as empty.

bool equals (const String &s) const
 
bool equals (const char *cstr) const
 
bool equals (const char *cstr, size_t length) const
 
bool equals (const FlashString &fstr) const
 
Equality operator ==
Return values
booltrue if Strings are identical
bool operator== (const String &rhs) const
 
bool operator== (const char *cstr) const
 
bool operator== (const FlashString &fstr) const
 
In-equality operator !=
Return values
boolReturns true if strings are not identical
bool operator!= (const String &rhs) const
 
bool operator!= (const char *cstr) const
 
Comparison operators
bool operator< (const String &rhs) const
 
bool operator> (const String &rhs) const
 
bool operator<= (const String &rhs) const
 
bool operator>= (const String &rhs) const
 
Test for equality, without case-sensitivity
Return values
booltrue if strings are considered the same

null strings are treated as empty.

bool equalsIgnoreCase (const char *cstr) const
 
bool equalsIgnoreCase (const char *cstr, size_t length) const
 
bool equalsIgnoreCase (const String &s2) const
 
bool equalsIgnoreCase (const FlashString &fstr) const
 
Array operators

If index is invalid, returns NUL \0

char operator[] (size_t index) const
 
char & operator[] (size_t index)
 
int indexOf(...)

Locate a character or String within another String.

Return values
intIndex if found, -1 if not found

By default, searches from the beginning of the String, but can also start from a given index, allowing for the locating of all instances of the character or String.

int indexOf (char ch, size_t fromIndex=0) const
 
int indexOf (const char *s2_buf, size_t fromIndex, size_t s2_len) const
 
int indexOf (const char *s2_buf, size_t fromIndex=0) const
 
int indexOf (const String &s2, size_t fromIndex=0) const
 
int lastIndexOf(...)

Locate a character or String within another String

Return values
intIndex if found, -1 if not found

By default, searches from the end of the String, but can also work backwards from a given index, allowing for the locating of all instances of the character or String.

int lastIndexOf (char ch) const
 
int lastIndexOf (char ch, size_t fromIndex) const
 
int lastIndexOf (const String &s2) const
 
int lastIndexOf (const String &s2, size_t fromIndex) const
 
int lastIndexOf (const char *s2_buf, size_t fromIndex, size_t s2_len) const
 
String substring(...)

Get a substring of a String.

Parameters
fromIndex of first character to retrieve
to(optional) One-past the ending character to retrieve

The starting index is inclusive (the corresponding character is included in the substring), but the optional ending index is exclusive (the corresponding character is not included in the substring).

If the ending index is omitted, the substring continues to the end of the String.

If you don't need the original String, consider using remove() instead:

    String original("This is the original string.");
    String sub = original.substring(0, 13);

This produces the same result:

    original.remove(13);
String substring (size_t from, size_t to) const
 
String substring (size_t from) const
 
replace(...)

Replace all instances of a given character or substring with another character or substring.

Return values
booltrue on success, false on allocation failure

Replacing a single character always succeeds as this is handled in-place.

Where replace is longer than find the String may need to be re-allocated, which could fail. If this happens the method returns false and the String is left unchanged.

void replace (char find, char replace)
 
bool replace (const String &find, const String &replace)
 
bool replace (const char *find_buf, size_t find_len, const char *replace_buf, size_t replace_len)
 
remove()

Remove characters from a String.

Parameters
indexIndex of the first character to remove
countNumber of characters to remove
Note
The String is modified in-situ without any reallocation

If no count is provided then all characters from the given index to the end of the String are removed.

void remove (size_t index)
 
void remove (size_t index, size_t count)
 

Private Attributes

union {
   PtrBuf   ptr
 
   SsoBuf   sso
 
}; 
 

Static Private Attributes

static const String nullstr
 A null string evaluates to false. More...
 
static const String empty
 An empty string evaluates to true. More...
 
static constexpr size_t SSO_CAPACITY = STRING_OBJECT_SIZE - 2
 Max chars. (excluding NUL terminator) we can store in SSO mode. More...
 

Detailed Description

Class to manage a double null-terminated list of strings, such as "one\0two\0three\0".

Constructor & Destructor Documentation

◆ CStringArray() [1/5]

CStringArray::CStringArray ( const String str)
inline

◆ CStringArray() [2/5]

CStringArray::CStringArray ( const char *  cstr = nullptr)
inline

◆ CStringArray() [3/5]

CStringArray::CStringArray ( const char *  cstr,
unsigned int  length 
)
inline

◆ CStringArray() [4/5]

CStringArray::CStringArray ( flash_string_t  pstr,
int  length = -1 
)
inlineexplicit

◆ CStringArray() [5/5]

CStringArray::CStringArray ( const FlashString fstr)
inline

Member Function Documentation

◆ add() [1/2]

bool CStringArray::add ( const char *  str,
int  length = -1 
)

Append a new string (or array of strings) to the end of the array.

Parameters
str
lengthLength of new string in array (default is length of str)
Return values
boolfalse on memory allocation error
Note
If str contains any NUL characters it will be handled as an array

◆ add() [2/2]

bool CStringArray::add ( const String str)
inline

Append a new string (or array of strings) to the end of the array.

Parameters
str
Return values
boolfalse on memory allocation error
Note
If str contains any NUL characters it will be handled as an array

◆ begin()

Iterator CStringArray::begin ( ) const
inline

◆ clear()

void CStringArray::clear ( )
inline

Empty the array.

◆ contains() [1/2]

bool CStringArray::contains ( const char *  str,
bool  ignoreCase = true 
) const
inline

Check if array contains a string.

Parameters
strString to search for
ignoreCaseWhether search is case-sensitive or not
Return values
boolTrue if string exists in array
Note
Search is not case-sensitive

◆ contains() [2/2]

bool CStringArray::contains ( const String str,
bool  ignoreCase = true 
) const
inline

Check if array contains a string.

Parameters
strString to search for
ignoreCaseWhether search is case-sensitive or not
Return values
boolTrue if string exists in array
Note
Search is not case-sensitive

◆ count()

unsigned CStringArray::count ( ) const

Get quantity of strings in array.

Return values
unsignedQuantity of strings

◆ end()

Iterator CStringArray::end ( ) const
inline

◆ getValue()

const char* CStringArray::getValue ( unsigned  index) const

Get string at the given position.

Parameters
index0-based index of string to obtain
Return values
constchar* nullptr if index is not valid

◆ indexOf() [1/2]

int CStringArray::indexOf ( const char *  str,
bool  ignoreCase = true 
) const

Find the given string and return its index.

Parameters
strString to find
ignoreCaseWhether search is case-sensitive or not
Return values
intindex of given string, -1 if not found
Note
Comparison is not case-sensitive

◆ indexOf() [2/2]

int CStringArray::indexOf ( const String str,
bool  ignoreCase = true 
) const
inline

Find the given string and return its index.

Parameters
strString to find
ignoreCaseWhether search is case-sensitive or not
Return values
intindex of given string, -1 if not found
Note
Comparison is not case-sensitive

◆ operator+=() [1/3]

CStringArray& CStringArray::operator+= ( const String str)
inline

◆ operator+=() [2/3]

CStringArray& CStringArray::operator+= ( const char *  cstr)
inline

◆ operator+=() [3/3]

template<typename T >
CStringArray& CStringArray::operator+= ( value)
inline

Append numbers, etc. to the array.

Parameters
valuechar, int, float, etc. as supported by String

◆ operator=()

CStringArray& CStringArray::operator= ( const char *  cstr)
inline

◆ operator[]()

const char* CStringArray::operator[] ( unsigned  index) const
inline

Get string at the given position.

Parameters
index0-based index of string to obtain
Return values
constchar* nullptr if index is not valid

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