A simple named string builder style class. More...

#include <CzString.h>

Public Member Functions
void	reallocString (int len)
	Reallocate the amount of space available to the string.
void	allocString (int len)
	Allocates a new string, destroying the existing string.
void	reset ()
	Destroys the string.
void	setString (const char *str)
	Sets the string to the new string.
void	setString (const char *str, int len)
	Sets the string to the new string of specified length.
char *	getString ()
	Returns the string.
CzString	getSubString (int start, int max_chars)
	Returns a sub string of this string.
CzString	getSubString (int start)
	Returns all chars from start to the enmd of the string.
unsigned int	getHash () const
	Gets ths strings hash value.
void	setAutoHash (bool enable)
	Sets string auo hashing on / off.
void	setLength (int length)
	Sets ths strings length (does not affect the amount of memory allocated to the string)
bool	isAutohash () const
	Returns true if auto hashing is enabled.
	CzString ()
	CzString (const CzString &string)
	Constructs a string from another string.
	CzString (const char *pString, int start, int num_chars)
	Construct a string from a sub string.
	CzString (const char *pString)
	Constructs a string from another string.
	CzString (int v)
	Construct a string from an integer.
	CzString (unsigned int v)
	Construct a string from an unsigned integer.
	CzString (float v)
	Construct a string from a floating point number.
	CzString (bool v)
	Construct a string from a boolean.
	CzString (const CzVec2 &v)
	CzString (const CzVec3 &v)
	CzString (const CzVec4 &v)
	CzString (const CzColour &v)
virtual	~CzString ()
int	getSize () const
	Returns the size of the string. Size is the amount of memory available to the string.
int	getLength () const
	Returns the length of the string.
int	getAsInt () const
	Returns the integer value of the string.
bool	getAsBool () const
	Returns the boolean value of the string. Valid values include true and 1, all other values are classed as false.
float	getAsFloat () const
	Returns the floating point value of the string.
int	getAsListOfInt (int *int_pool) const
	Returns a list of integers (string should contain comma separated values)
int	getAsListOfFloat (float *float_pool) const
	Returns a list of floats (string should contain comma separated values)
int	getAsVectorOfFloat (CzVector< float > *int_pool)
	Returns a vector of ints (string should contain comma separated values)
int	getAsVectorOfInt (CzVector< int > *int_pool)
	Returns a vector of floats (string should contain comma separated values)
bool	isEmpty () const
	Returns true if the string is empty.
void	set (int v)
void	set (float v)
void	set (bool v)
void	set (const CzVec2 &v)
void	set (const CzVec3 &v)
void	set (const CzVec4 &v)
void	set (const CzColour &v)
void	Copy (const char *pString)
	Copies the entire string to this string.
void	Copy (CzString &pString)
	Copies the entire string to this string.
void	Copy (const char *pString, int start, int count)
	Copies a portion of the supplied string to this string.
CzString &	operator= (const CzString &op)
CzString &	operator= (const char *op)
char	operator[] (int nIndex)
CzString &	operator+= (const CzString &op)
CzString &	operator+= (const char *op)
CzString &	operator= (int v)
CzString &	operator= (float v)
CzString &	operator= (char chr)
CzString &	operator+= (int v)
CzString &	operator+= (float v)
CzString &	operator+= (char chr)
bool	operator== (const CzString &op)
bool	operator== (const char *op)
bool	operator== (unsigned int hash)
char *	str () const
const char *	c_str () const
bool	Compare (const char *pString, int len) const
	Compares two strings, returns true if same.
bool	Compare (int start, const char *pString, int len) const
	Compares a string and a sub string, returns true if same.
int	Find (const char *string)
	Simple string search.
int	FindNext (const char *string, int len)
	Searches from last find position for text string.
int	FindNext (const char *string)
	Searches from last find position for text string.
int	FindNext (char chr)
	Searches from last find position for the specified character.
void	FindReset ()
	Resets the find position to start of string.
int	StepFindIndex (int amount)
	Adjust the find position by the specified.
int	StepFindIndexNoneWhiteSpace ()
	Adjust the find position to the next none white space.
int	StepFindIndexWhiteSpace ()
	Adjust the find position to the next white space.
void	setFindIndex (int index)
	Sets the current find index.
int	getFindIndex () const
	Gets the current find index.
int	GetNextMarkerOffset (char marker)
	Returns length to the end of paramneter marker.
int	GetNextString ()
	Returns the next string.
int	GetNextMarkedString (char start_mark, char end_mark, int &offset)
	Returns a string marked by start and end marker characters.
int	GetNextMarkedStringAfterString (const char *search_string, char start_mark, char end_mark, CzString &out_string)
	Returns the next marked string after finding a certain string.
int	Replace (const char string, const char with)
	Replaces all occurances of "string" with new string "with".
void	Replace (char chr, char with)
	Replaces all occurances of character "chr" with new character "with".
bool	ContainsHTMLCodes () const
	Query if the string potentially contains special HTML characters.
int	Contains (char c) const
	Determines if the string contains the sepcified character.
int	Occurrences (char c) const
	Counts the number of occurrences of a specific character.
void	ReplaceHTMLCodes ()
	Replace any specical HTML codes with single character versions.
void	URLEncode (const char *str)
	URL encodes the supplied string.
void	URLEncode ()
	URL encodes this string.
void	URLDecode ()
	URL decodes this string.
void	HexEncode (const char *str, int num_bytes)
	Hexadecimal encode the supplied string.
void	HexEncode ()
	Hexadecimal encode this string.
void	HexDecode ()
	Hexadecimal decode this string.
bool	SplitFilename (CzString &filename, CzString &ext)
	Splits this string into filename and extension.
bool	GetFilenameExt (CzString &ext)
	Gets the filename extent portion of the filename.
bool	SplitVarIndex (CzString &var, int &index, CzString &vindex)
	Splits an XOML variable name / index (var_name:index)
bool	SplitPropVarIndex (CzString &prop, CzString &var, int &index, CzString &vindex)
	Splits an XOML property variable name / index ([prop_name]var_name:index)
CzSlotArray< CzString * > *	Split (char split_char)
	Slpits the string at the specified characer.
void	Split (char split_char, CzSlotArray< CzString * > *strings)
	Slpits the string at the specified characer.
void	ToUpper ()
	Converts this string upper case.
void	ToLower ()
	Converts this string to lower case.
Static Public Member Functions
static unsigned int	CalculateHash (const char *pString, int hash=5381)
static bool	IsNumber (char c)
static bool	IsAlpha (char c)
static bool	IsLower (char c)
static bool	IsUpper (char c)
static int	GetValueFromHexDigit (char c)
Protected Attributes
char *	Data
	The string data.
int	Length
	Length of the string.
int	Size
	Size of memory reserved for the string.
unsigned int	DataHash
	Hash value of the data (for fast comparison)
bool	AutoHash
	true to calculate hash value every time string is updated
int	FindIndex
	Used to track multiple searches.

Detailed Description

A simple named string builder style class.

Introduction

Strings are used extensively throughout app / game development, making it an incredibly important subject. We use strings for everything from naming objects to presenting interactive text to the player.

String building can be a nightmare for memory managers as constantly rebuilding strings causes many memory allocations and deallocations fragmenting the available memory into small hard to use units.

A string builder is a class that allows you to build a string using a predefined sized buffer or at the very least a buffer than can be resized. CzString supports the following features:

String builder functionality
String concetanation and resizing
String building from basic types such as integers, floats and boolean types
String comparison
String splitting
Stream style string searching
Find strings between markers
Character replacement
HTML decoding
Hex encoding / decoding
URL encoding / decoding
Change of case
Extraction of numbers / items and lists of numbers / items

Basic String Building

Strings can be created from raw text, integers, floats, boolean and even vector variables as shown below:

CzString string("Hello");       // Creation from raw text
CzString int_string(1234);      // Creation from an integer
CzString int_string(100.234f);  // Creation from a float
CzString int_string(true);      // Creation from a boolean

Strings can also be concatenated:

CzString string("Hello"); string += ". How you doing";

If you are creating a string and you know that it will require quite a number of concatenations then you should set its initial size to prevent memory resizing, here's an example:

CzString string;
string.allocString(1024);   // here we preallocate 1024 bytes of memory for the string
string += "Hello!";
string += " How you doing.";
string += " I'm great thanks, how are you?";
string += " Fantastico!";

Comparing Strings

When two strings are compared using the CzString class their hash values are compared for equality. By default each time you create or modify a string a hash value for the string is recalculated. When building a long string it may be a good idea to turn auto string hashing off until the string has been built then turn itback on just before your last concatenation:

CzString string;
string.allocString(1024);
string.setAutoHash(false);
string += "Hello!";
string += " How you doing.";
string += " I'm great thanks, how are you?";
string.setAutoHash(true);
string += " Fantastico!";

Note that if string auto hashing is disabled then a full string compare will be carried out.

Stream Style Searching

CzString is set up to allow stream like searching whereby your last searched position will be saved, allowing you to carry out additional searches from where the last search left off. This type of string searching is incredibly useful when it comes to parsing areas of memory. The following methods can be used:

Getting Strings Values

CzString provides some useful methods for converting from strings to certain other types:

int             getAsInt() const;                               // Returns the integer value of the string
bool            getAsBool() const;                              // Returns the boolean value of the string. Valid values include true and 1, all other values are classed as false
float           getAsFloat() const;                             // Returns the floating point value of the string
int             getAsListOfInt(int *int_pool);                  // Returns a list of integers (string should contain comma separated values)
int             getAsListOfFloat(float* float_pool);            // Returns a list of floats (string should contain comma separated values)
int             getAsVectorOfFloat(CzVector<float> *int_pool);  // Returns a vector of ints (string should contain comma separated values)
int             getAsVectorOfInt(CzVector<int> *int_pool);      // Returns a vector of floats (string should contain comma separated values)

Other Useful String Tools

CzString contains many other useful utility methods to help make various tasks easier:

Replace() - Replaces all occurrences of char / string with the replacement in a string
Contains() - Returns true if a string contains the specified character
ReplaceHTMLCodes() - Replaces HTML style codes such as & with their ACII equivalents
URLEncode() - Encodes a string as URL encoded
URLDecode() - Decodes a URL encoded string
HexEncode() - Encodes the text as hexadecimal
HexDecode() - Decodes a string of Hex to text
ToLower() - Converts a string to all lower case
ToUpper() - Converts a string to all upper case
SplitFileName() - Splits a string into file name and extension strings
GetFilenameExt() - Extracts a file names extension as a string
Split() - Splits a string using a specified separator into an array of strings
SplitVarIndex() - Splits an XOML variable name / index (var_name:index)
SplitPropVarIndex() - Splits an XOML property variable name / index ([prop_name]var_name:index)

Constructor & Destructor Documentation

CzString::CzString ( ) [inline]

CzString::CzString ( const CzString & string )

Constructs a string from another string.

Parameters:

string The source string.

CzString::CzString	(	const char *	pString,
		int	start,
		int	num_chars
	)

Construct a string from a sub string.

Parameters:

pString	The source string.
start	The start index.
num_chars	Number of characters.

CzString::CzString ( const char * pString )

Constructs a string from another string.

Parameters:

string The source string.

CzString::CzString ( int v )

Construct a string from an integer.

Parameters:

v	The integer.

CzString::CzString ( unsigned int v )

Construct a string from an unsigned integer.

Parameters:

v	The unsigned integer.

CzString::CzString ( float v )

Construct a string from a floating point number.

Parameters:

v	The floating point number.

CzString::CzString ( bool value )

Construct a string from a boolean.

Parameters:

v	The boolean.

CzString::CzString ( const CzVec2 & v )

CzString::CzString ( const CzVec3 & v )

CzString::CzString ( const CzVec4 & v )

CzString::CzString ( const CzColour & v )

virtual CzString::~CzString ( ) [inline, virtual]

Member Function Documentation

void CzString::allocString ( int len )

Allocates a new string, destroying the existing string.

const char* CzString::c_str ( ) const [inline]

unsigned int CzString::CalculateHash	(	const char *	pString,
		int	hash = `5381`
	)		`[static]`

bool CzString::Compare	(	const char *	pString,
		int	len
	)		const

Compares two strings, returns true if same.

bool CzString::Compare	(	int	start,
		const char *	pString,
		int	len
	)		const

Compares a string and a sub string, returns true if same.

int CzString::Contains ( char c ) const

Determines if the string contains the sepcified character.

Parameters:

c	The character to test.

Returns:: Position at which character was found or -1 for not found.

bool CzString::ContainsHTMLCodes ( ) const

Query if the string potentially contains special HTML characters.

Returns:: true if it succeeds, false if it fails.

void CzString::Copy ( const char * pString )

Copies the entire string to this string.

Parameters:

pString The source string.

void CzString::Copy ( CzString & string )

Copies the entire string to this string.

Parameters:

[in] string The source string.

void CzString::Copy	(	const char *	pString,
		int	start,
		int	count
	)

Copies a portion of the supplied string to this string.

Parameters:

pString	The source string.
start	The start index.
count	Number of chars to copy.

int CzString::Find ( const char * string )

Simple string search.

int CzString::FindNext	(	const char *	string,
		int	len
	)

Searches from last find position for text string.

int CzString::FindNext ( const char * string )

Searches from last find position for text string.

int CzString::FindNext ( char chr )

Searches from last find position for the specified character.

void CzString::FindReset ( )

Resets the find position to start of string.

bool CzString::getAsBool ( ) const

Returns the boolean value of the string. Valid values include true and 1, all other values are classed as false.

float CzString::getAsFloat ( ) const

Returns the floating point value of the string.

int CzString::getAsInt ( ) const

Returns the integer value of the string.

int CzString::getAsListOfFloat ( float * float_pool ) const

Returns a list of floats (string should contain comma separated values)

int CzString::getAsListOfInt ( int * int_pool ) const

Returns a list of integers (string should contain comma separated values)

int CzString::getAsVectorOfFloat ( CzVector< float > * int_pool )

Returns a vector of ints (string should contain comma separated values)

int CzString::getAsVectorOfInt ( CzVector< int > * int_pool )

Returns a vector of floats (string should contain comma separated values)

bool CzString::GetFilenameExt ( CzString & ext )

Gets the filename extent portion of the filename.

Parameters:

[out] ext The extension.

Returns:: true if it succeeds, false if it fails.

int CzString::getFindIndex ( ) const [inline]

Gets the current find index.

unsigned int CzString::getHash ( ) const [inline]

Gets ths strings hash value.

int CzString::getLength ( ) const [inline]

Returns the length of the string.

int CzString::GetNextMarkedString	(	char	start_mark,
		char	end_mark,
		int &	offset
	)

Returns a string marked by start and end marker characters.

int CzString::GetNextMarkedStringAfterString	(	const char *	search_string,
		char	start_mark,
		char	end_mark,
		CzString &	out_string
	)

Returns the next marked string after finding a certain string.

int CzString::GetNextMarkerOffset ( char marker )

Returns length to the end of paramneter marker.

int CzString::GetNextString ( )

Returns the next string.

int CzString::getSize ( ) const [inline]

Returns the size of the string. Size is the amount of memory available to the string.

char* CzString::getString ( ) [inline]

Returns the string.

CzString CzString::getSubString	(	int	start,
		int	max_chars
	)

Returns a sub string of this string.

CzString CzString::getSubString ( int start )

Returns all chars from start to the enmd of the string.

static int CzString::GetValueFromHexDigit ( char c ) [inline, static]

void CzString::HexDecode ( )

Hexadecimal decode this string.

void CzString::HexEncode	(	const char *	str,
		int	num_bytes
	)

Hexadecimal encode the supplied string.

Parameters:

str	The source string.
num_bytes	Number of bytes.

void CzString::HexEncode ( )

Hexadecimal encode this string.

static bool CzString::IsAlpha ( char c ) [inline, static]

bool CzString::isAutohash ( ) const [inline]

Returns true if auto hashing is enabled.

bool CzString::isEmpty ( ) const [inline]

Returns true if the string is empty.

static bool CzString::IsLower ( char c ) [inline, static]

static bool CzString::IsNumber ( char c ) [inline, static]

static bool CzString::IsUpper ( char c ) [inline, static]

int CzString::Occurrences ( char c ) const

Counts the number of occurrences of a specific character.

Parameters:

c	The character to test.

Returns:: Number of occurances, -1 for error.

CzString & CzString::operator+= ( const CzString & op )

CzString & CzString::operator+= ( const char * op )

CzString & CzString::operator+= ( int v )

CzString & CzString::operator+= ( float v )

CzString & CzString::operator+= ( char chr )

CzString & CzString::operator= ( const CzString & op )

CzString & CzString::operator= ( const char * op )

CzString & CzString::operator= ( int v )

CzString & CzString::operator= ( float v )

CzString & CzString::operator= ( char chr )

bool CzString::operator== ( const CzString & op )

bool CzString::operator== ( const char * op )

bool CzString::operator== ( unsigned int hash )

char CzString::operator[] ( int nIndex )

void CzString::reallocString ( int len )

Reallocate the amount of space available to the string.

int CzString::Replace	(	const char *	string,
		const char *	with
	)

Replaces all occurances of "string" with new string "with".

Parameters:

string	The string to replace.
with	The replacement string.

Returns:: .

void CzString::Replace	(	char	chr,
		char	with
	)

Replaces all occurances of character "chr" with new character "with".

Parameters:

chr	The character to replace.
with	The replacement character.

void CzString::ReplaceHTMLCodes ( )

Replace any specical HTML codes with single character versions.

Supports the following codes:

<
>
&
"
'

void CzString::reset ( )

Destroys the string.

void CzString::set ( int v )

void CzString::set ( float v )

void CzString::set ( bool v )

void CzString::set ( const CzVec2 & v )

void CzString::set ( const CzVec3 & v )

void CzString::set ( const CzVec4 & v )

void CzString::set ( const CzColour & v )

void CzString::setAutoHash ( bool enable )

Sets string auo hashing on / off.

void CzString::setFindIndex ( int index ) [inline]

Sets the current find index.

void CzString::setLength ( int length ) [inline]

Sets ths strings length (does not affect the amount of memory allocated to the string)

void CzString::setString ( const char * str )

Sets the string to the new string.

void CzString::setString	(	const char *	str,
		int	len
	)

Sets the string to the new string of specified length.

CzSlotArray< CzString * > * CzString::Split ( char split_char )

Slpits the string at the specified characer.

Parameters:

split_char The split character.

Returns:: null if it fails, else an array of sub strings.

void CzString::Split	(	char	split_char,
		CzSlotArray< CzString * > *	strings
	)

Slpits the string at the specified characer.

Parameters:

	split_char	The split character.
[out]	strings	If non-null, the split strings.

bool CzString::SplitFilename	(	CzString &	filename,
		CzString &	ext
	)

Splits this string into filename and extension.

Parameters:

[out]	filename	Filename component.
[out]	ext	The extension component.

Returns:: true if it succeeds, false if it fails.

bool CzString::SplitPropVarIndex	(	CzString &	prop,
		CzString &	var,
		int &	index,
		CzString &	vindex
	)

Splits an XOML property variable name / index ([prop_name]var_name:index)

Parameters:

[out]	prop	The property name component.
[out]	var	The variable name component.
[out]	index	The index component.
[out]	vindex	The index component as text.

Returns:: true if it succeeds, false if it fails.

bool CzString::SplitVarIndex	(	CzString &	var,
		int &	index,
		CzString &	vindex
	)

Splits an XOML variable name / index (var_name:index)

Parameters:

[out]	var	The variable name component.
[out]	index	The index component.
[out]	vindex	The index component as text.

Returns:: true if it succeeds, false if it fails.

int CzString::StepFindIndex ( int amount )

Adjust the find position by the specified.

int CzString::StepFindIndexNoneWhiteSpace ( )

Adjust the find position to the next none white space.

int CzString::StepFindIndexWhiteSpace ( )

Adjust the find position to the next white space.

char* CzString::str ( ) const [inline]

void CzString::ToLower ( )

Converts this string to lower case.

void CzString::ToUpper ( )

Converts this string upper case.

void CzString::URLDecode ( )

URL decodes this string.

void CzString::URLEncode ( const char * str )

URL encodes the supplied string.

Parameters:

str	The string to encode.

void CzString::URLEncode ( )

URL encodes this string.

Member Data Documentation

bool CzString::AutoHash [protected]

true to calculate hash value every time string is updated

char* CzString::Data [protected]

The string data.

unsigned int CzString::DataHash [protected]

Hash value of the data (for fast comparison)

int CzString::FindIndex [protected]

Used to track multiple searches.

int CzString::Length [protected]

Length of the string.

int CzString::Size [protected]

Size of memory reserved for the string.

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Introduction

Basic String Building

Comparing Strings

Stream Style Searching

Getting Strings Values

Other Useful String Tools

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation