The XString Class

• Download demo project - 1.34 Kb
• Download source - 4.69 Kb

Introduction

XString or the "Extended String Class" is a generic C++ class that can handle both ASCII and UNICODE strings. It combines features of the Java String and StringBuffer classes. Like the Java "String" class, the XString class has the functions indexOf(), lastIndexOf(), startsWith(), endsWith() and equals(). Like the Java "StringBuffer" class, you can insert, replace or remove characters in an XString.

Background

The purpose of XString is to provide a single and easy interface to handle both ASCII and UNICODE strings. This class will simplify the development of real international software.

Using the code

The XString class is declared in "xstring.h" and implemented in "xstring.cpp". Include both these files in your project. The XString class is part of a namespace called "openutils".

#include "xstring.h"
using namespace openutils;

The following code create two XStrings, one with ASCII encoding and the other with UNICODE encoding.

XString ascii = "Hello ASCII world !"; // ASCII string
XString unicode = L"Hello UNICODE" world!"; // UNICODE string

You can call any of the following constructors to create an XString object:

XString Constructors

XString() Creates an XString object with ASCII encoding.

XString(const char* str) Construct a new XString by converting the specified array of chars using the ASCII character encoding.

XString(const wchar_t* str) Construct a new XString by converting the specified array of chars using UNICODE character encoding.

XString(const XString& str) Construct a new XString by copying the contents of the argument.

XString(XString str,int offset,int length) Construct a new XString by converting the value of the specified XString using it's own character encoding.

XString(const char* str,int offset,int length) Construct a new XString by converting the specified char subarray, using ASCII character encoding.

XString(const wchar_t* str,int offset,int length) Construct a new XString by converting the specified char subarray, using UNICODE character encoding.

You can also create XStrings by reading contents from text files:

XString ascii;
ascii.readFromFile("data.txt");
printf("%s",ascii); // the default encoding is ASCII, 
 //so "data.txt" must be a file saved
 // in the ASCII format.

XString unicode;
unicode.setEncoding(XString::UNICODE);
unicode.readFromFile("dataU.txt");
wprintf(L"%s",unicode.wvalue()); //"dataU.txt" must be a file saved
  // in the UNICODE format.ther operations possible on
 // an XString are listed below. Note that some functions 
will throw an XStringException, which is also declared in "xstring.h".

XString Functions

char charAt(int index) Returns the character at "index". The call will succeed only if the XString object has ASCII encoding. Throws an XStringException if called on an object with UNICODE encoding.

wchar_t wcharAt(int index) Returns the character at "index". The call will succeed only if the XString object has UNICODE encoding. Throws an XStringException if called on an object with ASCII encoding.

void concat(const XString& str) Appends the given XString to this XString.Throws an XStringException if the argument has an encoding different from this XString.

int indexOf(char c) Returns the index of the first occurrence of the specified char within this XString. Returns -1 if the char was not found.

int indexOf(char c,int offset) Returns the index of the first occurrence of the specified char within this XString. The search is performed starting at "offset". Returns -1 if the char was not found. Throws an XStringException if an invalid index is specified as offset.

int indexOf(wchar_t c) Returns the index of the first occurrence of the specified char within this XString. Returns -1 if the char was not found. Works only with UNICODE XStrings.

int indexOf(wchar_t c,int offset) Returns the index of the first occurrence of the specified char within this XString. The search is performed starting at "offset".Returns -1 if the char was not found. Works only with UNICODE XStrings. Throws an XStringException if an invalid index is specified as offset.

int indexOf(XString str) Returns the index within this xstring of the first occurrence of the specified substring.

int indexOf(XString str,int offset) Returns the index within this string of the first occurrence of the specified substring, starting at the specified offset. Throws an XStringException if an invalid index is specified as offset.

int lastIndexOf(char c) Returns the index within this string of the last occurrence of the specified character.

int lastIndexOf(char c,int offset) Returns the index within this string of the last occurrence of the specified character, searching backward starting at the specified index. Throws an XStringException if an invalid index is specified as offset.

int lastIndexOf(wchar_t c) Returns the index within this string of the last occurrence of the specified character. Works only with UNICODE XStrings.

int lastIndexOf(wchar_ c,int offset) Returns the index within this string of the last occurrence of the specified character, searching backward starting at the specified index. Works only with UNICODE XStrings. Throws an XStringException if an invalid index is specified as offset.

int lastIndexOf(XString str) Returns the index within this xstring of the last occurrence of the specified substring.

int lastIndexOf(XString str,int offset) Returns the index within this string of the last occurrence of the specified substring, starting at the specified offset. Throws an XStringException if an invalid index is specified as offset.

XString substring(int beginIndex) Returns a new string that is a substring of this string.

XString substring(int beginIndex,int endIndex) Returns a new string that is a substring of this string. Throws an XStringException if an invalid index is specified.

XString insert(XString str,int insertAt) Inserts the specified string to this string at the given index. Returns the new string.

XString replace(XString str,int insertAt) Replaces characters of this string with the specified string at the given index .Returns the new string.

XString remove(int beginIndex,int endIndex) Removes characters of this string with the specified string at the given index .Returns the new string.

XString reverse() Returns the reverse of this string.

XString rightTrim() Returns a string with right white spaces of this string removed.

XString leftTrim() Returns a string with left white spaces of this string removed.

XString trim() Returns a string with left and right white spaces of this string removed.

XString toUpperCase() Returns uppercase version of this string.

XString toLowerCase() Returns lowercase version of this string.

XString capitalize() Returns the capitalized version of this string.

XString invertCase() Returns the a version of this string with all uppercase letters converted to lowercase and vice versa.

int toInt() Constructs and returns an integer from this string.

long toLong() Constructs and returns a long from this string.

float toFloat() Constructs and returns a float from this string.

double toDouble() Constructs and returns a double from this string.

bool equals(XString str) Returns true if this string is equal to the specified string. The comparison is case sensitive.

bool equalsIgnoreCase(XString str) Returns true if this string is equal to the specified string. The comparison is case in-sensitive.

bool startsWith(XString str,bool ignoreCase = false) Returns true if this string starts with the specified string. The comparison is case in-sensitive if "ignoreCase" is true.

bool endsWith(XString str,bool ignoreCase = false) Returns true if this string ends with the specified string. The comparison is case in-sensitive if "ignoreCase" is true.

void readFromFile(const char* file) Reads the contents of the specified text file into this string. Throws an XStringException if file does not exists.

void writeToFile(const char* file,bool append = false) Write the contents of this string to the specified file. The file is overwritten if "append" is false.

void setEncoding(int enc) Sets encoding of this string to "enc". Valid values are XString::ASCII and XString::UNICODE. This function need to be called only before reading a UNICODE text files. Otherwise, encoding is automatically set based on the type of string assigned.

const char* value() Returns value of an ASCII XString as a series of chars. Throws as XStringException if the encoding is not ASCII.

const wchar_t* wvalue() Returns value of a UNICODE XString as a series of chars. Throws as XStringException if the encoding is not UNICODE.

XString overloads the '=' and '+' operators. To assign a unicode string to as XString, just prefix the string with an 'L':

XString str = L"Hello"; // assigns a unicode string 
 //and sets the encoding type to 
 // XString::UNICODE                          

In the demo project you will find a complete working program that demonstrate the use of various XString functions.

History

• Created: Dec 10th, 2003