Go to the previous, next section.

String--Character String

SYNOPSIS

BASE CLASS

DERIVED CLASSES

RELATED CLASSES

DESCRIPTION

Class String provides a convenient dynamic string manipulation package. Functions include a full complement of comparison and assignment operators, subscripting, concatenation, substring extraction and replacement, and conversion to upper case, lower case, and ASCII.

Class String defines the conversion of String objects to and from const char*, so you can use them as arguments to C library routines, for example.

When creating a String, you may optionally give a hint as to how many extra characters you expect the string to grow by. This can improve efficiency by reducing the number of calls made to the memory allocator. If the string length exceeds this estimate, the allocated space is increased automatically. Space for an additional DEFAULT_STRING_EXTRA characters (currently 15) is allocated by default. Note that space for a zero terminating character is always allocated.

The individual characters of a String are indexed originating at 0, like C strings and arrays. You can use the substring operator operator()(unsigned position, unsigned length) to extract, insert, or replace portions of a String.

CONSTRUCTORS

String()

Constructs an empty String with an initial capacity of DEFAULT_STRING_EXTRA characters.

String(int extra)

String(unsigned extra)

Constructs an empty String with an initial capacity of extra characters.

String(const char* cs)

String(const String& s)

String(const SubString& ss)

Constructs a String initialized to the specified C string cs, String s, or SubString ss with an initial capacity equal to the length of the argument plus DEFAULT_STRING_EXTRA characters.

String(const char* cs, unsigned extra)

String(const String& s, unsigned extra)

String(const SubString& ss, unsigned extra)

Constructs a String initialized to the specified C string cs, String s, or SubString ss with an initial capacity equal to the length of the argument plus extra characters.

String(char c, unsigned l =1, unsigned extra =DEFAULT_STRING_EXTRA)

Constructs a String of length l with each character initialized to c. Space for an additional extra characters is allocated.

SEARCHING

virtual unsigned hash() const

Returns a number suitable for use as a hash table probe.

RELATIONAL OPERATORS

bool operator<(const String& s) const

bool operator<(const SubString& ss) const

bool operator<(const char* cs) const

friend bool operator<(const char* cs, const String& s)

bool operator>(const String& s) const

bool operator>(const SubString& ss) const

bool operator>(const char* cs) const

friend bool operator>(const char* cs, const String& s)

bool operator<=(const String& s) const

bool operator<=(const SubString& ss) const

bool operator<=(const char* cs) const

friend bool operator<=(const char* cs, const String& s)

bool operator>=(const String& s) const

bool operator>=(const SubString& ss) const

bool operator>=(const char* cs) const

friend bool operator>=(const char* cs, const String& s)

bool operator==(const String& s) const

bool operator==(const SubString& ss) const

bool operator==(const char* cs) const

friend bool operator==(const char* cs, const String& s)

bool operator!=(const String& s) const

bool operator!=(const SubString& ss) const

bool operator!=(const char* cs) const

friend bool operator!=(const char* cs, const String& s)

Returns YES if the indicated relation holds between this String and the argument String s, SubString ss, or C string cs. The private SubString class also defines a similar set of relational operators so that a SubString may also appear as the left operand.

COMPARING STRINGS

virtual int compare(const Object& ob) const

Compares this String with the argument object ob, which must also be a kind of class String. Returns a negative result if this String is alphabetically before ob, zero if this String equals ob, and a positive result if this String is alphabetically after ob.

TESTING STRINGS

virtual bool isEqual(const Object& ob) const

Returns YES if ob is of species String and equals this String.

STRING ASSIGNMENT

void operator=(const String& s)

void operator=(const SubString& ss)

void operator=(const char* cs)

Replaces this String with a copy of String s, SubString ss, or C string cs.

COPYING STRINGS

virtual void deepenShallowCopy()

This function is a no-op for class String.

INDEXING STRINGS

char& operator[](unsigned i)

char operator[](unsigned i) const

char& at(unsigned i)

char at(unsigned i) const

Returns a reference to or the value of the ith character of this String. Characters are indexed from 0 to size()-1. If i is outside this range, an NIHCL_INDEXRANGE exception is raised.

SUBSTRING EXTRACTION AND REPLACEMENT

SubString operator()(unsigned pos, unsigned len)

const SubString operator()(unsigned pos, unsigned len) const

Returns the substring consisting of len characters starting at position pos. Characters are subscripted originating at 0. If the substring extends beyond the beginning or end of this String, an NIHCL_SUBSTRERR exception is raised. You can use the substring operator in an expression to extract a substring of a String, or as the left operand of an assignment operator to insert or replace a substring of a String. For example:

String s("abcXXXghi"), t("defYY");
s(3,3) = t(0,3);
cout << s;      // prints abcdefghi

You can use the substring operator to insert one string into another:

String s("abcghi");
s(3,0) = "def";
cout << s;      // prints abcdefghi

or to replace a substring by one of shorter or longer length:

String s "abcXXXdef";
s(3,3) = "";
cout << s;      // prints abcdef

String s "abcXghi";
s(3,1) = "def";
cout << s;      // prints abcdefghi

If a String has length L, the substring operator (L,0) is valid. It extracts a substring of length zero, or appends to the end of a String if you use it as the left operand of an assignment operator:

String s "abc";
s(3,0) = "def";
cout << s;      // prints abcdef

SubString operator()(const Range& r)

const SubString operator()(const Range& r) const

Returns the substring defined by the position and length of Range r. Raises an NIHCL_BADRANGE exception if r is undefined.

STRING CONCATENATION

String operator&(const String& s) const

String operator&(const SubString& ss) const

String operator&(const char* cs) const

Returns a String that is the result of appending the argument String s, SubString ss, or C string cs to the end of this String. These functions are also defined for SubStrings.

friend String operator&(const char* cs, const String& s)

friend String operator&(const char* cs, const SubString& ss)

Returns a String formed by appending String s or SubString ss to the end of the C string cs.

String& operator&=(const String& s)

String& operator&=(const SubString& ss)

String& operator&=(const char* cs)

Appends the argument String s, SubString ss, or C string cs to the end of this String. This is a more efficient operation than operator&().

CONVERTING STRINGS

operator const char*() const

Converts this String to a pointer to a C-style (i.e. null-terminated) character string.

virtual void toAscii()

virtual void toLower()

virtual void toUpper()

Converts the characters in this String to ASCII, lowercase, or uppercase, respectively.

STRING CAPACITY AND SIZE

unsigned length() const

virtual unsigned size() const

Returns the number of characters in this String, not including the null terminator.

unsigned reSize(unsigned newSize)

Changes the capacity of this String to newSize or length(), whichever is larger. Returns the resulting string capacity.

virtual unsigned capacity() const

Returns the maximum number of characters this String can hold, not counting the zero terminator byte, before it will be resized.

READING AND PRINTING STRINGS

virtual void printOn(ostream& strm =cout) const

Prints this String on output stream strm.

virtual void scanFrom(istream& strm)

Reads all characters up to, but not including, the next newline from input stream strm into this String. Note that scanFrom() will not read more than 512 characters, and that an initial empty line on the input stream will be ignored.

STRING SPECIES

virtual const Class* species() const

Returns a pointer to the class descriptor for class String.

PROTECTED MEMBERS

Object I/O

virtual void storer(OIOofd& fd) const

virtual void storer(OIOout& strm) const

Stores this String on fd or strm.

EXCEPTIONS RAISED

Go to the previous, next section.