IlsString Class Reference

Implements a null-terminated string. More...

#include <ilserver/sstring.h>

Public Member Functions
	IlsString (const char *s, int len)
	This constructor creates a new string using the first len bytes of the character array s. More...
	IlsString (const char *value=0)
	This default constructor creates an instance of a string from the character array value, if any. More...
	IlsString (const IlsString &value)
	Copy constructor. More...
	~IlsString ()
	Destructor. More...
RefCount	getRefCount () const
	Returns the current reference count.
IlsBoolean	isEmpty () const
	Returns IlsTrue if the string contains no characters.
const char *	value () const
	Returns a pointer to the underlying null-terminated string. If the string is null, this function will return an empty non-zero string.
Conversion Operators
	operator const char * () const
	Returns a pointer to the underlying null-terminated string. More...
String Length
int	getLength () const
	Returns the length of the underlying null-terminated string.
int	getLengthBytes () const
	Returns the length of the string in bytes. More...
Assignement Operators
IlsString &	operator= (const IlsString &)
	Assigns an IlsString to another. More...
IlsString &	operator= (const char *)
	Assigns a C string to the IlsString. More...
Comparison Operators
IlsBoolean	operator== (const char *) const
	Returns IlsTrue if the two underlying strings are the same.
IlsBoolean	operator== (const IlsString &) const
	Returns IlsTrue if the two underlying strings are the same.
IlsBoolean	operator!= (const char *) const
	Returns IlsTrue if the two underlying strings are not the same.
IlsBoolean	operator!= (const IlsString &) const
	Returns IlsTrue if the two underlying strings are not the same.
IlsBoolean	operator< (const char *value) const
	Returns IlsTrue if the underlying string of the instance is lexically lower than the string value.
IlsBoolean	operator< (const IlsString &value) const
	Returns IlsTrue if the underlying string of the instance is lexically lower than the string value.
IlsBoolean	operator> (const char *value) const
	Returns IlsTrue if the underlying string of the instance is lexically greater than the string value.
IlsBoolean	operator> (const IlsString &value) const
	Returns IlsTrue if the underlying string of the instance is lexically greater than the string value.
IlsBoolean	operator<= (const char *value) const
	Returns IlsTrue if the underlying string of the instance is lexically lower than or equal to the string value.
IlsBoolean	operator<= (const IlsString &value) const
	Returns IlsTrue if the underlying string of the instance is lexically lower than or equal to the string value.
IlsBoolean	operator>= (const char *value) const
	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
	Returns IlsTrue if the underlying string of the instance is lexically greater than or equal to the string value.
Copying and Appending to a String
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.
IlsString &	operator<< (char)
IlsString &	operator<< (const char *)
IlsString &	operator<< (short)
IlsString &	operator<< (unsigned short)
IlsString &	operator<< (int)
IlsString &	operator<< (unsigned int)
IlsString &	operator<< (long)
IlsString &	operator<< (unsigned long)
IlsString &	operator<< (long long)
IlsString &	operator<< (unsigned long long)
IlsString &	operator<< (float)
IlsString &	operator<< (double)
IlsString &	operator<< (const IlsString &)
Comparing Strings
int	strcmp (const IlsString &) const
	Compares lexically the two strings. More...
int	strncmp (const IlsString &, int n) const
	Identical to strcmp() except that it compares a maximum n characters or multibyte characters only.
Substrings
IlsString	substring (int start, int end=-1) const
	Returns a new string which is a substring of the calling string. More...
IlsBoolean	removeWord (IlsString &returnedString, char c)
	Removes a word, which is returned in the parameter returnedString, up to the separator character c included. More...

Static Public Member Functions
static int	GetMaxCharSize ()
	Returns the maximum size possible for a character (or multibyte character) in bytes.
static void	SetUseLocaleRoutines (IlsBoolean)
	Sets the IlsString class in multi-byte mode if the parameter to the function is IlsTrue. More...
Raising Exceptions
static IlsBoolean	GetRaiseExceptionOnError ()
	Tests whether the class IlsString raises an exception when an error is detected.
static void	SetRaiseExceptionOnError (IlsBoolean)
	Stop the class IlsString from raising an exception when an error is detected. More...

Static Public Attributes
static const IlsString	Null
	This static string constant contains an empty string. More...

Protected Member Functions
	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. More...

Friends
class	IlsStringFactory
ILSIMPORT IlsLogfile &	operator<< (IlsLogfile &lf, const IlsString &value)
	Writes the string value into the logfile lf.

Detailed Description

Implements a null-terminated string.

Library: server
and mvcomp

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.

See also

IlsStringFactory.

Constructor & Destructor Documentation

IlsString() [1/4]

IlsString::IlsString

(

const char *

value = 0

)

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

Parameters

value

a C string or null

IlsString() [2/4]

IlsString::IlsString	(	const char *	s,
		int	len
	)

This constructor creates a new string using the first len bytes of the character array s.

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() [3/4]

IlsString::IlsString

(

const IlsString &

value

)

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()

IlsString::~IlsString

(

)

Destructor.

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.

IlsString() [4/4]

IlsString::IlsString ( int  , const char *    )

protected

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.

Member Function Documentation

getLengthBytes()

int IlsString::getLengthBytes

(

)

const

Returns the length of the string in bytes.

• In the case where the static member function GetMaxCharSize() 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.

operator const char *()

IlsString::operator const char *

(

)

const

Returns a pointer to the underlying null-terminated string.

Note that this operator may return zero.

operator=() [1/2]

IlsString& IlsString::operator=

(

const char *

)

Assigns a C string to the IlsString.

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.

operator=() [2/2]

IlsString& IlsString::operator=

(

const IlsString &

)

Assigns an IlsString to another.

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

removeWord()

IlsBoolean IlsString::removeWord	(	IlsString &	returnedString,
		char	c
	)

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.

SetRaiseExceptionOnError()

void IlsString::SetRaiseExceptionOnError ( IlsBoolean  b )

static

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.

SetUseLocaleRoutines()

void IlsString::SetUseLocaleRoutines ( IlsBoolean  b )

static

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.

strcmp()

int IlsString::strcmp

(

const IlsString &

)

const

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

substring()

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

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.

Member Data Documentation

Null

const IlsString IlsString::Null

static

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; }