#include <UtlString.h>

Inheritance diagram for UtlString:

[legend]

Collaboration diagram for UtlString:

Public Types
enum	StripType { leading =1, trailing, both }

enum	CompareCase { matchCase, ignoreCase }

typedef enum UtlString::StripType	StripType

typedef enum UtlString::CompareCase	CompareCase

Static Public Attributes
static const UtlContainableType	TYPE = "UtlString"

static const char *	ssNull = ""

static const size_t	UTLSTRING_NOT_FOUND = (size_t) (-1)
	Returned from a search that failed. More...

static const size_t	UTLSTRING_TO_END = (size_t) (-1)

Static Public Attributes inherited from UtlCopyableContainable
static const UtlContainableType	TYPE = "UtlCopyableContainable"

Static Public Attributes inherited from UtlContainable
static const UtlContainableType	TYPE = "UtlContainable"

Constructors
	UtlString ()
	Default Constructor. More...

	UtlString (const char *szSource)
	Constructor accepting a null terminated source string. More...

	UtlString (const char *szSource, size_t length)
	Constructor accepting a source string with an explicit length. More...

	UtlString (const UtlString &source)
	Copy the source UtlString. More...

	UtlString (const UtlString &source, size_t length)
	Copy an initial substring. More...

virtual UtlCopyableContainable *	clone () const
	Clone method for UtlCopyableContainable requirements. More...

Assignment Operators
UtlString &	operator= (const char *szStr)
	Replace the contents of this string with a null terminated string. More...

UtlString &	operator= (const UtlString &str)
	Replace the contents of this string with contents of a UtlString. More...

Accessors
size_t	length () const
	The current length of the string value. More...

const char *	data () const
	Return a read-only pointer to the stored string value.. More...

	operator const char * () const
	Cast to a const char* - identical to the data() method. More...

size_t	capacity () const
	Return the current capacity allocated for this string. More...

Substring Operators
Extract a portion of the string value.
UtlString	operator() (size_t start, size_t len) const
	Allows references of the form stringVar(start,length) - also see append. More...

char	operator() (size_t N)
	Get the character at position N. More...

Comparison Operations
Returns the nth character (zero based) UtlString aString("abc"); char secondChar = aString(1); Sets secondChar to 'b'
UtlBoolean	isNull () const
	Return true if this is an empty string. More...

virtual int	compareTo (const char *) const
	Compare this string to a null terminated string (case sensitive). More...

int	compareTo (const char *, CompareCase type) const
	Compare this string to a null terminated string, with case sensitivity control. More...

int	compareTo (UtlString const *, CompareCase type) const
	Compare this object to another string, with case sensitivity control. More...

UtlBoolean	contains (const char *) const
	Check for a null terminated value in this string. More...

UtlBoolean	operator== (const char *) const

UtlBoolean	operator!= (const char *) const

UtlBoolean	operator== (const UtlString &) const

UtlBoolean	operator!= (const UtlString &) const

UtlBoolean	operator!= (const char *, const UtlString &)

UtlBoolean	operator!= (const char, const UtlString &)

UtlBoolean	operator== (const char, const UtlString &)

UtlBoolean	operator== (const char *, const UtlString &)

Search Operations
Also see the regular expression search operations in the RegEx class.
size_t	index (char c) const
	Find the first instance of a single character. More...

size_t	index (char c, size_t offset) const
	Find the first instance of a single character starting at a specified offset. More...

size_t	first (char c) const
	Find the first instance of a single character. More...

size_t	index (const char *) const
	Find the first instance of a null terminated string. More...

size_t	index (const char *, size_t) const
	Find the first instance of a specified length string. More...

size_t	index (const char *, size_t, CompareCase) const
	Find the first instance of a specified length string, with case control. More...

size_t	index (const UtlString &) const
	Find the first match for the specified string (which may contain null characters) More...

size_t	index (const UtlString &match, size_t offset) const
	Find a match for the specified string starting at offset. More...

size_t	index (const UtlString &, size_t, CompareCase) const
	Find a match for the specified string starting at offset, with case sensitivity control. More...

size_t	first (const char *) const
	Find the first instance of a null terminated string. More...

size_t	last (char s) const
	Find the last instance of a character. More...

Append Operations
Append operations add to the end of the current value of the string.
UtlString &	operator+= (const char *)
	Append a null terminated string to the end of the lvalue. More...

UtlString &	append (const char *szStr)
	Append a null terminated string to the end of this string. More...

UtlString &	operator+= (const UtlString &s)
	Append a UtlString to this string. More...

UtlString &	append (const UtlString &str)
	Append a UtlString to this string. More...

UtlString &	append (const UtlString &str, size_t position, size_t length)
	Append a substring of a UtlString to this string. More...

UtlString &	append (const char *szStr, size_t N)
	Append up to N bytes of the designated string to the end of this string. More...

UtlString &	operator+= (const char c)
	Append a single character to the end of this string. More...

UtlString &	append (const char c)
	Append a single character to the end of this string. More...

UtlString &	appendFormat (const char *format,...)
	Append format string like pritnf. More...

UtlString &	appendBinaryToString (const void *binaryData, int numBytes, int valuesPerRow=16)
	Append binary data in human readable string format. More...

Insertion Operators

Outputs strings similar to xxd -p and can be converted back to binary using xxd -r -p

Parameters

binaryData	- pointer to binary data to append as string in human readable format.
numBytes	- number of bytes to read from binaryData.
valuesPerRow	- number space sparated 4 byte string values to append per row (newline separated).

These methods insert values into the string; the capacity is increased as needed to hold the additional value.

Nothing is overwritten - Any existing value at the insertion point is shifted to make room.

UtlString & insert (size_t position, const UtlString &src)

Insert a UtlString. More...

UtlString & insert (size_t position, const char newChar)

Insert a single character. More...

UtlString & insert (size_t position, const char *src)

Insert a null terminated string. More...

UtlString & prepend (const char *szStr)

Prepend a null terminated string at the beginning of this string. More...

UtlString & insert (size_t position, const char *src, size_t sourceLenth)

Insert arbitrary length value. More...

Replacement Operations
void	replaceAt (size_t pos, char newChar)
	Replace a single character at the designated position. More...

UtlString &	replace (const char src, const char tgt)
	Replace all instances of character src with character tgt. More...

UtlString &	replace (size_t pos, size_t N, const char *replaceStr)
	Replace N characters from a char*. More...

UtlString &	replace (size_t pos, size_t N, const char *replaceStr, size_t L)
	Replace N characters from a char*, with specified length string. More...

UtlString &	replace (size_t pos, size_t N, const UtlString &replaceStr)
	Replace N characters from another UtlString. More...

Concatenation Operations
UtlString	operator+ (const UtlString &s1, const UtlString &s2)
	Concatenate two UtlStrings as: s1 + s2. More...

UtlString	operator+ (const UtlString &s, const char *c)
	Concatenate a UtlString with a constant string as: s + c. More...

UtlString	operator+ (const char *c, const UtlString &s)
	Concatenate a constant string with a UtlString as: c + s. More...

Remove Operations
Also see Stripping and Trimming, below
UtlString &	remove (size_t pos)
	Remove all characters after the specified position. More...

UtlString &	remove (size_t pos, size_t N)
	Remove N characters from this string starting at designated position. More...

Stripping and Trimming Operations
UtlString	strip ()
	Removes whitespace (space, tab, Cr, Lf) from the end of the string. More...

UtlString	strip (StripType whichEnd)
	Removes whitespace (space, tab, Cr, Lf) from either or both ends of the string. More...

UtlString	strip (StripType whichEnd, char charToStrip)
	Removes all instances of the specified character from either or both ends of the string. More...

Case Conversion Operations
void	toLower ()

void	toUpper ()

Capacity Management
size_t	capacity (size_t N)
	Set the minimum capacity a string can hold without reallocation. More...

void	resize (size_t N, UtlBoolean clearTail=TRUE)
	Set a new size for the string. More...

Container Support Operations
virtual unsigned	hash () const
	Calculate a hash over the string contents. More...

virtual UtlContainableType	getContainableType () const
	Determine whether or not the values in a containable are comparable. More...

virtual int	compareTo (UtlContainable const *other) const
	Compare to any other UtlContainable. More...

virtual UtlBoolean	isEqual (UtlContainable const *) const

virtual UtlBoolean	isInstanceOf (const UtlContainableType type) const
	Determine if this object is a derivative of the specified UtlContainableType. More...

Destructors
virtual	~UtlString ()
	Destructor. More...

Additional Inherited Members
Public Member Functions inherited from UtlCopyableContainable
	UtlCopyableContainable ()

virtual	~UtlCopyableContainable ()

Public Member Functions inherited from UtlContainable
virtual	~UtlContainable ()

unsigned	directHash () const
	Provides a hash function that uses the object pointer as the hash value. More...

Static Public Member Functions inherited from UtlContainable
static unsigned	stringHash (char const *value)
	Provides a hash function appropriate for null-terminated string values. More...

static UtlBoolean	areSameTypes (const UtlContainableType type1, const UtlContainableType type2)
	Are UtlContainable types the same. More...

Detailed Description

UtlString is a resizable string which is also containable in any UtlContainer. It may include null characters.

A UtlString will grow as needed to hold any value stored in it; because this expansion reallocates and copies memory, it is a good idea to specify an expected size either when the object is constructed or using the capacity method.

Member Typedef Documentation

typedef enum UtlString::StripType StripType

Flags to the various strip methods

typedef enum UtlString::CompareCase CompareCase

Case sensitivity control constants

Member Enumeration Documentation

enum StripType

Flags to the various strip methods

Enumerator
leading	only strip from the beginning of the string
trailing	only strip from the end of the string
both	strip from both ends of the string

enum CompareCase

Case sensitivity control constants

Enumerator
matchCase	Case sensitive comparison
ignoreCase	Case insensitive comparison

Constructor & Destructor Documentation

UtlString ( )

Default Constructor.

UtlString ( const char * szSource )

Constructor accepting a null terminated source string.

The source string is copied to this object.

Parameters

szSource initial string value

UtlString	(	const char *	szSource,
		size_t	length
	)

Constructor accepting a source string with an explicit length.

Any zero byte in the source string is ignored; all length chars of the source string are copied to this object.

UtlString ( const UtlString & source )

Copy the source UtlString.

UtlString	(	const UtlString &	source,
		size_t	length
	)

Copy an initial substring.

Constructor accepting a reference to another string and a length. Up to length characters are copied from the source string into this object. If length is greater than the length of source this becomes a copy of source with the same data and length.

~UtlString ( )

virtual

Destructor.

Member Function Documentation

UtlCopyableContainable * clone ( ) const

virtual

Clone method for UtlCopyableContainable requirements.

Implements UtlCopyableContainable.

UtlString & operator= ( const char * szStr )

Replace the contents of this string with a null terminated string.

UtlString & operator= ( const UtlString & str )

Replace the contents of this string with contents of a UtlString.

size_t length ( ) const

The current length of the string value.

const char * data ( ) const

Return a read-only pointer to the stored string value..

This pointer should not be stored, since operations on the UtlString may free it.

The returned pointer is never null, even if the UtlString is null or newly-allocated.

The stored value will have a null byte at the end, but may also have null bytes at other positions within the value.

operator const char * ( ) const

Cast to a const char* - identical to the data() method.

Cast this object to a const char* pointer. This is exactly the same as calling data().

size_t capacity ( ) const

Return the current capacity allocated for this string.

UtlString operator()	(	size_t	start,
		size_t	len
	)		const

Allows references of the form stringVar(start,length) - also see append.

An empty string is returned if the start and/or len is invalid.

Note: This method constructs a temporary UtlString object. It will usually be more efficient to use the append method taking a UtlString, position, and length.

Parameters

start	Starting character position (zero based)
len	Number of characters to copy or UTLSTRING_TO_END for "the rest of the string"

char operator() ( size_t N )

Get the character at position N.

UtlBoolean isNull ( ) const

Return true if this is an empty string.

int compareTo ( const char * compareStr ) const

virtual

Compare this string to a null terminated string (case sensitive).

Returns: 0 if equal, < 0 if less then and >0 if greater.

int compareTo	(	const char *	compareStr,
		CompareCase	type
	)		const

Compare this string to a null terminated string, with case sensitivity control.

int compareTo	(	UtlString const *	compareStr,
		CompareCase	type
	)		const

Compare this object to another string, with case sensitivity control.

Returns: 0 if equal, < 0 if less then and >0 if greater.

UtlBoolean contains ( const char * searchStr ) const

Check for a null terminated value in this string.

This is equivalent to ( index(str) != UTL_NOT_FOUND )

Returns: true if this string contains the specified string.

UtlBoolean operator== ( const char * compareStr ) const

UtlBoolean operator!= ( const char * compareStr ) const

UtlBoolean operator== ( const UtlString & compareStr ) const

UtlBoolean operator!= ( const UtlString & compareStr ) const

size_t index ( char c ) const

Find the first instance of a single character.

Returns: the offset of the first c or UTL_NOT_FOUND

size_t index	(	char	c,
		size_t	offset
	)		const

Find the first instance of a single character starting at a specified offset.

Returns: the offset from the beginning of the string of the first c after offset or UTL_NOT_FOUND

size_t first ( char c ) const

Find the first instance of a single character.

Returns: the offset of the first c or UTL_NOT_FOUND

(this is the same as index(c) )

size_t index ( const char * searchStr ) const

Find the first instance of a null terminated string.

Returns: the offset of the first matching string or UTL_NOT_FOUND

size_t index	(	const char *	searchStr,
		size_t	start
	)		const

Find the first instance of a specified length string.

The search target value may contain null characters.

Returns: the offset of the first matching string or UTL_NOT_FOUND

size_t index	(	const char *	searchStr,
		size_t	start,
		CompareCase	type
	)		const

Find the first instance of a specified length string, with case control.

The search target value may contain null characters.

Returns: the offset of the first matching string or UTL_NOT_FOUND

size_t index ( const UtlString & searchString ) const

Find the first match for the specified string (which may contain null characters)

The search target value may contain null characters.

Returns: the offset of the first matching string or UTL_NOT_FOUND

size_t index	(	const UtlString &	match,
		size_t	offset
	)		const

Find a match for the specified string starting at offset.

The search target value (match) may contain null characters.

Returns: the offset from the beginning of the string of the match value after offset or UTL_NOT_FOUND

Parameters

match	string value to search for
offset	offset in target to start search

size_t index	(	const UtlString &	searchString,
		size_t	start,
		CompareCase	type
	)		const

Find a match for the specified string starting at offset, with case sensitivity control.

The search target value (match) may contain null characters.

Returns: the offset from the beginning of the string of the match value after offset or UTL_NOT_FOUND

size_t first ( const char * searchStr ) const

Find the first instance of a null terminated string.

Returns: the offset of the string or UTL_NOT_FOUND

size_t last ( char s ) const

Find the last instance of a character.

Returns: the offset of the string or UTL_NOT_FOUND

UtlString & operator+= ( const char * szStr )

Append a null terminated string to the end of the lvalue.

UtlString & append ( const char * szStr )

Append a null terminated string to the end of this string.

UtlString & operator+= ( const UtlString & s )

Append a UtlString to this string.

UtlString & append ( const UtlString & str )

Append a UtlString to this string.

Parameters

str	source string

UtlString & append	(	const UtlString &	str,
		size_t	position,
		size_t	length
	)

Append a substring of a UtlString to this string.

Note the difference between these two copies:

UtlString source("0123456789");
UtlString destA;
destA = source(1,3);
UtlString destB;
destB.append(source, 6, 2);

The assignment to destA actually constructs a temporary UtlString on the stack as the output of the source(1,3), invokes the copy constructor to copy its contents into destA, and then destructs it.

The assignment to destB copies the string contents directly from source to destB.

Parameters

str	source string
position	offset into source to start copy
length	length of substring to copy

UtlString & append	(	const char *	szStr,
		size_t	N
	)

Append up to N bytes of the designated string to the end of this string.

UtlString & operator+= ( const char c )

Append a single character to the end of this string.

UtlString & append ( const char c )

Append a single character to the end of this string.

UtlString & appendFormat	(	const char *	format,
			...
	)

Append format string like pritnf.

UtlString & appendBinaryToString	(	const void *	binaryData,
		int	numBytes,
		int	valuesPerRow = `16`
	)

Append binary data in human readable string format.

UtlString & insert	(	size_t	position,
		const UtlString &	src
	)

Insert a UtlString.

If an invalid position is specified, nothing is performed.

Parameters

position	position to insert the src string.
src	value to be inserted

UtlString & insert	(	size_t	position,
		const char	newChar
	)

Insert a single character.

If an invalid position is specified, nothing is performed.

Parameters

position	position to insert newChar.
newChar	character to insert

UtlString & insert	(	size_t	position,
		const char *	src
	)

Insert a null terminated string.

If an invalid position is specified, nothing is performed.

Parameters

position	position to insert src C string
src	null terminated string to insert

UtlString & prepend ( const char * szStr )

Prepend a null terminated string at the beginning of this string.

Equivalent to insert(0, szStr);

UtlString & insert	(	size_t	position,
		const char *	src,
		size_t	sourceLenth
	)

Insert arbitrary length value.

Insert the value at character position.

If an invalid position is specified, nothing is performed.

Parameters

position	position to insert src value
src	value to insert (may contain null bytes)
sourceLenth	number of bytes to insert

void replaceAt	(	size_t	pos,
		char	newChar
	)

Replace a single character at the designated position.

Parameters

pos	offset into data to replace - must be < the length
newChar	character to be put into that offset

UtlString & replace	(	const char	src,
		const char	tgt
	)

Replace all instances of character src with character tgt.

UtlString & replace	(	size_t	pos,
		size_t	N,
		const char *	replaceStr
	)

Replace N characters from a char*.

Replace N characters starting at the designated position with the designated replacement string. Invalid position or length results in no changes.

Parameters

pos	position in string to begin replacing
N	number of characters to replace
replaceStr	replacement value

UtlString & replace	(	size_t	pos,
		size_t	N,
		const char *	replaceStr,
		size_t	L
	)

Replace N characters from a char*, with specified length string.

Replace N characters starting at the designated position with a subset of the designated replacement string. Invalid position or length results in no changes.

Parameters

pos	starting position of the replacement
N	number of characters to replace
replaceStr	target replacement string
L	maximum number of characters of the replacement string to use.

UtlString & replace	(	size_t	pos,
		size_t	N,
		const UtlString &	replaceStr
	)

Replace N characters from another UtlString.

Replace N characters starting at the designated position with the designated replacement string. Invalid position or length results in no changes.

Parameters

pos	position in string to begin replacing
N	number of characters to replace
replaceStr	replacement value

UtlString & remove ( size_t pos )

Remove all characters after the specified position.

Nothing is performed if the position is invalid.

UtlString & remove	(	size_t	pos,
		size_t	N
	)

Remove N characters from this string starting at designated position.

Invalid position or length results in no changes.

UtlString strip ( )

Removes whitespace (space, tab, Cr, Lf) from the end of the string.

UtlString strip ( StripType whichEnd )

Removes whitespace (space, tab, Cr, Lf) from either or both ends of the string.

Removes whitespace (space, tab, Cr, Lf) from the beginning of the string, from the end of the string, or from both the beginning and end of the string.

UtlString strip	(	StripType	whichEnd,
		char	charToStrip
	)

Removes all instances of the specified character from either or both ends of the string.

Remove the designated character from the beginning of the string, from the end of the string, or from both the beginning and end of the string.

void toLower ( )

Convert the string to all lower case characters (e.g. AbC1 -> abc1)

void toUpper ( )

Convert the string to all upper case characters (e.g. AbC1 -> ABC1)

size_t capacity ( size_t N )

Set the minimum capacity a string can hold without reallocation.

Set the string's storage capacity to the designated value. This does not modify the value of the string, but rather adjusts the dynamic memory allocated for this string.

This never reduces the capacity - any size less then the current capacity is a no-op.

Returns: The new capacity that was set. In case of success, it may be greater than the requested capacity. In case of failure, it may be less than the requested capacity.

void resize	(	size_t	N,
		UtlBoolean	clearTail = `TRUE`
	)

Set a new size for the string.

Resize the string to the specified size. If the requested size is less then the the current size (string length), the string will be truncated. If requested size is larger then current size and clearTail is TRUE (default), the string will be padded with nulls. If clearTail is FALSE, string will not be padded with nulls.

unsigned hash ( ) const

virtual

Calculate a hash over the string contents.

If the equals operator returns true for another object, then both objects must return the same hashcode.

Implements UtlContainable.

UtlContainableType getContainableType ( ) const

virtual

Determine whether or not the values in a containable are comparable.

This returns a unique type for UtlString

Reimplemented from UtlCopyableContainable.

int compareTo ( UtlContainable const * other ) const

virtual

Compare to any other UtlContainable.

Compare this object to another containable object. If the UtlContainableType of the other object is not the UtlString type, this will return unequal.

Returns: 0 if equal, < 0 if less than, and > 0 if greater.

Implements UtlContainable.

UtlBoolean isEqual ( UtlContainable const * compareContainable ) const

virtual

Test this object to another like-object for equality. This method returns false if unlike-objects are specified.

Reimplemented from UtlContainable.

UtlBoolean isInstanceOf ( const UtlContainableType type ) const

virtual

Determine if this object is a derivative of the specified UtlContainableType.

Determine if this object is an instance of the designated runtime class identifer or one of its derivatives. For example:

if (pMyObject->isInstanceOf(UtlInt::TYPE))
{
    ...
}

If you want to determine if this object is exactly the same type as the given type (i.e. not a deriviative) use the following:

if(myObject->getContainableType() == UtlInt::TYPE)
{
    ...
}

Returns: TRUE/FALSE if this object is of the given type or a derivative of the given type.

Reimplemented from UtlCopyableContainable.

Friends And Related Function Documentation

UtlBoolean operator!=	(	const char *	compareStr,
		const UtlString &	compareUtlStr
	)

friend

UtlBoolean operator!=	(	const char	compareChar,
		const UtlString &	compareUtlStr
	)

friend

UtlBoolean operator==	(	const char	compareChar,
		const UtlString &	compareUtlStr
	)

friend

UtlBoolean operator==	(	const char *	compareStr,
		const UtlString &	compareUtlStr
	)

friend

UtlString operator+	(	const UtlString &	s1,
		const UtlString &	s2
	)

friend

Concatenate two UtlStrings as: s1 + s2.

UtlString operator+	(	const UtlString &	s,
		const char *	c
	)

friend

Concatenate a UtlString with a constant string as: s + c.

UtlString operator+	(	const char *	c,
		const UtlString &	s
	)

friend

Concatenate a constant string with a UtlString as: c + s.

Member Data Documentation

const UtlContainableType TYPE = "UtlString"

static

const char * ssNull = ""

static

< Class type used for runtime checking

const size_t UTLSTRING_NOT_FOUND = (size_t) (-1)

static

Returned from a search that failed.

const size_t UTLSTRING_TO_END = (size_t) (-1)

static

When specifying the length of a substring, indicates that the substring should extend to the end of the string.

Public Types

Static Public Attributes

Constructors

Assignment Operators

Accessors

Substring Operators

Comparison Operations

Search Operations

Append Operations

Insertion Operators

Replacement Operations

Concatenation Operations

Remove Operations

Stripping and Trimming Operations

Case Conversion Operations

Capacity Management

Container Support Operations

Destructors

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation