WString.h
Go to the documentation of this file.
22 * The standard String object default constructor creates an empty string, which requires a heap allocation of 1 byte.
23 * I changed this behaviour to default to a null string (invalid) to avoid this (usually) un-necessary allocation.
24 * If the value of the string hasn't actually been assigned yet then an 'invalid' (or null) string is the more logical choice.
25 * Additional changes ensure that the content of such a string are equivalent to an empty string "".
29 * The intent of the Wiring authors seems to be that an expression producing a String object will fail and produce
30 * an 'invalid' String (that evaluates to False) if any of the allocations within that expression fail. This could
37 * If a heap allocation fails on either "A" or "B" the the result should be a null string. However, this is not actually
38 * the case. In practice, if "A" fails but "B" does not then the result will be "B", while if "A" succeeds but "B" fails
39 * then the result will be 'invalid'. This would appear to be an oversight in the Wiring library (last updated July 2016).
41 * I made a decision with these changes that heap allocation errors are a rare enough occurrence that attempting to deal with
44 * These changes have a knock-on effect in that if any of the allocations in an expression fail, then the result, tmp,
50 * An empty String object now consumes 12 bytes (from 8) but provides an SSO capacity of 11 characters.
113 #define F(string_literal) String(FPSTR(PSTR_COUNTED(string_literal)), sizeof(string_literal) - 1)
194 explicit String(unsigned char, unsigned char base = 10, unsigned char width = 0, char pad = '0');
199 explicit String(unsigned int num, unsigned char base = 10, unsigned char width = 0, char pad = '0')
205 explicit String(unsigned long, unsigned char base = 10, unsigned char width = 0, char pad = '0');
206 explicit String(unsigned long long, unsigned char base = 10, unsigned char width = 0, char pad = '0');
334 bool concat(unsigned char num, unsigned char base = 10, unsigned char width = 0, char pad = '0');
345 bool concat(unsigned long num, unsigned char base = 10, unsigned char width = 0, char pad = '0');
346 bool concat(unsigned long long num, unsigned char base = 10, unsigned char width = 0, char pad = '0');
351 constexpr typename std::enable_if<std::is_enum<E>::value && !std::is_convertible<E, int>::value, bool>::type
734 bool replace(const char* find_buf, size_t find_len, const char* replace_buf, size_t replace_len);
void invalidate(void)
void setString(const char *cstr)
char * end()
Get a modifiable pointer to one-past the end of the String.
Definition: WString.h:635
String substring(size_t from, size_t to) const
String & copy(const char *cstr, size_t length)
int compareTo(const char *cstr, size_t length) const
bool concat(unsigned int num, unsigned char base=10, unsigned char width=0, char pad='0')
Definition: WString.h:339
static const String nullstr
A null string evaluates to false.
Definition: WString.h:148
bool equalsIgnoreCase(const char *cstr) const
constexpr std::enable_if< std::is_enum< E >::value &&!std::is_convertible< E, int >::value, bool >::type concat(E value)
Definition: WString.h:352
bool setLength(size_t length)
set the string length accordingly, expanding if necessary
String & padLeft(uint16_t minWidth, char c=' ')
Insert padding at start of string if length is less than given width.
Definition: WString.h:788
String(unsigned int num, unsigned char base=10, unsigned char width=0, char pad='0')
Definition: WString.h:199
bool equals(const char *cstr, size_t len=0) const
Check for equality with a C-string.
std::enable_if< std::is_integral< T >::value, String >::type toString(T value)
Definition: BitSet.h:481
long toInt(void) const
Definition: WString.h:824
bool equalsIgnoreCase(const FlashString &fstr) const
Definition: WString.h:519
int lastIndexOf(char ch) const
static constexpr size_t SSO_CAPACITY
Max chars. (excluding NUL terminator) we can store in SSO mode.
Definition: WString.h:814
const char * c_str() const
Get a constant (un-modifiable) pointer to String content.
Definition: WString.h:616
bool concat(int num, unsigned char base=10, unsigned char width=0, char pad='0')
Definition: WString.h:335
bool equalsIgnoreCase(const WString &str) const
Definition: WString.h:891
String(int num, unsigned char base=10, unsigned char width=0, char pad='0')
Definition: WString.h:195
void replace(char find, char replace)
int indexOf(char ch, size_t fromIndex=0) const
void trim(const char *set=" \t\n\v\f\r")
Remove all leading and trailing characters from the String.
void toCharArray(char *buf, size_t bufsize, size_t index=0) const
Read contents of String into a buffer.
Definition: WString.h:607
bool startsWith(const String &prefix) const
Compare the start of a String Comparison is case-sensitive, must match exactly.
Definition: WString.h:531
String & operator=(const String &rhs)
char charAt(size_t index) const
Obtain the character at the given index.
Definition: WString.h:569
void move(String &rhs)
float toFloat(void) const
friend StringSumHelper & operator+(const StringSumHelper &lhs, const String &rhs)
size_t length(void) const
Obtain the String length in characters, excluding NUL terminator.
Definition: WString.h:243
size_t getBytes(unsigned char *buf, size_t bufsize, size_t index=0) const
Read contents of a String into a buffer.
char operator[](size_t index) const
const __FlashStringHelper * flash_string_t
Provides a strongly-typed pointer to allow safe implicit operation using String class methods.
Definition: WString.h:96
bool setBuffer(const Buffer &buffer)
Set String content using move semantics from external memory buffer.
String & padRight(uint16_t minWidth, char c=' ')
Insert padding at end of string if length is less than given width.
Definition: WString.h:796