NAME

OTC_String - A class for holding a sequence of characters.

SYNOPSIS


#include <OTC/text/string.hh>

class OTC_String
{
  public:
    static os_typespec* get_os_typespec();
    static int rank(
      char const* theString1,
      u_int theLength1,
      char const* theString2,
      u_int theLength2,
      OTC_CmpType theType=OTCLIB_EXACTMATCH
    );
    inline static int hash(char const* theString, u_int theNum);
    virtual ~OTC_String();
    OTC_String();
    OTC_String(OTC_Capacity theCapacity);
    OTC_String(OTC_Length theLength);
    OTC_String(OTC_Length theLength, OTC_Capacity theCapacity);
    OTC_String(char const* theString);
    OTC_String(char const* theString, u_int theNum);
    OTC_String(char theChar, u_int theNum=1);
    OTC_String(OTC_String const& theString);
    OTC_String(OTC_String const& theString, u_int theNum);
    OTC_String(OTC_SObject const& theString);
    OTC_String(OTC_CString const& theString);
    OTC_String(OTC_RString const& theString);
    OTC_String(OTC_TString const& theString);
    friend istream& operator>>(istream& ins, OTC_String& theString);
    friend ostream& operator<<(
      ostream& outs,
      OTC_String const& theString
    );
    static OTC_String get(istream& ins, char delim=EOL);
    static OTC_String& get(
      OTC_String& theString,
      istream& ins,
      char delim=EOL
    );
    static OTC_String getline(istream& ins, char delim=EOL);
    static OTC_String& getline(
      OTC_String& theString,
      istream& ins,
      char delim=EOL
    );
    static OTC_String read(istream& ins, u_int theNum);
    static OTC_String& read(
      OTC_String& theString,
      istream& ins,
      u_int theNum
    );
    char const* string() const;
    operator char const*() const;
    char const* buffer() const;
    char* buffer();
    inline OTC_RString const& rawString() const;
    inline OTC_RString& rawString();
    char operator[](u_int theIndex) const;
    char& operator[](u_int theIndex);
    void length(u_int theLength);
    void resize(u_int theLength);
    void capacity(u_int theCapacity);
    char* duplicate() const;
    inline OTC_String clone() const;
    u_int length() const;
    u_int size() const;
    OTC_Boolean isEmpty() const;
    OTC_Boolean isUndefined() const;
    u_int capacity() const;
    static OTC_String const& nullString();
    inline static OTC_String const& nullBuffer();
    static OTC_String const& undefinedString();
    inline OTC_String& replace(
      u_int theStart,
      u_int theLength,
      char theChar,
      u_int theNum=1
    );
    inline OTC_String& replace(
      OTC_Range const& theRange,
      char theChar,
      u_int theNum=1
    );
    inline OTC_String& replace(
      u_int theStart,
      u_int theLength,
      char const* theString
    );
    inline OTC_String& replace(
      OTC_Range const& theRange,
      char const* theString
    );
    inline OTC_String& replace(
      u_int theStart,
      u_int theLength,
      char const* theString,
      u_int theNum
    );
    inline OTC_String& replace(
      OTC_Range const& theRange,
      char const* theString,
      u_int theNum
    );
    inline OTC_String& replace(
      u_int theStart,
      u_int theLength,
      OTC_String const& theString
    );
    inline OTC_String& replace(
      OTC_Range const& theRange,
      OTC_String const& theString
    );
    inline OTC_String& replace(
      u_int theStart,
      u_int theLength,
      OTC_String const& theString,
      u_int theNum
    );
    inline OTC_String& replace(
      OTC_Range const& theRange,
      OTC_String const& theString,
      u_int theNum
    );
    inline OTC_String& assign(char theChar, u_int theNum=1);
    inline OTC_String& assign(char const* theString);
    inline OTC_String& assign(char const* theString, u_int theNum);
    OTC_String& assign(OTC_String const& theString);
    OTC_String& assign(OTC_String const& theString, u_int theNum);
    inline OTC_String& operator=(char theChar);
    inline OTC_String& operator=(char const* theString);
    inline OTC_String& operator=(OTC_String const& theString);
    inline OTC_String& insert(
      u_int theIndex,
      char theChar,
      u_int theNum=1
    );
    inline OTC_String& insert(u_int theIndex, char const* theString);
    inline OTC_String& insert(
      u_int theIndex,
      char const* theString,
      u_int theNum
    );
    inline OTC_String& insert(
      u_int theIndex,
      OTC_String const& theString
    );
    inline OTC_String& insert(
      u_int theIndex,
      OTC_String const& theString,
      u_int theNum
    );
    inline OTC_String& append(char theChar, u_int theNum=1);
    inline OTC_String& append(char const* theString);
    inline OTC_String& append(char const* theString, u_int theNum);
    inline OTC_String& append(OTC_String const& theString);
    inline OTC_String& append(
      OTC_String const& theString,
      u_int theNum
    );
    inline OTC_String& operator+=(char theChar);
    inline OTC_String& operator+=(char const* theString);
    inline OTC_String& operator+=(OTC_String const& theString);
    inline OTC_String& prepend(char theChar, u_int theNum=1);
    inline OTC_String& prepend(char const* theString);
    inline OTC_String& prepend(char const* theString, u_int theNum);
    inline OTC_String& prepend(OTC_String const& theString);
    inline OTC_String& prepend(
      OTC_String const& theString,
      u_int theNum
    );
    friend OTC_TString operator+(
      OTC_String const& s1,
      OTC_String const& s2
    );
    friend OTC_TString operator+(
      OTC_String const& s1,
      char const* s2
    );
    friend OTC_TString operator+(
      char const* s1,
      OTC_String const& s2
    );
    friend OTC_TString operator+(
      OTC_SObject const& s1,
      OTC_String const& s2
    );
    friend OTC_TString operator+(
      OTC_String const& s1,
      OTC_SObject const& s2
    );
    friend OTC_TString operator+(OTC_String const& s1, char c1);
    friend OTC_TString operator+(char c1, OTC_String const& s1);
    inline OTC_String& remove(u_int theStart, u_int theLength);
    inline OTC_String& remove(OTC_Range const& theRange);
    inline OTC_String& truncate();
    OTC_String& truncate(u_int theIndex);
    inline OTC_String section(u_int theStart, u_int theLength) const;
    inline OTC_String section(OTC_Range const& theRange) const;
    inline OTC_String between(u_int theStart, u_int theEnd) const;
    inline OTC_String after(u_int theIndex) const;
    inline OTC_String from(u_int theIndex) const;
    inline OTC_String before(u_int theIndex) const;
    inline OTC_String through(u_int theIndex) const;
    inline OTC_String except(u_int theStart, u_int theLength) const;
    inline OTC_String except(OTC_Range const& theRange) const;
    inline OTC_String& upper(u_int theStart, u_int theLength);
    inline OTC_String& upper(OTC_Range const& theRange);
    inline OTC_String& upper(u_int theLength);
    inline OTC_String& upper();
    inline OTC_String& lower(u_int theStart, u_int theLength);
    inline OTC_String& lower(OTC_Range const& theRange);
    inline OTC_String& lower(u_int theLength);
    inline OTC_String& lower();
    inline OTC_String& lchop(u_int theNum=1);
    inline OTC_String& rchop(u_int theNum=1);
    OTC_String& ljustify(u_int theWidth, char theChar=' ');
    OTC_String& rjustify(u_int theWidth, char theChar=' ');
    OTC_String& reverse();
    OTC_String& rtrim();
    OTC_String& rtrim(char theChar);
    OTC_String& ltrim();
    OTC_String& ltrim(char theChar);
    inline OTC_String& trim();
    int index(u_int theIndex, char theChar, u_int theNum=1) const;
    inline int index(char theChar, u_int theNum=1) const;
    int rindex(char theChar, u_int theNum=1) const;
    inline int index(u_int theIndex, char const* theString) const;
    inline int index(char const* theString) const;
    inline int index(
      u_int theIndex,
      OTC_String const& theString
    ) const;
    inline int index(OTC_String const& theString) const;
    int rank(OTC_String const& theString) const;
    inline int rank(char const* theString) const;
    inline int rank(char const* theString, u_int theLength) const;
    int rank(OTC_String const& theString, u_int theLength) const;
    inline int hash() const;
    OTC_Boolean compare(
      u_int theIndex,
      char const* theString,
      OTC_CmpType theType=OTCLIB_EXACTMATCH
    ) const;
    inline OTC_Boolean compare(
      char const* theString,
      OTC_CmpType theType=OTCLIB_EXACTMATCH
    ) const;
    OTC_Boolean compare(
      u_int theIndex,
      char const* theString,
      u_int theNum,
      OTC_CmpType theType=OTCLIB_EXACTMATCH
    ) const;
    OTC_Boolean compare(
      u_int theIndex,
      OTC_String const& theString,
      OTC_CmpType theType=OTCLIB_EXACTMATCH
    ) const;
    inline OTC_Boolean compare(
      OTC_String const& theString,
      OTC_CmpType theType=OTCLIB_EXACTMATCH
    ) const;
    OTC_Boolean compare(
      u_int theIndex,
      OTC_String const& theString,
      u_int theNum,
      OTC_CmpType theType=OTCLIB_EXACTMATCH
    ) const;
    inline OTC_Boolean operator==(char c1) const;
    inline OTC_Boolean operator==(char const* s2) const;
    inline OTC_Boolean operator==(OTC_String const& s2) const;
    inline OTC_Boolean operator!=(char c1) const;
    inline OTC_Boolean operator!=(char const* s2) const;
    inline OTC_Boolean operator!=(OTC_String const& s2) const;
    inline OTC_Boolean operator<=(char c1) const;
    inline OTC_Boolean operator<=(char const* s2) const;
    inline OTC_Boolean operator<=(OTC_String const& s2) const;
    inline OTC_Boolean operator>=(char c1) const;
    inline OTC_Boolean operator>=(char const* s2) const;
    inline OTC_Boolean operator>=(OTC_String const& s2) const;
    inline OTC_Boolean operator<(char c1) const;
    inline OTC_Boolean operator<(char const* s2) const;
    inline OTC_Boolean operator<(OTC_String const& s2) const;
    inline OTC_Boolean operator>(char c1) const;
    inline OTC_Boolean operator>(char const* s2) const;
    inline OTC_Boolean operator>(OTC_String const& s2) const;
    friend OTC_Boolean operator==(char c1, OTC_String const& s2);
    friend OTC_Boolean operator==(
      char const* s1,
      OTC_String const& s2
    );
    friend OTC_Boolean operator!=(char c1, OTC_String const& s2);
    friend OTC_Boolean operator!=(
      char const* s1,
      OTC_String const& s2
    );
    friend OTC_Boolean operator<=(char c1, OTC_String const& s2);
    friend OTC_Boolean operator<=(
      char const* s1,
      OTC_String const& s2
    );
    friend OTC_Boolean operator>=(char c1, OTC_String const& s2);
    friend OTC_Boolean operator>=(
      char const* s1,
      OTC_String const& s2
    );
    friend OTC_Boolean operator>(char c1, OTC_String const& s2);
    friend OTC_Boolean operator>(
      char const* s1,
      OTC_String const& s2
    );
    friend OTC_Boolean operator<(char c1, OTC_String const& s2);
    friend OTC_Boolean operator<(
      char const* s1,
      OTC_String const& s2
    );
};

CLASS TYPE

Concrete

DESCRIPTION

The OTC_String class is designed to hold a sequence of characters, including null characters. The class uses delayed copy to improve average performance. The delayed copy mechanism means that when an assignment of one string class is made to another, or when a new class is created using another, they initially share the same underlying character buffer. The number of instances of the string class referencing the buffer is maintained through reference counting. Only when an operation is performed which would modify the buffer is a private copy made for that class. This scheme avoids unnecessary copies being made of strings.

INITIALISATION

OTC_String();
OTC_String(OTC_Capacity theCapacity);
OTC_String(OTC_Length theLength);
OTC_String(OTC_Length theLength, OTC_Capacity theCapacity);
OTC_String(char const* theString);
OTC_String(char const* theString, u_int theNum);
OTC_String(char theChar, u_int theNum=1);
OTC_String(OTC_String const& theString);
OTC_String(OTC_String const& theString, u_int theNum);
OTC_String(OTC_SObject const& theString);
OTC_String(OTC_CString const& theString);
OTC_String(OTC_RString const& theString);
OTC_String(OTC_TString const& theString);

STREAM OPERATIONS

friend istream& operator>>(istream& ins, OTC_String& theString);
friend ostream& operator<<(
  ostream& outs,
  OTC_String const& theString
);
static OTC_String get(istream& ins, char delim=EOL);
static OTC_String& get(
  OTC_String& theString,
  istream& ins,
  char delim=EOL
);
static OTC_String getline(istream& ins, char delim=EOL);
static OTC_String& getline(
  OTC_String& theString,
  istream& ins,
  char delim=EOL
);
static OTC_String read(istream& ins, u_int theNum);
static OTC_String& read(
  OTC_String& theString,
  istream& ins,
  u_int theNum
);

ACCESS

It is not guaranteed that pointers returned by the following functions are valid after subsequent modifications to the underlying buffer, as modifications may result in new buffer space being allocated and the previous space being deleted. If a valid buffer is required, a copy should be made. See duplicate() about making copies. The return value of the following functions should not be cast from non const, to circumvent the restrictions in place to stop indirect modifications to the buffer, as the changes could effect more than one class due to the delayed copy mechanism.
char const* string() const;
operator char const*() const;
char const* buffer() const;
char* buffer();
WARNING. WARNING. WARNING. Ye who play with the following functions better know what they are doing.
inline OTC_RString const& rawString() const;
inline OTC_RString& rawString();

INDEXING

Whether the object is const or not, it is not possible to access the null terminator which is automatically added at the end of the string.
char operator[](u_int theIndex) const;
char& operator[](u_int theIndex);

RESIZING

void length(u_int theLength);
void resize(u_int theLength);
void capacity(u_int theCapacity);

COPYING

char* duplicate() const;
inline OTC_String clone() const;

QUERIES

u_int length() const;
u_int size() const;
OTC_Boolean isEmpty() const;
OTC_Boolean isUndefined() const;
u_int capacity() const;

NULL STRING

static OTC_String const& nullString();
inline static OTC_String const& nullBuffer();
static OTC_String const& undefinedString();

REPLACEMENT

In the following functions, theStart is an index. Valid values for theStart are 0 through length(). Values outside this range will result in an exception. theLength is the number of characters to be replaced. If theStart plus theLength is greater than length(), an exception will be raised. If theLength is equal to 0, insertion is performed at that point. Both theStart and theLength equal to 0 is equivalent to prepending something to the string. theStart equal to length() and theLength equal to 0 is equivalent to appending something to the string. Replacing a range of characters with a null terminated string, a zero number of characters, or a null pointer, is equivalent to removing that sequence of characters. theStart equal to 0 and theLength equal to length() is equivalent to assignment. Any functions where arguments of theStart and theLength are expected have also been overloaded such that an instance of the OTC_Range object can be supplied instead. In these cases theStart is equivalent to OTC_Range::lower() and theLength to OTC_Range::length().
inline OTC_String& replace(
  u_int theStart,
  u_int theLength,
  char theChar,
  u_int theNum=1
);
inline OTC_String& replace(
  OTC_Range const& theRange,
  char theChar,
  u_int theNum=1
);
inline OTC_String& replace(
  u_int theStart,
  u_int theLength,
  char const* theString
);
inline OTC_String& replace(
  OTC_Range const& theRange,
  char const* theString
);
inline OTC_String& replace(
  u_int theStart,
  u_int theLength,
  char const* theString,
  u_int theNum
);
inline OTC_String& replace(
  OTC_Range const& theRange,
  char const* theString,
  u_int theNum
);
inline OTC_String& replace(
  u_int theStart,
  u_int theLength,
  OTC_String const& theString
);
inline OTC_String& replace(
  OTC_Range const& theRange,
  OTC_String const& theString
);
inline OTC_String& replace(
  u_int theStart,
  u_int theLength,
  OTC_String const& theString,
  u_int theNum
);
inline OTC_String& replace(
  OTC_Range const& theRange,
  OTC_String const& theString,
  u_int theNum
);

ASSIGNMENT

inline OTC_String& assign(char theChar, u_int theNum=1);
inline OTC_String& assign(char const* theString);
inline OTC_String& assign(char const* theString, u_int theNum);
OTC_String& assign(OTC_String const& theString);
OTC_String& assign(OTC_String const& theString, u_int theNum);
Following return a reference to this string so that assignments may be chained. This makes the behaviour consistent with the standard assignment operator.
inline OTC_String& operator=(char theChar);
inline OTC_String& operator=(char const* theString);
inline OTC_String& operator=(OTC_String const& theString);

INSERTION

Valid indexes for insertion are 0 through length(). An index of length() will result in concatenation to this string. An index outside of this range will result in an exception.
inline OTC_String& insert(
  u_int theIndex,
  char theChar,
  u_int theNum=1
);
inline OTC_String& insert(u_int theIndex, char const* theString);
inline OTC_String& insert(
  u_int theIndex,
  char const* theString,
  u_int theNum
);
inline OTC_String& insert(
  u_int theIndex,
  OTC_String const& theString
);
inline OTC_String& insert(
  u_int theIndex,
  OTC_String const& theString,
  u_int theNum
);

EXTENSION

inline OTC_String& append(char theChar, u_int theNum=1);
inline OTC_String& append(char const* theString);
inline OTC_String& append(char const* theString, u_int theNum);
inline OTC_String& append(OTC_String const& theString);
inline OTC_String& append(OTC_String const& theString, u_int theNum);
inline OTC_String& operator+=(char theChar);
inline OTC_String& operator+=(char const* theString);
inline OTC_String& operator+=(OTC_String const& theString);
inline OTC_String& prepend(char theChar, u_int theNum=1);
inline OTC_String& prepend(char const* theString);
inline OTC_String& prepend(char const* theString, u_int theNum);
inline OTC_String& prepend(OTC_String const& theString);
inline OTC_String& prepend(OTC_String const& theString, u_int theNum);

CONCATENATION

friend OTC_TString operator+(
  OTC_String const& s1,
  OTC_String const& s2
);
friend OTC_TString operator+(OTC_String const& s1, char const* s2);
friend OTC_TString operator+(char const* s1, OTC_String const& s2);
friend OTC_TString operator+(
  OTC_SObject const& s1,
  OTC_String const& s2
);
friend OTC_TString operator+(
  OTC_String const& s1,
  OTC_SObject const& s2
);
friend OTC_TString operator+(OTC_String const& s1, char c1);
friend OTC_TString operator+(char c1, OTC_String const& s1);

REMOVAL

inline OTC_String& remove(u_int theStart, u_int theLength);
inline OTC_String& remove(OTC_Range const& theRange);

TRUNCATION

inline OTC_String& truncate();
OTC_String& truncate(u_int theIndex);

SUBSTRINGS

inline OTC_String section(u_int theStart, u_int theLength) const;
inline OTC_String section(OTC_Range const& theRange) const;
inline OTC_String between(u_int theStart, u_int theEnd) const;
inline OTC_String after(u_int theIndex) const;
inline OTC_String from(u_int theIndex) const;
inline OTC_String before(u_int theIndex) const;
inline OTC_String through(u_int theIndex) const;
inline OTC_String except(u_int theStart, u_int theLength) const;
inline OTC_String except(OTC_Range const& theRange) const;

MODIFIERS

inline OTC_String& upper(u_int theStart, u_int theLength);
inline OTC_String& upper(OTC_Range const& theRange);
inline OTC_String& upper(u_int theLength);
inline OTC_String& upper();
inline OTC_String& lower(u_int theStart, u_int theLength);
inline OTC_String& lower(OTC_Range const& theRange);
inline OTC_String& lower(u_int theLength);
inline OTC_String& lower();
inline OTC_String& lchop(u_int theNum=1);
inline OTC_String& rchop(u_int theNum=1);
OTC_String& ljustify(u_int theWidth, char theChar=' ');
OTC_String& rjustify(u_int theWidth, char theChar=' ');
OTC_String& reverse();
For the following functions, white space is any of SPACE, TAB, RETURN, NEWLINE, FORMFEED, or the vertical tab character.
OTC_String& rtrim();
OTC_String& rtrim(char theChar);
OTC_String& ltrim();
OTC_String& ltrim(char theChar);
inline OTC_String& trim();

SEARCHING

int index(u_int theIndex, char theChar, u_int theNum=1) const;
inline int index(char theChar, u_int theNum=1) const;
int rindex(char theChar, u_int theNum=1) const;
inline int index(u_int theIndex, char const* theString) const;
inline int index(char const* theString) const;
inline int index(u_int theIndex, OTC_String const& theString) const;
inline int index(OTC_String const& theString) const;

RANKING

In the following rank functions, a return value of -1 indicates that this string ranks less than that being compared against, using a lexographical comparison. A value of 0 indicates that the strings are equivalent, and a value of 1 indicates that this string ranks greater than that being compared against.
int rank(OTC_String const& theString) const;
inline int rank(char const* theString) const;
inline int rank(char const* theString, u_int theLength) const;
int rank(OTC_String const& theString, u_int theLength) const;

HASHING

inline int hash() const;

COMPARISION

Note that for the compare() functions, a value of 0 for theString is not interpreted as being the same as a null terminated string. As a result, if theString is 0 then OTCLIB_FALSE will always be returned, even if the length of this string is 0. Also, each of the compare() functions accept an optional argument to indicate whether an exact match is expected or whether case can be ignored. The two corresponding values to indicate this are OTCLIB_EXACTMATCH and OTCLIB_IGNORECASE with the default being an exact match.
OTC_Boolean compare(
  u_int theIndex,
  char const* theString,
  OTC_CmpType theType=OTCLIB_EXACTMATCH
) const;
inline OTC_Boolean compare(
  char const* theString,
  OTC_CmpType theType=OTCLIB_EXACTMATCH
) const;
OTC_Boolean compare(
  u_int theIndex,
  char const* theString,
  u_int theNum,
  OTC_CmpType theType=OTCLIB_EXACTMATCH
) const;
OTC_Boolean compare(
  u_int theIndex,
  OTC_String const& theString,
  OTC_CmpType theType=OTCLIB_EXACTMATCH
) const;
inline OTC_Boolean compare(
  OTC_String const& theString,
  OTC_CmpType theType=OTCLIB_EXACTMATCH
) const;
OTC_Boolean compare(
  u_int theIndex,
  OTC_String const& theString,
  u_int theNum,
  OTC_CmpType theType=OTCLIB_EXACTMATCH
) const;
Following all return OTCLIB_TRUE if the particular comparison is satisfied.
inline OTC_Boolean operator==(char c1) const;
inline OTC_Boolean operator==(char const* s2) const;
inline OTC_Boolean operator==(OTC_String const& s2) const;
inline OTC_Boolean operator!=(char c1) const;
inline OTC_Boolean operator!=(char const* s2) const;
inline OTC_Boolean operator!=(OTC_String const& s2) const;
inline OTC_Boolean operator<=(char c1) const;
inline OTC_Boolean operator<=(char const* s2) const;
inline OTC_Boolean operator<=(OTC_String const& s2) const;
inline OTC_Boolean operator>=(char c1) const;
inline OTC_Boolean operator>=(char const* s2) const;
inline OTC_Boolean operator>=(OTC_String const& s2) const;
inline OTC_Boolean operator<(char c1) const;
inline OTC_Boolean operator<(char const* s2) const;
inline OTC_Boolean operator<(OTC_String const& s2) const;
inline OTC_Boolean operator>(char c1) const;
inline OTC_Boolean operator>(char const* s2) const;
inline OTC_Boolean operator>(OTC_String const& s2) const;
friend OTC_Boolean operator==(char c1, OTC_String const& s2);
friend OTC_Boolean operator==(char const* s1, OTC_String const& s2);
friend OTC_Boolean operator!=(char c1, OTC_String const& s2);
friend OTC_Boolean operator!=(char const* s1, OTC_String const& s2);
friend OTC_Boolean operator<=(char c1, OTC_String const& s2);
friend OTC_Boolean operator<=(char const* s1, OTC_String const& s2);
friend OTC_Boolean operator>=(char c1, OTC_String const& s2);
friend OTC_Boolean operator>=(char const* s1, OTC_String const& s2);
friend OTC_Boolean operator>(char c1, OTC_String const& s2);
friend OTC_Boolean operator>(char const* s1, OTC_String const& s2);
friend OTC_Boolean operator<(char c1, OTC_String const& s2);
friend OTC_Boolean operator<(char const* s1, OTC_String const& s2);

NOTES

Except where special behaviour is mentioned, a nil pointer is dealt with as if it were a null terminated string.

LIBRARY

OTC

AUTHOR(S)

Graham Dumpleton

COPYRIGHT

Copyright 1993 1994 TELSTRA CORPORATION LIMITED
Copyright 1994 DUMPLETON SOFTWARE CONSULTING PTY LIMITED