String

String
Object-oriented string manipulation and management

Description

The String class encapsulates and manages regular C null-terminated byte arrays, taking care of memory management and pointer assignments. String objects enable C/C++ developers to manipulate strings as easily as if using other higher-level languages. Like the rest of html++, the String class is completely self-contained and does not rely on any external libraries or non-standard features of C++, making it suitable for all supported platforms.

Methods similar to those in the Basic language, such a Left, Mid, and Right, are provided. Among other features, the String class overrides the + and - operators, making string concatenation and removal as simple as addition and subtraction.

Methods are provided to make conversion to and from regular C strings convenient and efficient. Numeric values are easily accomodated, as methods are provided for converting all standard numeric data types to/from their text equivalents.

Formatting strings is particularly easy using the Format() method, which works similarly to the standard C library sprintf routine. One advantage of using Format() is that is eliminates the need to create a temporary local variables for use with sprintf.

The class also provides a handy parsing/tokenization feature via GetNextToken(), which can parse strings using single-character or multi-character delimiters. GetNextToken() automatically interprets quoted text as single tokens.

Declaration

#include <dcmicro/htmlpp/stringpp.h>

Hierarchy

See Also

Tutorial: Using html++: Strings

Class Constants/Definitions

enum   NO_SUBSTRING = -1

Related Constants/Definitions

None.

Constructors

String()

Constructs an empty string.

String( const short number )

String( const int number )

String( const long number )

String( const double number )

Constructs a string, converting the numeric value to text.

String( const char c )

Construct a string from a single character.

String( const char FAR * buffer )

Constructs a string from a null-terminated char * array of bytes.

String( const String& rhs )

Copy constructor.

Destructors

virtual ~String( void )

Destroys the string object.

Assignment Operators

=    String& operator= ( const String& rhs )

Replaces the string contents with a copy of rhs, and returns a reference to the string object.

=    String& operator= ( const char number )

   String& operator= ( const short number )

   String& operator= ( const int number )

   String& operator= ( const long number )

   String& operator= ( const double number )

Replaces the string contents with a text version of the supplied number, and returns a reference to the string object.

In-place Concatenation Operators

+=    String& operator+= ( const String& s )

+=    String& operator+= ( const char * s )

Appends string s, and returns a refererence to the string object.

+=    String& operator+= ( const int c )

+=    String& operator+= ( const char c )

Appends a single character c to the string, and returns a reference to the string object.

In-place Removal Operators

-=    String& operator-= ( const String& s )

-=    String& operator-= ( const char * s )

Search the string, from left to right, for substring s and remove it. Returns a refererence to the string object.

-=    String& operator-= ( const int c )

-=    String& operator-= ( const char c )

Search the string, from left to right, for character c and remove it. Returns a refererence to the string object.

Substring Operator

( )    String operator() ( const int start, const int number_of_chars ) const

Extract the substring, beginning at start (zero-based index) and of length number_of_chars, returning it as a new string. Functionally equivalent to the Mid() method.

Substring Functions

Left    String Left( const int number_of_chars ) const

Extract the leftmost number_of_chars of the string, and return it as a new string.

Mid    String Mid( const int start, const int number_of_chars ) const

Extract the substring, beginning at start (zero-based index) and of length number_of_chars, returning it as a new string. Functionally equivalent to the () operator.

Right    String Right( const int number_of_chars ) const

Extract the rightmost number_of_chars of the string, and return it as a new string.

Character Index Operators

[ ]    char operator[] ( const int position )

[ ]    const char& operator[] ( const int position ) const

Access the single character with the string, located at position offset (zero-based).

Implicit Casting Operators

char * operator char FAR * ( void )

const char * operator const char FAR * ( void ) const

Returns a pointer to the start of the internal null-terminated buffer used to store the string contents. To allocate a copy of the string buffer, refer to the GetString() method below.

Access Functions

Format String Format( char FAR * format, ... )

Performs in-place formatting of the string contents in the same way that sprintf formats data in a C-style character array, returning a copy of the result. format must be a char * array compatible with C-language sprintf formatting conventions. A variable number of arguments may follow format, as they would in a regular sprintf function call. When you pass a character string as an optional argument, you must explicitly cast it as (char *) -- do not pass String objects directly as optional arguments.

GetString char FAR * GetString( void ) const

Allocates a char * buffer of sufficient size, copies the string contents as a null-terminated array of bytes, then returns a pointer to the newly allocated buffer. It is the responsibility of the calling application to release the buffer using delete. To obtain a pointer to the string buffer without allocating new memory, use the (char *) casting operator.

GetLength int GetLength( void ) const

Returns the number of characters in the string.

HasSubstring int HasSubstring( const String& s ) const

Searches for substring s in string. If found, returns zero-based index of first character of s in string, otherwise String::NO_SUBSTRING (-1) is returned.

Contains int Contains( const String& s ) const

Contains int Contains( const char& c ) const

Searches for substring s or character c in string. If found, returns one-based offset of location in string. Otherwise, zero is returned.

IsNumeric Boolean IsNumeric( void ) const

Returns TRUE if the string is comprised of only digits, a decimal point, spaces, or the + or - characters. Otherwise, returns FALSE.

AsInt    int AsInt( void ) const

Returns the value of the string as an integer, or zero if the string is not numeric.

AsLong long AsLong( void ) const

Returns the value of the string as a long integer, or zero if the string is not numeric.

AsDouble double AsDouble( void ) const

Returns the value of the string as a double, or zero if the string is not numeric.

ToLower String& ToLower( void )

ToUpper String& ToUpper( void )

Converts the string to all lower or upperase, respectively, then returns a reference to it.

AsLower String AsLower( void )

AsUpper String AsUpper( void )

Creates an upper or lowercase copy of the string contents as a new String object.

RTrim String& RTrim( char trim_character = ' ' )

LTrim String& LTrim( char trim_character = ' ' )

Removes all consecutive occurances of trim_character (the default is a space character) from the right or left side of the string, then returns a reference to it. trim_character can be any character, including newline '\n'.

Parsing/Tokenization

GetNextToken String GetNextToken()

Searches the string for the next space, removes all characters to the left of it, and returns those characters as a new string.

GetNextToken String GetNextToken( const String& separator )

Searches the string for the next occurance of separator, removes all characters to the left of it, and returns those characters as a new string.

Concatenation and Subtraction

+    friend String operator+ ( const String& s1, const String& s2 )

+    friend String operator+ ( const String& s1, const char * s2 )

Appends the string on the right side of the expression to the string on the left side, returning the result as a new string object.

-    friend String operator- ( const String& s1, const String& s2 )

-    friend String operator- ( const String& s1, const char * s2 )

Removes the string on the right side of the expression from the string on the left side, returning the result as a new string object.



Comparison Operators

==    int operator==( const String& s1, char * s2)

==    int operator==( const String& s1, const char * s2)

==    int operator==( const String& s1, const String& s2)

Perform a byte-by-byte comparison of the string on the left side of the expression to the string (or null-terminated buffer) on the right side. If the contents are identical, TRUE is returned. If the contents differ, FALSE is returned.

!=    int operator!=( const String& s1, char * s2)

!=    int operator!=( const String& s1, const char * s2)

!=    int operator!=( const String& s1, const String& s2)

Perform a byte-by-byte comparison of the string on the left side of the expression to the string (or null-terminated buffer) on the right side. If the contents are different, TRUE is returned. If the contents are identical, FALSE is returned.

<    int operator< (const String& s1, const String& s2)

Perform a byte-by-byte comparison of the string on the left side of the expression to the string on the right side. If s1 is less than s2, TRUE is returned. Otherwise, FALSE is returned.

<=    int operator<= (const String& s1, const String& s2)

Perform a byte-by-byte comparison of the string on the left side of the expression to the string on the right side. If s1 is less than or equal to s2, TRUE is returned. Otherwise, FALSE is returned.

>    int operator> (const String& s1, const String& s2)

Perform a byte-by-byte comparison of the string on the left side of the expression to the string on the right side. If s1 is greater than s2, TRUE is returned. Otherwise, FALSE is returned.

>=    int operator>= (const String& s1, const String& s2)

Perform a byte-by-byte comparison of the string on the left side of the expression to the string on the right side. If s1 is greater than or equal to s2, TRUE is returned. Otherwise, FALSE is returned.

Stream I/O Operators

<<    String& operator<< ( const String& text )

Insert (append) the string text into the string, and return a reference to the string.

<<    ostream& operator<< (ostream& os, const String& s )

Output the contents of string s to the output stream os, returning a reference to the output stream.

>>    istream& operator>> ( istream& is, String& s )

Input data from stream is into string s (append), stopping when a newline '\n' character is reached (limit 255 characters).

Example Use

#include <stdio.h>

#include <stdlib.h>

#include <dcmicro/htmlpp/htmlpp.h>

//

//  This example exercises the String class,

//  illustrating use of many of it's methods.

//

void main( void )

{

    String s ;



    s = "abcd" ;

    //  use regular C++ I/O streams

    cout << "\n\nstring: " << s << "\n" ;



    //  display contents using pointer to string contents

    cout << "string = '" << s << "'\n" ;

    //  compare with a literal

    if ( s == "abcd" )

        cout << "strings are same\n" ;

    else

        cout << "strings are different\n" ;



    //  make a copy, then compare to original

    String   s2 = s ;

    if ( s2 == s )

        cout << "strings are same\n" ;

    else

        cout << "strings are different\n" ;

    //  make a change, then compare again

    s2 += "efgh" ;

    if ( s2 == s )

        cout << "strings are same\n" ;

    else

        cout << "strings are different\n" ;

    //  work with numbers

    s = 120 ;

    s2 = 4.5 ;

    cout << "'" << s << "'    '" << s2 << "'\n" ;

    if ( s2 == s )

        cout << "strings are same\n" ;

    else

        cout << "strings are different\n" ;

    //  concatenate

    cout << "s + s2 = '"

         << String( s + s2 ) << "'\n" ;

    //  allocate a copy using a pointer

    char * copy_ptr = s.GetString() ;

    cout << "Copy is '" << copy_ptr << "'\n" ;

    delete copy_ptr ;   //  release the memory

    // convert to uppercase

    s = "aBcDeF 1234" ;

    s.ToUpper() ;

    cout << "uppercase: '" << s << "'\n" ;

    // convert to lowercase

    s.ToLower() ;

    cout << "lowercase: '" << s << "'\n" ;

    //  substring operations

    s = "0123456789" ;

    String  sub = s( 0, 1 ) ;

    cout << "s = '" << s << "'\n" ;

    cout << "sub = '" << sub << "'\n" ;

   //  string removal

    s -= "0" ;

    cout << "s -= \"0\"  =  '" << s << "'\n" ;

    s -= "9" ;

    cout << "s -= \"9\"  =  '" << s << "'\n" ;

   //  midstring operations

    cout << "Left = '" << s.Left( 3 ) << "'\n"

         << "Mid = '" << s.Mid( 4, 3 ) << "'\n"

         << "Right = '" << s.Right( 3 ) << "'\n" ;

    s = s - String( "345" ) ;

    cout << "after removal: '" << s << "'\n" ;

    //  index operations

    int i ;

    for ( i = 0 ; i < s.GetLength() ; i++ )

        cout << s[ i ] << " " ;

    cout << "\n" ;

    //  trim spaces from the left

    s.LTrim() ;

    cout << "LTrim(): '" << s << "'\n" ;

    //  trim non-space characters from the left

    s.LTrim( '1' ) ;

    cout << "LTrim('1'): '" << s << "'\n" ;

    //  trim the '8' from the right

    s.RTrim( '8' ) ;

    cout << "RTrim('8'): '" << s << "'\n" ;

    //  empty string

    String test ;

    cout << "empty string: '" << test << "'\n" ;

    // string parsing

    cout << "Parsing test\n" ;

    test = "This is a test of \"quoted material\" processing." ;

    s = test.GetNextToken() ;

    while ( s != "" )

    {

        cout << "  " << s << "\n" ;

        s = test.GetNextToken() ;

    }

    //  Use the Format() method to format a few values.

    //  Note you don't have to create a local buffer

   //  or use sprintf.

    cout << "Date format test:   "

         << s.Format( "%02d/%02d/%04d\n", 1, 1, 1998 ) ;

   cout << "Double format test:   "

         << s.Format( "%s %7.02f\n", "the value is", 12.45 ) ;

   //  You can use String's with printf by simply

   //  casting the object to a (char *)

   s = "String works with printf, too" ;

   printf( "\n%s\n", (char *) s ) ;

}

Program Output

string: abcd

string = 'abcd'

strings are same

strings are same

strings are different

'120'    '4.500000'

strings are different

s + s2 = '1204.500000'

Copy is '120'

uppercase: 'ABCDEF 1234'

lowercase: 'abcdef 1234'

s = '0123456789'

sub = '0'

s -= "0"  =  '123456789'

s -= "9"  =  '12345678'

Left = '123'

Mid = '567'

Right = '678'

after removal: '12678'

1 2 6 7 8

LTrim(): '12678'

LTrim('1'): '2678'

RTrim('8'): '267'

empty string: 'NullString'

Parsing test

  This

  is

  a

  test

  of

  "quoted material"

  processing.

Date format test:   01/01/1998

Double format test:   the value is   12.45

String works with printf, too

©1998 DC Micro Development. All rights reserved.
No portion of this document may be c opied or reproduced without expressed written consent.
html++ is a trademark of DC Micro Development.

	The String class encapsulates and manages regular C null-terminated byte arrays, taking care of memory management and pointer assignments. String objects enable C/C++ developers to manipulate strings as easily as if using other higher-level languages. Like the rest of html++, the String class is completely self-contained and does not rely on any external libraries or non-standard features of C++, making it suitable for all supported platforms.

	Methods similar to those in the Basic language, such a Left, Mid, and Right, are provided. Among other features, the String class overrides the + and - operators, making string concatenation and removal as simple as addition and subtraction.

	Methods are provided to make conversion to and from regular C strings convenient and efficient. Numeric values are easily accomodated, as methods are provided for converting all standard numeric data types to/from their text equivalents.

	Formatting strings is particularly easy using the Format() method, which works similarly to the standard C library sprintf routine. One advantage of using Format() is that is eliminates the need to create a temporary local variables for use with sprintf.

	The class also provides a handy parsing/tokenization feature via GetNextToken(), which can parse strings using single-character or multi-character delimiters. GetNextToken() automatically interprets quoted text as single tokens.

	String( const short *number* )
	String( const int *number* )
	String( const long *number* )
	String( const double *number* )

	Constructs a string from a null-terminated char * array of bytes.

	Replaces the string contents with a copy of rhs, and returns a reference to the string object.

	=	String& operator= ( const char *number* )
		String& operator= ( const short *number* )
		String& operator= ( const int *number* )
		String& operator= ( const long *number* )
		String& operator= ( const double *number* )

	Replaces the string contents with a text version of the supplied number, and returns a reference to the string object.

	+=	String& operator+= ( const String& s )
	+=	String& operator+= ( const char * s )

	Appends string s, and returns a refererence to the string object.

	+=	String& operator+= ( const int c )
	+=	String& operator+= ( const char c )

	Appends a single character c to the string, and returns a reference to the string object.

	-=	String& operator-= ( const String& s )
	-=	String& operator-= ( const char * s )

	Search the string, from left to right, for substring s and remove it. Returns a refererence to the string object.

	-=	String& operator-= ( const int c )
	-=	String& operator-= ( const char c )

	( )	String operator() ( const int *start, const int number_of_chars* ) const

	Extract the substring, beginning at start (zero-based index) and of length number_of_chars, returning it as a new string. Functionally equivalent to the Mid() method.

	Left	String Left( const int *number_of_chars* ) const

	Extract the leftmost number_of_chars of the string, and return it as a new string.

	Mid	String Mid( const int *start, const int number_of_chars* ) const

	Right	String Right( const int *number_of_chars* ) const

	Extract the rightmost number_of_chars of the string, and return it as a new string.

	[ ]	char operator[] ( const int *position* )
	[ ]	const char& operator[] ( const int *position* ) const

	Access the single character with the string, located at position offset (zero-based).

	char *	operator char FAR * ( void )
	const char *	operator const char FAR * ( void ) const

	Returns a pointer to the start of the internal null-terminated buffer used to store the string contents. To allocate a copy of the string buffer, refer to the GetString() method below.

	Performs in-place formatting of the string contents in the same way that sprintf formats data in a C-style character array, returning a copy of the result. format must be a char * array compatible with C-language sprintf formatting conventions. A variable number of arguments may follow format, as they would in a regular sprintf function call. When you pass a character string as an optional argument, you must explicitly cast it as (char *) -- do not pass String objects directly as optional arguments.

	Allocates a char * buffer of sufficient size, copies the string contents as a null-terminated array of bytes, then returns a pointer to the newly allocated buffer. It is the responsibility of the calling application to release the buffer using delete. To obtain a pointer to the string buffer without allocating new memory, use the (char *) casting operator.

	Searches for substring s in string. If found, returns zero-based index of first character of s in string, otherwise String::NO_SUBSTRING (-1) is returned.

	Contains	int Contains( const String& s ) const
	Contains	int Contains( const char& c ) const

	Searches for substring s or character c in string. If found, returns one-based offset of location in string. Otherwise, zero is returned.

	Returns TRUE if the string is comprised of only digits, a decimal point, spaces, or the + or - characters. Otherwise, returns FALSE.