Cpl::Text Namespace Reference

The Text namespace provides yet-another String class and additional string and/or text processing utilities. More...

Detailed Description

The Text namespace provides yet-another String class and additional string and/or text processing utilities.

What makes the Cpl::Text::String classes different from other String classes is that it supports a ZERO dynamic memory allocation interface and implementation. There is also a dynamic memory implementation of the String interface for when strict memory management is not required.

Namespaces
namespace	Encoding
	The 'Encoding' namespace provides various encoding algorithms for converting binary data to (and from) ASCII text to facilitate transport of the binary data using text based protocols.
namespace	Frame
	The Frame namespace provides interfaces for encoding and decoding text frames.
namespace	Tokenizer
	The Tokenizer namespace provides interfaces for tokenizing strings.

Classes
class	DFString
	This concrete class is a mix of FString and a DString - the initial memory is dynamically allocated - but no additional memory allocation will occur after the instance is created, i.e. More...
class	DFStringItem
	This concrete class implements the StringItem class for a 'String' using a 'DFString' as the internal storage for String instance. More...
class	DString
	This concrete class implements a simple "dynamic storage" String Type. More...
class	DStringItem
	This concrete class implements the StringItem class for a 'String' using a 'DString' as the internal storage for String instance. More...
class	FString
	This template class represents a NULL terminated string of a specific length. More...
class	FString_
	This mostly concrete class implements a "fixed storage" String Type. More...
class	FStringItem
	This template class implements the StringItem class for a 'String' using a 'FString' as the internal storage for String instance. More...
class	String
	This abstract class defines the operations that can be before on a NULL terminated string. More...
class	String_
	This partially concrete class implements the portions of the String Api that is independent of the internal storage mechanisms. More...
class	StringItem
	This partially concrete provides a wrapper class that allows a String object to be stored directly in one the CPL Containers. More...

Functions
bool	a2i (int &convertedValue, const char *string, int base=10, const char *validStopChars=0, const char **endptr=0)
	This method converts the specified string to an integer.
bool	a2ui (unsigned &convertedValue, const char *string, int base=10, const char *validStopChars=0, const char **endptr=0)
	This method is the same as a2i() except that it converts unsigned integer.
bool	a2l (long &convertedValue, const char *string, int base=10, const char *validStopChars=0, const char **endptr=0)
	This method is the same as a2i() except that it converts long integer.
bool	a2ul (unsigned long &convertedValue, const char *string, int base=10, const char *validStopChars=0, const char **endptr=0)
	This method is the same as a2i() except that it converts unsigned long integer.
bool	a2ll (long long &convertedValue, const char *string, int base=10, const char *validStopChars=0, const char **endptr=0)
	This method is the same as a2i() except that it converts long long integer.
bool	a2ull (unsigned long long &convertedValue, const char *string, int base=10, const char *validStopChars=0, const char **endptr=0)
	This method is the same as a2i() except that it converts unsigned long long integer.
bool	a2d (double &convertedValue, const char *string, const char *validStopChars=0, const char **endptr=0)
	This method converts the specified string to an double.
bool	a2b (bool &convertedValue, const char *string, const char *trueToken="T", const char *falseToken="F", const char **endptr=0)
	This method convert the specified string to an boolean.
long	asciiHexToBuffer (void *dstBinary, const char *srcString, size_t dstMaxLen)
	This method will convert an 'ASCII HEX' string to an equivalent binary buffer, i.e.
long	asciiBinaryToBuffer (void *dstBinary, const char *srcString, size_t dstMaxLen, bool reverse=false)
	This method will convert an 'ASCII BINARY' string to an equivalent binary buffer, i.e.
bool	parsePrecisionTimeStamp (const char *timeStampToParse, Cpl::System::ElapsedTime::Precision_T &convertedValue)
	This method parses a 'timestamp' with the following format: [DD ]HH:MM:SS[.sss] The method returns true if the parse was successful.
const char *	longToStr (long num, char *dstString, size_t maxChars, unsigned base=10, char padChar=' ')
	This method converts a long to a string.
const char *	ulongToStr (unsigned long num, char *dstString, size_t maxChars, unsigned base=10, char padChar=' ')
	This method is same as longToStr(), except it converts a unsigned long value.
const char *	sizetToStr (size_t num, char *dstString, size_t maxChars, unsigned base=10, char padChar=' ')
	This method is same as longToStr(), except it converts a size_t value.
bool	bufferToString (const void *buffer, int len, Cpl::Text::String &destString, bool appendToString=false)
	This method will take a raw data buffer and convert it to an 'viewable' string.
bool	bufferToAsciiHex (const void *binaryData, int len, Cpl::Text::String &destString, bool upperCase=true, bool appendToString=false, char separator='\0')
	This method will convert a binary buffer to 'ASCII HEX', e.g.
bool	bufferToAsciiBinary (const void *binaryData, int len, Cpl::Text::String &destString, bool appendToString=false, bool reverse=false)
	This method converts the binary buffer to a single string that is ASCII BINARY.
bool	bufferToViewer (const void *binaryData, int len, Cpl::Text::String &destString, int bytesPerLine=16, const char *separator=" ", bool upperCase=true, bool appendToString=false)
	This method converts the binary buffer to a single string that is the ASCII HEX followed by 'separator', then by the binary data as 'viewable' text.
bool	formatMsecTimeStamp (Cpl::Text::String &buffer, unsigned long long timeStampInMsecs, bool encodeDay=true, bool appendToString=false)
	This method converts the binary millisecond count of 'timeStampInMsecs' to a string with the following format: "DD HH:MM:SS.SSS".
bool	formatSecTimeStamp (Cpl::Text::String &buffer, unsigned long long timeStampInSecs, bool encodeDay=true, bool appendToString=false)
	This method converts the binary second count of 'timeStampInSecs' to a string with the following format: "DD HH:MM:SS".
bool	formatPrecisionTimeStamp (Cpl::Text::String &buffer, Cpl::System::ElapsedTime::Precision_T timeStamp, bool encodeDay=true, bool appendToString=false)
	This method converts the Cpl::System::ElapsedTime::Precision_T value of time into a string with the following format: "DD HH:MM:SS.SSS".
uint8_t	unhexChar (char c)
	Returns the binary value for the 'ASCII HEX' character 'c'.
bool	unhex (const char *inString, size_t numCharToScan, uint8_t *outData)
	This method converts up to 'numCharToScan' characters from the ASCII HEX text string.
const char *	stripSpace (const char *s)
	This method returns a pointer to the FIRST non-whitespace character in the the specified null-terminated string.
const char *	stripNotSpace (const char *s)
	This method returns a pointer to the FIRST whitespace character in the the specified null-terminated string.
const char *	stripTrailingSpace (const char *s)
	This method returns a pointer to the LAST non-whitespace character in the the specified null-terminated string.
void	removeTrailingSpace (char *s)
	This method TRUNCATES the specified null-terminated string by eliminating any trailing white space.
const char *	stripChars (const char *s, const char *charsSet)
	This method is the same as stripSpace(), except the specified character set is used to terminate the search instead of the standard isspace() characters.
const char *	stripNotChars (const char *s, const char *charsSet)
	This method is the same as stripNotSpace(), except the specified character set is used to terminate the search instead of the standard isspace() characters.
const char *	stripTrailingChars (const char *s, const char *charsSet)
	This method is the same as stripTrailingSpaces(), except the specified character set is used to identify the last "non-whitespace" character.
void	removeTrailingChars (char *s, const char *charsSet)
	This method is the same as removeTrailingSpaces(), except the specified characters set is used for "whitespace" any trailing white space.
bool	isCharInString (const char *charsSet, const char c)
	This method returns true if the character 'c' is one of character(s) contained in 'charsSet'; else false is returned.

Function Documentation

a2b()

bool Cpl::Text::a2b	(	bool &	convertedValue,
		const char *	string,
		const char *	trueToken = "T",
		const char *	falseToken = "F",
		const char **	endptr = 0
	)

This method convert the specified string to an boolean.

The method returns true if the conversion was successful. When false is returned, the 'convertedValue' argument is NOT updated. If the first N characters of 'string' match the specified boolean token - the conversion is consider successful (i.e. there is no required separator/terminator character for a boolean token). If endptr is specified and the method returns true, a pointer to the first character 'after' the boolean token is returned.

a2d()

bool Cpl::Text::a2d	(	double &	convertedValue,
		const char *	string,
		const char *	validStopChars = 0,
		const char **	endptr = 0
	)

This method converts the specified string to an double.

The method returns true if the conversion was successful. When false is returned, the 'convertedValue' argument is NOT updated. By default the conversion assumes that the 'end-of-number' is end-of-string. If endptr is specified and the method returns true, a pointer to the first character 'after' the number is returned.

a2i()

bool Cpl::Text::a2i	(	int &	convertedValue,
		const char *	string,
		int	base = 10,
		const char *	validStopChars = 0,
		const char **	endptr = 0
	)

This method converts the specified string to an integer.

The method returns true if the conversion was successful. When false is returned, the 'convertedValue' argument is NOT updated. By default the conversion assumes a base 10 number and that the 'end-of-number' is end-of-string. If endptr is specified and the conversation was successful, a pointer to the first character 'after' the number is returned.

a2l()

bool Cpl::Text::a2l	(	long &	convertedValue,
		const char *	string,
		int	base = 10,
		const char *	validStopChars = 0,
		const char **	endptr = 0
	)

This method is the same as a2i() except that it converts long integer.

a2ll()

bool Cpl::Text::a2ll	(	long long &	convertedValue,
		const char *	string,
		int	base = 10,
		const char *	validStopChars = 0,
		const char **	endptr = 0
	)

This method is the same as a2i() except that it converts long long integer.

a2ui()

bool Cpl::Text::a2ui	(	unsigned &	convertedValue,
		const char *	string,
		int	base = 10,
		const char *	validStopChars = 0,
		const char **	endptr = 0
	)

This method is the same as a2i() except that it converts unsigned integer.

a2ul()

bool Cpl::Text::a2ul	(	unsigned long &	convertedValue,
		const char *	string,
		int	base = 10,
		const char *	validStopChars = 0,
		const char **	endptr = 0
	)

This method is the same as a2i() except that it converts unsigned long integer.

a2ull()

bool Cpl::Text::a2ull	(	unsigned long long &	convertedValue,
		const char *	string,
		int	base = 10,
		const char *	validStopChars = 0,
		const char **	endptr = 0
	)

This method is the same as a2i() except that it converts unsigned long long integer.

asciiBinaryToBuffer()

long Cpl::Text::asciiBinaryToBuffer	(	void *	dstBinary,
		const char *	srcString,
		size_t	dstMaxLen,
		bool	reverse = false
	)

This method will convert an 'ASCII BINARY' string to an equivalent binary buffer, i.e.

the reverse of bufferToAsciiBinary() in format.h. The 'reverse' argument when set to true will store the binary data starting with the last byte of 'dstBinary'.

If the number of '1' and '0' in 'srcString' is not a multiple of eight - the 'missing' bits will be set to zero in the binary output.

If the entire string was not able to be converted then -1 is returned OR if there are non '1'/'0' characters in the srcString; else the number of converted bits are returned.

Note: 'srcString' MUST be a null terminated string

asciiHexToBuffer()

long Cpl::Text::asciiHexToBuffer	(	void *	dstBinary,
		const char *	srcString,
		size_t	dstMaxLen
	)

This method will convert an 'ASCII HEX' string to an equivalent binary buffer, i.e.

the reverse of bufferToAsciiHex() in format.h. If the entire string was not able to be converted then -1 is returned, else the number of converted bytes are returned.

bufferToAsciiBinary()

bool Cpl::Text::bufferToAsciiBinary	(	const void *	binaryData,
		int	len,
		Cpl::Text::String &	destString,
		bool	appendToString = false,
		bool	reverse = false
	)

This method converts the binary buffer to a single string that is ASCII BINARY.

The number of digits in the output string is always a multiple of

1. The default order for traversing the 'binaryData' is to start with binaryData[0].

The converted result is returned via 'buffer'. If the results where truncated by the no enough memory in 'buffer' then false is returned; else true is returned.

Examples: binaryData = 0x844A, reverse=false, destString = "1000010001001010" binaryData = 0x844A, reverse=true, destString = "0100101010000100"

bufferToAsciiHex()

bool Cpl::Text::bufferToAsciiHex	(	const void *	binaryData,
		int	len,
		Cpl::Text::String &	destString,
		bool	upperCase = true,
		bool	appendToString = false,
		char	separator = '\0'
	)

This method will convert a binary buffer to 'ASCII HEX', e.g.

given the binary data of { 12, F2, 54 }, destString:= "12F254". The method will return true if buffer was successfully converted, i.e. the ENTIRE buffer was converted to a string; else false is returned (this include the cases of null 'buffer' pointer, 'len' equals zero, or not enough memory in 'destString' to contain the final result).

If 'separator' does not equal '\0', then it inserted between bytes in the output string.

Note: The default operation is to use uppercase text and to clear the destString before the conversion.

bufferToString()

bool Cpl::Text::bufferToString	(	const void *	buffer,
		int	len,
		Cpl::Text::String &	destString,
		bool	appendToString = false
	)

This method will take a raw data buffer and convert it to an 'viewable' string.

Non-printable values will displayed as '.'. Note: The default operation is to clear the destString before the conversion. The method will return if buffer was successfully converted, i.e. the ENTIRE buffer was converted; else false is returned (this include the cases of null 'buffer' pointer, 'len' equals zero, or not enough memory in 'destString' to contain the final result).

bufferToViewer()

bool Cpl::Text::bufferToViewer	(	const void *	binaryData,
		int	len,
		Cpl::Text::String &	destString,
		int	bytesPerLine = 16,
		const char *	separator = "    ",
		bool	upperCase = true,
		bool	appendToString = false
	)

This method converts the binary buffer to a single string that is the ASCII HEX followed by 'separator', then by the binary data as 'viewable' text.

The converted result is returned via 'buffer'. If the results where truncated by the no enough memory in 'buffer' then false is returned; else true is returned.

formatMsecTimeStamp()

bool Cpl::Text::formatMsecTimeStamp	(	Cpl::Text::String &	buffer,
		unsigned long long	timeStampInMsecs,
		bool	encodeDay = true,
		bool	appendToString = false
	)

This method converts the binary millisecond count of 'timeStampInMsecs' to a string with the following format: "DD HH:MM:SS.SSS".

The converted result is returned via 'buffer'. If the results where truncated by the no enough memory in 'buffer' then false is returned; else true is returned.

formatPrecisionTimeStamp()

bool Cpl::Text::formatPrecisionTimeStamp	(	Cpl::Text::String &	buffer,
		Cpl::System::ElapsedTime::Precision_T	timeStamp,
		bool	encodeDay = true,
		bool	appendToString = false
	)

This method converts the Cpl::System::ElapsedTime::Precision_T value of time into a string with the following format: "DD HH:MM:SS.SSS".

The converted result is returned via 'buffer'. If the results where truncated by the no enough memory in 'buffer' then false is returned; else true is returned.

formatSecTimeStamp()

bool Cpl::Text::formatSecTimeStamp	(	Cpl::Text::String &	buffer,
		unsigned long long	timeStampInSecs,
		bool	encodeDay = true,
		bool	appendToString = false
	)

This method converts the binary second count of 'timeStampInSecs' to a string with the following format: "DD HH:MM:SS".

The converted result is returned via 'buffer'. If the results where truncated by the no enough memory in 'buffer' then false is returned; else true is returned.

isCharInString()

bool Cpl::Text::isCharInString	(	const char *	charsSet,
		const char	c
	)

This method returns true if the character 'c' is one of character(s) contained in 'charsSet'; else false is returned.

longToStr()

const char * Cpl::Text::longToStr	(	long	num,
		char *	dstString,
		size_t	maxChars,
		unsigned	base = 10,
		char	padChar = ' '
	)

This method converts a long to a string.

If the number of converted digits exceeds the size of 'dstString', then the MOST significant digit(s) are discarded. When 'num' is negative there will always be a leading minus sign ('-') even if it means discarding a MOST significant digit. There is no feedback if/when digits are discarded.

Parameters

num	number to convert
dstString	buffer to hold the output
maxChars	size, in bytes, of 'dstString'. Note: This includes the space for the null terminator
base	Number base for conversion
padChar	The character to use to pad any unused leading characters in 'dstString'

Returns

a pointer to the beginning of the converted number when successful; else 0 is returned on error (e.g. illegal 'base' value). The returned pointer is essentially a left justified string of the converted value. For a right justified result, use the original pointer passed as 'dstString'.

parsePrecisionTimeStamp()

bool Cpl::Text::parsePrecisionTimeStamp	(	const char *	timeStampToParse,
		Cpl::System::ElapsedTime::Precision_T &	convertedValue
	)

This method parses a 'timestamp' with the following format: [DD ]HH:MM:SS[.sss] The method returns true if the parse was successful.

removeTrailingChars()

void Cpl::Text::removeTrailingChars	(	char *	s,
		const char *	charsSet
	)

This method is the same as removeTrailingSpaces(), except the specified characters set is used for "whitespace" any trailing white space.

NOTE: If 's' OR 'charsSet' is null, then nothing is done.

removeTrailingSpace()

void Cpl::Text::removeTrailingSpace

(

char *

s

)

This method TRUNCATES the specified null-terminated string by eliminating any trailing white space.

NOTE: If 's' is null, then nothing is done.

sizetToStr()

const char * Cpl::Text::sizetToStr	(	size_t	num,
		char *	dstString,
		size_t	maxChars,
		unsigned	base = 10,
		char	padChar = ' '
	)

This method is same as longToStr(), except it converts a size_t value.

stripChars()

const char * Cpl::Text::stripChars	(	const char *	s,
		const char *	charsSet
	)

This method is the same as stripSpace(), except the specified character set is used to terminate the search instead of the standard isspace() characters.

NOTES:

o If 's' is null, then null is returned
o If 'charsSet' is null, then 's' is returned and nothing is done.

stripNotChars()

const char * Cpl::Text::stripNotChars	(	const char *	s,
		const char *	charsSet
	)

This method is the same as stripNotSpace(), except the specified character set is used to terminate the search instead of the standard isspace() characters.

NOTES:

o If 's' is null, then null is returned
o If 'charsSet' is null, then 's' is returned and nothing is done.

stripNotSpace()

const char * Cpl::Text::stripNotSpace

(

const char *

s

)

This method returns a pointer to the FIRST whitespace character in the the specified null-terminated string.

NOTES:

o This method does NOT modify the original string in any way!
o If 's' is null, then null is returned.

This method is useful in finding the 'next' token in a string, for example:

// Returns a pointer to the first token in 'input'
const char* token = stripSpace(input)
 
// Returns a pointer to the second token in 'input'
token = stripSpace(stripNotSpace(token))

stripSpace()

const char * Cpl::Text::stripSpace

(

const char *

s

)

This method returns a pointer to the FIRST non-whitespace character in the the specified null-terminated string.

NOTES:

o This method does NOT modify the original string in any way!
o If 's' is null, then null is returned.

stripTrailingChars()

const char * Cpl::Text::stripTrailingChars	(	const char *	s,
		const char *	charsSet
	)

This method is the same as stripTrailingSpaces(), except the specified character set is used to identify the last "non-whitespace" character.

NOTES:

o If 's' is null, then null is returned
o If 'charsSet' is null, then 's' is returned and nothing is done.
o If the entire string is made up of 'charsSet', a pointer to the start
  of the string is returned (i.e. 's' returned)

stripTrailingSpace()

const char * Cpl::Text::stripTrailingSpace

(

const char *

s

)

This method returns a pointer to the LAST non-whitespace character in the the specified null-terminated string.

NOTES:

o This method does NOT modify the original string in any way!
o If 's' is null, then null is returned.
o If the entire string is whitespace, a pointer to the start of
  the string is returned (i.e. 's' returned)

ulongToStr()

const char * Cpl::Text::ulongToStr	(	unsigned long	num,
		char *	dstString,
		size_t	maxChars,
		unsigned	base = 10,
		char	padChar = ' '
	)

This method is same as longToStr(), except it converts a unsigned long value.

unhex()

bool Cpl::Text::unhex	(	const char *	inString,
		size_t	numCharToScan,
		uint8_t *	outData
	)

This method converts up to 'numCharToScan' characters from the ASCII HEX text string.

The converted binary data is stored in 'outData'.

The application is responsible for ENSURING that the 'outData' is large enough to hold the converted output!

unhexChar()

uint8_t Cpl::Text::unhexChar

(

char

c

)

Returns the binary value for the 'ASCII HEX' character 'c'.

Returns -1 if there is an error (e.g. 'c' is not valid 'hex' character)