String Class

Declared:

string.hpp

The String class is used to store arbitrarily long sequences of characters in memory. Objects of this type may be concatenated, substringed, compared and searched without the need for memory management by the user. Unlike a C string, a String object has no delimiting character, so any character in the collating sequence, or character set, may be stored in a String object.

Public Functions

The following constructors and destructors are declared:

String();
String( size_t, capacity );
String( String const &, size_t = 0, size_t = NPOS );
String( char const *, size_t = NPOS );
String( char, size_t = 1 );
~String();

The following member functions are declared:

operator char const *();
operator char() const;
String     &operator  =( String const & );
String     &operator  =( char const * );
String     &operator +=( String const & );
String     &operator +=( char const * );
String  operator ()( size_t, size_t ) const;
char       &operator ()( size_t );
char const &operator [ ]( size_t ) const;
char       &operator [ ]( size_t );
int       operator  !() const;
size_t length() const;
char const &get_at( size_t ) const;
void        put_at( size_t, char );
int      match( String const & ) const;
int      match( char const * ) const;
int      index( String const &, size_t = 0 ) const;
int      index( char const *, size_t = 0 ) const;
String upper() const;
String lower() const;
int      valid() const;
int      alloc_mult_size() const;
int      alloc_mult_size( int );

The following friend functions are declared:

friend int operator ==( String const &, String const & );
friend int operator ==( String const &, char const * );
friend int operator ==( char const *, String const & );
friend int operator ==( String const &, char         );
friend int operator ==( char, String const & );

friend int operator !=( String const &, String const & );
friend int operator !=( String const &, char const * );
friend int operator !=( char const *, String const & );
friend int operator !=( String const &, char         );
friend int operator !=( char        , String const & );

friend int operator <( String const &, String const & );
friend int operator <( String const &, char const * );
friend int operator <( char const *, String const & );
friend int operator <( String const &, char         );
friend int operator <( char        , String const & );

friend int operator <=( String const &, String const & );
friend int operator <=( String const &, char const * );
friend int operator <=( char const *, String const & );
friend int operator <=( String const &, char         );
friend int operator <=( char        , String const & );

friend int operator  >( String const &, String const & );
friend int operator  >( String const &, char const * );
friend int operator  >( char const *, String const & );
friend int operator  >( String const &, char         );
friend int operator  >( char        , String const & );

friend int operator >=( String const &, String const & );
friend int operator >=( String const &, char const * );
friend int operator >=( char const *, String const & );
friend int operator >=( String const &, char         );
friend int operator >=( char        , String const & );

friend String operator  +(        String &, String const & );
friend String operator  +(        String &, char const * );
friend String operator  +( char const *, String const & );
friend String operator  +(        String &, char         );
friend String operator  +( char        , String const & );

friend int valid( String const & );

The following I/O Stream inserter and extractor functions are declared:

friend istream &operator >>( istream &, String & );
friend ostream &operator <<( ostream &, String const & );

String::alloc_mult_size()

query and/or change the allocation multiple size

Synopsis:

#include <string.hpp>
public:
int String::alloc_mult_size() const;
int String::alloc_mult_size( int mult );

Semantics:

The alloc_mult_size() public member function is used to query and/or change the allocation multiple size.

The first form of the alloc_mult_size() public member function queries the current setting.

The second form of the function sets the value to a multiple of 8 based on the mult parameter. The value of mult is rounded down to a multiple of 8 characters. If mult is less than 8, the new multiple size is 1, and allocation sizes are exact.

The scheme used to store a String object allocates the memory for the characters in multiples of some size. By default, this size is 8 characters. For example, a String object with a length of 10 actually has 16 characters of storage allocated for it. Concatenating more characters on the end of the String object only allocates a new storage block if more than 6 (16-10) characters are appended. This scheme tries to find a balance between reallocating frequently (multiples of a small value) and creating a large amount of unused space (multiples of a large value).

Results:

The alloc_mult_size() public member function returns the previous allocation multiple size.

String::get_at()

get a constant reference to a character in the string

Synopsis:

#include <string.hpp>
public:
char const &String::get_at( size_t pos );

Semantics:

The get_at() public member function creates a constant reference to the character at offset pos within the String object. This reference may not be used to modify that character. The first character of a String object is at position zero.

If pos is greater than or equal to the length of the String object, and the resulting reference is used, the behavior is undefined.

The reference is associated with the String object, and therefore has meaning only as long as the String object isn't modified (or destroyed). If the String object has been modified and an old reference is used, the behavior is undefined.

Results:

The get_at() public member function returns a constant reference to a character.

String::index()

find the index of a substring in the string

Synopsis:

#include <string.hpp>
public:
int String::index( String const &str, 
                   size_t pos = 0 ) const;
int String::index( char const   *pch, 
                   size_t pos = 0 ) const;

Semantics:

The index() public member function computes the offset at which a sequence of characters in the String object is found.

The first form searches the String object for the contents of the str String object.

The second form searches the String object for the sequence of characters pointed at by pch.

If pos is specified, the search begins at that offset from the start of the String object. Otherwise, the search begins at offset zero (the first character).

Uppercase and lowercase letters aren't considered to be equal.

Results:

The index() public member function returns the offset at which the sequence of characters is found. If the substring isn't found, -1 is returned.

String::length()

calculate the length of the string

Synopsis:

#include <string.hpp>
public:
size_t String::length() const;

Semantics:

The length() public member function computes the number of characters contained in the String object.

Results:

This function returns the number of characters contained in the String object.

String::lower()

create a lowercase version of a string

Synopsis:

#include <string.hpp>
public:
String String::lower() const;

Semantics:

The lower() public member function creates a String object whose value is the same as the original object's value, except that all upper-case letters have been converted to lower-case.

Results:

The lower() public member function returns a lower-case String object.

String::match()

compare two character sequences

Synopsis:

#include <string.hpp>
public:
int String::match( String const &str ) const;
int String::match( char const *pch ) const;

Semantics:

The match() public member function compares two character sequences to find the offset where they differ.

The first form compares the String object to the str String object.

The second form compares the String object to the pch C string.

The first character is at offset zero. Uppercase and lowercase letters aren't considered to be equal.

Results:

The match() public member function returns the offset at which the two character sequences differ. If the character sequences are equal, -1 is returned.

String::operator !()

test the validity of the string

Synopsis:

#include <string.hpp>
public:
int String::operator !() const;

Semantics:

The operator !() public member function tests the validity of the String object.

Results:

The operator !() public member function returns a non-zero value if the String object is invalid, otherwise zero is returned.

String::operator !=()

see if one string is not equal to another

Synopsis:

#include <string.hpp>
public:
friend int operator !=( String const &lft,
                        String const &rht );
friend int operator !=( String const &lft,
                        char const   *rht );
friend int operator !=( char const   *lft,
                        String const &rht );
friend int operator !=( String const &lft,
                        char         rht );
friend int operator !=( char         lft,
                        String const &rht );

Semantics:

The operator !=() function compares two sequences of characters in terms of an inequality relationship:

A String object is different from another String object if the lengths are different, or they contain different sequences of characters.
A String object and a C string are different if their lengths are different, or they contain a different sequence of characters. A C string is terminated by a null character.
A String object and a character are different if the String object doesn't contain only the character.

Uppercase and lowercase characters are considered to be different.

Results:

The operator !=() function returns a non-zero value if the lengths or sequences of characters in the lft and rht parameter are different, otherwise zero is returned.

String::operator ()()

reference a character or string at a given offset in the string

Synopsis:

#include <string.hpp>
public:
char &String::operator ()( size_t pos );
String String::operator ()( size_t pos, 
                            size_t len ) const;

Semantics:

There are two forms of the operator ()() public member function:

The first form creates a reference to the character at offset pos within the String object. This reference may be used to modify that character. The first character of a String object is at position zero.
If pos is greater than or equal to the length of the String object, and the resulting reference is used, the behavior is undefined.
If the reference is used to modify other characters in the String object, the behavior is undefined.
The reference is associated with the String object, and therefore has meaning only as long as the String object isn't modified (or destroyed). If the String object has been modified and an old reference is used, the behavior is undefined.
The second form extracts a subsequence of characters from the String object. A new String object is created that contains the subsequence of characters. The subsequence begins at offset pos within the String object, and continues for len characters. The first character of a String object is at position zero.
If pos is greater than or equal to the length of the String object, the result is empty.
If len is such that pos + len exceeds the length of the object, the result is the subsequence of characters from the String object starting at offset pos, and running to the end of the String object.

Results:

The first form of the operator ()() public member function returns a reference to a character.
The operator ()() public member function returns a String object.

String::operator +()

concatenate two sequences of characters

Synopsis:

#include <string.hpp>
public:
friend String operator +( String       &lft,
                          String const &rht );
friend String operator +( String       &lft,
                          char const   *rht );
friend String operator +( char const   *lft,
                          String const &rht );
friend String operator +( String       &lft,
                          char         rht );
friend String operator +( char         lft,
                          String const &rht );

Semantics:

The operator +() function concatenates two sequences of characters into a new String object. The new String object contains the sequence of characters from the lft parameter, followed by the sequence of characters from the rht parameter.

A NULL pointer to a C string is treated as a pointer to an empty C string.

Results:

The operator +() function returns a new String object that contains the characters from the lft parameter, followed by the characters from the rht parameter.

String::operator +=()

append some characters to a string

Synopsis:

#include <string.hpp>
public:
String &String::operator +=( String const &str );
String &String::operator +=( char const    *pch );

Semantics:

The operator +=() public member function appends the contents of the parameter to the String object.

The first form of the operator +=() public member function appends the contents of the str String object to the String object.

The second form appends the null-terminated sequence of characters stored at pch to the String object. If the pch parameter is NULL, nothing is appended.

Results:

The operator +=() public member function returns a reference to the String object that was the target of the assignment.

String::operator <()

see if one string is less than another

Synopsis:

#include <string.hpp>
public:
friend int operator <( String const &lft, 
                       String const &rht );
friend int operator <( String const &lft, 
                       char const   *rht );
friend int operator <( char const   *lft, 
                       String const &rht );
friend int operator <( String const &lft, 
                       char         rht );
friend int operator <( char          lft, 
                       String const &rht );

Semantics:

The operator <() function compares two sequences of characters in terms of a less-than relationship.

lft is less than rht if the characters of lft occur before the characters of rht in the collating sequence. Upper-case and lower-case characters are considered to be different.

Results:

The operator <() function returns a non-zero value if the lft sequence of characters is less than the rht sequence, otherwise zero is returned.

String::operator <<()

write the string

Synopsis:

#include <string.hpp>
public:
friend ostream &operator <<( ostream &strm,
                             String const &str );

Semantics:

The operator <<() function is used to write the sequence of characters in the str String object to the strm ostream object. Like C strings, the value of the str String object is written to strm without the addition of any characters. No special processing occurs for any characters in the String object that have special meaning for the strm object, such as carriage-returns.

Results:

The operator <<() function returns a reference to the strm parameter.

String::operator <=()

see if one string is less than or equal to another

Synopsis:

#include <string.hpp>
public:
friend int operator <=( String const &lft,
                        String const &rht );
friend int operator <=( String const &lft,
                        char const   *rht );
friend int operator <=( char const   *lft,
                        String const &rht );
friend int operator <=( String const &lft,
                        char        rht );
friend int operator <=( char        lft,
                        String const &rht );

Semantics:

The operator <=() function compares two sequences of characters in terms of a less-than-or-equal relationship.

lft is less than or equal to rht if the characters of lft are equal to or occur before the characters of rht in the collating sequence. Upper-case and lower-case characters are considered to be different.

Results:

The operator <=() function returns a non-zero value if the lft sequence of characters is less than or equal to the rht sequence, otherwise zero is returned.

String::operator =()

assign a sequence of characters to the string

Synopsis:

#include <string.hpp>
public:
String &String::operator =( String const &str );
String &String::operator =( char const   *pch );

Semantics:

The operator =() public member function sets the contents of the String object to be the same as the parameter.

The first form of the operator =() public member function sets the value of the String object to be the same as the value of the str String object.

The second form sets the value of the String object to the null-terminated sequence of characters stored at pch. If the pch parameter is NULL, the String object is empty.

Results:

The operator =() public member function returns a reference to the String object that was the target of the assignment.

String::operator ==()

see if two strings are equivalent

Synopsis:

#include <string.hpp>
public:
friend int operator ==( String const &lft,
                        String const &rht );
friend int operator ==( String const &lft,
                        char const   *rht );
friend int operator ==( char const   *lft,
                        String const &rht );
friend int operator ==( String const &lft,
                        char        rht );
friend int operator ==( char         lft,
                        String const &rht );

Semantics:

The operator ==() function compares two sequences of characters in terms of an equality relationship:

A String object is equal to another String object if they have the same length, and they contain the same sequence of characters.
A String object and a C string are equal if their lengths are the same, and they contain the same sequence of characters. The C string is terminated by a null character.
A String object and a character are equal if the String object contains only that character.

Upper-case and lower-case characters are considered to be different.

Results:

The operator ==() function returns a non-zero value if the lengths and sequences of characters in the lft and rht parameter are identical, otherwise zero is returned.

String::operator >()

see if one string is greater than another

Synopsis:

#include <string.hpp>
public:
friend int operator >( String const &lft, 
                       String const &rht );
friend int operator >( String const &lft, 
                       char const   *rht );
friend int operator >( char const   *lft, 
                       String const &rht );
friend int operator >( String const &lft, 
                       char         rht );
friend int operator >( char          lft, 
                       String const &rht );

Semantics:

The operator >() function compares two sequences of characters in terms of a greater-than relationship.

lft is greater-than rht if the characters of lft occur after the characters of rht in the collating sequence. Upper-case and lower-case characters are considered to be different.

Results:

The operator >() function returns a non-zero value if the lft sequence of characters is greater than the rht sequence, otherwise zero is returned.

String::operator >=()

see if one string is greater than or equal to another

Synopsis:

#include <string.hpp>
public:
friend int operator >=( String const &lft,
                        String const &rht );
friend int operator >=( String const &lft,
                        char const   *rht );
friend int operator >=( char const   *lft,
                        String const &rht );
friend int operator >=( String const &lft,
                        char         rht );
friend int operator >=( char         lft,
                        String const &rht );

Semantics:

The operator >=() function compares two sequences of characters in terms of a greater-than or equal relationship.

lft is greater-than or equal to rht if the characters of lft are equal to or occur after the characters of rht in the collating sequence. Upper-case and lower-case characters are considered to be different.

Results:

The operator >=() function returns a non-zero value if the lft sequence of characters is greater than or equal to the rht sequence, otherwise zero is returned.

String::operator >>()

read a sequence of characters into a string

Synopsis:

#include <string.hpp>
public:
friend istream &operator >>( istream &strm, 
                             String &str );

Semantics:

The operator >>() function is used to read a sequence of characters from the strm istream object into the str String object. Like C strings, the gathering of characters for a str String object ends at the first whitespace encountered, so that the last character placed in str is the character before the whitespace.

Results:

The operator >>() function returns a reference to the strm parameter.

String::operator [ ]()

index into a string

Synopsis:

#include <string.hpp>
public:
char const &String::operator [ ]( 
    size_t pos ) const;
char &String::operator [ ]( size_t pos );

Semantics:

The operator [ ]() public member function creates either a constant or a non-constant reference to the character at offset pos in the String object. The non-constant reference may be used to modify that character. The first character of a String object is at position zero.

If pos is greater than or equal to the length of the String object, and the resulting reference is used, the behavior is undefined.

If the non-constant reference is used to modify other characters within the String object, the behavior is undefined.

Results:

The operator [ ]() public member function returns either a constant or a non-constant reference to a character.

String::operator char()

convert a string to its first character

Synopsis:

#include <string.hpp>
public:
String::operator char();

Semantics:

The operator char() public member function converts a String object into the first character it contains. If the String object is empty, the result is the null character.

Results:

The operator char() public member function returns the first character contained in the String object. If the String object is empty, the null character is returned.

String::operator char const *()

convert a string object into a C string

Synopsis:

#include <string.hpp>
public:
String::operator char const *();

Semantics:

The operator char const *() public member function converts a String object into a C string containing the same length and sequence of characters, terminated by a null character. If the String object contains a null character, the resulting C string is terminated by that null character.

The returned pointer is associated with the String object, and therefore has meaning only as long as the String object isn't modified. If the intention is to be able to refer to the C string after the String object has been modified, a copy of the string should be made, perhaps by using the C library strdup() function.

The returned pointer is a pointer to a constant C string. If the pointer is used in some way to modify the C string, the behavior is undefined.

Results:

The operator char const *() public member function returns a pointer to a null-terminated constant C string that contains the same characters as the String object.

String::put_at()

modify the character at a given offset in the string

Synopsis:

#include <string.hpp>
public:
void String::put_at( size_t pos, char chr );

Semantics:

The put_at() public member function modifies the character at offset pos within the String object. The character at the specified offset is set to the value of chr. If pos is greater than the number of characters within the String object, chr is appended to the String object.

Results:

The put_at() public member function has no return value.

String::String()

create a String object

Synopsis:

#include <string.hpp>
public:
String::String();
String::String( size_t size, 
                String::capacity cap );
String::String( String const &str,
                size_t pos = 0,
                size_t num = NPOS );
String::String( char const *pch, 
                size_t num = NPOS );
String::String( char ch, size_t rep = 1 );

Semantics:

There are five forms of the public String constructor:

The first creates a default String object containing no characters. The created String object has length zero.
The second form creates a String object:
- The length of the string is size if cap is equal to the enumeration constant default_size.
- The function reserves size bytes of memory, and sets the length of the String object to be zero if cap is equal to the enumeration constant reserve.
The third form creates a String object that contains a sub-string of the str parameter. The sub-string starts at position pos within str and continues for num characters or until the end of the str parameter, whichever comes first.
The fourth form creates a String object from a C string. The String object contains the sequence of characters located at the pch parameter. Characters are included up to num or the end of the C string pointed at by pch.

C strings are terminated by a null character. The value of the created String object won't contain that character, nor any following it.
The fifth form creates a String object containing rep copies of the ch parameter.

Results:

The first form of the public String constructor produces a String object.
The second form produces a String object of size size.
The third form produces a sub-string or duplicate of the str parameter.
The fourth form produces a String object of at most length n containing the characters in the C string starting at the pch parameter.
The fifth form produces a String object of length rep containing only the character specified by the ch parameter.

String::~String()

destroy a String object

Synopsis:

#include <string.hpp>
public:
String::~String();

Semantics:

The public String destructor destroys the String object. The call to this destructor is inserted implicitly by the compiler at the point where the String object goes out of scope.

Results:

The String object is destroyed.

String::upper()

creat an uppercase copy of a string

Synopsis:

#include <string.hpp>
public:
String String::upper() const;

Semantics:

The upper() public member function creates a new String object whose value is the same as the original String object, except that all lowercase letters have been converted to uppercase.

Results:

The upper() public member function returns a new uppercase String object.

String valid()

see if a string is valid

Synopsis:

#include <string.hpp>
public:
friend int valid( String const &str );

Semantics:

The valid() function tests the validity of the str String object.

Results:

The valid() function returns a non-zero value if the str String object is valid, otherwise zero is returned.

String::valid()

see if the string is valid

Synopsis:

#include <string.hpp>
public:
int String::valid() const;

Semantics:

The valid() public member function tests the validity of the String object.

Results:

The valid() public member function returns a non-zero value if the String object is valid, otherwise zero is returned.

Synopsis:

Semantics:

Results:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics: