This abstract class defines the operations that can be before on a NULL terminated string. More...

Detailed Description

This abstract class defines the operations that can be before on a NULL terminated string.

The intent is to provide a simple mechanism for manipulating and "passing-around" strings rather than using error prone explicit string operations.

NOTES:

o The memory management for the string data is determined by
  the concrete sub-class!
o The 'String' class IS A Cpl::Container::Key, but it is NOT a
  Cpl::Container::xxxItem instance.  Use the 'StringItem' class
  for storing a string directly in a container.

#include <String.h>

Inheritance diagram for Cpl::Text::String:

[legend]

Collaboration diagram for Cpl::Text::String:

[legend]

Public Member Functions
virtual	~String ()
	Virtual destructor!


virtual Cpl::Text::String &	operator= (const String &string)=0
	Assignment of a string.

virtual Cpl::Text::String &	operator= (const char *string)=0
	Assignment of a string.

virtual Cpl::Text::String &	operator= (char c)=0
	Assigns the character to first position in string and then NULL terminates the string.

virtual Cpl::Text::String &	operator= (int num)=0
	Converts the 'number' to a string and stores its in the internal storage of the object.

virtual Cpl::Text::String &	operator= (unsigned int num)=0
	Converts the 'number' to a string and stores its in the internal storage of the object.

virtual Cpl::Text::String &	operator= (long num)=0
	Converts the 'number' to a string and stores its in the internal storage of the object.

virtual Cpl::Text::String &	operator= (long long num)=0
	Converts the 'number' to a string and stores its in the internal storage of the object.

virtual Cpl::Text::String &	operator= (unsigned long num)=0
	Converts the 'number' to a string and stores its in the internal storage of the object.

virtual Cpl::Text::String &	operator= (unsigned long long num)=0
	Converts the 'number' to a string and stores its in the internal storage of the object.

virtual void	copyIn (const char *string, int n)=0
	This method copies the content of the source string, up to 'n' characters, into internal storage of the object.

virtual void	insertAt (int insertOffset, const char *stringToInsert)=0
	This method inserts the specified string starting at the specified offset.

virtual void	clear ()=0
	Clears the internal string (i.e.


virtual Cpl::Text::String &	operator+= (const Cpl::Text::String &string)=0
	Append a string.

virtual Cpl::Text::String &	operator+= (const char *string)=0
	Append a string.

virtual Cpl::Text::String &	operator+= (char c)=0
	Appends the character to the end of the string.

virtual Cpl::Text::String &	operator+= (int num)=0
	Converts the 'number' to a string and appends its to the end of the string.

virtual Cpl::Text::String &	operator+= (unsigned int num)=0
	Converts the 'number' to a string and appends its to the end of the string.

virtual Cpl::Text::String &	operator+= (long num)=0
	Converts the 'number' to a string and appends its to the end of the string.

virtual Cpl::Text::String &	operator+= (long long num)=0
	Converts the 'number' to a string and appends its to the end of the string.

virtual Cpl::Text::String &	operator+= (unsigned long num)=0
	Converts the 'number' to a string and appends its to the end of the string.

virtual Cpl::Text::String &	operator+= (unsigned long long num)=0
	Converts the 'number' to a string and appends its to the end of the string.

virtual void	appendTo (const char *string, int n)=0
	This method appends the content of the source string, up to 'n' characters, into internal storage of the object.


virtual	operator char () const =0
	Cast to character -->i.e returns the first character in the string.

virtual const char *	getString () const =0
	Read-only Access to the "raw" string.

	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.


virtual int	length () const =0
	Returns the length, in bytes, of the string.

virtual int	maxLength () const =0
	Returns the max allowed size of the string.

int	availLength ()
	Returns the available space left in the internal buffer.

virtual bool	isEmpty () const =0
	Returns true if the string is empty (i.e. string[0] == '\0')

virtual bool	truncated () const =0
	Returns true if the last String "write" operation caused the String contents to be truncated.


virtual bool	operator== (const char *string) const =0
	Compares two Strings and returns true if they are equal NOTE: if 'string' is a null pointer, then false is returned.

virtual bool	operator== (const Cpl::Text::String &string) const =0
	Compares two Strings and returns true if they are equal.

virtual bool	operator!= (const char *string) const =0
	Compares two Strings and returns true if they are NOT equal NOTE: if 'string' is a null pointer, then true is returned.

virtual bool	operator!= (const Cpl::Text::String &string) const =0
	Compares two Strings and returns true if they are NOT equal.

virtual bool	isEqualIgnoreCase (const char *string) const =0
	Compares two strings independently of case and return true if equal NOTE: if 'string' is a null pointer, then false is returned.

virtual bool	operator== (char c) const =0
	Compares the specified character to the first character in the string.

virtual int	compare (const char *string) const =0
	Compares two strings and returns <0, 0, >0 if this string is less than, equal, or greater than respectively to the specified string.

virtual int	compareIgnoreCase (const char *string) const =0
	Same as compare(), but case insensitive.

virtual bool	isEqualSubstring (int startOffset, int endOffset, const char *string) const =0
	Compares the specified substring with the specified string.

virtual bool	isEqualSubstringIgnoreCase (int startOffset, int endOffset, const char *string) const =0
	Same as above, except case insensitive comparison.

virtual bool	startsWith (const char *string) const =0
	Returns true if the string starts with the specified sub-string.

virtual bool	startsWith (const char *string, int startOffset) const =0
	Sames as starsWith(), but begins the search at index 'startOffset'.

virtual bool	endsWith (const char *string) const =0
	Returns true if the string ends with the specified sub-string.


virtual int	indexOf (char c) const =0
	Returns the index of the first match for the specified character.

virtual int	indexOf (char c, int startOffset) const =0
	Same as indexOf(char), but starts at 'startOffset' instead of the beginning of the string.

virtual int	indexOf (const char *string) const =0
	Returns the index (of the starting character) of the first match for the specified sub-string.

virtual int	indexOf (const char *string, int startOffset) const =0
	Same as indexOf(const char*), but starts at 'startOffset' instead of the beginning of the string.

virtual int	lastIndexOf (char c) const =0
	Returns the index of the last match for the specified character.

virtual int	count (char c) const =0
	Returns the number of times the specified character appears in the string.


virtual void	format (const char *format,...)=0
	Allows "printf" formatting of the string.

virtual void	formatAppend (const char *format,...)=0
	Same as format() - but appends "formatting" to the end of the string.

virtual void	formatOpt (bool appendFlag, const char *format,...)=0
	This method is the same as format(), except when 'appendFlag' is true then it behaves as formatAppend().

virtual void	vformat (const char *format, va_list ap)=0
	Same as format(), except that it is called with a va_list instead of a variable number of arguments.

virtual void	vformatAppend (const char *format, va_list ap)=0
	Same as formatAppend(), except that it is called with a va_list instead of a variable number of arguments.

virtual void	vformatOpt (bool appendFlag, const char *format, va_list ap)=0
	This method is the same as vformat(), except when 'appendFlag' is true then it behaves as vformatAppend().


virtual const char *	toUpper ()=0
	Forces the entire string to upper case characters.

virtual const char *	toLower ()=0
	Forces the entire string to lower case characters.

virtual void	removeLeadingSpaces ()=0
	Removes any leading white-space from the string (white-space is defined by the standard isspace() function).

virtual void	removeTrailingSpaces ()=0
	Removes any trailing white-space from the string (white-space is defined by the standard isspace() function).

virtual void	removeLeadingChars (const char *charsSet)=0
	Removes the specified leading characters from the string.

virtual void	removeTrailingChars (const char *charsSet)=0
	Removes the specified trailing characters from the string.

virtual void	cut (int startOffset, int endOffset)=0
	Removes the characters beginning with 'startOffset' and ending with 'endOffset'.

void	trimLeft (int n)
	Removes 'n' characters from the start-of-string.

virtual void	trimRight (int n)=0
	Removes 'n' characters from the end-of-string.

virtual void	setChar (int atOffset, char newchar)=0
	Replaces the character at index 'atOffset' with 'newchar'.

virtual int	replace (char targetChar, char newChar)=0
	Replaces all instances of targetChar in the string with newChar.


virtual char *	getBuffer (int &maxAllowedLength)=0
	Returns a "writable" pointer to the string's internal storage.

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.

virtual const void *	getRawKey (unsigned *returnRawKeyLenPtr=0) const =0
	Returns the object's length (in bytes) and point to the start of key data.

Constructor & Destructor Documentation

◆ ~String()

virtual Cpl::Text::String::~String ( )

inlinevirtual

Virtual destructor!

Member Function Documentation

◆ appendTo()

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

pure virtual

This method appends the content of the source string, up to 'n' characters, into internal storage of the object.

NOTE: The internal storage is always guaranteed to be NULL terminated.

Implemented in Cpl::Text::DString, and Cpl::Text::FString_.

◆ availLength()

int Cpl::Text::String::availLength ( )

inline

Returns the available space left in the internal buffer.

The size returned does NOT include NULL terminator (i.e. if the returned size is 15, my internal storage must be at least 15+1).

◆ clear()

virtual void Cpl::Text::String::clear ( )

pure virtual

Clears the internal string (i.e.

string[0] = '\0').

Implemented in Cpl::Text::String_.

◆ compare()

virtual int Cpl::Text::String::compare ( const char * string ) const

pure virtual

Compares two strings and returns <0, 0, >0 if this string is less than, equal, or greater than respectively to the specified string.

NOTE: if 'string' is a null pointer, then -1 is returned.

Implemented in Cpl::Text::String_.

◆ compareIgnoreCase()

virtual int Cpl::Text::String::compareIgnoreCase ( const char * string ) const

pure virtual

Same as compare(), but case insensitive.

Implemented in Cpl::Text::String_.

◆ copyIn()

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

pure virtual

This method copies the content of the source string, up to 'n' characters, into internal storage of the object.

NOTE: The internal storage is always guaranteed to be NULL terminated.

Implemented in Cpl::Text::DString, and Cpl::Text::FString_.

◆ count()

virtual int Cpl::Text::String::count ( char c ) const

pure virtual

Returns the number of times the specified character appears in the string.

Implemented in Cpl::Text::String_.

◆ cut()

virtual void Cpl::Text::String::cut	(	int	startOffset,
		int	endOffset
	)

pure virtual

Removes the characters beginning with 'startOffset' and ending with 'endOffset'.

The characters after 'endOffset' are shifted left to form a continuous string. If the position fields are invalid or out-of-bounds, nothing is done.

Implemented in Cpl::Text::String_.

◆ endsWith()

virtual bool Cpl::Text::String::endsWith ( const char * string ) const

pure virtual

Returns true if the string ends with the specified sub-string.

Note: if 'string' is a null pointer, then false is returned

Implemented in Cpl::Text::String_.

◆ format()

virtual void Cpl::Text::String::format	(	const char *	format,
			...
	)

pure virtual

Allows "printf" formatting of the string.

NOTE: Since the amount of information being written to the string is variable, this method does NOT guarantee how much, if any, of the information is actually written to the string. The method does guarantee that the string's internal storage will NOT be exceeded.

NOTE: if 'format' is null, then nothing is done

Implemented in Cpl::Text::String_.

◆ formatAppend()

virtual void Cpl::Text::String::formatAppend	(	const char *	format,
			...
	)

pure virtual

Same as format() - but appends "formatting" to the end of the string.

Implemented in Cpl::Text::String_.

◆ formatOpt()

virtual void Cpl::Text::String::formatOpt	(	bool	appendFlag,
		const char *	format,
			...
	)

pure virtual

This method is the same as format(), except when 'appendFlag' is true then it behaves as formatAppend().

Implemented in Cpl::Text::String_.

◆ getBuffer()

virtual char * Cpl::Text::String::getBuffer ( int & maxAllowedLength )

pure virtual

Returns a "writable" pointer to the string's internal storage.

The caller is RESPONSIBLE for insuring that the string is left in a valid state - that is the string is NULL terminated and has NOT exceeded the 'maxAllowedLength'. Also The pointer and length have a VERY LIMITED life span - the values become invalid when any of the another string methods are called! NOTE: This method always clears the 'truncated' flags/status.

THIS METHOD SHOULD BE USED WITH EXTREME CAUTION AND AVOIDED WHENEVER POSSIBLE! ***

Implemented in Cpl::Text::String_.

◆ getString()

virtual const char * Cpl::Text::String::getString ( ) const

pure virtual

Read-only Access to the "raw" string.

Implemented in Cpl::Text::String_.

◆ indexOf() [1/4]

virtual int Cpl::Text::String::indexOf ( char c ) const

pure virtual

Returns the index of the first match for the specified character.

If no match is found, -1 is returned.

Implemented in Cpl::Text::String_.

◆ indexOf() [2/4]

virtual int Cpl::Text::String::indexOf	(	char	c,
		int	startOffset
	)		const

pure virtual

Same as indexOf(char), but starts at 'startOffset' instead of the beginning of the string.

Note: If 'startOffset' is out-of-bounds than -1 is returned.

Implemented in Cpl::Text::String_.

◆ indexOf() [3/4]

virtual int Cpl::Text::String::indexOf ( const char * string ) const

pure virtual

Returns the index (of the starting character) of the first match for the specified sub-string.

If no match is found, -1 is returned.

Note: If 'string' is null, then -1 is returned

Implemented in Cpl::Text::String_.

◆ indexOf() [4/4]

virtual int Cpl::Text::String::indexOf	(	const char *	string,
		int	startOffset
	)		const

pure virtual

Same as indexOf(const char*), but starts at 'startOffset' instead of the beginning of the string.

Note: If 'string' is null or 'startOffset' is out-of-bounds than -1 is returned.

Implemented in Cpl::Text::String_.

◆ insertAt()

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

pure virtual

This method inserts the specified string starting at the specified offset.

The original contents of the string beginning with 'insertOffset' is "shifted to the right" to make room for the string being inserted. If an attempt is made to insert the string past the current end-of-string, then the stringToInsert is simply appended. If an attempt is made to insert the string at a negative offset, then the stringToInsert is prepended to the string.

Implemented in Cpl::Text::DString, and Cpl::Text::FString_.

◆ isEmpty()

virtual bool Cpl::Text::String::isEmpty ( ) const

pure virtual

Returns true if the string is empty (i.e. string[0] == '\0')

Implemented in Cpl::Text::String_.

◆ isEqualIgnoreCase()

virtual bool Cpl::Text::String::isEqualIgnoreCase ( const char * string ) const

pure virtual

Compares two strings independently of case and return true if equal NOTE: if 'string' is a null pointer, then false is returned.

Implemented in Cpl::Text::String_.

◆ isEqualSubstring()

virtual bool Cpl::Text::String::isEqualSubstring	(	int	startOffset,
		int	endOffset,
		const char *	string
	)		const

pure virtual

Compares the specified substring with the specified string.

Substring is inclusive of the endpoints. If the endpoints are out-of-range, they are clamped by the actual bounds of the string. Position parameters are zero-based indexes into this String object. NOTE: if 'string' is a null pointer, then false is returned.

Implemented in Cpl::Text::String_.

◆ isEqualSubstringIgnoreCase()

virtual bool Cpl::Text::String::isEqualSubstringIgnoreCase	(	int	startOffset,
		int	endOffset,
		const char *	string
	)		const

pure virtual

Same as above, except case insensitive comparison.

Implemented in Cpl::Text::String_.

◆ lastIndexOf()

virtual int Cpl::Text::String::lastIndexOf ( char c ) const

pure virtual

Returns the index of the last match for the specified character.

If no match is found, -1 is returned.

Implemented in Cpl::Text::String_.

◆ length()

virtual int Cpl::Text::String::length ( ) const

pure virtual

Returns the length, in bytes, of the string.

The size returned does NOT include NULL terminator (i.e. if the returned size is 15, my internal storage must be at least 15+1)

Implemented in Cpl::Text::String_.

◆ maxLength()

virtual int Cpl::Text::String::maxLength ( ) const

pure virtual

Returns the max allowed size of the string.

The size returned does NOT include NULL terminator (i.e. if the returned size is 15, my internal storage must be at least 15+1)

Implemented in Cpl::Text::DString, and Cpl::Text::FString_.

◆ operator char()

virtual Cpl::Text::String::operator char ( ) const

pure virtual

Cast to character -->i.e returns the first character in the string.

Implemented in Cpl::Text::String_.

◆ operator const char *()

Cpl::Text::String::operator const char * ( ) const

inline

Cast to read-only character string pointer.

◆ operator!=() [1/2]

virtual bool Cpl::Text::String::operator!= ( const char * string ) const

pure virtual

Compares two Strings and returns true if they are NOT equal NOTE: if 'string' is a null pointer, then true is returned.

Implemented in Cpl::Text::String_.

◆ operator!=() [2/2]

virtual bool Cpl::Text::String::operator!= ( const Cpl::Text::String & string ) const

pure virtual

Compares two Strings and returns true if they are NOT equal.

Implemented in Cpl::Text::String_.

◆ operator()()

const char * Cpl::Text::String::operator() ( ) const

inline

Returns a Read-only pointer to the "raw" (short-hand for getString())

◆ operator+=() [1/9]

virtual Cpl::Text::String & Cpl::Text::String::operator+= ( char c )

pure virtual

Appends the character to the end of the string.

Implemented in Cpl::Text::String_.

◆ operator+=() [2/9]

virtual Cpl::Text::String & Cpl::Text::String::operator+= ( const char * string )

pure virtual

Append a string.

The argument string is concatenated to the end of the string object.

Implemented in Cpl::Text::String_.

◆ operator+=() [3/9]

virtual Cpl::Text::String & Cpl::Text::String::operator+= ( const Cpl::Text::String & string )

pure virtual

Append a string.

The argument string is concatenated to the end of the string object.

Implemented in Cpl::Text::String_.

◆ operator+=() [4/9]

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

pure virtual

Converts the 'number' to a string and appends its to the end of the string.

Implemented in Cpl::Text::DString, and Cpl::Text::FString_.

◆ operator+=() [5/9]

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

pure virtual

Converts the 'number' to a string and appends its to the end of the string.

Implemented in Cpl::Text::DString, and Cpl::Text::FString_.

◆ operator+=() [6/9]

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

pure virtual

Converts the 'number' to a string and appends its to the end of the string.

Implemented in Cpl::Text::DString, and Cpl::Text::FString_.

◆ operator+=() [7/9]

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

pure virtual

Converts the 'number' to a string and appends its to the end of the string.

Implemented in Cpl::Text::DString, and Cpl::Text::FString_.

◆ operator+=() [8/9]

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

pure virtual

Converts the 'number' to a string and appends its to the end of the string.

Implemented in Cpl::Text::DString, and Cpl::Text::FString_.

◆ operator+=() [9/9]

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

pure virtual

Converts the 'number' to a string and appends its to the end of the string.

Implemented in Cpl::Text::DString, and Cpl::Text::FString_.

◆ operator=() [1/9]

virtual Cpl::Text::String & Cpl::Text::String::operator= ( char c )

pure virtual

Assigns the character to first position in string and then NULL terminates the string.

Implemented in Cpl::Text::String_.

◆ operator=() [2/9]

virtual Cpl::Text::String & Cpl::Text::String::operator= ( const char * string )

pure virtual

Assignment of a string.

The argument string is copied to the internal storage of the object.

Implemented in Cpl::Text::String_.

◆ operator=() [3/9]

virtual Cpl::Text::String & Cpl::Text::String::operator= ( const String & string )

pure virtual

Assignment of a string.

The argument string is copied to the internal storage of the object.

Implemented in Cpl::Text::String_.