#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();
};
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.
OTC_OldString();
OTC_OldString(u_int theSize);
theSize
.
OTC_OldString(char const* theString);
theString
. If theString
is 0
then
an empty string is created.
OTC_OldString(OTC_OldBuffer const& theBuffer);
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);
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);
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);
theNum
occurrences of theChar
.
If theNum
is 0
or theChar
is
EOS
then an empty string is created.
static OTC_OldString get(istream& ins, char delim=EOL);
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);
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);
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.
inline char const* string() const;
duplicate()
about making copies.
inline operator char const*() const;
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;
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;
inline u_int length() const;
inline OTC_Boolean isEmpty() const;
OTCLIB_TRUE
if the length of
this string is 0
.
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
);
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
);
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);
theLength
characters from
theStart
with theString
.
inline void replace(OTC_Range const& theRange, char const* theString);
theRange
of characters with
theString
.
void replace(
u_int theStart,
u_int theLength,
char const* theString,
u_int theNum
);
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
);
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
);
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
);
theRange
of characters with
theBuffer
. If theBuffer
contains an
embedded null character then only
characters up till the null character are
copied.
inline void assign(char theChar, u_int theNum=1);
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);
theString
.
If theString
is 0
then this
string is nulled.
inline void assign(char const* theString, u_int theNum);
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);
theBuffer
.
If theBuffer
has an embedded null
character then only characters up till
the null character are copied.
void assign(OTC_OldString const& theString);
theString
.
A copy is only made of the string when an
attempt is made to modify it. See
description of delayed copy mechanism
above.
inline OTC_OldString& operator=(char theChar);
theChar
. If theChar
is EOS
then this string is simply nulled.
inline OTC_OldString& operator=(char const* theString);
theString
. If
theString
is 0
then this string is
nulled.
inline OTC_OldString& operator=(OTC_OldBuffer const& theBuffer);
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);
theString
. A copy
is only made of the string when an attempt
is made to modify it. See description of
delayed copy mechanism above.
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);
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);
theString
before theIndex
position of this string.
inline void insert(
u_int theIndex,
char const* theString,
u_int theNum
);
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);
theBuffer
before theIndex
position of this string. If theBuffer
contains an embedded null character
then only characters up till the null
are copied.
inline void append(char theChar, u_int theNum=1);
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);
theString
to the end of this
string.
inline void append(char const* theString, u_int theNum);
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);
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);
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);
theString
to the start of this
string.
inline void prepend(char const* theString, u_int theNum);
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);
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);
theChar
to the end of this
string. If theChar
is EOS
then
no change is made.
inline void operator+=(char const* theString);
theString
to the end of this
string.
inline void operator+=(OTC_OldBuffer const& theBuffer);
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 remove(u_int theStart, u_int theLength);
theLength
characters starting at theStart
.
inline void remove(OTC_Range const& theRange);
theRange
of characters.
void truncate(u_int theIndex=0);
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.
inline OTC_OldString section(u_int theStart, u_int theLength) const;
theLength
characters starting at
theStart
.
inline OTC_OldString section(OTC_Range const& theRange) const;
theRange
.
inline OTC_OldString between(u_int theStart, u_int theEnd) const;
theStart
and theEnd
.
inline OTC_OldString after(u_int theIndex) const;
theIndex
.
inline OTC_OldString from(u_int theIndex) const;
theIndex
through to
the end of the string.
inline OTC_OldString before(u_int theIndex) const;
theIndex
.
inline OTC_OldString through(u_int theIndex) const;
theIndex
.
inline OTC_OldString except(OTC_Range const& theRange) const;
theRange
of characters.
inline OTC_OldString except(u_int theStart, u_int theLength) const;
theStart
and
with theLength
.
void upper(u_int theStart, u_int theLength);
theStart
and theLength
to upper case.
inline void upper(OTC_Range const& theRange);
theRange
of characters to upper case.
inline void upper(u_int theLength);
theLength
characters of this string
string to upper case.
inline void upper();
void lower(u_int theStart, u_int theLength);
theStart
and theLength
to lower case.
inline void lower(OTC_Range const& theRange);
theRange
of characters to lower case.
inline void lower(u_int theLength);
theLength
characters of this string
string to lower case.
inline void lower();
void rtrim();
void ltrim();
inline void trim();
void reverse();
int index(u_int theIndex, char theChar, u_int theNum=1) const;
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;
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;
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;
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;
theNum
'th instance
of theChar
nearest to the end of this
string or -1
if this string doesn't
contain any instance of theChar
.
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;
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;
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;
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.
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;
static OTC_OldString const& nullString();
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.