NAME
OTC_OldBuffer -
A class for holding an arbitrary sequence of characters.
SYNOPSIS
#include <OTC/text/buffer.hh>
class OTC_OldBuffer
{
public:
static os_typespec* get_os_typespec();
OTC_OldBuffer();
OTC_OldBuffer(u_int theSize);
OTC_OldBuffer(char const* theBuffer);
OTC_OldBuffer(char const* theBuffer, u_int theNum);
OTC_OldBuffer(char theChar, u_int theNum=1);
OTC_OldBuffer(OTC_OldBuffer const& theBuffer);
static OTC_OldBuffer get(istream& ins, char delim=EOL);
static OTC_OldBuffer getline(istream& ins, char delim=EOL);
static OTC_OldBuffer read(istream& ins, u_int theNum);
inline u_int size() const;
inline OTC_Boolean isEmpty() const;
inline void resize(u_int theSize);
char operator[](u_int theIndex) const;
OTC_OldBufferRef operator[](u_int theIndex);
char* duplicate() const;
char const* buffer() const;
char* buffer();
inline operator char const*() const;
inline operator char*();
inline operator OTC_String() 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* theBuffer
);
inline void replace(
OTC_Range const& theRange,
char const* theBuffer
);
void replace(
u_int theStart,
u_int theLength,
char const* theBuffer,
u_int theNum
);
inline void replace(
OTC_Range const& theRange,
char const* theBuffer,
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* theBuffer);
inline void assign(char const* theBuffer, u_int theNum);
inline void assign(OTC_OldBuffer const& theBuffer);
inline OTC_OldBuffer& operator=(char const* theBuffer);
inline OTC_OldBuffer& operator=(OTC_OldBuffer const& theBuffer);
inline void insert(u_int theIndex, char theChar, u_int theNum=1);
inline void insert(u_int theIndex, char const* theBuffer);
inline void insert(
u_int theIndex,
OTC_OldBuffer const& theBuffer
);
inline void insert(
u_int theIndex,
char const* theBuffer,
u_int theNum
);
inline void append(char theChar, u_int theNum=1);
inline void append(char const* theBuffer);
inline void append(OTC_OldBuffer const& theBuffer);
inline void append(char const* theBuffer, u_int theNum);
inline void prepend(char theChar, u_int theNum=1);
inline void prepend(char const* theBuffer);
inline void prepend(OTC_OldBuffer const& theBuffer);
inline void prepend(char const* theBuffer, u_int theNum);
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_OldBuffer section(
u_int theStart,
u_int theLength
) const;
inline OTC_OldBuffer section(OTC_Range const& theRange) const;
inline OTC_OldBuffer between(u_int theStart, u_int theEnd) const;
inline OTC_OldBuffer after(u_int theIndex) const;
inline OTC_OldBuffer from(u_int theIndex) const;
inline OTC_OldBuffer before(u_int theIndex) const;
inline OTC_OldBuffer through(u_int theIndex) const;
inline OTC_OldBuffer except(OTC_Range const& theRange) const;
inline OTC_OldBuffer except(
u_int theStart,
u_int theLength
) const;
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;
OTC_Boolean compare(u_int theIndex, char const* theBuffer) const;
inline OTC_Boolean compare(char const* theBuffer) const;
OTC_Boolean compare(
u_int theIndex,
char const* theBuffer,
u_int theNum
) const;
OTC_Boolean compare(
u_int theIndex,
OTC_OldBuffer const& theBuffer
) const;
inline OTC_Boolean compare(OTC_OldBuffer const& theBuffer) const;
inline OTC_Boolean operator==(char const* theBuffer) const;
inline OTC_Boolean operator==(
OTC_OldBuffer const& theBuffer
) const;
inline OTC_Boolean operator!=(char const* theBuffer) const;
inline OTC_Boolean operator!=(
OTC_OldBuffer const& theBuffer
) const;
static OTC_OldBuffer const& nullBuffer();
};
CLASS TYPE
Concrete
DESCRIPTION
The OTC_OldBuffer class is designed to hold an arbitrary sequence
of characters. The class utilises a number of techniques to aid in
the efficient use of memory. These are realised in a block
buffering and delayed copy mechanism.
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.
The delayed copy mechanism means that when an assignment of one
buffer 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 buffer 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 buffers.
INITIALISATION
OTC_OldBuffer();
OTC_OldBuffer(u_int theSize);
Create a buffer with initial size
of theSize.
OTC_OldBuffer(char const* theBuffer);
Creates a buffer holding a copy of the
characters in theBuffer up to but not
including a null terminator. If
theBuffer is 0 then an empty
buffer is created.
OTC_OldBuffer(char const* theBuffer, u_int theNum);
Creates a buffer holding a copy of the
first theNum characters of theBuffer.
If theBuffer is 0 and theNum is
not also 0 then an exception will be
raised.
OTC_OldBuffer(char theChar, u_int theNum=1);
Creates a buffer containing theNum
occurrences of theChar.
This is an easy way of allocating
a buffer of a certain size and also
initialising it.
OTC_OldBuffer(OTC_OldBuffer const& theBuffer);
Creates a buffer which references the same
character buffer as held by theBuffer. A
copy is only made of the buffer when an
attempt is made to modify it.
STREAM OPERATIONS
static OTC_OldBuffer 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 buffer. delim is left in
ins.
static OTC_OldBuffer 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 buffer. delim is extracted
from ins.
static OTC_OldBuffer read(istream& ins, u_int theNum);
Performs an operation much like
istream::read(). The buffer into
which the characters are read will
be returned. If EOF is encountered
the reading will be stopped.
BUFFER MANAGEMENT
inline u_int size() const;
Returns the size of the buffer.
inline OTC_Boolean isEmpty() const;
Returns OTCLIB_TRUE if the buffer is empty.
inline void resize(u_int theSize);
Resizes the buffer to theSize. Any
contents of the old buffer are copied over
to the new.
char operator[](u_int theIndex) const;
Returns the character at the location
in this buffer given by theIndex.
If theIndex is larger than the
size of the buffer then an exception is
raised. Note that if the object is const
then this operator cannot be used on
the left hand side of an assignment.
OTC_OldBufferRef operator[](u_int theIndex);
Returns a reference to the character at
the location in this buffer given by
theIndex. If theIndex is larger than
the size of the buffer then an exception
is raised.
char* duplicate() const;
Returns a copy of the underlying buffer.
Note that it is the users responsibility
to delete the copy.
Note that for the following it is not guaranteed that the pointer
returned is valid after subsequent modifications to the underlying
buffer through the functions of this class as these may result in new
buffer space being allocated and the previous space being deleted.
Thus if a valid copy of the buffer is required a copy should be made.
See duplicate() about making copies.
char const* buffer() const;
Returns a pointer to the underlying buffer
used to hold the characters. If the buffer
is empty then 0 is returned.
char* buffer();
Returns a pointer to the underlying buffer
used to hold the characters. If the buffer
is empty then 0 is returned.
inline operator char const*() const;
Returns a pointer to the underlying buffer
used to hold the characters. If the buffer
is empty then 0 is returned.
inline operator char*();
Returns a pointer to the underlying buffer
used to hold the characters. If the buffer
is empty then 0 is returned.
inline operator OTC_String() const;
REPLACEMENT
In the following, theStart is an index. Valid values for
theStart are 0 to size(). 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
size of the portion of the buffer being used 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 buffer. theStart equal
to size() and theLength equal to 0 is equivalent to
appending something to the end of the buffer currently being
used. theStart equal to 0 and theLength equal to size()
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.
inline void replace(
OTC_Range const& theRange,
char theChar,
u_int theNum=1
);
Replaces theRange of characters with
theNum instances of theChar.
void replace(u_int theStart, u_int theLength, char const* theBuffer);
Replaces theLength characters from
theStart with the characters in
theBuffer up to but not including a null
terminator. If theBuffer is 0 then the
characters are simply deleted.
inline void replace(OTC_Range const& theRange, char const* theBuffer);
Replaces theRange of characters with the
characters in theBuffer up to but not
including a null terminator. If
theBuffer is 0 then the characters are
simply deleted.
void replace(
u_int theStart,
u_int theLength,
char const* theBuffer,
u_int theNum
);
Replaces theLength characters from
theStart with the first theNum
characters of theBuffer. If theBuffer
is 0 and theNum is not also zero
then an exception is raised.
inline void replace(
OTC_Range const& theRange,
char const* theBuffer,
u_int theNum
);
Replaces theRange of characters with the
first theNum characters of theBuffer.
If theBuffer is 0 and theNum is not
also zero then an exception is raised.
inline void replace(
u_int theStart,
u_int theLength,
OTC_OldBuffer const& theBuffer
);
Replaces theLength characters from
theStart with the characters in
theBuffer.
inline void replace(
OTC_Range const& theRange,
OTC_OldBuffer const& theBuffer
);
Replaces theRange of characters with the
characters in theBuffer.
ASSIGNMENT
inline void assign(char theChar, u_int theNum=1);
Sets this buffer to be a sequence of
theNum instances of the character
theChar.
inline void assign(char const* theBuffer);
Sets this buffer to be the characters in
theBuffer up to but not including a null
terminator. If theBuffer is 0 then the
buffer is emptied.
inline void assign(char const* theBuffer, u_int theNum);
Sets this buffer to be the first
theNum characters of theBuffer. If
theBuffer is 0 and theNum is not
also 0 then an exception is raised.
inline void assign(OTC_OldBuffer const& theBuffer);
Sets this buffer to reference the same
underlying buffer as theBuffer. A copy
is only made of the buffer when an attempt
is made to modify it. See description of
delayed copy mechanism above.
Following return a reference to this buffer so that assignments
may be chained. This makes the behaviour consistent with the
standard assignment operator.
inline OTC_OldBuffer& operator=(char const* theBuffer);
Sets this buffer to be the characters in
theBuffer up to but not including a null
terminator. If theBuffer is 0 then the
buffer is emptied.
inline OTC_OldBuffer& operator=(OTC_OldBuffer const& theBuffer);
Sets this buffer to reference the same
underlying buffer as theBuffer. A copy
is only made of the buffer when an attempt
is made to modify it. See description of
delayed copy mechanism above.
INSERTION
Valid indexes for insertion are from 0 to size().
An index of size() will result in concatenation to
this buffer. 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 buffer theNum times.
inline void insert(u_int theIndex, char const* theBuffer);
Inserts the characters in theBuffer up
to but not including a null terminator
before theIndex position of this buffer.
If theBuffer is 0 then no change is
made.
inline void insert(u_int theIndex, OTC_OldBuffer const& theBuffer);
Inserts the characters in theBuffer
before theIndex position of this buffer.
inline void insert(
u_int theIndex,
char const* theBuffer,
u_int theNum
);
Inserts the first theNum characters
of theBuffer before theIndex position
of this buffer. If theBuffer is 0 and
theNum is no also 0 then an
exception is raised.
EXTENSION
inline void append(char theChar, u_int theNum=1);
Appends theChar to the end of this
buffer theNum times.
inline void append(char const* theBuffer);
Appends the characters in theBuffer up
to but not including a null terminator to
the end of this buffer. If theBuffer is
0 then no change is made.
inline void append(OTC_OldBuffer const& theBuffer);
Appends the characters in theBuffer
to the end of this buffer.
inline void append(char const* theBuffer, u_int theNum);
Appends the first theNum characters
of theBuffer to the end of this buffer.
If theBuffer is 0 and theNum is
not also 0 then an exception is raised.
inline void prepend(char theChar, u_int theNum=1);
Prepends theChar to the start of this
buffer theNum times.
inline void prepend(char const* theBuffer);
Prepends the characters in theBuffer up
to but not including a null terminator to
the start of this buffer. If theBuffer
is 0 then no change is made.
inline void prepend(OTC_OldBuffer const& theBuffer);
Prepends the characters in theBuffer
to the start of this buffer.
inline void prepend(char const* theBuffer, u_int theNum);
Prepends the first theNum characters
of theBuffer to the start of this buffer.
If theBuffer is 0 and theNum is
not also 0 then an exception is raised.
inline void operator+=(char theChar);
Appends theChar to the end of this
string.
inline void operator+=(char const* theString);
Appends the characters in theString up
to but not including a null character to
the end of this string.
inline void operator+=(OTC_OldBuffer const& theBuffer);
Appends the characters in theBuffer
to the end of this buffer.
REMOVAL
inline void remove(u_int theStart, u_int theLength);
Removes from this buffer theLength
characters starting at theStart.
inline void remove(OTC_Range const& theRange);
Removes from this buffer theRange
characters.
TRUNCATION
void truncate(u_int theIndex=0);
Removes those characters from theIndex
to the end of this buffer. If theIndex
is greater than or equal to the size of
the buffer then an exception is raised.
EXTRACTION
inline OTC_OldBuffer section(u_int theStart, u_int theLength) const;
Returns a new buffer containing
theLength characters starting at
theStart.
inline OTC_OldBuffer section(OTC_Range const& theRange) const;
Returns a new buffer containing
those characters in theRange.
inline OTC_OldBuffer between(u_int theStart, u_int theEnd) const;
Returns a new buffer containing the
characters between theStart and theEnd.
inline OTC_OldBuffer after(u_int theIndex) const;
Returns a new buffer containing characters
appearing after theIndex.
inline OTC_OldBuffer from(u_int theIndex) const;
Returns a new buffer containing characters
appearing from theIndex through to
the end of the buffer.
inline OTC_OldBuffer before(u_int theIndex) const;
Returns a new buffer containing characters
appearing before theIndex.
inline OTC_OldBuffer through(u_int theIndex) const;
Returns a new buffer containing characters
appearing from the start of this buffer
through to theIndex.
inline OTC_OldBuffer except(OTC_Range const& theRange) const;
Returns a new buffer containing the
characters not appearing in theRange
of characters.
inline OTC_OldBuffer except(u_int theStart, u_int theLength) const;
Returns a new buffer containing the
characters not appearing in the part
of this buffer from theStart with
length theLength.
SEARCHING
int index(u_int theIndex, char theChar, u_int theNum=1) const;
Returns the index of theNum'th instance
of theChar appearing from theIndex
forward or -1 if no instance of
theChar could be found. If theNum is
0 an exception is raised.
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
buffer or -1 if no instance of theChar
could be found. If theNum is 0 an
exception is raised.
int rindex(char theChar, u_int theNum=1) const;
Returns the index of theNum'th instance
of theChar nearest to the end of this
buffer or -1 if no instance of theChar
could be found. If theNum is 0 an
exception is raised.
COMPARISION
OTC_Boolean compare(u_int theIndex, char const* theBuffer) const;
Returns OTCLIB_TRUE if the characters in
theBuffer up to but not including a
null terminator are equivalent to
the characters from theIndex to the
end of the buffer. If the buffer is
not empty and theIndex is
greater than or equal to the size of
this buffer then an exception is
generated. If the buffer is empty
then an exception will be raised
only if theIndex is not equal to
0.
inline OTC_Boolean compare(char const* theBuffer) const;
Returns OTCLIB_TRUE if the characters in
theBuffer up to but not including a
null terminator are equivalent to
this buffer.
OTC_Boolean compare(
u_int theIndex,
char const* theBuffer,
u_int theNum
) const;
Returns OTCLIB_TRUE if theNum
characters starting at theIndex are
equivalent to the first theNum
characters of theBuffer. If the buffer
is not empty and theIndex is greater
than or equal to the size of this buffer
then an exception is generated. If the
buffer is empty then an exception will be
raised only if theIndex is not equal to
0.
OTC_Boolean compare(
u_int theIndex,
OTC_OldBuffer const& theBuffer
) const;
Returns OTCLIB_TRUE if the characters in
theBuffer are equivalent to the
characters from theIndex to the end of
the buffer. If theIndex is greater
than or equal to the size of the buffer
then an exception is generated.
inline OTC_Boolean compare(OTC_OldBuffer const& theBuffer) const;
Returns OTCLIB_TRUE if this buffer is
equivalent to the theBuffer.
inline OTC_Boolean operator==(char const* theBuffer) const;
Returns OTCLIB_TRUE if this buffer is
equivalent to the theBuffer.
inline OTC_Boolean operator==(OTC_OldBuffer const& theBuffer) const;
Returns OTCLIB_TRUE if this buffer is
equivalent to the theBuffer.
inline OTC_Boolean operator!=(char const* theBuffer) const;
Returns OTCLIB_TRUE if this buffer is
not equivalent to the theBuffer.
inline OTC_Boolean operator!=(OTC_OldBuffer const& theBuffer) const;
Returns OTCLIB_TRUE if this buffer is
not equivalent to the theBuffer.
NULL BUFFER
static OTC_OldBuffer const& nullBuffer();
Returns a reference to an empty
buffer. Can be used where it is
necessary to return an empty buffer
from a function returning a reference
and where no actual instance of
a buffer exists to return.
STREAMS
The OTC_OldBuffer class may be used with both inserters and
extractors on streams. In the case of an inserter it will call
stream::write() although it will perform any formatting as
necessary according to width, fill character and adjustment as
specified in the stream. In the case of the extractor it will read
in as many characters as possible as dictated by how many
characters are available or the width specified previous to the
operation via ios::width() or the setw() manipulator.
NOTES
The buffer is never nulled by this class. Thus if you want to
be sure that the buffer doesn't contain garbage characters then
you should initialise the contents yourself.
LIBRARY
OTC
AUTHOR(S)
Graham Dumpleton
COPYRIGHT
Copyright 1992 OTC LIMITED
Copyright 1994 DUMPLETON SOFTWARE CONSULTING PTY LIMITED