To create SafeStrings use one of the four (4) macros createSafeString or cSF, createSafeStringFromCharArray or cSFA, createSafeStringFromCharPtr or cSFP, createSafeStringFromCharPtrWithSize or cSFPS see the detailed description. More...

#include <SafeString.h>

Inherits Printable, and Print.

Inherited by SafeStringReader, and SerialComs.

Classes
class	DebugPrint

class	noDebugPrint

Public Member Functions
	SafeString (unsigned int maxLen, char buf, const char cstr, const char *_name=NULL, bool _fromBuffer=false, bool _fromPtr=true)
	SafeString Constructor called from the four (4) macros createSafeString or cSF, createSafeStringFromCharArray or cSFA, createSafeStringFromCharPtr or cSFP, createSafeStringFromCharPtrWithSize or cSFPS. More...

unsigned char	hasError ()
	Returns non-zero if any error detected for this SafeString, each call clears the internal flag. More...

const char *	debug (bool verbose=true)
	Output the details about the this SafeString to the output specified by setOutput(). More...

const char *	debug (const char *title, bool verbose=true)
	Output the details about the this SafeString to the output specified by setOutput(). More...

const char *	debug (const __FlashStringHelper *title, bool verbose=true)
	Output the details about the this SafeString to the output specified by setOutput(). More...

const char *	debug (SafeString &stitle, bool verbose=true)
	Output the details about the this SafeString to the output specified by setOutput(). More...

virtual size_t	write (uint8_t b)
	Write (concatinate) a byte to this SafeString, from Print class. More...

virtual size_t	write (const uint8_t *buffer, size_t length)
	Write (concatinate) bytes to this SafeString, from Print class. More...

size_t	printTo (Print &p) const
	Implements the Printable interface. More...

unsigned char	reserve (unsigned int size)
	Checks there is enough free space in this SafeString for the current operation. More...

unsigned int	length (void)
	Number of characters current in the SafeString, excluding the terminating '\0'. More...

unsigned int	capacity (void)
	The maximum number of characters this SafeString can hold, excluding the terminating '\0'. More...

unsigned char	isFull (void)
	Returns non-zero if the SafeString is full. More...

unsigned char	isEmpty (void)
	Returns non-zero if the SafeString is empty. More...

int	availableForWrite (void)
	Returns the number chars that can be added to this SafeString before it is full. More...

SafeString &	clear (void)
	Empties this SafeString. More...

size_t	print (unsigned char, int=DEC)

size_t	print (int, int=DEC)

size_t	print (unsigned int, int=DEC)

size_t	print (long, int=DEC)

size_t	print (unsigned long, int=DEC)

size_t	print (double, int=2)

size_t	print (const __FlashStringHelper *)

size_t	print (const char *)

size_t	print (char)

size_t	print (SafeString &str)

size_t	println (unsigned char, int=DEC)

size_t	println (int, int=DEC)

size_t	println (unsigned int, int=DEC)

size_t	println (long, int=DEC)

size_t	println (unsigned long, int=DEC)

size_t	println (double, int=2)

size_t	println (const __FlashStringHelper *)

size_t	println (const char *)

size_t	println (char)

size_t	println (SafeString &str)

size_t	println (void)

size_t	println (double d, int decs, int width, bool forceSign=false)
	Prints a double (or long/int) to this SafeString padded with spaces (left or right) and limited to the specified width and adds a trailing CR NL. More...

size_t	print (double d, int decs, int width, bool forceSign=false)
	Prints a double (or long/int) to this SafeString padded with spaces (left or right) and limited to the specified width. More...

SafeString &	operator= (char c)
	Clears this SafeString and concatinates a single char. More...

SafeString &	operator= (unsigned char num)
	Clears this SafeString and concatinates the text version of the argument. More...

SafeString &	operator= (int num)
	Clears this SafeString and concatinates the text version of the argument. More...

SafeString &	operator= (unsigned int num)
	Clears this SafeString and concatinates the text version of the argument. More...

SafeString &	operator= (long num)
	Clears this SafeString and concatinates the text version of the argument. More...

SafeString &	operator= (unsigned long num)
	Clears this SafeString and concatinates the text version of the argument. More...

SafeString &	operator= (float num)
	Clears this SafeString and concatinates the text version of the argument. More...

SafeString &	operator= (double num)
	Clears this SafeString and concatinates the text version of the argument. More...

SafeString &	operator= (SafeString &sfStr)
	Clears this SafeString and copies and concatinates the contents of the argument. More...

SafeString &	operator= (const char *cstr)
	Clears this SafeString and copies and concatinates the contents of the argument. More...

SafeString &	operator= (const __FlashStringHelper *pstr)
	Clears this SafeString and copies and concatinates the contents of the argument. More...

SafeString &	prefix (SafeString &s)
	prefix methods add to the front of the current SafeString. More...

SafeString &	prefix (const char *cstr)

SafeString &	prefix (char c)

SafeString &	prefix (unsigned char c)

SafeString &	prefix (int num)

SafeString &	prefix (unsigned int num)

SafeString &	prefix (long num)

SafeString &	prefix (unsigned long num)

SafeString &	prefix (float num)

SafeString &	prefix (double num)

SafeString &	prefix (const __FlashStringHelper *str)

SafeString &	prefix (const char *cstr, size_t length)

SafeString &	prefix (const __FlashStringHelper *str, size_t length)

SafeString &	concat (SafeString &str)
	concat methods add to the end of the current SafeString. More...

SafeString &	concat (const char *cstr)

SafeString &	concat (char c)

SafeString &	concat (unsigned char c)

SafeString &	concat (int num)

SafeString &	concat (unsigned int num)

SafeString &	concat (long num)

SafeString &	concat (unsigned long num)

SafeString &	concat (float num)

SafeString &	concat (double num)

SafeString &	concat (const __FlashStringHelper *str)

SafeString &	concat (const char *cstr, size_t length)

SafeString &	concat (const __FlashStringHelper *str, size_t length)

SafeString &	newline ()
	Adds \r\n to this SafeString. More...

SafeString &	operator-= (SafeString &rhs)
	-= operator prefixes the SafeString. More...

SafeString &	operator-= (const char *cstr)

SafeString &	operator-= (char c)

SafeString &	operator-= (unsigned char num)

SafeString &	operator-= (int num)

SafeString &	operator-= (unsigned int num)

SafeString &	operator-= (long num)

SafeString &	operator-= (unsigned long num)

SafeString &	operator-= (float num)

SafeString &	operator-= (double num)

SafeString &	operator-= (const __FlashStringHelper *str)

SafeString &	operator+= (SafeString &rhs)
	+= operator concatinate to the SafeString. More...

SafeString &	operator+= (const char *cstr)

SafeString &	operator+= (char c)

SafeString &	operator+= (unsigned char num)

SafeString &	operator+= (int num)

SafeString &	operator+= (unsigned int num)

SafeString &	operator+= (long num)

SafeString &	operator+= (unsigned long num)

SafeString &	operator+= (float num)

SafeString &	operator+= (double num)

SafeString &	operator+= (const __FlashStringHelper *str)

int	compareTo (SafeString &s)
	returns -1 if this SafeString is < s, 0 if this SafeString == s and +1 if this SafeString > s More...

int	compareTo (const char *cstr)
	returns -1 if this SafeString is < cstr, 0 if this SafeString == cstr and +1 if this SafeString > cst More...

unsigned char	equals (SafeString &s)

unsigned char	equals (const char *cstr)

unsigned char	equals (const char c)

unsigned char	operator== (SafeString &rhs)

unsigned char	operator== (const char *cstr)

unsigned char	operator== (const char c)

unsigned char	operator!= (SafeString &rhs)

unsigned char	operator!= (const char *cstr)

unsigned char	operator!= (const char c)

unsigned char	operator< (SafeString &rhs)

unsigned char	operator> (SafeString &rhs)

unsigned char	operator<= (SafeString &rhs)

unsigned char	operator>= (SafeString &rhs)

unsigned char	operator< (const char *rhs)

unsigned char	operator> (const char *rhs)

unsigned char	operator<= (const char *rhs)

unsigned char	operator>= (const char *rhs)

unsigned char	equalsIgnoreCase (SafeString &s)

unsigned char	equalsIgnoreCase (const char *str2)

unsigned char	equalsConstantTime (SafeString &s)

unsigned char	startsWith (const char c, unsigned int fromIndex=0)
	returns non-zero of this SafeString starts this argument looking from fromIndex onwards. More...

unsigned char	startsWith (const char *str2, unsigned int fromIndex=0)
	returns non-zero of this SafeString starts this argument looking from fromIndex onwards. More...

unsigned char	startsWith (SafeString &s2, unsigned int fromIndex=0)
	returns non-zero of this SafeString starts this argument looking from fromIndex onwards. More...

unsigned char	startsWithIgnoreCase (const char c, unsigned int fromIndex=0)
	returns non-zero of this SafeString starts this argument, ignoring case, looking from fromIndex onwards. More...

unsigned char	startsWithIgnoreCase (const char *str2, unsigned int fromIndex=0)
	returns non-zero of this SafeString starts this argument, ignoring case, looking from fromIndex onwards. More...

unsigned char	startsWithIgnoreCase (SafeString &s2, unsigned int fromIndex=0)
	returns non-zero of this SafeString starts this argument, ignoring case, looking from fromIndex onwards. More...

unsigned char	endsWith (const char c)
	returns non-zero of this SafeString ends with the argument More...

unsigned char	endsWith (SafeString &suffix)
	returns non-zero of this SafeString ends with the argument More...

unsigned char	endsWith (const char *suffix)
	returns non-zero of this SafeString ends with the argument More...

unsigned char	endsWithCharFrom (SafeString &suffix)
	returns non-zero of this SafeString ends any one of the chars in the argument More...

unsigned char	endsWithCharFrom (const char *suffix)
	returns non-zero of this SafeString ends any one of the chars in the argument More...

char	charAt (unsigned int index)
	returns the char at that location in this SafeString. More...

char	operator[] (unsigned int index)
	returns the char at that location in this SafeString. More...

void	setCharAt (unsigned int index, char c)
	sets the char at that location in this SafeString. More...

const char *	c_str ()
	returns a const char* to the underlying char[ ] in this SafeString. More...

int	indexOf (char ch, unsigned int fromIndex=0)
	returns the index of the char, searching from fromIndex. More...

int	indexOf (const char *str, unsigned int fromIndex=0)
	returns the index of the string, searching from fromIndex. More...

int	indexOf (SafeString &str, unsigned int fromIndex=0)
	returns the index of the SafeString, searching from fromIndex. More...

int	lastIndexOf (char ch)
	returns the last index of the char, searching backwards from fromIndex (inclusive). More...

int	lastIndexOf (char ch, unsigned int fromIndex)
	returns the last index of the char, searching backwards from fromIndex (inclusive). More...

int	lastIndexOf (SafeString &str)
	returns the last index of the arguement, searching backwards from fromIndex (inclusive). More...

int	lastIndexOf (SafeString &str, unsigned int fromIndex)
	returns the last index of the char, searching backwards from fromIndex (inclusive). More...

int	lastIndexOf (const char *cstr)
	returns the last index of the arguement, searching backwards from fromIndex (inclusive). More...

int	lastIndexOf (const char *cstr, unsigned int fromIndex)
	returns the last index of the char, searching backwards from fromIndex (inclusive). More...

int	indexOfCharFrom (SafeString &str, unsigned int fromIndex=0)
	returns the first index of any char from the argument. More...

int	indexOfCharFrom (const char *chars, unsigned int fromIndex=0)
	returns the first index of any char from the argument More...

SafeString &	substring (SafeString &result, unsigned int beginIdx)
	The result is the substring from the beginIdx to the end of the SafeString. More...

SafeString &	substring (SafeString &result, unsigned int beginIdx, unsigned int endIdx)
	The result is the substring from the beginIdx to endIdx (exclusive), that is the endIdx is NOT included. More...

void	replace (char findChar, char replaceChar)
	replace the findChar with the replaceChar More...

void	replace (const char findChar, const char *replaceStr)
	replace the findChar with the replace string More...

void	replace (const char findChar, SafeString &sfReplace)
	replace the findChar with the sfReplace SafeString contents More...

void	replace (const char findStr, const char replaceStr)
	replace the findStr string with the replace string More...

void	replace (SafeString &sfFind, SafeString &sfReplace)
	replace the occurances of the sfFind string, with the sfReplace SafeString contents More...

void	removeFrom (unsigned int startIndex)
	remove all chars from startIndex to the end of the SafeString (inclusive) More...

void	removeBefore (unsigned int startIndex)
	remove all chars from 0 to startIndex (exclusive), that is the char at startIndex is NOT removed More...

void	remove (unsigned int index)
	remove all chars from index to the end of the SafeString (inclusive) More...

void	remove (unsigned int index, unsigned int count)
	remove count chars starting from index More...

void	removeLast (unsigned int count)
	remove the last count chars More...

void	keepLast (unsigned int count)
	keep the last count chars and remove the rest More...

void	toLowerCase (void)
	convert this SafeString to all lower case More...

void	toUpperCase (void)
	convert this SafeString to all lower case More...

void	trim (void)
	remove all white space from the front and back of this SafeString. More...

void	processBackspaces (void)
	recursively remove backspaces, '\b' and the preceeding char. More...

unsigned char	toInt (int &i)
	convert the SafeString to an int. More...

unsigned char	toLong (long &l)
	convert the SafeString to a long. More...

unsigned char	binToLong (long &l)
	convert the SafeString to a long assuming the SafeString in binary (0/1). More...

unsigned char	octToLong (long &l)
	convert the SafeString to a long assuming the SafeString in octal (0 to 7). More...

unsigned char	hexToLong (long &l)
	convert the SafeString to a long assuming the SafeString in HEX (0 to f or 0 to F). More...

unsigned char	toUnsignedLong (unsigned long &l)
	convert the SafeString to an unsigned long. More...

unsigned char	binToUnsignedLong (unsigned long &l)
	convert the SafeString to an unsigned long assuming the SafeString in binary (0/1). More...

unsigned char	octToUnsignedLong (unsigned long &l)
	convert the SafeString to an unsigned long assuming the SafeString in octal (0 to 7). More...

unsigned char	hexToUnsignedLong (unsigned long &l)
	convert the SafeString to an unsigned long assuming the SafeString in HEX (0 to f or 0 to F). More...

unsigned char	toFloat (float &f)
	convert the SafeString to a float assuming the SafeString in the decimal format (not scientific) More...

unsigned char	toDouble (double &d)
	convert the SafeString to a float assuming the SafeString in the decimal format (not scientific) More...

int	stoken (SafeString &token, unsigned int fromIndex, const char delimiter, bool returnEmptyFields=false, bool useAsDelimiters=true)
	break into the SafeString into tokens using the char delimiter, the end of the SafeString is always a delimiter More...

int	stoken (SafeString &token, unsigned int fromIndex, const char *delimiters, bool returnEmptyFields=false, bool useAsDelimiters=true)
	break into the SafeString into tokens using the delimiters, the end of the SafeString is always a delimiter More...

int	stoken (SafeString &token, unsigned int fromIndex, SafeString &delimiters, bool returnEmptyFields=false, bool useAsDelimiters=true)
	break into the SafeString into tokens using the delimiters, the end of the SafeString is always a delimiter More...

unsigned char	firstToken (SafeString &token, char delimiter, bool returnLastNonDelimitedToken=true)
	returns true if a delimited token is found, removes the first delimited token from this SafeString and returns it in the token argument by default a leading delimiter is stepped over before scanning for a delimited token when nextToken() is called this firstToken() method overrides this and returns true and an empty token if the first char is a delimiter More...

unsigned char	nextToken (SafeString &token, char delimiter, bool returnEmptyFields=false, bool returnLastNonDelimitedToken=true, bool firstToken=false)
	returns true if a delimited token is found, removes the first delimited token from this SafeString and returns it in the token argument by default a leading delimiter is stepped over before scanning for a delimited token, the firstToken argument can override this setting the firstToken arguemnent = true, suppresses this so that an empty first token can be returned if the first char is a delimiter AND if returnEmptyFields is true More...

unsigned char	firstToken (SafeString &token, SafeString delimiters, bool returnLastNonDelimitedToken=true)
	returns true if a delimited token is found, removes the first delimited token from this SafeString and returns it in the token argument by default a leading delimiter is stepped over before scanning for a delimited token when nextToken() is called this firstToken() method overrides this and returns true and an empty token if the first char is a delimiter More...

unsigned char	nextToken (SafeString &token, SafeString &delimiters, bool returnEmptyFields=false, bool returnLastNonDelimitedToken=true, bool firstToken=false)
	returns true if a delimited token is found, removes the first delimited token from this SafeString and returns it in the token argument by default a leading delimiter is stepped over before scanning for a delimited token, the firstToken argument can override this setting the firstToken arguemnent = true, suppresses this so that an empty first token can be returned if the first char is a delimiter AND if returnEmptyFields is true More...

unsigned char	firstToken (SafeString &token, const char *delimiters, bool returnLastNonDelimitedToken=true)
	returns true if a delimited token is found, removes the first delimited token from this SafeString and returns it in the token argument by default a leading delimiter is stepped over before scanning for a delimited token when nextToken() is called this firstToken() method overrides this and returns true and an empty token if the first char is a delimiter More...

unsigned char	nextToken (SafeString &token, const char *delimiters, bool returnEmptyFields=false, bool returnLastNonDelimitedToken=true, bool firstToken=false)
	returns true if a delimited token is found, removes the first delimited token from this SafeString and returns it in the token argument by default a leading delimiter is stepped over before scanning for a delimited token, the firstToken argument can override this setting the firstToken arguemnent = true, suppresses this so that an empty first token can be returned if the first char is a delimiter AND if returnEmptyFields is true More...

unsigned int	readFrom (SafeString &sfInput, unsigned int startIdx=0)
	reads from the SafeString argument, starting at startIdx, into this SafeString. More...

unsigned int	readFrom (const char *strPtr, unsigned int maxCharsToRead=((unsigned int) -1))
	reads from the const char* argument, starting at 0 and read up to maxCharToRead, into this SafeString. More...

unsigned int	writeTo (SafeString &output, unsigned int startIdx=0)
	writes from this SafeString, starting from startIdx, into the SafeString output arguement. More...

unsigned char	read (Stream &input)
	reads from the Stream (if chars available) into the SafeString. More...

unsigned char	readUntil (Stream &input, const char delimiter)
	reads chars into this SafeString until either it is full OR a delimiter is read OR there are no more chars available returns true if a delimiter found or SafeString is full, else false if a delimiter is found it is returned at the end of the SafeString Only at most one delimiter is added per call Multiple sucessive delimiters require multiple calls to read them More...

unsigned char	readUntil (Stream &input, const char *delimiters)
	reads chars into this SafeString until either it is full OR a delimiter is read OR there are no more chars available returns true if a delimiter found or SafeString is full, else false if a delimiter is found it is returned at the end of the SafeString Only at most one delimiter is added per call Multiple sucessive delimiters require multiple calls to read them More...

unsigned char	readUntil (Stream &input, SafeString &delimiters)
	reads chars into this SafeString until either it is full OR a delimiter is read OR there are no more chars available returns true if a delimiter found or SafeString is full, else false if a delimiter is found it is returned at the end of the SafeString Only at most one delimiter is added per call Multiple sucessive delimiters require multiple calls to read them More...

unsigned char	readUntilToken (Stream &input, SafeString &token, const char delimiter, bool &skipToDelimiter, uint8_t echoInput=false, unsigned long timeout_ms=0)
	returns true if a delimited token is found, else false ONLY delimited tokens of length less than this SafeString's capacity will return true with a non-empty token. More...

unsigned char	readUntilToken (Stream &input, SafeString &token, const char *delimiters, bool &skipToDelimiter, uint8_t echoInput=false, unsigned long timeout_ms=0)
	returns true if a delimited token is found, else false ONLY delimited tokens of length less than this SafeString's capacity will return true with a non-empty token. More...

unsigned char	readUntilToken (Stream &input, SafeString &token, SafeString &delimiters, bool &skipToDelimiter, uint8_t echoInput=false, unsigned long timeout_ms=0)
	returns true if a delimited token is found, else false ONLY delimited tokens of length less than this SafeString's capacity will return true with a non-empty token. More...

size_t	getLastReadCount ()
	returns the number of chars read on previous calls to read, readUntil or readUntilToken (includes '\0' read if any). More...

Static Public Member Functions
static void	setOutput (Print &debugOut, bool verbose=true)
	Turns on Error msgs and debug( ) output for all SafeStrings. More...

static void	turnOutputOff (void)
	Turns off all debugging messages, both error messages AND debug() method output. More...

static void	setVerbose (bool verbose)
	Controls size of error messages, setOutput sets verbose to true. More...

static unsigned char	errorDetected ()
	Returns non-zero if any SafeString has detected and error, each call clears the internal global static flag. More...

Static Public Attributes
static SafeString::DebugPrint	Output

Protected Member Functions
SafeString &	concatln (const __FlashStringHelper *pstr)

SafeString &	concatln (char c)

SafeString &	concatln (const char *cstr, size_t length)

void	outputName () const

SafeString &	concatInternal (const char *cstr, size_t length, bool assignOp=false)

SafeString &	concatInternal (const __FlashStringHelper *str, size_t length, bool assignOp=false)

SafeString &	concatInternal (const char *cstr, bool assignOp=false)

SafeString &	concatInternal (char c, bool assignOp=false)

SafeString &	concatInternal (const __FlashStringHelper *str, bool assignOp=false)

size_t	printInternal (long, int=DEC, bool assignOp=false)

size_t	printInternal (unsigned long, int=DEC, bool assignOp=false)

size_t	printInternal (double, int=2, bool assignOp=false)

void	setError ()

void	printlnErr () const

void	debugInternalMsg (bool _fullDebug) const

size_t	limitedStrLen (const char *p, size_t limit)

size_t	printInt (double d, int decs, int width, bool forceSign, bool addNL)

Protected Attributes
char *	buffer

size_t	_capacity

size_t	len

Static Protected Attributes
static Print *	debugPtr

static bool	fullDebug

static SafeString::noDebugPrint	emptyPrint

static Print *	currentOutput

Detailed Description

To create SafeStrings use one of the four (4) macros createSafeString or cSF, createSafeStringFromCharArray or cSFA, createSafeStringFromCharPtr or cSFP, createSafeStringFromCharPtrWithSize or cSFPS see the detailed description.

There are four (4) macros used to create SafeStrings.
createSafeString(name, size); creates a char[size+1] for you and wraps it in a SafeString called name.
createSafeStringFromCharArray(name, char[]); wraps an existing char[] in a SafeString called name.
createSafeStringFromCharPtr(name, char*); wraps an existing char[], pointed to by char*, in a SafeString called name. The capacity of the SafeString is limited to the initial strlen(char*) and cannot be increased
createSafeStringFromCharPtrWithSize(name, char*, size); wraps an existing char[size], pointed to by char*, in a SafeString called name.

Each of thise macros has a short hand
cSF(name,size) for createSafeString(name, size);
cSFA(name,char[]) for createSafeStringFromCharArray(name, char[]);
cSFP(name,char*) for createSafeStringFromCharPtr(name, char*);
cSFPS(name,char*,size) for createSafeStringFromCharPtrWithSize(name, char*, size);

createSafeString and cSF

createSafeString(name, size) or cSF(name,size)
and
createSafeString(name, size, "initialText") or cSF(name,size,"initialText")
are utility macros to create a SafeString of a given name and size and optionally, an initial value

createSafeString(str, 40); or cSF(str, 40); expands in the pre-processor to
char str_SAFEBUFFER[40+1];
SafeString str(sizeof(str_SAFEBUFFER),str_SAFEBUFFER,"","str");

createSafeString(str, 40, "test"); or cSF(str, 40, "test"); expands in the pre-processor to
char str_SAFEBUFFER[40+1];
SafeString str(sizeof(str_SAFEBUFFER),str_SAFEBUFFER,"test","str");

createSafeStringFromCharArray and cSFA

createSafeStringFromCharArray(name, char[]); or cSFA(name, char[]); wraps an existing char[] in a SafeString of the given name. e.g.
char charBuffer[15];
createSafeStringFromCharArray(str,charBuffer); or cSFA(str,charBuffer);
expands in the pre-processor to
SafeString str(sizeof(charBuffer),charBuffer, charBuffer, "str", true);
The capacity of the SafeString is set to 14, from the sizeof(charBuffer)-1 to allow for the terminating '\0'.

createSafeStringFromCharPtr and cSFP

createSafeStringFromCharPtr(name, char*); or cSFP(name, char*); wraps an existing char[] pointed to by char* in a SafeString of the given name
The capacity of the SafeString is set to strlen(charBuffer) and cannot be increased. e.g.
char charBuffer[15] = "1234567890";
char *bufPtr = charBuffer;
createSafeStringFromCharPtr(str,bufPtr); or cSFP(str,bufPtr);
expands in the pre-processor to
SafeString str((unsigned int)-1,charBuffer, charBuffer, "str", true);
The capacity of the SafeString is set to 10, from the strlen(bufPtr)

createSafeStringFromCharPtrWithSize and cSFPS

createSafeStringFromCharPtrWithSize(name, char*, unsigned int size); or cSFPS(name, char*, unsigned int size); wraps an existing char[], pointed to by char*, in a SafeString of the given name
and sets the capacity to the given unsigned int size e.g.
char charBuffer[15]="1234567890";
char *bufPtr = charBuffer;
createSafeStringFromCharPtrWithSize(str,bufPtr, 15); or cSFPS(str,bufPtr, 15);
expands in the pre-processor to
SafeString str(15,charBuffer, charBuffer, "str", true);
The capacity of the SafeString is set to 14 from size-1 to allow for the terminating '\0'.

See The SafeString alternative to Arduino Strings for Beginners for a tutorial.

Also see the example sketches included with the library
SafeString_ConstructorAndDebugging.ino, SafeStringFromCharArray.ino, SafeStringFromCharPtr.ino and SafeStringFromCharPtrWithSize.ino

Definition at line 307 of file SafeString.h.

Constructor & Destructor Documentation

◆ SafeString()

SafeString::SafeString	(	unsigned int	maxLen,
		char *	buf,
		const char *	cstr,
		const char *	_name = `NULL`,
		bool	_fromBuffer = `false`,
		bool	_fromPtr = `true`
	)

explicit

SafeString Constructor called from the four (4) macros createSafeString or cSF, createSafeStringFromCharArray or cSFA, createSafeStringFromCharPtr or cSFP, createSafeStringFromCharPtrWithSize or cSFPS.

This constructor is not designed to called directly by your code. See the detailed SafeString class description above.

Parameters

maxLen	- the number of chars that can stored not including the terminating '\0'
buf	- the fixed sized char buffer to hold the data
cstr	- the initial data to be loaded into this SafeString
_name	- the code variable name of this SafeString, default NULL
_fromBuffer	- true if this SafeString is wrapping an existing char[]
_fromPtr	- true if this SafeString's buf parameter was a char* rather then a char[], _fromPtr is not checked unless _fromBuffer is true

Member Function Documentation

◆ availableForWrite()

int SafeString::availableForWrite ( void )

Returns the number chars that can be added to this SafeString before it is full.

◆ binToLong()

unsigned char SafeString::binToLong ( long & l )

convert the SafeString to a long assuming the SafeString in binary (0/1).

Parameters

l	– long reference, where the result is stored. l is only updated if the conversion is successful

Returns: – 0 if the SafeString is not a valid int, else return non-zero
leading and trailing white space is allowed around a valid int

◆ binToUnsignedLong()

unsigned char SafeString::binToUnsignedLong ( unsigned long & l )

convert the SafeString to an unsigned long assuming the SafeString in binary (0/1).

Parameters

l	– unsigned long reference, where the result is stored. l is only updated if the conversion is successful

Returns: – 0 if the SafeString is not a valid int, else return non-zero
leading and trailing white space is allowed around a valid int

◆ c_str()

const char* SafeString::c_str ( )

returns a const char* to the underlying char[ ] in this SafeString.

Do not make changes this char[ ]

◆ capacity()

unsigned int SafeString::capacity ( void )

The maximum number of characters this SafeString can hold, excluding the terminating '\0'.

◆ charAt()

char SafeString::charAt ( unsigned int index )

returns the char at that location in this SafeString.

Parameters

index - the zero based index of the char to return.

Returns: the char at that index OR if index >= length() return 0 and raise error

◆ clear()

SafeString& SafeString::clear ( void )

Empties this SafeString.

returns the current SafeString so you can cascade calls e.g.
sfStr.clear().concat("New output");

◆ compareTo() [1/2]

int SafeString::compareTo ( const char * cstr )

returns -1 if this SafeString is < cstr, 0 if this SafeString == cstr and +1 if this SafeString > cst

◆ compareTo() [2/2]

int SafeString::compareTo ( SafeString & s )

returns -1 if this SafeString is < s, 0 if this SafeString == s and +1 if this SafeString > s

◆ concat() [1/13]

SafeString& SafeString::concat ( char c )

◆ concat() [2/13]

SafeString& SafeString::concat ( const __FlashStringHelper * str )

◆ concat() [3/13]

SafeString& SafeString::concat	(	const __FlashStringHelper *	str,
		size_t	length
	)

◆ concat() [4/13]

SafeString& SafeString::concat ( const char * cstr )

◆ concat() [5/13]

SafeString& SafeString::concat	(	const char *	cstr,
		size_t	length
	)

◆ concat() [6/13]

SafeString& SafeString::concat ( double num )

◆ concat() [7/13]

SafeString& SafeString::concat ( float num )

◆ concat() [8/13]

SafeString& SafeString::concat ( int num )

◆ concat() [9/13]

SafeString& SafeString::concat ( long num )

◆ concat() [10/13]

SafeString& SafeString::concat ( SafeString & str )

concat methods add to the end of the current SafeString.

returns the current SafeString so you can cascade calls e.g.
sfStr.concat(1).concat("second");
If there's not enough memory for the concatenated value, the SafeString will be left unchanged.
If the argument is null or invalid, the concatenation is considered unsucessful.

◆ concat() [11/13]

SafeString& SafeString::concat ( unsigned char c )

◆ concat() [12/13]

SafeString& SafeString::concat ( unsigned int num )

◆ concat() [13/13]

SafeString& SafeString::concat ( unsigned long num )

◆ concatInternal() [1/5]

SafeString& SafeString::concatInternal	(	char	c,
		bool	assignOp = `false`
	)

protected

◆ concatInternal() [2/5]

SafeString& SafeString::concatInternal	(	const __FlashStringHelper *	str,
		bool	assignOp = `false`
	)

protected

◆ concatInternal() [3/5]

SafeString& SafeString::concatInternal	(	const __FlashStringHelper *	str,
		size_t	length,
		bool	assignOp = `false`
	)

protected

◆ concatInternal() [4/5]

SafeString& SafeString::concatInternal	(	const char *	cstr,
		bool	assignOp = `false`
	)

protected

◆ concatInternal() [5/5]

SafeString& SafeString::concatInternal	(	const char *	cstr,
		size_t	length,
		bool	assignOp = `false`
	)

protected

◆ concatln() [1/3]

SafeString& SafeString::concatln ( char c )

protected

◆ concatln() [2/3]

SafeString& SafeString::concatln ( const __FlashStringHelper * pstr )

protected

◆ concatln() [3/3]

SafeString& SafeString::concatln	(	const char *	cstr,
		size_t	length
	)

protected

◆ debug() [1/4]

const char* SafeString::debug ( bool verbose = true )

Output the details about the this SafeString to the output specified by setOutput().

Parameters

verbose - true for detailed output including current contents

◆ debug() [2/4]

const char* SafeString::debug	(	const __FlashStringHelper *	title,
		bool	verbose = `true`
	)

Output the details about the this SafeString to the output specified by setOutput().

Parameters

title	- the title to preceed the debug output, a space between this and the debug output
verbose	- true for detailed output including current contents

◆ debug() [3/4]

const char* SafeString::debug	(	const char *	title,
		bool	verbose = `true`
	)

Output the details about the this SafeString to the output specified by setOutput().

Parameters

title	- the title to preceed the debug output, a space between this and the debug output
verbose	- true for detailed output including current contents

◆ debug() [4/4]

const char* SafeString::debug	(	SafeString &	stitle,
		bool	verbose = `true`
	)

Output the details about the this SafeString to the output specified by setOutput().

Parameters

title	- the title to preceed the debug output, a space between this and the debug output
verbose	- true for detailed output including current contents

◆ debugInternalMsg()

void SafeString::debugInternalMsg ( bool _fullDebug ) const

protected

◆ endsWith() [1/3]

unsigned char SafeString::endsWith ( const char * suffix )

returns non-zero of this SafeString ends with the argument

Parameters

suffix – string to check for

◆ endsWith() [2/3]

unsigned char SafeString::endsWith ( const char c )

returns non-zero of this SafeString ends with the argument

Parameters

c	– the char to check for

◆ endsWith() [3/3]

unsigned char SafeString::endsWith ( SafeString & suffix )

returns non-zero of this SafeString ends with the argument

Parameters

suffix – SafeString to check for

◆ endsWithCharFrom() [1/2]

unsigned char SafeString::endsWithCharFrom ( const char * suffix )

returns non-zero of this SafeString ends any one of the chars in the argument

Parameters

suffix – the string containing the chars to check for

◆ endsWithCharFrom() [2/2]

unsigned char SafeString::endsWithCharFrom ( SafeString & suffix )

returns non-zero of this SafeString ends any one of the chars in the argument

Parameters

suffix – the SafeString containing the chars to check for

◆ equals() [1/3]

unsigned char SafeString::equals ( const char * cstr )

◆ equals() [2/3]

unsigned char SafeString::equals ( const char c )

◆ equals() [3/3]

unsigned char SafeString::equals ( SafeString & s )

◆ equalsConstantTime()

unsigned char SafeString::equalsConstantTime ( SafeString & s )

◆ equalsIgnoreCase() [1/2]

unsigned char SafeString::equalsIgnoreCase ( const char * str2 )

◆ equalsIgnoreCase() [2/2]

unsigned char SafeString::equalsIgnoreCase ( SafeString & s )

◆ errorDetected()

static unsigned char SafeString::errorDetected ( )

static

Returns non-zero if any SafeString has detected and error, each call clears the internal global static flag.

◆ firstToken() [1/3]

unsigned char SafeString::firstToken	(	SafeString &	token,
		char	delimiter,
		bool	returnLastNonDelimitedToken = `true`
	)

inline

returns true if a delimited token is found, removes the first delimited token from this SafeString and returns it in the token argument
by default a leading delimiter is stepped over before scanning for a delimited token when nextToken() is called
this firstToken() method overrides this and returns true and an empty token if the first char is a delimiter

The delimiter is not returned and remains in the SafeString so you can test which delimiter terminated the token, provided this SafeString is not empty!
The token argument is always cleared at the start of the nexttToken().
IMPORTANT!! Changed V4.0.4 Now by default un-delimited tokens at the end of the SafeString are returned
To leave partial un-delimited tokens on the end of the SafeString, set returnLastNonDelimitedToken = false.
Setting returnLastNonDelimitedToken = false allows the SafeString to hold partial tokens when reading from an input stream one char at a time.

Parameters

token	- the SafeString to return the token in, it is always cleared first and will be empty if no delimited token is found or if there are errors The token's capacity should be >= this SafeString's capacity incase the entire SafeString needs to be returned. If the token's capacity is < the next token, then nextToken() returns true, but the returned token argument is empty and an error messages printed if debug is enabled. In this case to next token is still removed from the SafeString so that the program will not be stuck in an infinite loop calling nextToken()
delimiter	- the char which can delimit a token
returnLastNonDelimitedToken	– default true, will return last part of SafeString even if not delimited. If set false, will keep it for further input to be added to this SafeString NOTE: since the last delimiter is left in the SafeString, you should only use firstToken() for the first call.

Returns: – true if firstToken() finds a token in this SafeString that is terminated by one of the delimiters, else false
If the return is true, but hasError() is true then the SafeString token argument did not have the capacity to hold the next token.
in this case to next token is still removed from the SafeString so that the program will not be stuck in an infinite loop calling nextToken()
while being consistent with the SafeString's all or nothing insertion rule
Input argument errors return false and an empty token and hasError() is set on both this SafeString and the token SafeString.

Definition at line 1528 of file SafeString.h.

◆ firstToken() [2/3]

unsigned char SafeString::firstToken	(	SafeString &	token,
		const char *	delimiters,
		bool	returnLastNonDelimitedToken = `true`
	)

inline

returns true if a delimited token is found, removes the first delimited token from this SafeString and returns it in the token argument
by default a leading delimiter is stepped over before scanning for a delimited token when nextToken() is called
this firstToken() method overrides this and returns true and an empty token if the first char is a delimiter

The delimiter is not returned and remains in the SafeString so you can test which delimiter terminated the token, provided this SafeString is not empty!
The token argument is always cleared at the start of the nexttToken().
IMPORTANT!! Changed V4.0.4 Now by default un-delimited tokens at the end of the SafeString are returned
To leave partial un-delimited tokens on the end of the SafeString, set returnLastNonDelimitedToken = false.
Setting returnLastNonDelimitedToken = false allows the SafeString to hold partial tokens when reading from an input stream one char at a time.

Parameters

token	- the SafeString to return the token in, it is always cleared first and will be empty if no delimited token is found or if there are errors The token's capacity should be >= this SafeString's capacity incase the entire SafeString needs to be returned. If the token's capacity is < the next token, then firstToken() returns true, but the returned token argument is empty and an error messages printed if debug is enabled. In this case to next token is still removed from the SafeString so that the program will not be stuck in an infinite loop calling nextToken()
delimiters	- the string containing the delimiting characters, any one of which can delimit a token
returnLastNonDelimitedToken	– default true, will return last part of SafeString even if not delimited. If set false, will keep it for further input to be added to this SafeString NOTE: since the last delimiter is left in the SafeString, you should only use firstToken() for the first call.

Returns: – true if firstToken() finds a token in this SafeString that is terminated by one of the delimiters, else false
If the return is true, but hasError() is true then the SafeString token argument did not have the capacity to hold the next token.
in this case to next token is still removed from the SafeString so that the program will not be stuck in an infinite loop calling nextToken()
while being consistent with the SafeString's all or nothing insertion rule
Input argument errors return false and an empty token and hasError() is set on both this SafeString and the token SafeString.

Definition at line 1650 of file SafeString.h.

◆ firstToken() [3/3]

unsigned char SafeString::firstToken	(	SafeString &	token,
		SafeString	delimiters,
		bool	returnLastNonDelimitedToken = `true`
	)

inline

returns true if a delimited token is found, removes the first delimited token from this SafeString and returns it in the token argument
by default a leading delimiter is stepped over before scanning for a delimited token when nextToken() is called
this firstToken() method overrides this and returns true and an empty token if the first char is a delimiter

The delimiter is not returned and remains in the SafeString so you can test which delimiter terminated the token, provided this SafeString is not empty!
The token argument is always cleared at the start of the nexttToken().
IMPORTANT!! Changed V4.0.4 Now by default un-delimited tokens at the end of the SafeString are returned
To leave partial un-delimited tokens on the end of the SafeString, set returnLastNonDelimitedToken = false.
Setting returnLastNonDelimitedToken = false allows the SafeString to hold partial tokens when reading from an input stream one char at a time.

Parameters

token	- the SafeString to return the token in, it is always cleared first and will be empty if no delimited token is found or if there are errors The token's capacity should be >= this SafeString's capacity incase the entire SafeString needs to be returned. If the token's capacity is < the next token, then nextToken() returns true, but the returned token argument is empty and an error messages printed if debug is enabled. In this case to next token is still removed from the SafeString so that the program will not be stuck in an infinite loop calling nextToken()
delimiters	- the SafeString containing the delimiting characters, any one of which can delimit a token
returnLastNonDelimitedToken	– default true, will return last part of SafeString even if not delimited. If set false, will keep it for further input to be added to this SafeString NOTE: since the last delimiter is left in the SafeString, you should only use firstToken() for the first call.

Returns: – true if firstToken() finds a token in this SafeString that is terminated by one of the delimiters, else false
If the return is true, but hasError() is true then the SafeString token argument did not have the capacity to hold the next token.
in this case to next token is still removed from the SafeString so that the program will not be stuck in an infinite loop calling nextToken()
while being consistent with the SafeString's all or nothing insertion rule
Input argument errors return false and an empty token and hasError() is set on both this SafeString and the token SafeString.

Definition at line 1589 of file SafeString.h.

◆ getLastReadCount()

size_t SafeString::getLastReadCount ( )

returns the number of chars read on previous calls to read, readUntil or readUntilToken (includes '\0' read if any).

Each call read, readUntil, readUntilToken first clears this count

Returns: - the char count read since the last call to this method.

◆ hasError()

unsigned char SafeString::hasError ( )

Returns non-zero if any error detected for this SafeString, each call clears the internal flag.

◆ hexToLong()

unsigned char SafeString::hexToLong ( long & l )

convert the SafeString to a long assuming the SafeString in HEX (0 to f or 0 to F).

Parameters

l	– long reference, where the result is stored. l is only updated if the conversion is successful

Returns: – 0 if the SafeString is not a valid int, else return non-zero
leading and trailing white space is allowed around a valid int

◆ hexToUnsignedLong()

unsigned char SafeString::hexToUnsignedLong ( unsigned long & l )

convert the SafeString to an unsigned long assuming the SafeString in HEX (0 to f or 0 to F).

Parameters

l	– unsigned long reference, where the result is stored. l is only updated if the conversion is successful

Returns: – 0 if the SafeString is not a valid int, else return non-zero
leading and trailing white space is allowed around a valid int

◆ indexOf() [1/3]

int SafeString::indexOf	(	char	ch,
		unsigned int	fromIndex = `0`
	)

returns the index of the char, searching from fromIndex.

Parameters

ch	- the char to search for
fromIndex	- where to start the search from, default 0, that is from begining if fromIndex > length() raise an error if fromIndex == -1 OR fromIndex == length(), return -1 without error

Returns: -1 if not found, else the index in the range 0 to length()-1

◆ indexOf() [2/3]

int SafeString::indexOf	(	const char *	str,
		unsigned int	fromIndex = `0`
	)

returns the index of the string, searching from fromIndex.

Parameters

str	- the string to search for
fromIndex	- where to start the search from, default 0, that is from begining if fromIndex > length() raise an error if fromIndex == -1 OR fromIndex == length(), return -1 without error

Returns: -1 if not found, else the index in the range 0 to length()-1

◆ indexOf() [3/3]

int SafeString::indexOf	(	SafeString &	str,
		unsigned int	fromIndex = `0`
	)

returns the index of the SafeString, searching from fromIndex.

Parameters

str	- the SafeString to search for
fromIndex	- where to start the search from, default 0, that is from begining if fromIndex > length() raise an error if fromIndex == -1 OR fromIndex == length(), return -1 without error

Returns: -1 if not found, else the index in the range 0 to length()-1

◆ indexOfCharFrom() [1/2]

int SafeString::indexOfCharFrom	(	const char *	chars,
		unsigned int	fromIndex = `0`
	)

returns the first index of any char from the argument

Parameters

chars	- the string containing the chars to search for
fromIndex	- where to start searching backwards from, if fromIndex > length() raise an error if fromIndex == -1 OR fromIndex == length(), return -1 without error

Returns: -1 if not found, else the index in the range 0 to length()-1

◆ indexOfCharFrom() [2/2]

int SafeString::indexOfCharFrom	(	SafeString &	str,
		unsigned int	fromIndex = `0`
	)

returns the first index of any char from the argument.

Parameters

str	- the SafeString containing the chars to search for
fromIndex	- where to start searching from, if fromIndex > length() raise an error if fromIndex == -1 OR fromIndex == length(), return -1 without error

Returns: -1 if not found, else the index in the range 0 to length()-1

◆ isEmpty()

unsigned char SafeString::isEmpty ( void )

Returns non-zero if the SafeString is empty.

◆ isFull()

unsigned char SafeString::isFull ( void )

Returns non-zero if the SafeString is full.

◆ keepLast()

void SafeString::keepLast ( unsigned int count )

keep the last count chars and remove the rest

Parameters

count - the number of chars to keep
0 to length() is valid for count
count == 0 clears the SafeString
count > length() raises and error and leaves the SafeString unchanged

◆ lastIndexOf() [1/6]

int SafeString::lastIndexOf ( char ch )

returns the last index of the char, searching backwards from fromIndex (inclusive).

Parameters

c	- the char to search for

Returns: -1 if not found, else the index in the range 0 to length()-1

◆ lastIndexOf() [2/6]

int SafeString::lastIndexOf	(	char	ch,
		unsigned int	fromIndex
	)

returns the last index of the char, searching backwards from fromIndex (inclusive).

Parameters

c	- the char to search for
fromIndex	- where to start searching backwards from, if fromIndex > length() raise an error if fromIndex == -1 OR fromIndex == length(), return -1 without error

Returns: -1 if not found, else the index in the range 0 to length()-1

◆ lastIndexOf() [3/6]

int SafeString::lastIndexOf ( const char * cstr )

returns the last index of the arguement, searching backwards from fromIndex (inclusive).

Parameters

cstr	- the string to search for

Returns: -1 if not found, else the index in the range 0 to length()-1

◆ lastIndexOf() [4/6]

int SafeString::lastIndexOf	(	const char *	cstr,
		unsigned int	fromIndex
	)

returns the last index of the char, searching backwards from fromIndex (inclusive).

Parameters

cstr	- the string to search for
fromIndex	- where to start searching backwards from, if fromIndex > length() raise an error if fromIndex == -1 OR fromIndex == length(), return -1 without error

Returns: -1 if not found, else the index in the range 0 to length()-1

◆ lastIndexOf() [5/6]

int SafeString::lastIndexOf ( SafeString & str )

returns the last index of the arguement, searching backwards from fromIndex (inclusive).

Parameters

str	- the SafeString to search for

Returns: -1 if not found, else the index in the range 0 to length()-1

◆ lastIndexOf() [6/6]

int SafeString::lastIndexOf	(	SafeString &	str,
		unsigned int	fromIndex
	)

returns the last index of the char, searching backwards from fromIndex (inclusive).

Parameters

str	- the SafeString to search for
fromIndex	- where to start searching backwards from, if fromIndex > length() raise an error if fromIndex == -1 OR fromIndex == length(), return -1 without error

Returns: -1 if not found, else the index in the range 0 to length()-1

◆ length()

unsigned int SafeString::length ( void )

Number of characters current in the SafeString, excluding the terminating '\0'.

◆ limitedStrLen()

size_t SafeString::limitedStrLen	(	const char *	p,
		size_t	limit
	)

protected

◆ newline()

SafeString& SafeString::newline ( )

Adds \r\n to this SafeString.

returns the current SafeString so you can cascade calls e.g.
sfStr.newline().concat("next line");

◆ nextToken() [1/3]

unsigned char SafeString::nextToken	(	SafeString &	token,
		char	delimiter,
		bool	returnEmptyFields = `false`,
		bool	returnLastNonDelimitedToken = `true`,
		bool	firstToken = `false`
	)

returns true if a delimited token is found, removes the first delimited token from this SafeString and returns it in the token argument
by default a leading delimiter is stepped over before scanning for a delimited token, the firstToken argument can override this
setting the firstToken arguemnent = true, suppresses this so that an empty first token can be returned if the first char is a delimiter AND if returnEmptyFields is true

The delimiter is not returned and remains in the SafeString so you can test which delimiter terminated the token, provided this SafeString is not empty!
The token argument is always cleared at the start of the nexttToken().
IMPORTANT!! Changed V4.0.4 Now by default un-delimited tokens at the end of the SafeString are returned
To leave partial un-delimited tokens on the end of the SafeString, set returnLastNonDelimitedToken = false.
Setting returnLastNonDelimitedToken = false allows the SafeString to hold partial tokens when reading from an input stream one char at a time.
Setting firstToken = true suppressed skipping over a leading delimiter so that an empty first field can be returned if the first char is a delimiter

Parameters

token	- the SafeString to return the token in, it is always cleared first and will be empty if no delimited token is found or if there are errors The token's capacity should be >= this SafeString's capacity incase the entire SafeString needs to be returned. If the token's capacity is < the next token, then firstToken() returns true, but the returned token argument is empty and an error messages printed if debug is enabled. In this case to next token is still removed from the SafeString so that the program will not be stuck in an infinite loop calling nextToken()
delimiter	- the char which can delimit a token
returnEmptyFields	– default false, if true, nextToken() will return true, and an empty token for each consecutive delimiters
returnLastNonDelimitedToken	– default true, will return last part of SafeString even if not delimited. If set false, will keep it for further input to be added to this SafeString
firstToken	– default false, a leading delimiter will be stepped over before looking for a delimited token if set to true, a leading delimiter will delimit an empty token which will be returned only if returnEmptyFields is true otherwise it is skipped over. NOTE: if returnEmptyFields == false this firstToken argument has no effect. NOTE: since the last delimiter is left in the SafeString, you must set firstToken to be false (or omit it) after the first call.

Returns: – true if nextToken() finds a token in this SafeString that is terminated by one of the delimiters, else false
If the return is true, but hasError() is true then the SafeString token argument did not have the capacity to hold the next token.
in this case to next token is still removed from the SafeString so that the program will not be stuck in an infinite loop calling nextToken()
while being consistent with the SafeString's all or nothing insertion rule
Input argument errors return false and an empty token and hasError() is set on both this SafeString and the token SafeString.

◆ nextToken() [2/3]

unsigned char SafeString::nextToken	(	SafeString &	token,
		const char *	delimiters,
		bool	returnEmptyFields = `false`,
		bool	returnLastNonDelimitedToken = `true`,
		bool	firstToken = `false`
	)

returns true if a delimited token is found, removes the first delimited token from this SafeString and returns it in the token argument
by default a leading delimiter is stepped over before scanning for a delimited token, the firstToken argument can override this
setting the firstToken arguemnent = true, suppresses this so that an empty first token can be returned if the first char is a delimiter AND if returnEmptyFields is true

The delimiter is not returned and remains in the SafeString so you can test which delimiter terminated the token, provided this SafeString is not empty!
The token argument is always cleared at the start of the nexttToken().
IMPORTANT!! Changed V4.0.4 Now by default un-delimited tokens at the end of the SafeString are returned
To leave partial un-delimited tokens on the end of the SafeString, set returnLastNonDelimitedToken = false.
Setting returnLastNonDelimitedToken = false allows the SafeString to hold partial tokens when reading from an input stream one char at a time.
Setting firstToken = true suppressed skipping over a leading delimiter so that an empty first field can be returned if the first char is a delimiter

Parameters

token	- the SafeString to return the token in, it is always cleared first and will be empty if no delimited token is found or if there are errors The token's capacity should be >= this SafeString's capacity incase the entire SafeString needs to be returned. If the token's capacity is < the next token, then nextToken() returns true, but the returned token argument is empty and an error messages printed if debug is enabled. In this case to next token is still removed from the SafeString so that the program will not be stuck in an infinite loop calling nextToken()
delimiters	- the string containing the delimiting characters, any one of which can delimit a token
returnEmptyFields	– default false, if true, nextToken() will return true, and an empty token for each consecutive delimiters
returnLastNonDelimitedToken	– default true, will return last part of SafeString even if not delimited. If set false, will keep it for further input to be added to this SafeString
firstToken	– default false, a leading delimiter will be stepped over before looking for a delimited token if set to true, a leading delimiter will delimit an empty token which will be returned only if returnEmptyFields is true otherwise it is skipped over. NOTE: if returnEmptyFields == false this firstToken argument has no effect. NOTE: since the last delimiter is left in the SafeString, you must set firstToken to be false (or omit it) after the first call.

Returns: – true if nextToken() finds a token in this SafeString that is terminated by one of the delimiters, else false
If the return is true, but hasError() is true then the SafeString token argument did not have the capacity to hold the next token.
in this case to next token is still removed from the SafeString so that the program will not be stuck in an infinite loop calling nextToken()
while being consistent with the SafeString's all or nothing insertion rule
Input argument errors return false and an empty token and hasError() is set on both this SafeString and the token SafeString.

◆ nextToken() [3/3]

unsigned char SafeString::nextToken	(	SafeString &	token,
		SafeString &	delimiters,
		bool	returnEmptyFields = `false`,
		bool	returnLastNonDelimitedToken = `true`,
		bool	firstToken = `false`
	)

returns true if a delimited token is found, removes the first delimited token from this SafeString and returns it in the token argument
by default a leading delimiter is stepped over before scanning for a delimited token, the firstToken argument can override this
setting the firstToken arguemnent = true, suppresses this so that an empty first token can be returned if the first char is a delimiter AND if returnEmptyFields is true

The delimiter is not returned and remains in the SafeString so you can test which delimiter terminated the token, provided this SafeString is not empty!
The token argument is always cleared at the start of the nexttToken().
IMPORTANT!! Changed V4.0.4 Now by default un-delimited tokens at the end of the SafeString are returned
To leave partial un-delimited tokens on the end of the SafeString, set returnLastNonDelimitedToken = false.
Setting returnLastNonDelimitedToken = false allows the SafeString to hold partial tokens when reading from an input stream one char at a time.
Setting firstToken = true suppressed skipping over a leading delimiter so that an empty first field can be returned if the first char is a delimiter

Parameters

token	- the SafeString to return the token in, it is always cleared first and will be empty if no delimited token is found or if there are errors The token's capacity should be >= this SafeString's capacity incase the entire SafeString needs to be returned. If the token's capacity is < the next token, then firstToken() returns true, but the returned token argument is empty and an error messages printed if debug is enabled. In this case to next token is still removed from the SafeString so that the program will not be stuck in an infinite loop calling nextToken()
delimiters	- the SafeString containing the delimiting characters, any one of which can delimit a token
returnEmptyFields	– default false, if true, nextToken() will return true, and an empty token for each consecutive delimiters
returnLastNonDelimitedToken	– default true, will return last part of SafeString even if not delimited. If set false, will keep it for further input to be added to this SafeString
firstToken	– default false, a leading delimiter will be stepped over before looking for a delimited token if set to true, a leading delimiter will delimit an empty token which will be returned only if returnEmptyFields is true otherwise it is skipped over. NOTE: if returnEmptyFields == false this firstToken argument has no effect. NOTE: since the last delimiter is left in the SafeString, you must set firstToken to be false (or omit it) after the first call.

Returns: – true if nextToken() finds a token in this SafeString that is terminated by one of the delimiters, else false
If the return is true, but hasError() is true then the SafeString token argument did not have the capacity to hold the next token.
in this case to next token is still removed from the SafeString so that the program will not be stuck in an infinite loop calling nextToken()
while being consistent with the SafeString's all or nothing insertion rule
Input argument errors return false and an empty token and hasError() is set on both this SafeString and the token SafeString.

◆ octToLong()

unsigned char SafeString::octToLong ( long & l )

convert the SafeString to a long assuming the SafeString in octal (0 to 7).

Parameters

l	– long reference, where the result is stored. l is only updated if the conversion is successful

Returns: – 0 if the SafeString is not a valid int, else return non-zero
leading and trailing white space is allowed around a valid int

◆ octToUnsignedLong()

unsigned char SafeString::octToUnsignedLong ( unsigned long & l )

convert the SafeString to an unsigned long assuming the SafeString in octal (0 to 7).

Parameters

l	– unsigned long reference, where the result is stored. l is only updated if the conversion is successful

Returns: – 0 if the SafeString is not a valid int, else return non-zero
leading and trailing white space is allowed around a valid int

◆ operator!=() [1/3]

unsigned char SafeString::operator!= ( const char * cstr )

inline

Definition at line 828 of file SafeString.h.

◆ operator!=() [2/3]

unsigned char SafeString::operator!= ( const char c )

inline

Definition at line 831 of file SafeString.h.

◆ operator!=() [3/3]

unsigned char SafeString::operator!= ( SafeString & rhs )

inline

Definition at line 825 of file SafeString.h.

◆ operator+=() [1/11]

SafeString& SafeString::operator+= ( char c )

inline

Definition at line 771 of file SafeString.h.

◆ operator+=() [2/11]

SafeString& SafeString::operator+= ( const __FlashStringHelper * str )

inline

Definition at line 795 of file SafeString.h.

◆ operator+=() [3/11]

SafeString& SafeString::operator+= ( const char * cstr )

inline

Definition at line 768 of file SafeString.h.

◆ operator+=() [4/11]

SafeString& SafeString::operator+= ( double num )

inline

Definition at line 792 of file SafeString.h.

◆ operator+=() [5/11]

SafeString& SafeString::operator+= ( float num )

inline

Definition at line 789 of file SafeString.h.

◆ operator+=() [6/11]

SafeString& SafeString::operator+= ( int num )

inline

Definition at line 777 of file SafeString.h.

◆ operator+=() [7/11]

SafeString& SafeString::operator+= ( long num )

inline

Definition at line 783 of file SafeString.h.

◆ operator+=() [8/11]

SafeString& SafeString::operator+= ( SafeString & rhs )

inline

+= operator concatinate to the SafeString.

e.g.
sfStr += "end";
gives the same SafeString as
sfStr.concat("end");

Definition at line 765 of file SafeString.h.

◆ operator+=() [9/11]

SafeString& SafeString::operator+= ( unsigned char num )

inline

Definition at line 774 of file SafeString.h.

◆ operator+=() [10/11]

SafeString& SafeString::operator+= ( unsigned int num )

inline

Definition at line 780 of file SafeString.h.

◆ operator+=() [11/11]

SafeString& SafeString::operator+= ( unsigned long num )

inline

Definition at line 786 of file SafeString.h.

◆ operator-=() [1/11]

SafeString& SafeString::operator-= ( char c )

inline

Definition at line 724 of file SafeString.h.

◆ operator-=() [2/11]

SafeString& SafeString::operator-= ( const __FlashStringHelper * str )

inline

Definition at line 748 of file SafeString.h.

◆ operator-=() [3/11]

SafeString& SafeString::operator-= ( const char * cstr )

inline

Definition at line 721 of file SafeString.h.

◆ operator-=() [4/11]

SafeString& SafeString::operator-= ( double num )

inline

Definition at line 745 of file SafeString.h.

◆ operator-=() [5/11]

SafeString& SafeString::operator-= ( float num )

inline

Definition at line 742 of file SafeString.h.

◆ operator-=() [6/11]

SafeString& SafeString::operator-= ( int num )

inline

Definition at line 730 of file SafeString.h.

◆ operator-=() [7/11]

SafeString& SafeString::operator-= ( long num )

inline

Definition at line 736 of file SafeString.h.

◆ operator-=() [8/11]

SafeString& SafeString::operator-= ( SafeString & rhs )

inline

-= operator prefixes the SafeString.

e.g.
sfStr -= "top";
gives the same SafeString as
sfStr.prefix("top");

Definition at line 718 of file SafeString.h.

◆ operator-=() [9/11]

SafeString& SafeString::operator-= ( unsigned char num )

inline

Definition at line 727 of file SafeString.h.

◆ operator-=() [10/11]

SafeString& SafeString::operator-= ( unsigned int num )

inline

Definition at line 733 of file SafeString.h.

◆ operator-=() [11/11]

SafeString& SafeString::operator-= ( unsigned long num )

inline

Definition at line 739 of file SafeString.h.

◆ operator<() [1/2]

unsigned char SafeString::operator< ( const char * rhs )

inline

Definition at line 846 of file SafeString.h.

◆ operator<() [2/2]

unsigned char SafeString::operator< ( SafeString & rhs )

inline

Definition at line 834 of file SafeString.h.

◆ operator<=() [1/2]

unsigned char SafeString::operator<= ( const char * rhs )

inline

Definition at line 852 of file SafeString.h.

◆ operator<=() [2/2]

unsigned char SafeString::operator<= ( SafeString & rhs )

inline

Definition at line 840 of file SafeString.h.