User Defined String Class

---

Topics:

Overview
Conditional Directives
Type Definitions
Functions

---

Overview

The gxString class is a user-defined string class used to create and manipulate null-terminated resizable character strings. By design you can use another string class in place of the user-defined string class simply by modifying the gxString type definition. This implementation allows you to use other existing string classes as required by your application.

By default the UString class is used to define the gxString type. The UString class includes a basic set of typical string class functions such as c_str(), length(), resize(), is_null, etc. It also incorporates several string manipulation and search functions plus several overloads that allow you to use UString objects like the built-in data types: char, int, long, float, and double.

---

Conditional Directives

The following conditional directives are used to define non-portable string routines that need to be ported between UNIX and WIN32 platforms.

__DOS__ - Directive used for all DOS compilers

__UNIX__ - Directive used for all UNIX compilers

__WIN32__ - Directive used for all WIN32 compilers

---

Type Definitions

The "gxstring.h" uses the following type definition to define the type used for the UString class. By default the UString class is used:

typedef UString gxString;

This type definition allows you to substitute another string class for the UString class.

---

Functions

UString::UString()
UString::~UString()
UString::Cat()
UString::Clear()
UString::DeleteAfter()
UString::DeleteAfterIncluding()
UString::DeleteAfterLast()
UString::DeleteAfterLastIncluding()
UString::DeleteAt()
UString::DeleteBefore()
UString::DeleteBeforeIncluding()
UString::DeleteBeforeLast()
UString::DeleteBeforeLastIncluding()
UString::FilterChar()
UString::FilterString()
UString::Find()
UString::FindLast()
UString::IFind()
UString::InsertAt()
UString::ReplaceAt()
UString::ReplaceChar()
UString::ReplaceString()
UString::SetString()
UString::ToLower()
UString::ToUpper()
UString::TrimLeadingSpaces()
UString::TrimTrailingSpaces()
UString::c_str()
UString::is_null()
UString::length()
UString::resize()
UString::strdup()
UString Overloaded Operators
Standalone Helper Functions

UString::UString() - Default class constructor.

UString::UString(const char *s, unsigned bytes = 0) - Class constructor used to construct a UString object and load the specified string in memory. The number of bytes allocated for the string is dependent on the string length, if this is a null terminated string, or the number of bytes specified. By Default this constructor assumes that "s" is a null terminated string. If a byte size is specified by the "bytes" variable the string is treated as raw pattern of bytes and a null terminator is not required.

UString::UString(unsigned bytes) - Class constructor used to allocate a specified number of bytes in memory for a string.

UString::UString(const UString &s) - Class copy constructor. This copy constructor does not use share semantics and guarantees that each copy will be unique.

UString::~UString() - Class destructor responsible for freeing the memory allocated for this string object.

void UString::Cat(const char *s, unsigned bytes) - Public member function used to concatenate a specified number of bytes 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 string to the end of the object that invoked the call.

void UString::Clear() - Public member function used to clear this string without freeing its memory segment.

int UString::DeleteAfter(const char *s) - Public member function used to delete everything after the specified string. Returns true if successful.

int UString::DeleteAfterIncluding(const char *s) - Public member function used to delete everything after the specified string including the string itself. Returns true if successful.

int UString::DeleteAfterLast(const char *s) - Public member function used to delete everything after the last occurrence of the specified string. Returns true if the any characters were deleted.

int UString::DeleteAfterLastIncluding(const char *s) - Public member function used to delete everything after the last occurrence of the specified string including the string itself. Returns true if the any characters were deleted.

unsigned UString::DeleteAt(unsigned position, unsigned bytes) - Public member function used to delete a specified number of bytes, starting at the specified position. Returns the number of bytes deleted.

int UString::DeleteBefore(const char *s) - - Public member function used to delete everything before the specified string. Returns true if successful.

int UString::DeleteBeforeIncluding(const char *s) - Public member function used to delete everything before the specified string including the string itself. Returns true if successful.

int UString::DeleteBeforeLast(const char *s) - Public member function used to delete everything before the last occurrence of the specified string. Returns true if the any characters were deleted.

int UString::DeleteBeforeLastIncluding(const char *s) - Public member function used to delete everything before the last occurrence of the specified string including the string itself. Returns true if the any characters were deleted.

unsigned UString::FilterChar(const char c, unsigned offset = 0) - Public member function used to filter the specified character from the object. Returns the number of characters filtered from the object.

unsigned UString::FilterString(const char *s, unsigned offset = 0) - Public member function used to filter the specified string from the object. Returns the number of strings filtered from the object.

unsigned UString::FilterString(char *s, unsigned offset = 0) - Public member function used to filter the specified string from the object. Returns the number of strings filtered from the object.

unsigned UString::Find(char *s, unsigned offset = 0) - Public member function used to find an occurrence of pattern "s" in this object. The search starts at the specified offset that will default to zero. Returns the index of the first occurrence or -1 if the string is not found.

unsigned UString::Find(char *s, unsigned bytes, unsigned offset) - Public member function the uses a case sensitive compare to find an occurrence of a sequence of bytes in this object. The search starts at the specified offset. Returns the index of the first occurrence or -1 if the string is not found.

unsigned UString::Find(const UString &s, unsigned offset = 0) - Public member function used to find an occurrence object "s" in this object. The search starts at the specified offset that will default to zero. Returns the index of the first occurrence or -1 if the string is not found.

unsigned UString::Find(const UString &s, unsigned bytes, unsigned offset) - Public member function the uses a case sensitive compare to find an occurrence of a sequence of bytes in this object. The search starts at the specified offset. Returns the index of the first occurrence or -1 if the string is not found.

unsigned UString::FindLast(const char *s) - Public member function that returns the index of the last occurrence of string "s." Returns -1 if the string is not found.

unsigned UString::FindLast(char *s) - Public member function that returns the index of the last occurrence of string "s." Returns -1 if the string is not found.

unsigned UString::IFind(char *s, unsigned offset = 0) - Public member function that returns the index of first occurrence of string "s" starting at specified offset using a case insensitive compare. Returns the index of the first occurrence or -1 if the string is not found.

unsigned UString::IFind(char *s, unsigned bytes, unsigned offset) - Public member function the uses a case insensitive compare to find an occurrence of a sequence of bytes in this object. The search starts at the specified offset. Returns the index of the first occurrence or -1 if the string is not found.

unsigned UString::IFind(const UString &s, unsigned offset = 0) - Public member function that returns the index of first occurrence of object "s" starting at specified offset using a case insensitive compare. Returns the index of the first occurrence or -1 if the string is not found.

unsigned UString::IFind(const UString &s, unsigned bytes, unsigned offset) - Public member function the uses a case insensitive compare to find an occurrence of a sequence of bytes in this object. The search starts at the specified offset. Returns the index of the first occurrence or -1 if the string is not found.

unsigned UString::InsertAt(unsigned position, const char *s, unsigned bytes) - Public member function used to insert a bytes sequence starting at the specified position. Returns the number of bytes inserted.

unsigned UString::InsertAt(unsigned position, const char *s) - Public member function used to insert a null terminated string starting at the specified position. Returns the number of bytes inserted.

unsigned UString::InsertAt(unsigned position, const UString &s) - Public member function used to insert a string object starting at the specified position. Returns the number of bytes inserted.

unsigned UString::ReplaceAt(unsigned position, const char *s, unsigned bytes) - Public member function used to replace a byte sequence starting at the specified position. Returns the number of bytes replaced.

unsigned UString::ReplaceAt(unsigned position, const char *s) - Public member function used to replace a null terminated string starting at the specified position. Returns the number of bytes replaced.

unsigned UString::ReplaceAt(unsigned position, const UString &s) - Public member function used to replace a string object starting at the specified position. Returns the number of bytes replaced.

unsigned UString::ReplaceChar(const char c, const char replacement,unsigned offset = 0) - Public member function used to replace every occurrence of the specified character starting at the specified offset. Returns the number of characters replaced in the string.

unsigned UString::ReplaceString(const char *s, const char *replacement,unsigned offset = 0) - Public member function used to replace every occurrence of the specified string starting at the specified offset. Returns the number of strings replaced.

unsigned UString::ReplaceString(char *s, char *replacement, unsigned offset = 0) - Public member function used to replace every occurrence of the specified string starting at the specified offset. Returns the number of strings replaced.

int UString::SetString(const char *s, unsigned bytes = 0) - Public member function used to set the string value for this object. This function will try to re-use the current memory segment allocated for this string before re-allocating memory for the string. Returns true if successful or false if an error occurs. NOTE: The UString class guarantees that each object is unique by storing a unique copy of the string with each object. This ensures that UString objects can be safely copy constructed, assigned, resized, and deleted by multiple threads. Multiple threads accessing shared memory segments must be handled by the application.

int UString::ToLower() - Public member function used to change all characters in the string to lower case. Returns true if successful.

int UString::ToUpper() - Public member function used to change all characters in the string to upper case. Returns true if successful.

unsigned UString::TrimLeadingSpaces() - Public member function used to filter all leading spaces from a string. Returns the number of spaces filtered.

unsigned UString::TrimTrailingSpaces() - Public member function used to filter all trailing spaces from a string. Returns the number of spaces filtered.

char *UString::c_str() - Public member function that returns the null terminated string this object is referencing.

int UString::is_null() - Public member function that returns true if this string is null.

unsigned UString::length() - Public member function that returns the string length of this string.

int UString::resize(unsigned bytes , int keep = 1) - Public member function used to resize the logical length of the buffer. If the "keep" variable is true the old data will be copied into the new space. By default the old data will not be deleted. Returns true if successful or false if an error occurs.

UString *UString::strdup() - Public member function that returns a duplicate string object or a null value if an error occurs.

Overloaded operators:
UString &UString::operator=(const UString &buf) - Class assignment operator. This assignment operator does not use share semantics and guarantees that each copy will be unique.

UString &UString::operator=(const char *s) - Class assignment operator used to assign this object to a null terminated string. This assignment operator does not use share semantics and guarantees that each copy will be unique.

int UString::operator!() - Overloaded not operator that returns true if the buffer is null.

operator UString::int () - Conversion function that returns true if the buffer is not null.

char &UString::operator[ ](unsigned i) - Overloaded subscript operator used to ensure that an index is in range before subscripting this object's string data.

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 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.

friend 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."

Standalone Helper Functions:
int CaseICmp(const UString &s1, const UString &s2) - Compare two UString objects without regard to the case of the letters. Returns -1 if a < b, 0 if a == b, and 1 if a > b

int CaseICmp(const UString &s1, const char *s) - Compare a UString object to a null terminated string without regard to the case of the letters. Returns -1 if a < b, 0 if a == b, and 1 if a > b

int CaseICmp(const char *s, const UString &s2) - Compare a null terminated string to a UString object without regard to the case of the letters. Returns -1 if a < b, 0 if a == b, and 1 if a > b

---

End Of Document