NAME
OTC_RString -
Envelope class for holder of string memory.
SYNOPSIS
#include <OTC/text/rstring.hh>
class OTC_RString
{
public:
~OTC_RString();
OTC_RString(
u_int theLength,
OTC_StringBuffering theType=OTCLIB_BUFFERED
);
OTC_RString(
u_int theLength,
void const* theObject,
OTC_StringBuffering theType=OTCLIB_BUFFERED
);
OTC_RString(OTC_RString const& theString);
inline u_int length() const;
inline u_int capacity() const;
inline OTC_Boolean isShared() const;
inline OTC_Boolean isLocked() const;
inline OTC_Boolean isSymbol() const;
char const* string() const;
char* string();
inline char operator[](u_int theIndex) const;
inline char& operator[](u_int theIndex);
void reallocate(u_int theLength);
inline void sync();
void lock();
void unlock();
OTC_RString const& operator=(OTC_RString const& theString);
friend ostream& operator<<(
ostream& outs,
OTC_RString const& theString
);
};
CLASS TYPE
Concrete
DESCRIPTION
The OTC_RString class is a wrapper for OTC_StringData. This
class implements the functionality for maintaining the string
memory and the delayed copy mechanism. The OTC_StringData class
holds all the data required. This class ensures that the string is
null terminated on initial allocation and reallocation. If you
overwrite the null terminator it is your own problem.
INITIALISATION
OTC_RString(
u_int theLength,
OTC_StringBuffering theType=OTCLIB_BUFFERED
);
Allocates string memory for string of
length theLength. If theType is
OTCLIB_UNBUFFERED, only enough memory
to hold the string and a null terminator
will initially be allocated. If theType
is OTCLIB_BUFFERED, the default,
additional memory may be allocated to try
to reduce memory allocations on changes in
the length of the string.
OTC_RString(
u_int theLength,
void const* theObject,
OTC_StringBuffering theType=OTCLIB_BUFFERED
);
Allocates string memory for string of
length theLength. If theType is
OTCLIB_UNBUFFERED, only enough memory
to hold the string and a null terminator
will initially be allocated. If theType
is OTCLIB_BUFFERED, the default,
additional memory may be allocated to try
to reduce memory allocations on changes in
the length of the string. The additional
argument of theObject indicates which
object internal memory should be allocated
with when ObjectStore is being used.
OTC_RString(OTC_RString const& theString);
Results in this class referencing the same
memory as theString.
QUERY
inline u_int length() const;
Returns the length of the string.
Does not include the null terminator.
inline u_int capacity() const;
Returns the capacity of the string.
Doesn't include the cell which is
reserved for the null terminator.
inline OTC_Boolean isShared() const;
Returns OTCLIB_TRUE if this class
references a chunk of memory which is also
being referenced by another instance of
the class.
inline OTC_Boolean isLocked() const;
Returns OTCLIB_TRUE if the memory is
currently locked for exclusive use.
inline OTC_Boolean isSymbol() const;
Returns OTCLIB_TRUE if the memory
represents a symbol. Only really useful to
OTC_Symbol.
ACCESS
Note that the following functions do nothing special if another
instance of the class is referencing the same string. If
modifications are going to be made to the memory, either
sync() or reallocate() should be invoked to force a separate
copy to be made.
If you overwrite the null terminator added by this class via
these functions, it is your problem.
char const* string() const;
Returns a pointer to the string.
char* string();
Returns a pointer to the string.
inline char operator[](u_int theIndex) const;
Returns a reference to the character at
position theIndex into the string. No
bounds checking is performed.
inline char& operator[](u_int theIndex);
Returns a reference to the character at
position theIndex into the string. No
bounds checking is performed.
ALLOCATION
void reallocate(u_int theLength);
Similar to invoking realloc(3), this
function will result in a new string being
allocated with sufficient size to hold
theLength characters. If theLength is
less than or equal to the current capacity
of this string and the string is not also
being referenced by another instance of
this class, no reallocation will be
made, instead the same piece of memory
will be used, the length adjusted and a
new null terminator inserted. If a new
string is allocated, the contents of
the old string will be copied into the
new. In doing this, instances of this
class which previously shared the same
string as this class will no longer do so,
instead they will continue to reference
the old string.
inline void sync();
If the string is shared, this forces a
copy to be made. It is equivalent to
invoking reallocate(length()).
LOCKING
void lock();
Locks the memory for exclusive use.
If the memory is shared, a copy will
be made first. If the memory is already
locked an exception is raised.
void unlock();
Unlocks the memory from exclusive use.
Raises an exception if the memory is not
locked.
ASSIGNMENT
OTC_RString const& operator=(OTC_RString const& theString);
Results in the current string being
discarded and the one held by theString
to be referenced instead. The old string
will only be deleted if no other instances
of the class reference it.
STREAMS OUTPUT
friend ostream& operator<<(
ostream& outs,
OTC_RString const& theString
);
Dumps theString to the stream outs.
Width and justification specifications
are honoured.
LIBRARY
OTC
AUTHOR(S)
Graham Dumpleton
COPYRIGHT
Copyright 1993 1994 TELSTRA CORPORATION LIMITED
Copyright 1994 DUMPLETON SOFTWARE CONSULTING PTY LIMITED