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);
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);

STREAM OPERATIONS

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);

BUFFER MANAGEMENT

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;
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;
char* buffer();
inline operator char const*() const;
inline operator char*();
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
);
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
);

ASSIGNMENT

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);
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);
inline OTC_OldBuffer& operator=(OTC_OldBuffer const& theBuffer);

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);
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
);

EXTENSION

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);

REMOVAL

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

TRUNCATION

void truncate(u_int theIndex=0);

EXTRACTION

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;

SEARCHING

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;

COMPARISION

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;

NULL BUFFER

static OTC_OldBuffer const& nullBuffer();

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