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);
Create an empty string where the
underlying buffer has enough capacity
to hold a string of theSize.
OTC_OldString(char const* theString);
Creates a string holding a copy of
theString. If theString is 0 then
an empty string is created.
OTC_OldString(OTC_OldBuffer const& theBuffer);
Creates a string holding a copy of
theBuffer. If theBuffer contains
any imbedded null characters, then
the string created will only hold
the characters up to the first
null character.
OTC_OldString(char const* theString, u_int theNum);
Creates a string holding a copy of the
first theNum characters of theString.
If theString is null terminated and
theNum is greater than the length of
theString then only characters up till
the end of theString are copied.
OTC_OldString(OTC_OldString const& theString);
Creates a string which references the same
character string as held by theString. A
copy is only made of the string when an
attempt is made to modify it. See
description of delayed copy mechanism
above.
OTC_OldString(char theChar, u_int theNum=1);
Creates a string containing theNum
occurrences of theChar.
If theNum is 0 or theChar is
EOS then an empty string is created.
STREAM OPERATIONS
static OTC_OldString get(istream& ins, char delim=EOL);
Performs an operation much like
istream::get() except that it is not
required to specify a maximum length for a
buffer. In other words, any number of
characters up to but not including delim
are read from ins, the result being
returned as a string. delim is left in
ins. Reading will also be stopped
if EOS is encountered, with EOS being
left in the stream.
static OTC_OldString getline(istream& ins, char delim=EOL);
Performs an operation much like
istream::getline() except that it is not
required to specify a maximum length for a
buffer. In other words, any number of
characters up to but not including delim
are read from ins, the result being
returned as a string. delim is extracted
from ins. Reading will also be stopped
if EOS is encountered, with EOS being
extracted and not left in the stream.
static OTC_OldString read(istream& ins, u_int theNum);
Performs an operation much like
istream::read(). The string into
which the characters are read is
returned. Note that if EOS or EOF
is encountered before theNum characters
are read then reading will be stopped.
If EOS is encountered then it will
be discarded.
BUFFER ACCESS
inline char const* string() const;
Returns a pointer to the underlying buffer
used to hold characters.
This value should not be cast in order 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.
In addition, it is not guaranteed that
this pointer is valid after subsequent
modifications to the underlying buffer as
these may result in new buffer space being
allocated and the previous space being
deleted. Thus if a valid buffer is
required a copy should be made. See
duplicate() about making copies.
inline operator char const*() const;
Invokes string() to return
a pointer to the underlying buffer used
to hold characters. This allows the
OTC_OldString class to be used anywhere
a char const* is expected.
char operator[](u_int theIndex) const;
Returns the character at the location
in this string given by theIndex.
If theIndex is larger than the
length of this string then an exception
is raised. Note that this operator
cannot be used on the left hand
side of an assignment.
char* duplicate() const;
Returns a copy of the underlying buffer.
Note that it is the users responsibility
to delete the copy. Also, only enough
space to hold the string is allocated.
QUERIES
inline u_int length() const;
Returns the length of this string.
inline OTC_Boolean isEmpty() const;
Returns OTCLIB_TRUE if the length of
this string is 0.
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
);
Replaces theLength characters from
theStart with theNum instances of
theChar. If theChar is EOS or
theNum is 0 then the characters in
that range are simply removed.
inline void replace(
OTC_Range const& theRange,
char theChar,
u_int theNum=1
);
Replaces theRange of characters with
theNum instances of theChar. If
theChar is EOS or theNum is 0 then
the characters in that range are simply
removed.
void replace(u_int theStart, u_int theLength, char const* theString);
Replaces theLength characters from
theStart with theString.
inline void replace(OTC_Range const& theRange, char const* theString);
Replaces theRange of characters with
theString.
void replace(
u_int theStart,
u_int theLength,
char const* theString,
u_int theNum
);
Replaces theLength characters from
theStart with the first theNum
characters of theString. If theString
is null terminated and theNum is greater
than the length of theString then only
characters up till the end of theString
are copied into this string.
inline void replace(
OTC_Range const& theRange,
char const* theString,
u_int theNum
);
Replaces theRange of characters with the
first theNum characters of theString.
If theString is null terminated and
theNum is greater than the length of
theString then only characters up till
the end of theString are copied into
this string.
inline void replace(
u_int theStart,
u_int theLength,
OTC_OldBuffer const& theBuffer
);
Replaces theLength characters from
theStart with theBuffer. If theBuffer
contains an embedded null character then
only characters up till the null character
are copied.
inline void replace(
OTC_Range const& theRange,
OTC_OldBuffer const& theBuffer
);
Replaces theRange of characters with
theBuffer. If theBuffer contains an
embedded null character then only
characters up till the null character are
copied.
ASSIGNMENT
inline void assign(char theChar, u_int theNum=1);
Sets this string to be a sequence of
theNum instances of the character
theChar. If theChar is EOS or
theNum is 0 then this string is simply
nulled.
inline void assign(char const* theString);
Sets this string to be theString.
If theString is 0 then this
string is nulled.
inline void assign(char const* theString, u_int theNum);
Sets this string to be the first
theNum characters of theString.
If theString is null terminated and
theNum is greater than the length of
theString then only characters up till
the end of theString are copied into
this string. If theString is 0 then
this string is nulled.
inline void assign(OTC_OldBuffer const& theBuffer);
Sets this string to be theBuffer.
If theBuffer has an embedded null
character then only characters up till
the null character are copied.
void assign(OTC_OldString const& theString);
Sets this string to reference the same
underlying buffer as theString.
A copy is only made of the string when an
attempt is made to modify it. See
description of delayed copy mechanism
above.
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);
Sets this string to be the single
character theChar. If theChar is EOS
then this string is simply nulled.
inline OTC_OldString& operator=(char const* theString);
Sets this string to be theString. If
theString is 0 then this string is
nulled.
inline OTC_OldString& operator=(OTC_OldBuffer const& theBuffer);
Sets this string to be theBuffer. If
theBuffer contains an embedded null
character then only characters up
till the null character are copied.
inline OTC_OldString& operator=(OTC_OldString const& theString);
Sets this string to reference the same
underlying buffer as theString. A copy
is only made of the string when an attempt
is made to modify it. See description of
delayed copy mechanism above.
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);
Inserts theChar before theIndex
position of this string theNum times. If
theChar is EOS or theNum is 0 then
no change is made.
inline void insert(u_int theIndex, char const* theString);
Inserts theString before theIndex
position of this string.
inline void insert(
u_int theIndex,
char const* theString,
u_int theNum
);
Inserts the first theNum characters
of theString before theIndex position
of this string. If theString is null
terminated and theNum is greater than
the length of theString then only
characters up till the end of theString
are copied into this string.
inline void insert(u_int theIndex, OTC_OldBuffer const& theBuffer);
Inserts theBuffer before theIndex
position of this string. If theBuffer
contains an embedded null character
then only characters up till the null
are copied.
EXTENSION
inline void append(char theChar, u_int theNum=1);
Appends theChar to the end of this
string theNum times. If theChar
is EOS or theNum is 0 then
no change is made.
inline void append(char const* theString);
Appends theString to the end of this
string.
inline void append(char const* theString, u_int theNum);
Appends the first theNum characters
of theString to the end of this string.
If theString is null terminated and
theNum is greater than the length of
theString then only characters up till
the end of theString are copied into
this string.
inline void append(OTC_OldBuffer const& theBuffer);
Appends theBuffer to the end of this
string. If theBuffer contains an
embedded null character, then only
characters up till the null character
are copied.
inline void prepend(char theChar, u_int theNum=1);
Prepends theChar to the start of this
string theNum times. If theChar is
EOS or theNum is 0 then no change is
made.
inline void prepend(char const* theString);
Prepends theString to the start of this
string.
inline void prepend(char const* theString, u_int theNum);
Prepends the first theNum characters
of theString to the start of this string.
If theString is null terminated and
theNum is greater than the length of
theString then only characters up till
the end of theString are copied into
this string.
inline void prepend(OTC_OldBuffer const& theBuffer);
Prepends theBuffer to the start of this
string. If theBuffer contains an
embedded null character, then only
characters up till the null character
are copied.
inline void operator+=(char theChar);
Appends theChar to the end of this
string. If theChar is EOS then
no change is made.
inline void operator+=(char const* theString);
Appends theString to the end of this
string.
inline void operator+=(OTC_OldBuffer const& theBuffer);
Appends theBuffer to the end of this
string. If theBuffer contains an
embedded null character, then only
characters up till the null character
are copied.
REMOVAL
inline void remove(u_int theStart, u_int theLength);
Removes from this string theLength
characters starting at theStart.
inline void remove(OTC_Range const& theRange);
Removes from this string theRange
of characters.
TRUNCATION
void truncate(u_int theIndex=0);
Removes those characters from theIndex
to the end of this string. If theIndex
is greater than or equal to the length
of the string then an exception is
generated.
SUBSTRINGS
inline OTC_OldString section(u_int theStart, u_int theLength) const;
Returns a new string containing
theLength characters starting at
theStart.
inline OTC_OldString section(OTC_Range const& theRange) const;
Returns a new string containing
those characters in theRange.
inline OTC_OldString between(u_int theStart, u_int theEnd) const;
Returns a new string containing the
characters between theStart and theEnd.
inline OTC_OldString after(u_int theIndex) const;
Returns a new string containing characters
appearing after theIndex.
inline OTC_OldString from(u_int theIndex) const;
Returns a new string containing characters
appearing from theIndex through to
the end of the string.
inline OTC_OldString before(u_int theIndex) const;
Returns a new string containing characters
appearing before theIndex.
inline OTC_OldString through(u_int theIndex) const;
Returns a new string containing characters
appearing from the start of the string
through to theIndex.
inline OTC_OldString except(OTC_Range const& theRange) const;
Returns a new string containing the
characters not appearing in theRange
of characters.
inline OTC_OldString except(u_int theStart, u_int theLength) const;
Returns a new string containing the
characters not appearing in the part
of the string from theStart and
with theLength.
MODIFIERS
void upper(u_int theStart, u_int theLength);
Converts any lower case characters in the
range defined by theStart and theLength
to upper case.
inline void upper(OTC_Range const& theRange);
Converts any lower case characters in
theRange of characters to upper case.
inline void upper(u_int theLength);
Converts any lower case characters in the
first theLength characters of this string
string to upper case.
inline void upper();
Converts any lower case characters in this
string to upper case.
void lower(u_int theStart, u_int theLength);
Converts any upper case characters in the
range defined by theStart and theLength
to lower case.
inline void lower(OTC_Range const& theRange);
Converts any upper case characters in
theRange of characters to lower case.
inline void lower(u_int theLength);
Converts any upper case characters in the
first theLength characters of this string
string to lower case.
inline void lower();
Converts any upper case characters in this
string to lower case.
void rtrim();
Removes trailing white space from
this string.
void ltrim();
Removes leading white space from
this string.
inline void trim();
Removes trailing and leading white space
from this string.
void reverse();
Reverses the order of characters in
this string.
SEARCHING
int index(u_int theIndex, char theChar, u_int theNum=1) const;
Returns the index of theNum'th instance of
theChar in this string appearing from
theIndex forward, or -1 if an instance
of theChar couldn't be found.
inline int index(char theChar, u_int theNum=1) const;
Returns the index of theNum'th instance
of theChar nearest to the start of this
string or -1 if this string doesn't
contain any instance of theChar.
int index(u_int theIndex, char const* theString) const;
Returns the index of theString in this
string appearing beyond theIndex. If
theString doesn't match against this
string then -1 is returned.
inline int index(char const* theString) const;
Returns the index of theString in this
string. If theString doesn't match
against this string then -1 is returned.
int rindex(char theChar, u_int theNum=1) const;
Returns the index of theNum'th instance
of theChar nearest to the end of this
string or -1 if this string doesn't
contain any instance of theChar.
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;
Returns OTCLIB_TRUE if theString is
equivalent to the portion of this
string starting at theIndex.
If theIndex is greater than the length
of this string then an exception is
raised.
inline OTC_Boolean compare(
char const* theString,
OTC_CmpType theType=OTCLIB_EXACTMATCH
) const;
Returns OTCLIB_TRUE if theString is
equivalent to this string.
OTC_Boolean compare(
u_int theIndex,
char const* theString,
u_int theNum,
OTC_CmpType theType=OTCLIB_EXACTMATCH
) const;
Returns OTCLIB_TRUE if theNum characters
of this string starting at theIndex
are the same as the first theNum
characters of theString. Note that if
either theString or the portion of this
string starting at theIndex contain less
characters than theNum then they will be
deemed different. If theIndex is greater
than the length of this string then an
exception is raised.
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();
Returns a reference to an empty string.
Can be used when it is necessary to return
an empty string where the return type of
the function is a reference but you
do not have an actual instance to return.
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