|
| String () |
| Default constructor. More...
|
|
| ~String (void) |
|
void | setString (const char *cstr) |
|
void | setString (const char *cstr, size_t length) |
|
void | setString (flash_string_t pstr) |
|
void | setString (flash_string_t pstr, size_t length) |
|
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...
|
|
bool | setBuffer (const Buffer &buffer) |
| Set String content using move semantics from external memory buffer. More...
|
|
Buffer | getBuffer () |
| Get String content using move semantics. 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 (char suffix) const |
| Compare the end of a String. 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 (const char *set=" \t\n\v\f\r") |
| Remove all leading and trailing characters from the String. More...
|
|
long | toInt (void) const |
|
float | toFloat (void) const |
|
|
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, size_t length) |
|
| String (flash_string_t pstr) |
|
| String (String &&rval) noexcept |
|
| String (StringSumHelper &&rval) noexcept |
|
| String (char c) |
|
| String (unsigned char, unsigned char base=10, unsigned char width=0, char pad='0') |
|
| String (int num, unsigned char base=10, unsigned char width=0, char pad='0') |
|
| String (unsigned int num, unsigned char base=10, unsigned char width=0, char pad='0') |
|
| String (long, unsigned char base=10, unsigned char width=0, char pad='0') |
|
| String (long long, unsigned char base=10, unsigned char width=0, char pad='0') |
|
| String (unsigned long, unsigned char base=10, unsigned char width=0, char pad='0') |
|
| String (unsigned long long, unsigned char base=10, unsigned char width=0, char pad='0') |
|
| String (float, unsigned char decimalPlaces=2) |
|
| String (double, unsigned char decimalPlaces=2) |
|
|
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).
|
String & | operator= (const String &rhs) |
|
String & | operator= (const char *cstr) |
|
|
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.
|
String & | operator= (String &&rval) noexcept |
|
String & | operator= (StringSumHelper &&rval) noexcept |
|
|
- Return values
-
bool | true 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 unsuccessful.
|
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, unsigned char base=10, unsigned char width=0, char pad='0') |
|
bool | concat (int num, unsigned char base=10, unsigned char width=0, char pad='0') |
|
bool | concat (unsigned int num, unsigned char base=10, unsigned char width=0, char pad='0') |
|
bool | concat (long num, unsigned char base=10, unsigned char width=0, char pad='0') |
|
bool | concat (long long num, unsigned char base=10, unsigned char width=0, char pad='0') |
|
bool | concat (unsigned long num, unsigned char base=10, unsigned char width=0, char pad='0') |
|
bool | concat (unsigned long long num, unsigned char base=10, unsigned char width=0, char pad='0') |
|
bool | concat (float num) |
|
bool | concat (double num) |
|
template<typename E > |
constexpr std::enable_if< std::is_enum< E >::value &&!std::is_convertible< E, int >::value, bool >::type | concat (E value) |
|
|
If there's not enough memory for the concatenated value, the string will be left unchanged (but this isn't signalled in any way)
|
String & | operator+= (const String &rhs) |
|
String & | operator+= (const FlashString &rhs) |
|
String & | operator+= (const char *cstr) |
|
template<typename T > |
String & | operator+= (T value) |
|
|
Works with String and 'c' string - Return values
-
int | Returns < 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 |
|
|
Compares content byte-for-byte using binary comparison - Return values
-
bool | Returns 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 |
|
|
- Return values
-
bool | true if Strings are identical |
|
bool | operator== (const String &rhs) const |
|
bool | operator== (const char *cstr) const |
|
bool | operator== (const FlashString &fstr) const |
|
|
- Return values
-
bool | Returns true if strings are not identical |
|
bool | operator!= (const String &rhs) const |
|
bool | operator!= (const char *cstr) const |
|
|
bool | operator< (const String &rhs) const |
|
bool | operator> (const String &rhs) const |
|
bool | operator<= (const String &rhs) const |
|
bool | operator>= (const String &rhs) const |
|
|
- Return values
-
bool | true 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 |
|
|
If index is invalid, returns NUL \0
|
char | operator[] (size_t index) const |
|
char & | operator[] (size_t index) |
|
|
Locate a character or String within another String. - Return values
-
int | Index 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 |
|
|
Locate a character or String within another String - Return values
-
int | Index 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 |
|
|
Get a substring of a String. - Parameters
-
from | Index 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 all instances of a given character or substring with another character or substring. - Return values
-
bool | true 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 characters from a String. - Parameters
-
index | Index of the first character to remove |
count | Number 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) |
|
|
This is used, for example, when outputting tabular data. The string is modified in-situ to minimise memory reallocations.
Methods may be chained like this:: Serial << String(value).padLeft(10, '.') << endl;
|
String & | padLeft (uint16_t minWidth, char c=' ') |
| Insert padding at start of string if length is less than given width. More...
|
|
String & | padRight (uint16_t minWidth, char c=' ') |
| Insert padding at end of string if length is less than given width. More...
|
|
String & | pad (int16_t minWidth, char c=' ') |
| Pad string if length is less than given width. More...
|
|
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.