WString.h

/*
 WString.h - String library for Wiring & Arduino
 ...mostly rewritten by Paul Stoffregen...
 Copyright (c) 2009-10 Hernando Barragan. All right reserved.
 Copyright 2011, Paul Stoffregen, paul@pjrc.com

 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 Lesser General Public License for more details.

 You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/

#ifndef String_class_h
#defineString_class_h
#ifdef __cplusplus

#include<pgmspace.h>

#include<stdlib.h>
#include<stdint.h>
#include<string.h>
#include<ctype.h>

// A pure abstract class forward used as a means to proide a unique pointer type
// but really is never defined.
class__FlashStringHelper;
#defineFPSTR(str_pointer) (reinterpret_cast<const __FlashStringHelper *>(str_pointer))
#defineF(string_literal) (FPSTR(PSTR(string_literal)))

// An inherited class for holding the result of a concatenation. These
// result objects are assumed to be writable by subsequent concatenations.
classStringSumHelper;

// The string class
classString {
// use a function pointer to allow for "if (s)" without the
// complications of an operator bool(). for more information, see:
// http://www.artima.com/cppsource/safebool.html
typedefvoid (String::*StringIfHelperType)() const;
voidStringIfHelper() const {}

public:
// constructors
// creates a copy of the initial value.
// 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(constchar *cstr = "");
String(constchar *cstr, unsignedint length);
#ifdef __GXX_EXPERIMENTAL_CXX0X__
String(constuint8_t *cstr, unsignedint length) : String(reinterpret_cast<constchar *>(cstr), length) {}
#endif
String(const String &str);
String(const __FlashStringHelper *str) : String(reinterpret_cast<constchar *>(str)) {}
#ifdef __GXX_EXPERIMENTAL_CXX0X__
String(String &&rval);
String(StringSumHelper &&rval);
#endif
explicitString(char c);
explicitString(unsignedchar, unsignedchar base = 10);
explicitString(int, unsignedchar base = 10);
explicitString(unsignedint, unsignedchar base = 10);
explicitString(long, unsignedchar base = 10);
explicitString(unsignedlong, unsignedchar base = 10);
explicitString(float, unsignedint decimalPlaces = 2);
explicitString(double, unsignedint decimalPlaces = 2);
explicitString(longlong, unsignedchar base = 10);
explicitString(unsignedlonglong, unsignedchar base = 10);
~String(void);

// memory management
// return true on success, false on failure (in which case, the string
// is left unchanged). reserve(0), if successful, will validate an
// invalid string (i.e., "if (s)" will be true afterwards)
boolreserve(unsignedint size);
inlineunsignedintlength(void) const {
if (buffer()) {
returnlen();
 } else {
return0;
 }
 }
inlinevoidclear(void) {
setLen(0);
 }
inlineboolisEmpty(void) const {
returnlength() == 0;
 }

// creates a copy of the assigned value. 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=(constchar *cstr);
 String &operator=(const __FlashStringHelper *str) {
return *this = reinterpret_cast<constchar *>(str);
 }
#ifdef __GXX_EXPERIMENTAL_CXX0X__
 String &operator=(String &&rval);
 String &operator=(StringSumHelper &&rval);
#endif

// concatenate (works w/ built-in types, same as assignment)

// returns true on success, false on failure (in which case, the string
// is left unchanged). if the argument is null or invalid, the
// concatenation is considered unsuccessful.
boolconcat(const String &str);
boolconcat(constchar *cstr);
boolconcat(constchar *cstr, unsignedint length);
boolconcat(constuint8_t *cstr, unsignedint length) {
returnconcat(reinterpret_cast<constchar *>(cstr), length);
 }
boolconcat(char c);
boolconcat(unsignedchar c);
boolconcat(int num);
boolconcat(unsignedint num);
boolconcat(long num);
boolconcat(unsignedlong num);
boolconcat(float num);
boolconcat(double num);
boolconcat(longlong num);
boolconcat(unsignedlonglong num);
boolconcat(const __FlashStringHelper *str) {
returnconcat(reinterpret_cast<constchar *>(str));
 }

// if there's not enough memory for the concatenated value, the string
// will be left unchanged (but this isn't signaled in any way)
 String &operator+=(const String &rhs) {
concat(rhs);
return (*this);
 }
 String &operator+=(constchar *cstr) {
concat(cstr);
return (*this);
 }
 String &operator+=(char c) {
concat(c);
return (*this);
 }
 String &operator+=(unsignedchar num) {
concat(num);
return (*this);
 }
 String &operator+=(int num) {
concat(num);
return (*this);
 }
 String &operator+=(unsignedint num) {
concat(num);
return (*this);
 }
 String &operator+=(long num) {
concat(num);
return (*this);
 }
 String &operator+=(unsignedlong num) {
concat(num);
return (*this);
 }
 String &operator+=(float num) {
concat(num);
return (*this);
 }
 String &operator+=(double num) {
concat(num);
return (*this);
 }
 String &operator+=(longlong num) {
concat(num);
return (*this);
 }
 String &operator+=(unsignedlonglong num) {
concat(num);
return (*this);
 }
 String &operator+=(const __FlashStringHelper *str) {
return *this += reinterpret_cast<constchar *>(str);
 }

friend StringSumHelper &operator+(const StringSumHelper &lhs, const String &rhs);
friend StringSumHelper &operator+(const StringSumHelper &lhs, constchar *cstr);
friend StringSumHelper &operator+(const StringSumHelper &lhs, char c);
friend StringSumHelper &operator+(const StringSumHelper &lhs, unsignedchar num);
friend StringSumHelper &operator+(const StringSumHelper &lhs, int num);
friend StringSumHelper &operator+(const StringSumHelper &lhs, unsignedint num);
friend StringSumHelper &operator+(const StringSumHelper &lhs, long num);
friend StringSumHelper &operator+(const StringSumHelper &lhs, unsignedlong num);
friend StringSumHelper &operator+(const StringSumHelper &lhs, float num);
friend StringSumHelper &operator+(const StringSumHelper &lhs, double num);
friend StringSumHelper &operator+(const StringSumHelper &lhs, longlong num);
friend StringSumHelper &operator+(const StringSumHelper &lhs, unsignedlonglong num);

// comparison (only works w/ Strings and "strings")
operatorStringIfHelperType() const {
returnbuffer() ? &String::StringIfHelper : 0;
 }
intcompareTo(const String &s) const;
boolequals(const String &s) const;
boolequals(constchar *cstr) const;
booloperator==(const String &rhs) const {
returnequals(rhs);
 }
booloperator==(constchar *cstr) const {
returnequals(cstr);
 }
booloperator!=(const String &rhs) const {
return !equals(rhs);
 }
booloperator!=(constchar *cstr) const {
return !equals(cstr);
 }
booloperator<(const String &rhs) const;
booloperator>(const String &rhs) const;
booloperator<=(const String &rhs) const;
booloperator>=(const String &rhs) const;
boolequalsIgnoreCase(const String &s) const;
unsignedcharequalsConstantTime(const String &s) const;
boolstartsWith(const String &prefix) const;
boolstartsWith(constchar *prefix) const {
returnthis->startsWith(String(prefix));
 }
boolstartsWith(const __FlashStringHelper *prefix) const {
returnthis->startsWith(reinterpret_cast<constchar *>(prefix));
 }
boolstartsWith(const String &prefix, unsignedint offset) const;
boolendsWith(const String &suffix) const;
boolendsWith(constchar *suffix) const {
returnthis->endsWith(String(suffix));
 }
boolendsWith(const __FlashStringHelper *suffix) const {
returnthis->endsWith(reinterpret_cast<constchar *>(suffix));
 }

// character access
charcharAt(unsignedint index) const;
voidsetCharAt(unsignedint index, char c);
charoperator[](unsignedint index) const;
char &operator[](unsignedint index);
voidgetBytes(unsignedchar *buf, unsignedint bufsize, unsignedint index = 0) const;
voidtoCharArray(char *buf, unsignedint bufsize, unsignedint index = 0) const {
getBytes((unsignedchar *)buf, bufsize, index);
 }
constchar *c_str() const {
returnbuffer();
 }
char *begin() {
returnwbuffer();
 }
char *end() {
returnwbuffer() + length();
 }
constchar *begin() const {
returnc_str();
 }
constchar *end() const {
returnc_str() + length();
 }

// search
intindexOf(char ch) const;
intindexOf(char ch, unsignedint fromIndex) const;
intindexOf(const String &str) const;
intindexOf(const String &str, unsignedint fromIndex) const;
intlastIndexOf(char ch) const;
intlastIndexOf(char ch, unsignedint fromIndex) const;
intlastIndexOf(const String &str) const;
intlastIndexOf(const String &str, unsignedint fromIndex) const;
 String substring(unsignedint beginIndex) const {
returnsubstring(beginIndex, len());
 }
 String substring(unsignedint beginIndex, unsignedint endIndex) const;

// modification
voidreplace(char find, char replace);
voidreplace(const String &find, const String &replace);
voidreplace(constchar *find, const String &replace) {
this->replace(String(find), replace);
 }
voidreplace(const __FlashStringHelper *find, const String &replace) {
this->replace(reinterpret_cast<constchar *>(find), replace);
 }
voidreplace(constchar *find, constchar *replace) {
this->replace(String(find), String(replace));
 }
voidreplace(const __FlashStringHelper *find, constchar *replace) {
this->replace(reinterpret_cast<constchar *>(find), String(replace));
 }
voidreplace(const __FlashStringHelper *find, const __FlashStringHelper *replace) {
this->replace(reinterpret_cast<constchar *>(find), reinterpret_cast<constchar *>(replace));
 }
voidremove(unsignedint index);
voidremove(unsignedint index, unsignedint count);
voidtoLowerCase(void);
voidtoUpperCase(void);
voidtrim(void);

// parsing/conversion
longtoInt(void) const;
floattoFloat(void) const;
doubletoDouble(void) const;

protected:
// Contains the string info when we're not in SSO mode
struct_ptr {
char *buff;
uint32_t cap;
uint32_t len;
 };
// This allows strings up up to 11 (10 + \0 termination) without any extra space.
enum {
 SSOSIZE = sizeof(struct_ptr) + 4 - 1
 }; // Characters to allocate space for SSO, must be 12 or more
struct_sso {
char buff[SSOSIZE];
unsignedchar len : 7; // Ensure only one byte is allocated by GCC for the bitfields
unsignedchar isSSO : 1;
 } __attribute__((packed)); // Ensure that GCC doesn't expand the flag byte to a 32-bit word for alignment issues
#ifdef BOARD_HAS_PSRAM
enum {
 CAPACITY_MAX = 3145728
 };
#else
enum {
 CAPACITY_MAX = 65535
 };
#endif
union {
struct_ptr ptr;
struct_sso sso;
 };
// Accessor functions
inlineboolisSSO() const {
return sso.isSSO;
 }
inlineunsignedintlen() const {
returnisSSO() ? sso.len : ptr.len;
 }
inlineunsignedintcapacity() const {
returnisSSO() ? (unsignedint)SSOSIZE - 1 : ptr.cap;
 } // Size of max string not including terminal NUL
inlinevoidsetSSO(bool set) {
 sso.isSSO = set;
 }
inlinevoidsetLen(int len) {
if (isSSO()) {
 sso.len = len;
 sso.buff[len] = 0;
 } else {
 ptr.len = len;
if (ptr.buff) {
 ptr.buff[len] = 0;
 }
 }
 }
inlinevoidsetCapacity(int cap) {
if (!isSSO()) {
 ptr.cap = cap;
 }
 }
inlinevoidsetBuffer(char *buff) {
if (!isSSO()) {
 ptr.buff = buff;
 }
 }
// Buffer accessor functions
inlineconstchar *buffer() const {
returnreinterpret_cast<constchar *>(isSSO() ? sso.buff : ptr.buff);
 }
inlinechar *wbuffer() const {
returnisSSO() ? const_cast<char *>(sso.buff) : ptr.buff;
 } // Writable version of buffer

protected:
voidinit(void);
voidinvalidate(void);
boolchangeBuffer(unsignedint maxStrLen);

// copy and move
 String &copy(constchar *cstr, unsignedint length);
 String &copy(const __FlashStringHelper *pstr, unsignedint length) {
returncopy(reinterpret_cast<constchar *>(pstr), length);
 }
#ifdef __GXX_EXPERIMENTAL_CXX0X__
voidmove(String &rhs);
#endif
};

classStringSumHelper : publicString {
public:
StringSumHelper(const String &s) : String(s) {}
StringSumHelper(constchar *p) : String(p) {}
StringSumHelper(char c) : String(c) {}
StringSumHelper(unsignedchar num) : String(num) {}
StringSumHelper(int num) : String(num) {}
StringSumHelper(unsignedint num) : String(num) {}
StringSumHelper(long num) : String(num) {}
StringSumHelper(unsignedlong num) : String(num) {}
StringSumHelper(float num) : String(num) {}
StringSumHelper(double num) : String(num) {}
StringSumHelper(longlong num) : String(num) {}
StringSumHelper(unsignedlonglong num) : String(num) {}
};

inline StringSumHelper &operator+(const StringSumHelper &lhs, const __FlashStringHelper *rhs) {
return lhs + reinterpret_cast<constchar *>(rhs);
}

externconst String emptyString;

#endif// __cplusplus
#endif// String_class_h