IlsString

Category

Utility class

Inheritance Path

IlsString

Description

This class implements a null-terminated string. The class is optimized to share strings transparently unless the string is modified, in which case a copy of the string is made. Instances of a string can be created via an optional string factory. This can be useful for caching strings or adding functionality to the strings.

The class IlsString supports multibyte strings. A multibyte string is represented by char* or const char* and cannot contain any embedded zeroes. For the class IlsString to work correctly in a multibyte environment, you must call the global function IlsSetLocaleOnce before using IlsString.

Libraries

Header File

#include <ilserver/sstring.h>

Synopsis

class IlsString

{

public:

typedef long RefCount;

IlsString(const char* value=0);

IlsString(const IlsString& value);

IlsString(const char* s, int len);

protected

IlsString(int, const char*);

public:

virtual ~IlsString();

Raising Exceptions

static IlsBoolean GetRaiseExceptionOnError();

static void SetRaiseExceptionOnError(IlsBoolean);

Operators

IlsString& operator =(const IlsString& value);

IlsString& operator =(const char* value);

Comparison Operators

IlsBoolean operator ==(const char*) const;

IlsBoolean operator ==(const IlsString&) const;

IlsBoolean operator !=(const char*) const;

IlsBoolean operator !=(const IlsString&) const;

IlsBoolean operator <(const char* value) const;

IlsBoolean operator <(const IlsString& value) const;

IlsBoolean operator >(const char* value) const;

IlsBoolean operator >(const IlsString& value) const;

IlsBoolean operator <=(const char* value) const;

IlsBoolean operator <=(const IlsString& value) const;

IlsBoolean operator >=(const char* value) const;

IlsBoolean operator >=(const IlsString& value) const;

Conversion Operators

operator const char*() const;

char operator [](int n) const;

const char& operator [](int n);

Comparing Strings

int strcmp(const IlsString&) const;

int strncmp(const IlsString&, int n) const;

Substrings

IlsString substring(int start, int end = -1) const;

IlsBoolean removeWord(IlsString& returnedString, char c);

Reference Counting

RefCount getRefCount() const;

String Length

int getLength() const;

int getLengthBytes() const;

Returning a Non-Zero String

const char* value() const;

Copying and Appending to a String

IlsString& operator << (char value);

IlsString& operator << (const char* value);

IlsString& operator << (short value);

IlsString& operator << (unsigned short value);

IlsString& operator << (int value);

IlsString& operator << (unsigned int value);

IlsString& operator << (long value);

IlsString& operator << (unsigned long value);

IlsString& operator << (float value);

IlsString& operator << (double value);

IlsString& operator << (const IlsString& value);

Writing a String to the Logfile

friend IlsLogfile& operator <<(IlsLogfile& lf,

const IlsString& value);

Constant

static const IlsString Null;

Miscellaneous

IlsBoolean isEmpty() const;

static void SetUseLocaleRoutines(IlsBoolean);

static int GetMaxCharSize();

};

Constructors

IlsString(const char* value=0);

This default constructor creates an instance of a string from the character array value, if any.

IlsString(const IlsString& value);

This is a copy constructor. The behavior of this constructor is to increment the reference counter of the underlying string that belongs to value, if there is one.

IlsString(const char* s, int len);

This constructor creates a new string using the first bytes of the character array s as specified by the parameter len. If s is a multi-byte string, the len parameter must be the number of bytes and not the number of multi-byte characters to copy. The resulting string is null-terminated.

IlsString(int, const char*);

This protected constructor is used internally by the member function IlsStringFactory::makeNonFactoryString and creates a new string without using the factory if there is one installed. In this way, a factory can create a new instance of a string when required.

Destructor

virtual ~IlsString();

The behavior of the destructor is to decrement the reference counter of the underlying string. If the reference counter drops to zero, then the underlying string is freed.

Member Functions

Raising Exceptions

[static] IlsBoolean GetRaiseExceptionOnError();

This static member function can be used to test whether the class IlsString raises an exception when an error is detected.

[static] void SetRaiseExceptionOnError(IlsBoolean);

This static member function can be used to stop the class IlsString from raising an exception when an error is detected. By default, exceptions are raised on an error.

The class IlsString can raise exceptions of type IlsInvalidStringException.

Operators

IlsString& operator =(const IlsString& value);

This assignment operator decrements the reference counter on the instance, freeing the string if the reference counter drops to zero. The reference counter of the string in value is then incremented.

IlsString& operator =(const char* value);

This assignment operator decrements the reference counter on the instance, freeing the string if the reference counter drops to zero. The string value is then copied and the reference counter set to one.

Comparison Operators

IlsBoolean operator ==(const char*) const;

This comparison operator returns IlsTrue if the two underlying strings are the same.

IlsBoolean operator ==(const IlsString&) const;

This comparison operator returns IlsTrue if the two underlying strings are the same.

IlsBoolean operator !=(const char*) const;

This comparison operator returns IlsTrue if the two underlying strings are not the same.

IlsBoolean operator !=(const IlsString&) const;

This comparison operator returns IlsTrue if the two underlying strings are not the same.

IlsBoolean operator <(const char* value) const;

This comparison operator returns IlsTrue if the underlying string of the instance is lexically less than the string value.

IlsBoolean operator <(const IlsString& value) const;

This comparison operator returns IlsTrue if the underlying string of the instance is lexically less than the string value.

IlsBoolean operator >(const char* value) const;

This comparison operator returns IlsTrue if the underlying string of the instance is lexically greater than the string value.

IlsBoolean operator >(const IlsString& value) const;

This comparison operator returns IlsTrue if the underlying string of the instance is lexically greater than the string value.

IlsBoolean operator <=(const char* value) const;

This comparison operator returns IlsTrue if the underlying string of the instance is lexically less than or equal to the string value.

IlsBoolean operator <=(const IlsString& value) const;

This comparison operator returns IlsTrue if the underlying string of the instance is lexically less than or equal to the string value.

IlsBoolean operator >=(const char* value) const;

This comparison operator returns IlsTrue if the underlying string of the instance is lexically greater than or equal to the string value.

IlsBoolean operator >=(const IlsString& value) const;

This comparison operator returns IlsTrue if the underlying string of the instance is lexically greater than or equal to the string value.

Conversion Operators

operator const char*() const;

This operator returns a pointer to the underlying null-terminated string. Note that this operator may return zero.

char operator [](int n) const;

This operator returns the character at the n'th element of the underlying string. Bounds checking is done on the index n. A value of zero means that either the index refers to the null-terminating character, or the index is out of range. Indexes start at zero.

const char& operator [](int n);

This operator assigns a character to the n'th element in the array. If the index is off the end of the array, then the string is padded with blanks and the n'th element is assigned. The result of this operation is always a null-terminated string.

Comparing Strings

int strcmp(const IlsString&) const;

This member function can be used to compare lexically the two strings. This method works correctly for multibyte strings and the current locale. The return value for the method is:

zero if the strings are the same,

less than zero if the instance of the string is lexically less than the string passed as the parameter,

greater than zero otherwise.

int strncmp(const IlsString&, int n) const;

This member function is identical to strcmp described above except that it compares a maximum n characters or multibyte characters only.

Substrings

IlsString substring(int start, int end = -1) const;

This member function returns a new string which is a substring of the calling string. The substring returned is the string that starts at the character index start and finishes at the character index end. If the parameter end is less than zero, the substring returned is from the character index start to the end of the string.

IlsBoolean removeWord(IlsString& returnedString, char c);

This member function removes a word, which is returned in the parameter returnedString, up to the separator character c included. The calling string is modified such that the returned word is removed as well as the separator character. This method works correctly for multibyte strings but does not allow you to use a multibyte character as the separator character.

Reference Counting

RefCount getRefCount() const;

This member function returns the current reference count.

String Length

int getLength() const;

This member function returns the length of the underlying null-terminated string.

int getLengthBytes() const;

This member function returns the length of the string in bytes.

In the case where the static member function GetMaxCharSize described above returns 1, calling getLengthBytes is equivalent to calling getLength.

In the case of a multibyte string, the result is the number of bytes required to store the multibyte string physically.

In all cases, the trailing zero is not included in the count.

Returning a Non-Zero String

const char* value() const;

This member function returns a pointer to the underlying null-terminated string.
If the string is null, this function will return an empty non-zero string.

Copying and Appending to a String

IlsString& operator << (char value);

IlsString& operator << (const char* value);

IlsString& operator << (short value);

IlsString& operator << (unsigned short value);

IlsString& operator << (int value);

IlsString& operator << (unsigned int value);

IlsString& operator << (long value);

IlsString& operator << (unsigned long value);

IlsString& operator << (float value);

IlsString& operator << (double value);

IlsString& operator << (const IlsString& value);

Each of these operators decrements the reference counter on the instance, freeing the string if the reference counter drops to zero, then makes a new string by appending value onto the end of the old string.

Writing a String to the Logfile

friend IlsLogfile& operator <<(IlsLogfile& lf, const IlsString& value);

This operator writes the string value into the logfile lf.

Constant

[static] const IlsString Null;

This static string constant contains an empty string. This constant can be used as a default value for functions as well as a way of returning a null string. For example:

void MyFunc1(const IlsString& name = IlsString::Null);
IlsString MyFunc2() { return IlsString::Null; }

Miscellaneous

IlsBoolean isEmpty() const;

This member function returns IlsTrue if the string contains no characters.

[static] void SetUseLocaleRoutines(IlsBoolean);

This static member function sets the IlsString class in multi-byte mode if the parameter to the function is IlsTrue. This function is called by the global function IlsSetLocaleOnce and does not normally need to be called explicitly by the application.

[static] int GetMaxCharSize();

This static member function returns the maximum size possible for a character (or multibyte character) in bytes.