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();
Creates an empty string with a notionally
undefined value. The string will behave
exactly like an empty string, but
isUndefinedString() will return
true until the value of the string has
been set.
OTC_String(OTC_Capacity theCapacity);
Creates an empty string with enough
underlying capacity to hold a string of
theCapacity. This is equivalent to
the old OTC_String constructor
taking u_int.
OTC_String(OTC_Length theLength);
Creates a string of length theLength.
The string is not initialised and
will be filled with garbage. This is
equivalent to the old OTC_Buffer
constructor taking u_int.
OTC_String(OTC_Length theLength, OTC_Capacity theCapacity);
Creates a string of length theLength.
The string is not initialised and
will be filled with garbage. The
underlying buffer capacity will at the
same time be set to at least
theCapacity.
OTC_String(char const* theString);
Creates a string holding a copy of the
null terminated string theString. If
theString is 0, an empty string is
created.
OTC_String(char const* theString, u_int theNum);
Creates a string holding a copy of the
first theNum characters of theString.
If theString is 0, and theNum is
not 0, an exception will be raised.
OTC_String(char theChar, u_int theNum=1);
Creates a string containing theNum
occurrences of theChar. If theNum
is 0 an empty string is created.
OTC_String(OTC_String 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.
OTC_String(OTC_String const& theString, u_int theNum);
Creates a string holding a copy of the
first theNum characters of theString.
If the length of theString is less
than theNum, an exception is raised.
OTC_String(OTC_SObject const& theString);
Creates a string which references the same
character string obtained from
theString. A copy is only made of the
string when an attempt is made to modify
it.
OTC_String(OTC_CString 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. OTC_CString
is a constant string.
OTC_String(OTC_RString 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. OTC_RString
is the raw string used to implement this
class.
OTC_String(OTC_TString 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. Instances of
OTC_TString are returned from the
operator+() defined for strings.
STREAM OPERATIONS
friend istream& operator>>(istream& ins, OTC_String& theString);
If the flag ios::skipws is set in ins,
any whitespace at the start of ins is
discarded. Characters are then read in and
placed into theString. Reading stops
when further whitespace or EOF is
encountered. If ios::skipws is not
defined and there is initial white space,
an empty string is returned. If a field
width is specified in ins it will be
honoured.
friend ostream& operator<<(
ostream& outs,
OTC_String const& theString
);
Outputs theString onto outs. Any field
widths and justification flags set in
outs are honoured.
static OTC_String get(istream& ins, char delim=EOL);
Similiar to 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.
static OTC_String& get(
OTC_String& theString,
istream& ins,
char delim=EOL
);
Similiar to 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 and
appended to theString. delim is left
in ins. Characters are appended to
theString. A reference to theString is
returned.
static OTC_String getline(istream& ins, char delim=EOL);
Similar to 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.
static OTC_String& getline(
OTC_String& theString,
istream& ins,
char delim=EOL
);
Similar to 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
and appended to theString. delim is
extracted from ins. Characters are
appended to theString. A reference to
theString is returned.
static OTC_String read(istream& ins, u_int theNum);
Similar to istream::read(). The string
into which the characters are read is
returned. The length of the string
returned should be checked to determine
how many characters were actually read.
static OTC_String& read(
OTC_String& theString,
istream& ins,
u_int theNum
);
Similar to istream::read(). Characters
read in are appended to theString. The
length of the string returned should be
checked to determine how many characters
were actually read. A reference to
theString is returned.
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;
Returns a pointer to the underlying buffer
used to hold characters. If the string
is empty, a pointer to an empty but null
terminated string will be returned.
operator char const*() const;
Returns a pointer to the underlying buffer
used to hold characters. If the string
is empty, a pointer to an empty but null
terminated string will be returned.
char const* buffer() const;
Returns a pointer to the underlying buffer
used to hold characters. If the string
is empty, a 0 pointer will be returned.
char* buffer();
Returns a pointer to the underlying buffer
used to hold characters. If the string is
empty, a 0 pointer will be returned.
Note that this variant of the buffer()
function is only used on non const
instances of the class. The returned
pointer can be used to directly write into
the buffer. It is guaranteed that any
delayed copy will be broken before the
pointer is returned. If however, you
overwrite the end of the buffer and
destroy the null terminator, it is your
own problem.
WARNING. WARNING. WARNING. Ye who play with the following functions
better know what they are doing.
inline OTC_RString const& rawString() const;
Returns a reference to the raw string
information.
inline OTC_RString& rawString();
Returns a reference to the raw string
information.
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;
Returns the character at the location in
this string given by theIndex. If
theIndex is greater than or equal to the
length of this string, an exception is
raised.
char& operator[](u_int theIndex);
Returns a reference to the character at
the location in this string given by
theIndex. If theIndex is greater than
or equal to the length of this string, an
exception is raised. When this function is
invoked, any delayed copy will be broken
first.
RESIZING
void length(u_int theLength);
Resizes the string. Old data in the string
is preserved for whatever range would be
valid in the new string. If the length of
the string is increased, any new portion
of memory is not initialised.
void resize(u_int theLength);
Resizes the string. Old data in the string
is preserved for whatever range would be
valid in the new string. If the length of
the string is increased, any new portion
of memory is not initialised. Kept for
backward compatibility with the old
OTC_Buffer, use length(u_int) instead.
void capacity(u_int theCapacity);
Resizes the underlying buffer to increase
its size so that it can hold a string of
length theCapacity. The length of the
current string and its contents are
unchanged. If the underlying buffer is
shared, this operation will result in the
buffer being reallocated, the capacity
being the greater of what is required
to hold the current string and the value
theCapacity. If the underlying buffer is
not shared, a reallocation will only occur
if theCapacity is greater than the
existing capacity.
COPYING
char* duplicate() const;
Returns a copy of the underlying buffer.
Note that it is the users responsibility
to delete the copy. Only enough
space to hold the string and the null
terminator is allocated. Also, the
memory is always obtained from transient
memory in situations where a database
product is being used.
inline OTC_String clone() const;
Returns a clone of this string as a new
instance of an OTC_String object.
Actually, the delayed copy mechanism is
used, meaning that once a modification
is made separate memory for the string
will be allocated.
QUERIES
u_int length() const;
Returns the length of this string.
The length does not include the null
terminator.
u_int size() const;
Provided for backward compatibility with
OTC_Buffer only. Use length() instead.
OTC_Boolean isEmpty() const;
Returns OTCLIB_TRUE if the length of
this string is 0.
OTC_Boolean isUndefined() const;
Returns OTCLIB_TRUE if the value of
the string has not as yet been set. Note
that isEmpty() will also return
OTCLIB_TRUE if the string has not as
yet been set.
u_int capacity() const;
Returns the maximum capacity of the buffer
being used to hold the current string. The
value returned does not include the cell
reserved for holding the null terminator.
NULL STRING
static OTC_String 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.
inline static OTC_String const& nullBuffer();
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.
Provided only for backward compatibility
with OTC_Buffer. Use nullString()
instead.
static OTC_String const& undefinedString();
Returns a reference to an empty string.
This string is different to that returned
by nullString(). When a string has been
set to the value of undefinedString()
the isUndefinedString() function will
return true.
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
);
Replaces theLength characters from
theStart with theNum instances of
theChar.
inline OTC_String& replace(
OTC_Range const& theRange,
char theChar,
u_int theNum=1
);
Replaces theRange of characters with
theNum instances of theChar.
inline OTC_String& replace(
u_int theStart,
u_int theLength,
char const* theString
);
Replaces theLength characters from
theStart with theString.
inline OTC_String& replace(
OTC_Range const& theRange,
char const* theString
);
Replaces theRange of characters with
theString.
inline OTC_String& 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.
inline OTC_String& replace(
OTC_Range const& theRange,
char const* theString,
u_int theNum
);
Replaces theRange of characters with the
first theNum characters of theString.
inline OTC_String& replace(
u_int theStart,
u_int theLength,
OTC_String const& theString
);
Replaces theLength characters from
theStart with theString.
inline OTC_String& replace(
OTC_Range const& theRange,
OTC_String const& theString
);
Replaces theRange of characters with
theString.
inline OTC_String& replace(
u_int theStart,
u_int theLength,
OTC_String const& theString,
u_int theNum
);
Replaces theLength characters from
theStart with the first theNum
characters of theString. If the length
of theString is less than theNum an
exception is raised.
inline OTC_String& replace(
OTC_Range const& theRange,
OTC_String const& theString,
u_int theNum
);
Replaces theRange of characters with the
first theNum characters of theString.
If the length of theString is less than
theNum an exception is raised.
ASSIGNMENT
inline OTC_String& assign(char theChar, u_int theNum=1);
Sets this string to be a sequence of
theNum instances of the character
theChar. If theNum is 0 the result
is an empty string.
inline OTC_String& assign(char const* theString);
Sets this string to be theString. If
theString is 0 the result is an empty
string.
inline OTC_String& assign(char const* theString, u_int theNum);
Sets this string to be the first theNum
characters of theString. If theString
is 0 the result is an empty string.
OTC_String& assign(OTC_String const& theString);
Sets this string to reference the same
character string 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.
OTC_String& assign(OTC_String const& theString, u_int theNum);
Sets this string to be the first theNum
characters of theString. If the length
of theString is less than theNum an
exception is raised.
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);
Sets this string to be the single
character theChar.
inline OTC_String& operator=(char const* theString);
Sets this string to be theString. If
theString is 0 the result is an empty
string.
inline OTC_String& operator=(OTC_String const& theString);
Sets this string to reference the same
character string 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 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
);
Inserts theChar before theIndex
position of this string theNum times.
inline OTC_String& insert(u_int theIndex, char const* theString);
Inserts theString before theIndex
position of this string.
inline OTC_String& insert(
u_int theIndex,
char const* theString,
u_int theNum
);
Inserts the first theNum characters of
theString before theIndex position of
this string.
inline OTC_String& insert(
u_int theIndex,
OTC_String const& theString
);
Inserts theString before theIndex
position of this string.
inline OTC_String& insert(
u_int theIndex,
OTC_String const& theString,
u_int theNum
);
Inserts the first theNum characters of
theString before theIndex position of
this string. If the length of theString
is less than theNum an exception is
raised.
EXTENSION
inline OTC_String& append(char theChar, u_int theNum=1);
Appends theChar to the end of this
string theNum times.
inline OTC_String& append(char const* theString);
Appends theString to the end of this
string.
inline OTC_String& append(char const* theString, u_int theNum);
Appends the first theNum characters
of theString to the end of this string.
inline OTC_String& append(OTC_String const& theString);
Appends theString to the end of this
string.
inline OTC_String& append(OTC_String const& theString, u_int theNum);
Appends the first theNum characters
of theString to the end of this string.
If the length of theString is less
than theNum an exception is raised.
inline OTC_String& operator+=(char theChar);
Appends theChar to the end of this
string.
inline OTC_String& operator+=(char const* theString);
Appends theString to the end of this
string.
inline OTC_String& operator+=(OTC_String const& theString);
Appends theString to the end of this
string.
inline OTC_String& prepend(char theChar, u_int theNum=1);
Prepends theChar to the start of this
string theNum times.
inline OTC_String& prepend(char const* theString);
Prepends theString to the start of this
string.
inline OTC_String& prepend(char const* theString, u_int theNum);
Prepends the first theNum characters
of theString to the start of this string.
inline OTC_String& prepend(OTC_String const& theString);
Prepends theString to the start of this
string.
inline OTC_String& prepend(OTC_String const& theString, u_int theNum);
Prepends the first theNum characters
of theString to the start of this string.
If the length of theString is less
than theNum an exception is raised.
CONCATENATION
friend OTC_TString operator+(
OTC_String const& s1,
OTC_String const& s2
);
Returns a string which is the concatenation
of s1 and s2.
friend OTC_TString operator+(OTC_String const& s1, char const* s2);
Returns a string which is the concatenation
of s1 and s2.
friend OTC_TString operator+(char const* s1, OTC_String const& s2);
Returns a string which is the concatenation
of s1 and s2.
friend OTC_TString operator+(
OTC_SObject const& s1,
OTC_String const& s2
);
Returns a string which is the concatenation
of s1 and s2.
friend OTC_TString operator+(
OTC_String const& s1,
OTC_SObject const& s2
);
Returns a string which is the concatenation
of s1 and s2.
friend OTC_TString operator+(OTC_String const& s1, char c1);
Returns a string which is the concatenation
of s1 and c1.
friend OTC_TString operator+(char c1, OTC_String const& s1);
Returns a string which is the concatenation
of c1 and s1.
REMOVAL
inline OTC_String& remove(u_int theStart, u_int theLength);
Removes from this string theLength
characters starting at theStart.
inline OTC_String& remove(OTC_Range const& theRange);
Removes from this string theRange
of characters.
TRUNCATION
inline OTC_String& truncate();
Sets the size of the string back to 0.
OTC_String& truncate(u_int theIndex);
Removes those characters from theIndex
to the end of this string. If theIndex
is greater than the length of the string
an exception is raised.
SUBSTRINGS
inline OTC_String section(u_int theStart, u_int theLength) const;
Returns a new string containing
theLength characters starting at
theStart.
inline OTC_String section(OTC_Range const& theRange) const;
Returns a new string containing
those characters in theRange.
inline OTC_String between(u_int theStart, u_int theEnd) const;
Returns a new string containing the
characters between theStart and theEnd.
inline OTC_String after(u_int theIndex) const;
Returns a new string containing characters
appearing after theIndex.
inline OTC_String from(u_int theIndex) const;
Returns a new string containing characters
appearing from theIndex through to
the end of the string.
inline OTC_String before(u_int theIndex) const;
Returns a new string containing characters
appearing before theIndex.
inline OTC_String through(u_int theIndex) const;
Returns a new string containing characters
appearing from the start of the string
through theIndex.
inline OTC_String 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.
inline OTC_String except(OTC_Range const& theRange) const;
Returns a new string containing the
characters not appearing in theRange
of characters.
MODIFIERS
inline OTC_String& upper(u_int theStart, u_int theLength);
Converts any lower case characters in the
range defined by theStart and
theLength to upper case.
inline OTC_String& upper(OTC_Range const& theRange);
Converts any lower case characters in
theRange of characters to upper case.
inline OTC_String& upper(u_int theLength);
Converts any lower case characters in the
first theLength characters of this string
string to upper case.
inline OTC_String& upper();
Converts any lower case characters in this
string to upper case.
inline OTC_String& lower(u_int theStart, u_int theLength);
Converts any upper case characters in the
range defined by theStart and theLength
to lower case.
inline OTC_String& lower(OTC_Range const& theRange);
Converts any upper case characters in
theRange of characters to lower case.
inline OTC_String& lower(u_int theLength);
Converts any upper case characters in the
first theLength characters of this string
string to lower case.
inline OTC_String& lower();
Converts any upper case characters in this
string to lower case.
inline OTC_String& lchop(u_int theNum=1);
Removes the first theNum characters
from this string. If that number of
characters does not exist, an exception
is raised.
inline OTC_String& rchop(u_int theNum=1);
Removes the last theNum characters
from this string. If that number of
characters does not exist, an exception
is raised.
OTC_String& ljustify(u_int theWidth, char theChar=' ');
If there are less than theWidth
characters in the string, instances
of theChar will be added to the
string to fill it out to a width
of theWidth. The original string
will be left justified.
OTC_String& rjustify(u_int theWidth, char theChar=' ');
If there are less than theWidth
characters in the string, instances
of theChar will be added to the
string to fill it out to a width
of theWidth. The original string
will be right justified.
OTC_String& reverse();
Reverses the order of characters in
this string.
For the following functions, white space is any of SPACE, TAB,
RETURN, NEWLINE, FORMFEED, or the vertical tab character.
OTC_String& rtrim();
Removes trailing white space from
this string.
OTC_String& rtrim(char theChar);
Removes trailing instances of theChar
from the end of this string.
OTC_String& ltrim();
Removes leading white space from
this string.
OTC_String& ltrim(char theChar);
Removes leading instances of theChar
from the end of this string.
inline OTC_String& trim();
Removes trailing and leading white space
from 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 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.
inline int index(u_int theIndex, char const* theString) const;
Returns the index of the first instance
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 the first instance
of theString, in this string. If
theString doesn't match against
this string then -1 is returned.
inline int index(u_int theIndex, OTC_String const& theString) const;
Returns the index of the first instance
of theString in this string appearing
beyond theIndex. If theString doesn't
match against this string then -1 is
returned.
inline int index(OTC_String const& theString) const;
Returns the index of the first instance
of theString in this string. If
theString doesn't match against
this string then -1 is returned.
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;
Performs a comparison between this string
and theString and return a value
corresponding to how the two strings
rank.
inline int rank(char const* theString) const;
Performs a comparison between this string
and theString and return a value
corresponding to how the two strings
rank.
inline int rank(char const* theString, u_int theLength) const;
Performs a comparison between this string
and the first theLength characters of
theString and return a value
corresponding to how the two strings rank.
int rank(OTC_String const& theString, u_int theLength) const;
Performs a comparison between this string
and the first theLength characters of
theString and return a value
corresponding to how the two strings rank.
If theString is less than theLength
characters in length, an exception is
raised.
HASHING
inline int hash() const;
Returns a hash value for this string.
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 through to the end
of this string. If theIndex is greater
than the length of this string 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. If
theIndex is greater than the length of
this string an exception is raised. If
theIndex plus theNum is greater than
the length of this string, OTCLIB_FALSE
will always be returned.
OTC_Boolean compare(
u_int theIndex,
OTC_String const& theString,
OTC_CmpType theType=OTCLIB_EXACTMATCH
) const;
Returns OTCLIB_TRUE if theString is
equivalent to the portion of this string
starting at theIndex through to the
end of this string. If theIndex is
greater than the length of this string
an exception is raised.
inline OTC_Boolean compare(
OTC_String const& theString,
OTC_CmpType theType=OTCLIB_EXACTMATCH
) const;
Returns OTCLIB_TRUE if theString is
equivalent to this string.
OTC_Boolean compare(
u_int theIndex,
OTC_String 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. If
theIndex is greater than the length of
this string, or theNum is greater than
the length of theString, an exception is
raised. If theIndex plus theNum is
greater than the length of this string,
OTCLIB_FALSE will always be returned.
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