Overview |
Topics |
|
C/C++ does not have a built-in string data type, but provides library support for null-terminated character arrays. The null termination is used as a marker to signal that the end of the array has been reached. The character array format does not support binary strings since the null termination ('\0') is not a valid binary number. The UString class is a user-defined string class used to create and manipulate non null-terminated resizable, variable-length strings of binary data. UString objects are implemented as a concrete data type, just like the built-in data types: char, int, long, float, and double. The UString class supports concatenation, find, fill, and sub-string creation.
The StrData class is used to hold the string data and its associated reference count. Reference counting is a technique used to ensure the safe deletion or modification of an object. It works by storing a reference count with each object. Each time the object is used (referenced) by some other entity the counter is incremented. When the entity is finished with the object the counter is decremented. When the counter goes to zero, it means that no entities are referencing the object, so it can be safely deleted or modified. StrData objects are always allocated dynamically. When allocated, enough additional memory will be reserved to handle the maximum string length and the reference count will be set to one. StrData objects with a reference count of one indicate that a string is unique and can be modified during assignment, sub-string creation, concatenation, fill, replacement, or insertion operations performed by the UString class. If the string is not unique the UString class will make a copy of the string data.
class StrData
{
private:
friend class UString;
StrData() { RefCount = 1; }
private:
void *operator new(size_t StrSize, unsigned Bytes = 0);
void operator delete(void *ptr);
private:
unsigned int RefCount; // Reference count for string text
char Data[1]; // Start of the string text
static StrData Null_Ptr; // Used for null strings
// The data will always be one byte long
};
void *StrData::operator new(size_t StrSize, unsigned Bytes = 0) - Overloaded new operator used to allocate memory for the size of a StrData object plus number of bytes that represent the length of the string's data. The memory for the string is allocated as an array of characters. It is the responsibility of the UString class to keep track of the string's length. The UString class must store the string data immediately following the reference count. A null pointer object will be statically allocated when a new StrData object is constructed. Null strings will always point to the null pointer object.
void StrData::operator delete(void *ptr) - Overloaded delete operator used to delete a StrData object exactly as it was allocated by the overloaded new operator.
The UString class is responsible for constructing StrData objects. After the overloaded new operator in the StrData class has allocated the memory, the UString class will copy the actual string data into memory. The allocated length of the sting data is referred to as the dimensioned length of the string. The number of bytes that the string data occupies is referred to as its logical length. Strings will be allowed to grow by a "grow by" value specified when a UString object is constructed. A "grow by" value of zero will not allow the string to grow or be reallocated.
UString::UString(unsigned Bytes = DefSize, int GB = DefInc) - Class constructor used to allocate a specified number of bytes in memory for a string, with a specified grow by increment. The DefSize and DefInc integer constants are defined within the UString class by an anonymous enumeration. The "grow by" value is used to grow the string in specified increments. If GB is set to zero the string will not be allowed to grow.
UString::UString(const char *s, int GB = DefInc) - Class constructor used to allocate memory for a string and copy the string into memory. The number of bytes allocated depends on the length of the string. The DefInc integer constant is defined within the UString class by an anonymous enumeration. The "grow by" value is used to grow the string in specified increments. If GB is set to zero the string will not be allowed to grow.
UString::UString(const char *s, unsigned Bytes, int GB = DefInc) - Class constructor used to allocate a specified number of bytes for string s and copy string s into memory based on the number of bytes specified. The DefInc integer constant is defined within the UString class by an anonymous enumeration. The "grow by" value is used to grow the string in specified increments. If GB is set to zero the string will not be allowed to grow.
UString(const UString &s, unsigned Offset, unsigned Bytes, int GB = DefInc) - Class constructor used to create a sub-string of string s. The sub-string shares its data with s, starting at the specified offset and allocating the specific number of bytes. The DefInc integer constant is defined within the UString class by an anonymous enumeration. The "grow by" value is used to grow the string in specified increments. If GB is set to zero the string will not be allowed to grow.
UString::~UString() - Class destructor responsible for unbinding the string from any shared text and deleting the text if necessary.
UString::UString(const UString &s) - Class copy constructor used to copy construct an object using share semantics. This copy constructor does not actually copy the string data. Instead the new string is bound to the same data that object s is bound to.
UString &operator=(const UString &s) - Class assignment operator used to assign one object to another using share semantics. This assignment operator unbinds the string from its data and binds it to the data shared by object s.
UString::UString &operator=(const char *s) - Class assignment operator used to assign an object to a null-terminated C string.
void UString::Cat(const char *s, unsigned Bytes) - Public member function used to concatenate a specified number of bytes from a null-terminated C string to the end of the object that invoked the call.
void UString::Cat(const char *s) - Public member function used to concatenate a null-terminated C string to the end of the object that invoked the call.
void UString::Copy(const char *s) - Public member function used to copy data from a null-terminated C string into this object.
void UString::Copy(const UString &s) - Public member function used to copy string data from object s into this object.
unsigned UString::Find(char *s, unsigned Offset = 0) - Public member function used to find an occurrence of a null-terminated C string in this object. The search starts at the specified offset that will default to zero. Returns the index of the first occurrence or the integer constant NoMatch if the string is not found. The NoMatch integer constant is defined within the UString class by an anonymous enumeration.
unsigned UString::Find(char *s, unsigned Bytes, unsigned Offset = 0) const - Public member function used to find an occurrence of a sequence of bytes, represented by a null-terminated C string, in this object. The search starts at the specified offset with will default to zero. Returns the index of the first occurrence or the integer constant NoMatch if the string is not found. The NoMatch integer constant is defined within the UString class by an anonymous enumeration.
unsigned UString::Find(const UString &s, unsigned Offset = 0) const - Public member function used to find an occurrence object s in this object. The search starts at the specified offset with will default to zero. Returns the index of the first occurrence or the integer constant NoMatch if the string is not found. The NoMatch integer constant is defined within the UString class by an anonymous enumeration.
unsigned UString::DeleteAt(unsigned Pos, unsigned Bytes) - Public member function used to delete a specified number of bytes, starting at position Pos. Returns the number of bytes deleted.
unsigned UString::ReplaceAt(unsigned Pos, const char *s, unsigned Bytes) - Public member function used to replace a specified number of bytes, starting at position Pos, with the null-terminated C string s. Returns the number of bytes replaced.
unsigned UString::ReplaceAt(unsigned Pos, const char *s) - Public member function used to replace the bytes starting at position Pos, with the null-terminated C string s. The length of string s determines the number of bytes that will be replaced. Returns the number of bytes replaced.
unsigned UString::ReplaceAt(unsigned Pos, const UString &s) - Public member function used to replace the bytes starting at position Pos, with the data pointed to by object s. The length of object s determines the number of bytes that will be replaced. Returns the number of bytes replaced.
unsigned UString::InsertAt(unsigned Pos, const char *s, unsigned Bytes) - Public member function used to insert a specified number of bytes starting at position Pos, with the null-terminated C string s. Returns the number of bytes inserted.
unsigned UString::InsertAt(unsigned Pos, const char *s) - Public member function used to insert bytes starting at position Pos, with the null-terminated C string s. The length of string s determines the number of bytes that will be inserted. Returns the number of bytes inserted.
unsigned UString::InsertAt(unsigned Pos, const UString &s) - Public member function used to insert bytes starting at position Pos, with the data pointed to by object s. The length of object s determines the number of bytes that will be inserted. Returns the number of bytes inserted.
void UString::Fill(const char *p, unsigned Bytes, unsigned Offset=0, unsigned Ln=0) - Public member function used to fill in a specified number of bytes, with null-terminated C string s, up to length Ln, starting at the specified offset. If length Ln equals zero, the dimensioned length of this object is used instead of the logical length. This function will not cause this object to grow.
void UString::Fill(const char c, unsigned Offset=0, unsigned Ln=0) { Fill(&c, 1, Offset, Ln) - Public member function used to fill in this object with a single character, up to length Ln, starting at the specified offset. If length Ln equals zero, the dimensioned length of this object is used instead of the logical length. This function will not cause this object to grow.
void UString::Fill(const char *s, unsigned Offset=0, unsigned Ln=0) - Public member function used to fill in this object with a pattern of raw bytes, up to length Ln, starting at the specified offset. If length Ln equals zero, the dimensioned length of this object is used instead of the logical length. This function will not cause this object to grow.
void UString::Fill(const UString &s, unsigned Offset=0, unsigned Ln=0) - Public member function used to fill in this object with a object s, up to length Ln, starting at the specified offset. If length Ln equals zero, the dimensioned length of this object is used instead of the logical length. This function will not cause this object to grow.
UString UString::Mid(unsigned Index, unsigned Bytes) const - Public member function that returns a sub-string of this object, starting at the specified index, for a specified number of bytes.
UString UString::Left(unsigned Ln) const - Public member function that returns the left sub-string of this object, of the specified length.
UString UString::Right(unsigned Ln) const - Public member function that returns the right sub-string of this object, of the specified length.
const char *UString::UString::NullTermStr() - Public member function used to make this object's string a null-terminated C string by making sure a null byte is inserted at the end of the string. If a null byte has to be added, the string is grown if necessary. If the string needs to grow but can't, the last character is replaced, and the logical length of the string shrinks.
unsigned UString::GetLength() const - Public member function that returns the logical length of this object's string. The logical length refers to the actual length of the string and the dimensioned length refers to the total number of bytes that have been allocated in memory for this string.
unsigned UString::length() const - Public member function that returns the logical length of this object's string. The logical length refers to the actual length of the string and the dimensioned length refers to the total number of bytes that have been allocated in memory for this string.
unsigned UString::GetDimLen() const - Public member function that returns the dimensioned length of this object's string. The dimensioned length refers to the total number of bytes that have been allocated in memory for this string and the logical length refers to the actual length of the string.
char *UString::GetTextPtr() - Public member function that returns a pointer to the start of this object's string.
const char *UString::GetTextPtr() const - Public member function that returns a pointer to the start of this object's string.
char *UString::c_str() - Public member function that returns a null-terminated C string that represents this object string.
const char *UString::c_str() const - Public member function that returns a constant null-terminated C string that represents this object string.
int UString::Grow() - Public member function use to grow this object's string by the "grow by" value set when this object was constructed or the current grow by value.
int UString::Resize(unsigned Bytes) - Public member function used to resize the number of bytes allocated for this object's string.
int UString::resize(unsigned Bytes) - Public member function used to resize the number of bytes allocated for this object's string.
int UString::FreeExtra() - Public member function used to shrink the bytes allocated for this object's string by reallocating the number bytes used. This function uses the actual length of the string and not the dimensioned length to shrink the string.
void UString::ChgGrowByInc(int GB) - Public member function used to change the default grow by increment to a specified size.
void UString::SetLength(unsigned Bytes) - Public member function used to set the logical length of this object's string to a specified number of bytes. The maximum length of the string is its dimensioned length.
int UString::IsNull() const - Public member function that returns true if this object's string is null.
int UString::is_null() const - Public member function that returns true if this object's string is null.
void UString::CopyN(const char *s, unsigned Bytes) - Private member function used to copy the data from a null-terminated C string, resizing the string if the number of bytes specified is larger than the this object's dimensioned length and the "grow by" value is not set to zero. If this object's string can't be resized, it keeps its old size, and not all of the data will be copied.
unsigned UString::InsReplAt(unsigned Pos, const char *s, unsigned Bytes, int Ins=1) - Private member function used to insert or replace (depending on Ins flag) the data pointed to by null-terminated s into this object's string. The insert or replace operation will start at a specified position in the object's string and insert or replace a specified number of bytes. The string will be truncated if necessary or grow if it is allowed to. The size it will grow will be the next highest multiple of its grow by value. If position Pos is greater then or equal to the string's logical length, then the data is concatenated on the end. Returns number of bytes inserted or replaced, or zero if error occurs.
int UString::Grow_By(unsigned Bytes) - Private member function used to grow this object's string by the specified amount.
int UString::EnsureUnique() - Private member function used to ensure that this string uniquely owns its string data. A reference count of one is used to ensure this string is unique. This function may have to copy string data to ensure this. Returns true if can make the string unique, false if can't (indicating that the allocation for a copy failed.)
int UString::IsUnique() const - Private member function that returns true if this object has only one reference to its string data or is a null string. Null strings are always unique even if several of them are pointing to the same null object.
unsigned UString::CheckIndex(unsigned i) - Private member function used to compare the logical length of this object's string to a specified index value. If the index is out of range the index value will be set to the logical length. Returns the index value.
int UString::Alloc(unsigned Bytes, int GB) - Private member function used to allocate a specified number of bytes for a new string with a "grow by" increment of GB. If memory cannot be allocated for the string data, the string will reference a null object. The dimensioned length will be set to the specified number of bytes and the logical length will be set to zero. The logical length remains a zero value until the actual data is copied into the memory location that was allocated for it.
int UString::Realloc(unsigned NewDimLen, int Keep = 1) - Private member function used to re-dimension this object's string to the specified length. If this object's "grow by" value equals zero (meaning that the string is not allowed to grow) or the no more memory could be allocated zero is returned. Returns true if successful.
void UString::Bind(const UString &s) - Private member function used to bind this object's string data to the same data the object s is bound to. This means that this object's string will no longer be unique.
void UString::UnBind() - Private member function used by the UString destructor to unbind this object from shared string data. The StrData object will be deleted if the reference count equals zero. If the string data is a null it will not be deleted.
void UString::NewBinding(const UString &s) - Private member function used to unbind this object's string data from StrData object it shares and bind it to the StrData object shared by object s.
char &UString::operator[ ](unsigned i) - Overloaded subscript operator used to ensure that an index is in range before subscripting this object's string data. If the index is out of range the index value will be set to the logical length. Subscripting may update a character in this object's string, so a check is made to ensure that the string data is unique. If the string data cannot be made unique it will point a null object.
void UString::operator+=(const UString &s) - Overloaded member operator used to concatenate the string data of object s to the end of the object that invoked the call.
void UString::operator+=(const char *s) - Overloaded member operator used to concatenate a null-terminated C string to the end of the object that invoked the call
void UString::operator+=(const char c) - Overloaded member operator used to concatenate the a single character to the end of the object that invoked the call
friend ostream &operator<<(ostream &os, const UString &s) - Overloaded operator used to convert a UString type into an ostream type.
friend istream &operator>>(istream &os, UString &s) - Overloaded operator used to convert a UString type into an istream type.
riend UString operator+(const UString &a, const UString &b) - Overloaded operator used to add two UString objects together.
friend int operator==(const UString &a, const UString &b) - Overloaded operator that returns true if its operands are equal to each other.
friend int operator!=(const UString &a, const UString &b) - Overloaded operator that returns true if its operands are not equal to each other.
friend int operator>(const UString &a, const UString &b) - Overloaded operator that returns true if its operand a is greater then b.
friend int operator>=(const UString &a, const UString &b) - Overloaded operator that returns true if its operand a is greater then or equal to b.
friend int operator<(const UString &a, const UString &b) - Overloaded operator that returns true if its operand a is less then b.
friend int operator<=(const UString &a, const UString &b) - Overloaded operator that returns true if its operand a is less then or equal to b.
friend int StringCompare(const UString &a, const UString &b) - Friend function used to compare UString object a to UString object b. Returns -1 if a is less then b, 0 if a equals b, and 1 if a is greater then b.