The String class. More...

#include <WString.h>

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

Classes

struct  PtrBuf
 Used when contents allocated on heap. More...
 
struct  SsoBuf
 

Public Member Functions

 String ()
 Default constructor. More...
 
 ~String (void)
 
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...
 
const char * begin () const
 
const char * end () const
 
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
 
Copy constructors

If the initial value is null or invalid, or if memory allocation fails, the string will be marked as invalid (i.e. "if (s)" will be false).

 String (const char *cstr)
 
 String (const char *cstr, size_t length)
 
 String (const String &str)
 
 String (flash_string_t pstr, int length=-1)
 
 String (String &&rval)
 
 String (StringSumHelper &&rval)
 
 String (char c)
 
 String (unsigned char, unsigned char base=10)
 
 String (int, unsigned char base=10)
 
 String (unsigned int, unsigned char base=10)
 
 String (long, unsigned char base=10)
 
 String (long long, unsigned char base=10)
 
 String (unsigned long, unsigned char base=10)
 
 String (unsigned long long, unsigned char base=10)
 
 String (float, unsigned char decimalPlaces=2)
 
 String (double, unsigned char decimalPlaces=2)
 
Copy operators

If the value is null or invalid, or if the memory allocation fails, the String will be marked as invalid ("if (s)" will be false).

Stringoperator= (const String &rhs)
 
Stringoperator= (const char *cstr)
 
Move operators

Move content from one String to another without any heap allocation.

Move operators are automatically selected by the compiler when it is able, such as when returning temporary String objects from functions.

In other situations, use std::move:

String original("A String");
String copy("This is the content for the copy");
copy = std::move(myString);

copy will now contain "A String", whilst original will be invalidated.

Stringoperator= (String &&rval)
 
Stringoperator= (StringSumHelper &&rval)
 
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 String &rhs)
 
Stringoperator+= (const FlashString &rhs)
 
Stringoperator+= (const char *cstr)
 
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)
 

Static Public 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...
 

Protected Member Functions

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)
 

Protected Attributes

union {
   PtrBuf   ptr
 
   SsoBuf   sso
 
}; 
 

Friends

StringSumHelperoperator+ (const StringSumHelper &lhs, const String &rhs)
 
StringSumHelperoperator+ (const StringSumHelper &lhs, const char *cstr)
 
StringSumHelperoperator+ (const StringSumHelper &lhs, char c)
 
StringSumHelperoperator+ (const StringSumHelper &lhs, unsigned char num)
 
StringSumHelperoperator+ (const StringSumHelper &lhs, int num)
 
StringSumHelperoperator+ (const StringSumHelper &lhs, unsigned int num)
 
StringSumHelperoperator+ (const StringSumHelper &lhs, long num)
 
StringSumHelperoperator+ (const StringSumHelper &lhs, unsigned long num)
 
StringSumHelperoperator+ (const StringSumHelper &lhs, unsigned long long num)
 
StringSumHelperoperator+ (const StringSumHelper &lhs, float num)
 
StringSumHelperoperator+ (const StringSumHelper &lhs, double num)
 

Detailed Description

The String class.

Note that a string object's default constructor creates an empty string. This is not the same as a null string. A null string evaluates to false, but an empty string evaluates to true.

Small String Optimisation means that heap is only used for strings longer than 10 characters, not including the NUL terminator. This is simply making use of existing storage within the String object.

This length can be increased using STRING_OBJECT_SIZE, but note the additional space remains unused when switching to heap storage for longer Strings.

Constructor & Destructor Documentation

◆ String() [1/17]

String::String ( )
inline

Default constructor.

Note
Creates a null String which evaluates to false.

◆ String() [2/17]

String::String ( const char *  cstr)

◆ String() [3/17]

String::String ( const char *  cstr,
size_t  length 
)
inline

◆ String() [4/17]

String::String ( const String str)
inline

◆ String() [5/17]

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

◆ String() [6/17]

String::String ( String &&  rval)
inline

◆ String() [7/17]

String::String ( StringSumHelper &&  rval)

◆ String() [8/17]

String::String ( char  c)
explicit

◆ String() [9/17]

String::String ( unsigned  char,
unsigned char  base = 10 
)
explicit

◆ String() [10/17]

String::String ( int  ,
unsigned char  base = 10 
)
explicit

◆ String() [11/17]

String::String ( unsigned  int,
unsigned char  base = 10 
)
explicit

◆ String() [12/17]

String::String ( long  ,
unsigned char  base = 10 
)
explicit

◆ String() [13/17]

String::String ( long  long,
unsigned char  base = 10 
)
explicit

◆ String() [14/17]

String::String ( unsigned  long,
unsigned char  base = 10 
)
explicit

◆ String() [15/17]

String::String ( unsigned long  long,
unsigned char  base = 10 
)
explicit

◆ String() [16/17]

String::String ( float  ,
unsigned char  decimalPlaces = 2 
)
explicit

◆ String() [17/17]

String::String ( double  ,
unsigned char  decimalPlaces = 2 
)
explicit

◆ ~String()

String::~String ( void  )
inline

Member Function Documentation

◆ begin() [1/2]

char* String::begin ( )
inline

Get a modifiable pointer to String content.

Note
If String is NUL, returns nullptr.

◆ begin() [2/2]

const char* String::begin ( ) const
inline

◆ buffer()

char* String::buffer ( )
inlineprotected

◆ c_str()

const char* String::c_str ( ) const
inline

Get a constant (un-modifiable) pointer to String content.

Return values
constchar* Always valid, even for a null string

◆ capacity()

size_t String::capacity ( ) const
inlineprotected

◆ cbuffer()

const char* String::cbuffer ( ) const
inlineprotected

◆ charAt()

char String::charAt ( size_t  index) const
inline

Obtain the character at the given index.

Parameters
index
Return values
char
Note
If index is invalid, returns NUL \0

◆ compareTo() [1/2]

int String::compareTo ( const char *  cstr,
size_t  length 
) const

◆ compareTo() [2/2]

int String::compareTo ( const String s) const
inline

◆ concat() [1/14]

bool String::concat ( const String str)
inline

◆ concat() [2/14]

bool String::concat ( const FlashString fstr)

◆ concat() [3/14]

bool String::concat ( const char *  cstr)

◆ concat() [4/14]

bool String::concat ( const char *  cstr,
size_t  length 
)

◆ concat() [5/14]

bool String::concat ( char  c)
inline

◆ concat() [6/14]

bool String::concat ( unsigned char  num)

◆ concat() [7/14]

bool String::concat ( int  num)

◆ concat() [8/14]

bool String::concat ( unsigned int  num)

◆ concat() [9/14]

bool String::concat ( long  num)

◆ concat() [10/14]

bool String::concat ( long long  num)

◆ concat() [11/14]

bool String::concat ( unsigned long  num)

◆ concat() [12/14]

bool String::concat ( unsigned long long  num)

◆ concat() [13/14]

bool String::concat ( float  num)

◆ concat() [14/14]

bool String::concat ( double  num)

◆ copy() [1/2]

String& String::copy ( const char *  cstr,
size_t  length 
)
protected

◆ copy() [2/2]

String& String::copy ( flash_string_t  pstr,
size_t  length 
)
protected

◆ end() [1/2]

char* String::end ( )
inline

Get a modifiable pointer to one-past the end of the String.

Note
Points to the terminating NUL character. If String is NUL, returns nullptr.

◆ end() [2/2]

const char* String::end ( ) const
inline

◆ endsWith()

bool String::endsWith ( const String suffix) const

Compare the end of a String.

Parameters
suffix
Return values
booltrue on match

◆ equals() [1/4]

bool String::equals ( const String s) const
inline

◆ equals() [2/4]

bool String::equals ( const char *  cstr) const

◆ equals() [3/4]

bool String::equals ( const char *  cstr,
size_t  length 
) const

◆ equals() [4/4]

bool String::equals ( const FlashString fstr) const
inline

◆ equalsIgnoreCase() [1/4]

bool String::equalsIgnoreCase ( const char *  cstr) const

◆ equalsIgnoreCase() [2/4]

bool String::equalsIgnoreCase ( const char *  cstr,
size_t  length 
) const

◆ equalsIgnoreCase() [3/4]

bool String::equalsIgnoreCase ( const String s2) const
inline

◆ equalsIgnoreCase() [4/4]

bool String::equalsIgnoreCase ( const FlashString fstr) const
inline

◆ getBytes()

size_t String::getBytes ( unsigned char *  buf,
size_t  bufsize,
size_t  index = 0 
) const

Read contents of a String into a buffer.

Parameters
bufbuffer to write data
bufsizesize of buffer in bytes
indexoffset to start
Return values
unsignednumber of bytes copied, excluding nul terminator
Note
Returned data always nul terminated so buffer size needs to take this into account

◆ indexOf() [1/4]

int String::indexOf ( char  ch,
size_t  fromIndex = 0 
) const

◆ indexOf() [2/4]

int String::indexOf ( const char *  s2_buf,
size_t  fromIndex,
size_t  s2_len 
) const

◆ indexOf() [3/4]

int String::indexOf ( const char *  s2_buf,
size_t  fromIndex = 0 
) const
inline

◆ indexOf() [4/4]

int String::indexOf ( const String s2,
size_t  fromIndex = 0 
) const
inline

◆ invalidate()

void String::invalidate ( void  )
protected

◆ isNull()

bool String::isNull ( ) const
inlineprotected

◆ lastIndexOf() [1/5]

int String::lastIndexOf ( char  ch) const

◆ lastIndexOf() [2/5]

int String::lastIndexOf ( char  ch,
size_t  fromIndex 
) const

◆ lastIndexOf() [3/5]

int String::lastIndexOf ( const String s2) const

◆ lastIndexOf() [4/5]

int String::lastIndexOf ( const String s2,
size_t  fromIndex 
) const

◆ lastIndexOf() [5/5]

int String::lastIndexOf ( const char *  s2_buf,
size_t  fromIndex,
size_t  s2_len 
) const

◆ length()

size_t String::length ( void  ) const
inline

Obtain the String length in characters, excluding NUL terminator.

◆ move()

void String::move ( String rhs)
protected

◆ operator StringIfHelperType()

String::operator StringIfHelperType ( ) const
inline

Provides safe bool() operator.

Evaluates as false if String is null, otherwise evaluates as true

◆ operator!=() [1/2]

bool String::operator!= ( const String rhs) const
inline

◆ operator!=() [2/2]

bool String::operator!= ( const char *  cstr) const
inline

◆ operator+=() [1/13]

String& String::operator+= ( const String rhs)
inline

◆ operator+=() [2/13]

String& String::operator+= ( const FlashString rhs)
inline

◆ operator+=() [3/13]

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

◆ operator+=() [4/13]

String& String::operator+= ( char  c)
inline

◆ operator+=() [5/13]

String& String::operator+= ( unsigned char  num)
inline

◆ operator+=() [6/13]

String& String::operator+= ( int  num)
inline

◆ operator+=() [7/13]

String& String::operator+= ( unsigned int  num)
inline

◆ operator+=() [8/13]

String& String::operator+= ( long  num)
inline

◆ operator+=() [9/13]

String& String::operator+= ( long long  num)
inline

◆ operator+=() [10/13]

String& String::operator+= ( unsigned long  num)
inline

◆ operator+=() [11/13]

String& String::operator+= ( unsigned long long  num)
inline

◆ operator+=() [12/13]

String& String::operator+= ( float  num)
inline

◆ operator+=() [13/13]

String& String::operator+= ( double  num)
inline

◆ operator<()

bool String::operator< ( const String rhs) const
inline

◆ operator<=()

bool String::operator<= ( const String rhs) const
inline

◆ operator=() [1/4]

String& String::operator= ( const String rhs)

◆ operator=() [2/4]

String& String::operator= ( const char *  cstr)

◆ operator=() [3/4]

String& String::operator= ( String &&  rval)
inline

◆ operator=() [4/4]

String& String::operator= ( StringSumHelper &&  rval)

◆ operator==() [1/3]

bool String::operator== ( const String rhs) const
inline

◆ operator==() [2/3]

bool String::operator== ( const char *  cstr) const
inline

◆ operator==() [3/3]

bool String::operator== ( const FlashString fstr) const
inline

◆ operator>()

bool String::operator> ( const String rhs) const
inline

◆ operator>=()

bool String::operator>= ( const String rhs) const
inline

◆ operator[]() [1/2]

char String::operator[] ( size_t  index) const

◆ operator[]() [2/2]

char& String::operator[] ( size_t  index)

◆ remove() [1/2]

void String::remove ( size_t  index)
inline

◆ remove() [2/2]

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

◆ replace() [1/3]

void String::replace ( char  find,
char  replace 
)

◆ replace() [2/3]

bool String::replace ( const String find,
const String replace 
)

◆ replace() [3/3]

bool String::replace ( const char *  find_buf,
size_t  find_len,
const char *  replace_buf,
size_t  replace_len 
)

◆ reserve()

bool String::reserve ( size_t  size)

Pre-allocate String memory.

Parameters
size
Return values
booltrue on success, false on failure

On failure, the String is left unchanged. reserve(0), if successful, will validate an invalid string (i.e., "if (s)" will be true afterwards)

◆ setCharAt()

void String::setCharAt ( size_t  index,
char  c 
)

Sets the character at a given index.

Parameters
index
c
Note
If index is invalid, does nothing

◆ setlen()

void String::setlen ( size_t  len)
inlineprotected

◆ setLength()

bool String::setLength ( size_t  length)

set the string length accordingly, expanding if necessary

Parameters
lengthrequired for string (nul terminator additional)
Return values
trueon success, false on failure
Note
extra characters are undefined

◆ setString() [1/2]

void String::setString ( const char *  cstr,
int  length = -1 
)

◆ setString() [2/2]

void String::setString ( flash_string_t  pstr,
int  length = -1 
)

◆ startsWith() [1/2]

bool String::startsWith ( const String prefix) const
inline

Compare the start of a String Comparison is case-sensitive, must match exactly.

Parameters
prefix
Return values
booltrue on match

◆ startsWith() [2/2]

bool String::startsWith ( const String prefix,
size_t  offset 
) const

Compare a string portion.

Parameters
prefix
offsetIndex to start comparison at
Return values
booltrue on match
Note
Comparison is case-sensitive, must match exactly

mis-named as does not necessarily compare from start

◆ substring() [1/2]

String String::substring ( size_t  from,
size_t  to 
) const

◆ substring() [2/2]

String String::substring ( size_t  from) const
inline

◆ toCharArray()

void String::toCharArray ( char *  buf,
size_t  bufsize,
size_t  index = 0 
) const
inline

Read contents of String into a buffer.

See also
See getBytes()

◆ toFloat()

float String::toFloat ( void  ) const

◆ toInt()

long String::toInt ( void  ) const

◆ toLowerCase()

void String::toLowerCase ( void  )

Convert the entire String content to lower case.

◆ toUpperCase()

void String::toUpperCase ( void  )

Convert the entire String content to upper case.

◆ trim()

void String::trim ( void  )

Remove all leading and trailing whitespace characters from the String.

Friends And Related Function Documentation

◆ operator+ [1/11]

StringSumHelper& operator+ ( const StringSumHelper lhs,
const String rhs 
)
friend

◆ operator+ [2/11]

StringSumHelper& operator+ ( const StringSumHelper lhs,
const char *  cstr 
)
friend

◆ operator+ [3/11]

StringSumHelper& operator+ ( const StringSumHelper lhs,
char  c 
)
friend

◆ operator+ [4/11]

StringSumHelper& operator+ ( const StringSumHelper lhs,
unsigned char  num 
)
friend

◆ operator+ [5/11]

StringSumHelper& operator+ ( const StringSumHelper lhs,
int  num 
)
friend

◆ operator+ [6/11]

StringSumHelper& operator+ ( const StringSumHelper lhs,
unsigned int  num 
)
friend

◆ operator+ [7/11]

StringSumHelper& operator+ ( const StringSumHelper lhs,
long  num 
)
friend

◆ operator+ [8/11]

StringSumHelper& operator+ ( const StringSumHelper lhs,
unsigned long  num 
)
friend

◆ operator+ [9/11]

StringSumHelper& operator+ ( const StringSumHelper lhs,
unsigned long long  num 
)
friend

◆ operator+ [10/11]

StringSumHelper& operator+ ( const StringSumHelper lhs,
float  num 
)
friend

◆ operator+ [11/11]

StringSumHelper& operator+ ( const StringSumHelper lhs,
double  num 
)
friend

Member Data Documentation

◆ @2

union { ... }

◆ empty

const String String::empty
static

An empty string evaluates to true.

◆ nullstr

const String String::nullstr
static

A null string evaluates to false.

◆ ptr

PtrBuf String::ptr

◆ sso

SsoBuf String::sso

◆ SSO_CAPACITY

constexpr size_t String::SSO_CAPACITY = STRING_OBJECT_SIZE - 2
static

Max chars. (excluding NUL terminator) we can store in SSO mode.


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