NAME

OTC_OldString - A class for holding a null terminated sequence of characters.

SYNOPSIS


#include <OTC/text/string.hh>

class OTC_OldString
{
  public:
    static os_typespec* get_os_typespec();
    virtual ~OTC_OldString();
    OTC_OldString();
    OTC_OldString(u_int theSize);
    OTC_OldString(char const* theString);
    OTC_OldString(OTC_OldBuffer const& theBuffer);
    OTC_OldString(char const* theString, u_int theNum);
    OTC_OldString(OTC_OldString const& theString);
    OTC_OldString(char theChar, u_int theNum=1);
    static OTC_OldString get(istream& ins, char delim=EOL);
    static OTC_OldString getline(istream& ins, char delim=EOL);
    static OTC_OldString read(istream& ins, u_int theNum);
    inline char const* string() const;
    inline operator char const*() const;
    char operator[](u_int theIndex) const;
    char* duplicate() const;
    inline u_int length() const;
    inline OTC_Boolean isEmpty() const;
    void replace(
      u_int theStart,
      u_int theLength,
      char theChar,
      u_int theNum=1
    );
    inline void replace(
      OTC_Range const& theRange,
      char theChar,
      u_int theNum=1
    );
    void replace(
      u_int theStart,
      u_int theLength,
      char const* theString
    );
    inline void replace(
      OTC_Range const& theRange,
      char const* theString
    );
    void replace(
      u_int theStart,
      u_int theLength,
      char const* theString,
      u_int theNum
    );
    inline void replace(
      OTC_Range const& theRange,
      char const* theString,
      u_int theNum
    );
    inline void replace(
      u_int theStart,
      u_int theLength,
      OTC_OldBuffer const& theBuffer
    );
    inline void replace(
      OTC_Range const& theRange,
      OTC_OldBuffer const& theBuffer
    );
    inline void assign(char theChar, u_int theNum=1);
    inline void assign(char const* theString);
    inline void assign(char const* theString, u_int theNum);
    inline void assign(OTC_OldBuffer const& theBuffer);
    void assign(OTC_OldString const& theString);
    inline OTC_OldString& operator=(char theChar);
    inline OTC_OldString& operator=(char const* theString);
    inline OTC_OldString& operator=(OTC_OldBuffer const& theBuffer);
    inline OTC_OldString& operator=(OTC_OldString const& theString);
    inline void insert(u_int theIndex, char theChar, u_int theNum=1);
    inline void insert(u_int theIndex, char const* theString);
    inline void insert(
      u_int theIndex,
      char const* theString,
      u_int theNum
    );
    inline void insert(
      u_int theIndex,
      OTC_OldBuffer const& theBuffer
    );
    inline void append(char theChar, u_int theNum=1);
    inline void append(char const* theString);
    inline void append(char const* theString, u_int theNum);
    inline void append(OTC_OldBuffer const& theBuffer);
    inline void prepend(char theChar, u_int theNum=1);
    inline void prepend(char const* theString);
    inline void prepend(char const* theString, u_int theNum);
    inline void prepend(OTC_OldBuffer const& theBuffer);
    inline void operator+=(char theChar);
    inline void operator+=(char const* theString);
    inline void operator+=(OTC_OldBuffer const& theBuffer);
    inline void remove(u_int theStart, u_int theLength);
    inline void remove(OTC_Range const& theRange);
    void truncate(u_int theIndex=0);
    inline OTC_OldString section(
      u_int theStart,
      u_int theLength
    ) const;
    inline OTC_OldString section(OTC_Range const& theRange) const;
    inline OTC_OldString between(u_int theStart, u_int theEnd) const;
    inline OTC_OldString after(u_int theIndex) const;
    inline OTC_OldString from(u_int theIndex) const;
    inline OTC_OldString before(u_int theIndex) const;
    inline OTC_OldString through(u_int theIndex) const;
    inline OTC_OldString except(OTC_Range const& theRange) const;
    inline OTC_OldString except(
      u_int theStart,
      u_int theLength
    ) const;
    void upper(u_int theStart, u_int theLength);
    inline void upper(OTC_Range const& theRange);
    inline void upper(u_int theLength);
    inline void upper();
    void lower(u_int theStart, u_int theLength);
    inline void lower(OTC_Range const& theRange);
    inline void lower(u_int theLength);
    inline void lower();
    void rtrim();
    void ltrim();
    inline void trim();
    void reverse();
    int index(u_int theIndex, char theChar, u_int theNum=1) const;
    inline int index(char theChar, u_int theNum=1) const;
    int index(u_int theIndex, char const* theString) const;
    inline int index(char const* theString) const;
    int rindex(char theChar, u_int theNum=1) 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;
    inline OTC_Boolean operator==(char const* theStr) const;
    inline OTC_Boolean operator==(OTC_OldString const& theStr) const;
    inline OTC_Boolean operator!=(char const* theStr) const;
    inline OTC_Boolean operator!=(OTC_OldString const& theStr) const;
    inline OTC_Boolean operator<=(char const* theStr) const;
    inline OTC_Boolean operator<=(OTC_OldString const& theStr) const;
    inline OTC_Boolean operator>=(char const* theStr) const;
    inline OTC_Boolean operator>=(OTC_OldString const& theStr) const;
    inline OTC_Boolean operator<(char const* theStr) const;
    inline OTC_Boolean operator<(OTC_OldString const& theStr) const;
    inline OTC_Boolean operator>(char const* theStr) const;
    inline OTC_Boolean operator>(OTC_OldString const& theStr) const;
    static OTC_OldString const& nullString();
};

CLASS TYPE

Concrete

DESCRIPTION

The OTC_OldString class is designed to hold a null terminated sequence of characters. It is not intended that the class hold an arbitrary sequence of bytes, this is because the class always treats the null character as special. All operations will ignore any characters in character arrays following the null character. The class implements two techniques to aid in the efficient manipulation of character strings. These are block buffering and delayed copy. In the implementation of block buffering all buffer space allocations will occur in multiples of a specified hunk size. This scheme ensures that additions of single characters will not cause reallocations and copying of the underlying buffer each time an addition is performed. Note that since the string always uses some space, you are guaranteed that it will always contain at least a single character. This means that even when the string is empty, you will get back a null terminated string if you attempt to access the buffer and not a null pointer. 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. Note though that no attempt should be made to circumvent the protection of the underlying buffer by casting in order to change it directly as this could result in changes being made to multiple strings. Something which was probably not intended.

INITIALISATION

OTC_OldString();
OTC_OldString(u_int theSize);
OTC_OldString(char const* theString);
OTC_OldString(OTC_OldBuffer const& theBuffer);
OTC_OldString(char const* theString, u_int theNum);
OTC_OldString(OTC_OldString const& theString);
OTC_OldString(char theChar, u_int theNum=1);

STREAM OPERATIONS

static OTC_OldString get(istream& ins, char delim=EOL);
static OTC_OldString getline(istream& ins, char delim=EOL);
static OTC_OldString read(istream& ins, u_int theNum);

BUFFER ACCESS

inline char const* string() const;
inline operator char const*() const;
char operator[](u_int theIndex) const;
char* duplicate() const;

QUERIES

inline u_int length() const;
inline OTC_Boolean isEmpty() const;

REPLACEMENT

theStart is an index. Valid values for theStart are 0 to 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 the length of the string then an assertion failure will be generated. If theLength is equal to 0 then insertion is performed at that point. Both indexes 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 EOS, a nil or null terminated string 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 this cases theStart is equivalent to OTC_Range::lower() and theLength to OTC_Range::length(). All of these overloaded functions are typically inline and simply call those functions where theStart and theLength are expected explicitly.
void replace(
  u_int theStart,
  u_int theLength,
  char theChar,
  u_int theNum=1
);
inline void replace(
  OTC_Range const& theRange,
  char theChar,
  u_int theNum=1
);
void replace(u_int theStart, u_int theLength, char const* theString);
inline void replace(OTC_Range const& theRange, char const* theString);
void replace(
  u_int theStart,
  u_int theLength,
  char const* theString,
  u_int theNum
);
inline void replace(
  OTC_Range const& theRange,
  char const* theString,
  u_int theNum
);
inline void replace(
  u_int theStart,
  u_int theLength,
  OTC_OldBuffer const& theBuffer
);
inline void replace(
  OTC_Range const& theRange,
  OTC_OldBuffer const& theBuffer
);

ASSIGNMENT

inline void assign(char theChar, u_int theNum=1);
inline void assign(char const* theString);
inline void assign(char const* theString, u_int theNum);
inline void assign(OTC_OldBuffer const& theBuffer);
void assign(OTC_OldString const& theString);
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_OldString& operator=(char theChar);
inline OTC_OldString& operator=(char const* theString);
inline OTC_OldString& operator=(OTC_OldBuffer const& theBuffer);
inline OTC_OldString& operator=(OTC_OldString const& theString);

INSERTION

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

EXTENSION

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

REMOVAL

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

TRUNCATION

void truncate(u_int theIndex=0);

SUBSTRINGS

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

MODIFIERS

void upper(u_int theStart, u_int theLength);
inline void upper(OTC_Range const& theRange);
inline void upper(u_int theLength);
inline void upper();
void lower(u_int theStart, u_int theLength);
inline void lower(OTC_Range const& theRange);
inline void lower(u_int theLength);
inline void lower();
void rtrim();
void ltrim();
inline void trim();
void reverse();

SEARCHING

int index(u_int theIndex, char theChar, u_int theNum=1) const;
inline int index(char theChar, u_int theNum=1) const;
int index(u_int theIndex, char const* theString) const;
inline int index(char const* theString) const;
int rindex(char theChar, u_int theNum=1) 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;
Following all return OTCLIB_TRUE if the particular comparison is satisfied. Global inline functions exist so that comparisons can be written with a char* on the left hand side of the comparison.
inline OTC_Boolean operator==(char const* theStr) const;
inline OTC_Boolean operator==(OTC_OldString const& theStr) const;
inline OTC_Boolean operator!=(char const* theStr) const;
inline OTC_Boolean operator!=(OTC_OldString const& theStr) const;
inline OTC_Boolean operator<=(char const* theStr) const;
inline OTC_Boolean operator<=(OTC_OldString const& theStr) const;
inline OTC_Boolean operator>=(char const* theStr) const;
inline OTC_Boolean operator>=(OTC_OldString const& theStr) const;
inline OTC_Boolean operator<(char const* theStr) const;
inline OTC_Boolean operator<(OTC_OldString const& theStr) const;
inline OTC_Boolean operator>(char const* theStr) const;
inline OTC_Boolean operator>(OTC_OldString const& theStr) const;

NULL STRING

static OTC_OldString const& nullString();

STREAMS

The extraction operation of the streams classes may be used on the string class. This has the same behaviour as the extraction operation for char*, ie. it will first skip whitespace if the flag ios::skipws is defined; the default. If ios::skipws is not defined and there is initial white space then an empty string is returned. Reading will also be stopped if EOS is encountered, with EOS being left in the stream.

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 1991 1992 OTC LIMITED
Copyright 1994 DUMPLETON SOFTWARE CONSULTING PTY LIMITED