Cpl::Text::DString Class Reference

This concrete class implements a simple "dynamic storage" String Type. More...

Detailed Description

This concrete class implements a simple "dynamic storage" String Type.

All memory is allocated from the heap. For memory allocation errors, the following happens: 1) The _truncated flag is set to true. 2) If the error occurred in the constructor, then the internal string is set an empty string. If the error occurred because of a requested size increase, the internal string is simply truncated.

#include <DString.h>

Inheritance diagram for Cpl::Text::DString:

Collaboration diagram for Cpl::Text::DString:

Public Member Functions
	DString (const String &string, int initialSize=0, int blocksize=OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE)
	Constructor.
	DString (const DString &string, int initialSize=0, int blocksize=OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE)
	Constructor. See above constructor for details.
	DString (const char *string="", int initialSize=0, int blocksize=OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE)
	Constructor. See above constructor for details.
	DString (char c, int initialSize=0, int blocksize=OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE)
	Constructor. See above constructor for details.
	DString (int num, int initialSize=0, int blocksize=OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE)
	Constructor. See above constructor for details.
	DString (unsigned num, int initialSize=0, int blocksize=OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE)
	Constructor. See above constructor for details.
	DString (long num, int initialSize=0, int blocksize=OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE)
	Constructor. See above constructor for details.
	DString (long long num, int initialSize=0, int blocksize=OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE)
	Constructor. See above constructor for details.
	DString (unsigned long num, int initialSize=0, int blocksize=OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE)
	Constructor. See above constructor for details.
	DString (unsigned long long num, int initialSize=0, int blocksize=OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE)
	Constructor. See above constructor for details.
	~DString ()
	Destructor.
Cpl::Text::String &	operator= (const DString &string)
	Assignment.
Cpl::Text::String &	operator= (int num)
	Assignment.
Cpl::Text::String &	operator= (unsigned int num)
	Assignment.
Cpl::Text::String &	operator= (long num)
	Assignment.
Cpl::Text::String &	operator= (long long num)
	Assignment.
Cpl::Text::String &	operator= (unsigned long num)
	Assignment.
Cpl::Text::String &	operator= (unsigned long long num)
	Assignment.
Cpl::Text::String &	operator+= (const DString &string)
	Append.
Cpl::Text::String &	operator+= (int num)
	Append.
Cpl::Text::String &	operator+= (unsigned int num)
	Append.
Cpl::Text::String &	operator+= (long num)
	Append.
Cpl::Text::String &	operator+= (long long num)
	Append.
Cpl::Text::String &	operator+= (unsigned long num)
	Append.
Cpl::Text::String &	operator+= (unsigned long long num)
	Append.
void	copyIn (const char *string, int n)
	Override base class.
void	appendTo (const char *string, int n)
	Override base class.
void	insertAt (int insertOffset, const char *stringToInsert)
	Override base class.
int	maxLength () const
	Override base class.
Public Member Functions inherited from Cpl::Text::String_
void	clear ()
	See Cpl::Text::String.
	operator char () const
	See Cpl::Text::String.
int	length () const
	See Cpl::Text::String.
bool	isEmpty () const
	See Cpl::Text::String.
bool	truncated () const
	See Cpl::Text::String.
bool	operator== (const char *string) const
	See Cpl::Text::String.
bool	operator== (const String &string) const
	See Cpl::Text::String.
bool	operator!= (const char *string) const
	See Cpl::Text::String.
bool	operator!= (const String &string) const
	See Cpl::Text::String.
bool	isEqualIgnoreCase (const char *string) const
	See Cpl::Text::String.
int	compare (const char *string) const
	See Cpl::Text::String.
int	compareIgnoreCase (const char *string) const
	See Cpl::Text::String.
bool	operator== (char c) const
	See Cpl::Text::String.
bool	isEqualSubstring (int startpos, int endpos, const char *string) const
	See Cpl::Text::String.
bool	isEqualSubstringIgnoreCase (int startpos, int endpos, const char *string) const
	See Cpl::Text::String.
bool	startsWith (const char *string) const
	See Cpl::Text::String.
bool	startsWith (const char *string, int startOffset) const
	See Cpl::Text::String.
bool	endsWith (const char *string) const
	See Cpl::Text::String.
void	format (const char *format,...)
	See Cpl::Text::String.
void	formatAppend (const char *format,...)
	See Cpl::Text::String.
void	formatOpt (bool appendFlag, const char *format,...)
	See Cpl::Text::String.
void	vformat (const char *format, va_list ap)
	See Cpl::Text::String.
void	vformatAppend (const char *format, va_list ap)
	See Cpl::Text::String.
void	vformatOpt (bool appendFlag, const char *format, va_list ap)
	See Cpl::Text::String.
int	indexOf (char c) const
	See Cpl::Text::String.
int	indexOf (char c, int startpos) const
	See Cpl::Text::String.
int	indexOf (const char *str) const
	See Cpl::Text::String.
int	indexOf (const char *str, int startpos) const
	See Cpl::Text::String.
int	lastIndexOf (char c) const
	See Cpl::Text::String.
int	count (char c) const
	See Cpl::Text::String.
const char *	toUpper ()
	See Cpl::Text::String.
const char *	toLower ()
	See Cpl::Text::String.
void	removeLeadingSpaces ()
	See Cpl::Text::String.
void	removeTrailingSpaces ()
	See Cpl::Text::String.
void	removeLeadingChars (const char *charsSet)
	See Cpl::Text::String.
void	removeTrailingChars (const char *charsSet)
	See Cpl::Text::String.
void	cut (int startpos, int endpos)
	See Cpl::Text::String.
void	trimRight (int n)
	See Cpl::Text::String.
void	setChar (int atPosition, char newchar)
	See Cpl::Text::String.
int	replace (char targetChar, char newChar)
	See Cpl::Text::String.
const char *	getString () const
	See Cpl::Text::String.
char *	getBuffer (int &maxAllowedLength)
	See Cpl::Text::String.
Cpl::Text::String &	operator= (const String &string)
	Assignment.
Cpl::Text::String &	operator= (const char *string)
	Assignment.
Cpl::Text::String &	operator= (char c)
	Assignment.
Cpl::Text::String &	operator+= (const String &string)
	Append.
Cpl::Text::String &	operator+= (const char *string)
	Append.
Cpl::Text::String &	operator+= (char c)
	Append.
int	compareKey (const Key &key) const
	See Cpl::Container::Key.
const void *	getRawKey (unsigned *returnRawKeyLenPtr=0) const
	See Cpl::Container::Key.
Public Member Functions inherited from Cpl::Text::String
virtual	~String ()
	Virtual destructor!
	operator const char * () const
	Cast to read-only character string pointer.
const char *	operator() () const
	Returns a Read-only pointer to the "raw" (short-hand for getString())
char	operator[] (int i) const
	Returns the specified character. If n is out-bounds, then '\0' is returned.
int	availLength ()
	Returns the available space left in the internal buffer.
void	trimLeft (int n)
	Removes 'n' characters from the start-of-string.
Public Member Functions inherited from Cpl::Container::Key
virtual	~Key ()
	Ensure a Virtual destructor.
virtual int	compareKey (const Key &key) const =0
	Key Compare function.

Protected Member Functions
int	calcMemSize (int len)
	Returns the need memory size in "block units".
void	freeCurrentString (void)
	Frees the current string memory - IF it was previously allocated.
int	maxStrLen (void) const
	Returns the max length of internal WITHOUT the '\0' string terminator.
void	validateAndCopy (const char *string, int len)
	Validates the just created string is 'valid'
Protected Member Functions inherited from Cpl::Text::String_
	String_ (char *internalStringPtr)
	Constructor.
void	validateSizeAfterFormat (int availableLen, int formattedLen, int maxlen)
	Sets the truncated flag if needed and insures string is null terminated.

Protected Attributes
int	m_blockSize
	Block size in bytes.
int	m_storageLen
	Size, in bytes, of allocated storage.
Protected Attributes inherited from Cpl::Text::String_
bool	m_truncated
	Flag to track when the internal string get truncated.
char *	m_strPtr
	Pointer to the actual internal string.

Constructor & Destructor Documentation

DString() [1/10]

Cpl::Text::DString::DString	(	const String &	string,
		int	initialSize = 0,
		int	blocksize = OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE
	)

Constructor.

The amount of storage initially allocated for the string is the maximum of the size of the source string AND the value of initialSize. Whatever value is chosen, it is then rounded up to the nearest block size multiple. There are two main reasons to specify an intialSize. 1) To reduce the number of malloc/free that occur over the life of the String. If you supply a large enough initialSize - no additional mallocs will be needed. 2) If you plan to use the format(..) methods. The format() methods will NOT allocate additional storage. To prevent the format() methods from truncating, you must start with a large enough 'buffer'. The block size parameter can be used to control the size of the 'chunks' memory is allocated in. This 'blocking' paradigm helps to reduce fragmentation and number of internal malloc/free operations.

NOTE: The space reserved for the trailing null terminator is part of the block calculation, i.e. if your initial size is 16, and your block size is 16, then number of bytes allocated is 32 to allow space for a 16 byte string and a one byte terminator and then rounded up to the next block size.

DString() [2/10]

Cpl::Text::DString::DString	(	const DString &	string,
		int	initialSize = 0,
		int	blocksize = OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE
	)

Constructor. See above constructor for details.

DString() [3/10]

Cpl::Text::DString::DString	(	const char *	string = "",
		int	initialSize = 0,
		int	blocksize = OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE
	)

Constructor. See above constructor for details.

DString() [4/10]

Cpl::Text::DString::DString	(	char	c,
		int	initialSize = 0,
		int	blocksize = OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE
	)

Constructor. See above constructor for details.

DString() [5/10]

Cpl::Text::DString::DString	(	int	num,
		int	initialSize = 0,
		int	blocksize = OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE
	)

Constructor. See above constructor for details.

DString() [6/10]

Cpl::Text::DString::DString	(	unsigned	num,
		int	initialSize = 0,
		int	blocksize = OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE
	)

Constructor. See above constructor for details.

DString() [7/10]

Cpl::Text::DString::DString	(	long	num,
		int	initialSize = 0,
		int	blocksize = OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE
	)

Constructor. See above constructor for details.

DString() [8/10]

Cpl::Text::DString::DString	(	long long	num,
		int	initialSize = 0,
		int	blocksize = OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE
	)

Constructor. See above constructor for details.

DString() [9/10]

Cpl::Text::DString::DString	(	unsigned long	num,
		int	initialSize = 0,
		int	blocksize = OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE
	)

Constructor. See above constructor for details.

DString() [10/10]

Cpl::Text::DString::DString	(	unsigned long long	num,
		int	initialSize = 0,
		int	blocksize = OPTION_CPL_TEXT_DSTRING_ALLOC_BLOCK_SIZE
	)

Constructor. See above constructor for details.

~DString()

Cpl::Text::DString::~DString

(

)

Destructor.

Member Function Documentation

appendTo()

void Cpl::Text::DString::appendTo ( const char *  string, int  n  )

virtual

Override base class.

Implements Cpl::Text::String.

calcMemSize()

int Cpl::Text::DString::calcMemSize ( int  len )

inlineprotected

Returns the need memory size in "block units".

Note: The size calculation includes the memory for the trailing '\0' string terminator.

copyIn()

void Cpl::Text::DString::copyIn ( const char *  string, int  n  )

virtual

Override base class.

Implements Cpl::Text::String.

freeCurrentString()

void Cpl::Text::DString::freeCurrentString ( void  )

protected

Frees the current string memory - IF it was previously allocated.

insertAt()

void Cpl::Text::DString::insertAt ( int  insertOffset, const char *  stringToInsert  )

virtual

Override base class.

Implements Cpl::Text::String.

maxLength()

int Cpl::Text::DString::maxLength ( ) const

virtual

Override base class.

Implements Cpl::Text::String.

maxStrLen()

int Cpl::Text::DString::maxStrLen ( void  ) const

inlineprotected

Returns the max length of internal WITHOUT the '\0' string terminator.

operator+=() [1/7]

Cpl::Text::String & Cpl::Text::DString::operator+=

(

const DString &

string

)

Append.

operator+=() [2/7]

Cpl::Text::String & Cpl::Text::DString::operator+= ( int  num )

virtual

Append.

Implements Cpl::Text::String.

operator+=() [3/7]

Cpl::Text::String & Cpl::Text::DString::operator+= ( long long  num )

virtual

Append.

Implements Cpl::Text::String.

operator+=() [4/7]

Cpl::Text::String & Cpl::Text::DString::operator+= ( long  num )

virtual

Append.

Implements Cpl::Text::String.

operator+=() [5/7]

Cpl::Text::String & Cpl::Text::DString::operator+= ( unsigned int  num )

virtual

Append.

Implements Cpl::Text::String.

operator+=() [6/7]

Cpl::Text::String & Cpl::Text::DString::operator+= ( unsigned long long  num )

virtual

Append.

Implements Cpl::Text::String.

operator+=() [7/7]

Cpl::Text::String & Cpl::Text::DString::operator+= ( unsigned long  num )

virtual

Append.

Implements Cpl::Text::String.

operator=() [1/7]

Cpl::Text::String & Cpl::Text::DString::operator=

(

const DString &

string

)

Assignment.

operator=() [2/7]

Cpl::Text::String & Cpl::Text::DString::operator= ( int  num )

virtual

Assignment.

Implements Cpl::Text::String.

operator=() [3/7]

Cpl::Text::String & Cpl::Text::DString::operator= ( long long  num )

virtual

Assignment.

Implements Cpl::Text::String.

operator=() [4/7]

Cpl::Text::String & Cpl::Text::DString::operator= ( long  num )

virtual

Assignment.

Implements Cpl::Text::String.

operator=() [5/7]

Cpl::Text::String & Cpl::Text::DString::operator= ( unsigned int  num )

virtual

Assignment.

Implements Cpl::Text::String.

operator=() [6/7]

Cpl::Text::String & Cpl::Text::DString::operator= ( unsigned long long  num )

virtual

Assignment.

Implements Cpl::Text::String.

operator=() [7/7]

Cpl::Text::String & Cpl::Text::DString::operator= ( unsigned long  num )

virtual

Assignment.

Implements Cpl::Text::String.

validateAndCopy()

void Cpl::Text::DString::validateAndCopy ( const char *  string, int  len  )

protected

Validates the just created string is 'valid'

Member Data Documentation

m_blockSize

int Cpl::Text::DString::m_blockSize

protected

Block size in bytes.

m_storageLen

int Cpl::Text::DString::m_storageLen

protected

Size, in bytes, of allocated storage.

---

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

• Cpl/Text/DString.h