rwlogo

Rogue Wave Views
Foundation Package API Reference Guide

Product Documentation:

Rogue Wave Views
Documentation Home

 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
List of all members | Public Member Functions
IlString Class Reference

Class that manages strings in single or multi-bytes. More...

#include <ilog/string.h>

Public Member Functions

 IlString (const char *cstring=0, int length=-1)
 This constructor builds a new IlString object from a C pointer to char. More...
 
 IlString (const IlString &string)
 Copy constructor. More...
 
 IlString (int value, const char *format=DefaultIntegerFormat)
 Initializes a new IlString from an integer. More...
 
 IlString (unsigned int value, const char *format=DefaultUnsignedIntegerFormat)
 Initializes a new IlString from an unsigned integer. More...
 
 IlString (short value, const char *format=DefaultShortFormat)
 Initializes a new IlString from an short integer. More...
 
 IlString (unsigned short value, const char *format=DefaultUnsignedShortFormat)
 Initializes a new IlString from an unsigned short integer. More...
 
 IlString (long value, const char *format=DefaultLongFormat)
 Initializes a new IlString from a long integer. More...
 
 IlString (unsigned long value, const char *format=DefaultUnsignedLongFormat)
 Initializes a new IlString from an unsigned long integer. More...
 
 IlString (float value, const char *format=DefaultFloatFormat)
 Initializes a new IlString from a float. More...
 
 IlString (double value, const char *format=DefaultDoubleFormat)
 Initializes a new IlString from a double. More...
 
int caseCompare (const IlString &string, int start1=0, int end1=-1, int start2=0, int end2=-1) const
 Compares this IlString, or part of it, to another, or part of it, lexicographically, ignoring case differences. More...
 
IlStringcatenate (const IlString &string, int start=0, int end=-1)
 Appends a string to this IlString. More...
 
int compare (const IlString &string, int start1=0, int end1=-1, int start2=0, int end2=-1) const
 Compares this IlString, or part of it, to another, or part of it, lexicographically. More...
 
char * copyValue () const
 Returns a copy of the internal C-style string. More...
 
IlBoolean endsWith (const IlString &suffix, int start=0, int end=-1) const
 Tests if this string ends with the specified suffix. More...
 
IlBoolean equals (const IlString &string, int start1=0, int end1=-1, int start2=0, int end2=-1) const
 Compares this string, or part of it, to another, or part of it, for equality. More...
 
int getIndexOf (const IlString &subString, int start=0, int subStart=0, int subEnd=-1) const
 Returns the index of the first occurence of a string in this IlString. More...
 
int getLastIndexOf (const IlString &subString, int end=-1, int subStart=0, int subEnd=-1) const
 Returns the index of the last occurence of a string in this IlString. More...
 
size_t getLength () const
 Returns the length of the string. More...
 
size_t getSize () const
 Returns the size, in bytes, of the string. More...
 
IlString getSubString (int start=0, int end=-1) const
 Returns a new IlString that is a sub-string of this string. More...
 
const char * getValue () const
 Returns the internal C-style string. More...
 
IlStringinsert (const IlString &string, int position=0, int start=0, int end=-1)
 Inserts a string into this IlString at a given position. More...
 
IlBoolean isBlank () const
 Tests if this string contains only white-space characters. More...
 
IlBoolean isEmpty () const
 Tests if this string is empty. More...
 
 operator const char * () const
 Cast operator to C-style string. More...
 
IlBoolean operator! () const
 The not operator. More...
 
IlBoolean operator!= (const IlString &string) const
 Inequality operator. More...
 
IlStringoperator+= (const IlString &string)
 Append operator. More...
 
IlBoolean operator< (const IlString &string) const
 Less-than operator. More...
 
IlBoolean operator<= (const IlString &string) const
 Less-or-equal operator. More...
 
IlStringoperator= (const IlString &string)
 Assignment operator. More...
 
IlBoolean operator== (const IlString &string) const
 Equality operator. More...
 
IlBoolean operator> (const IlString &string) const
 Greater-than operator. More...
 
IlBoolean operator>= (const IlString &string) const
 Greater-or-equal operator. More...
 
IlStringprepend (const IlString &string, int start=0, int end=-1)
 Prepends a string to this IlString. More...
 
void readQuoted (std::istream &istr)
 Reads this IlString content from and an input stream. More...
 
IlStringremove (int start=0, int end=-1)
 Removes a part from the current string. More...
 
IlStringremove (const IlString &removed, int start=0, int end=-1)
 Removes a sub-string from the current string. More...
 
IlStringreplace (const IlString &replacement, int start=0, int end=-1, int subStart=0, int subEnd=-1)
 Replaces a part of the current string by another string. More...
 
IlBoolean startsWith (const IlString &prefix, int start=0, int end=-1) const
 Tests if this string starts with the specified prefix. More...
 
IlStringsubstitute (const IlString &target, const IlString &replacement, int start=0, int end=-1, int targetStart=0, int targetEnd=-1, int replacementStart=0, int replacementEnd=-1)
 Substitutes all the occurrences of a sub-string by another one. More...
 
IlStringtoLower ()
 Converts all of the characters in this IlString to upper case using the rules of the default locale. More...
 
IlStringtoUpper ()
 Converts all of the characters in this IlString to lowe ase using the rules of the default locale. More...
 
void writeQuoted (std::ostream &ostr) const
 Serializes the string to an output stream, surrounded by double quotes. More...
 

Detailed Description

Class that manages strings in single or multi-bytes.

Library: ilog

According to the locale, the string is created internally with a single or multi-byte representation. This class lets you use it without having to take care of this representation. However, this class is not intended to convert either from a single byte to a multi-byte string, or from a multi-byte to a single-byte string. When an IlString object is created, it is supposed to deal with the same locale for its entire life.

This class uses a mechanism of reference counter in order to share the C strings used internally. This means that the pointers returned by operator const char*() and getValue() must be used with care. They may be invalid after any call to a member function that modifies the object that returned this pointer.

Constructor & Destructor Documentation

IlString::IlString ( const char *  cstring = 0,
int  length = -1 
)

This constructor builds a new IlString object from a C pointer to char.

A copy of cstring, up to length characters, is maintained internally. A null value is equivalent to the empty string "".

Parameters
cstringThe source string that is copied to initialize this new IlString.
lengthThe number of characters to copy from cstring. If length is -1 or greater than the length of cstring, the whole string is copied, up to the final 0 character. Note that if this object represents a multi-byte string, this value may be different than the number of bytes needed to store the string value.
See Also
IlString(const IlString&).
IlString(int, const char*).
IlString(unsigned int, const char*).
IlString(short, const char*).
IlString(unsigned short, const char*).
IlString(long, const char*).
IlString(unsigned long, const char*).
IlString(float, const char*).
IlString(double, const char*).
IlString::IlString ( const IlString string)

Copy constructor.

It builds a new IlString object from the object string. The internal C string is shared by both objects until one of them is modified.

Parameters
stringThe source IlString that is copied.
See Also
IlString(const char*, int).
IlString(int, const char*).
IlString(unsigned int, const char*).
IlString(short, const char*).
IlString(unsigned short, const char*).
IlString(long, const char*).
IlString(unsigned long, const char*).
IlString(float, const char*).
IlString(double, const char*).
IlString::IlString ( int  value,
const char *  format = DefaultIntegerFormat 
)
explicit

Initializes a new IlString from an integer.

The conversion is done according to the format string format that follows the same specifications as the format string in the "C" function printf.

Note
This constructor is declared as explicit for compilers that implement this keyword.
Parameters
valueThe value that is used to initialize this new IlString.
formatThe format to use for the conversion. The default value is "%d".
See Also
IlString(const char*, int).
IlString(const IlString&).
IlString(unsigned int, const char*).
IlString(short, const char*).
IlString(unsigned short, const char*).
IlString(long, const char*).
IlString(unsigned long, const char*).
IlString(float, const char*).
IlString(double, const char*).
IlString::IlString ( unsigned int  value,
const char *  format = DefaultUnsignedIntegerFormat 
)
explicit

Initializes a new IlString from an unsigned integer.

The conversion is done according to the format string format that follows the same specifications as the format string in the "C" function printf.

Note
This constructor is declared as explicit for compilers that implement this keyword.
Parameters
valueThe value that is used to initialize this new IlString.
formatThe format to use for the conversion. The default value is "%u".
See Also
IlString(const char*, int).
IlString(const IlString&).
IlString(int, const char*).
IlString(short, const char*).
IlString(unsigned short, const char*).
IlString(long, const char*).
IlString(unsigned long, const char*).
IlString(float, const char*).
IlString(double, const char*).
IlString::IlString ( short  value,
const char *  format = DefaultShortFormat 
)
explicit

Initializes a new IlString from an short integer.

The conversion is done according to the format string format that follows the same specifications as the format string in the "C" function printf.

Note
This constructor is declared as explicit for compilers that implement this keyword.
Parameters
valueThe value that is used to initialize this new IlString.
formatThe format to use for the conversion. The default value is "%hd".
See Also
IlString(const char*, int).
IlString(const IlString&).
IlString(int, const char*).
IlString(unsigned int, const char*).
IlString(unsigned short, const char*).
IlString(long, const char*).
IlString(unsigned long, const char*).
IlString(float, const char*).
IlString(double, const char*).
IlString::IlString ( unsigned short  value,
const char *  format = DefaultUnsignedShortFormat 
)
explicit

Initializes a new IlString from an unsigned short integer.

The conversion is done according to the format string format that follows the same specifications as the format string in the "C" function printf.

Note
This constructor is declared as explicit for compilers that implement this keyword.
Parameters
valueThe value that is used to initialize this new IlString.
formatThe format to use for the conversion. The default value is "%hu".
See Also
IlString(const char*, int).
IlString(const IlString&).
IlString(int, const char*).
IlString(unsigned int, const char*).
IlString(short, const char*).
IlString(long, const char*).
IlString(unsigned long, const char*).
IlString(float, const char*).
IlString(double, const char*).
IlString::IlString ( long  value,
const char *  format = DefaultLongFormat 
)
explicit

Initializes a new IlString from a long integer.

The conversion is done according to the format string format that follows the same specifications as the format string in the "C" function printf.

Note
This constructor is declared as explicit for compilers that implement this keyword.
Parameters
valueThe value that is used to initialize this new IlString.
formatThe format to use for the conversion. The default value is "%ld".
See Also
IlString(const char*, int).
IlString(const IlString&).
IlString(int, const char*).
IlString(unsigned int, const char*).
IlString(short, const char*).
IlString(unsigned short, const char*).
IlString(unsigned long, const char*).
IlString(float, const char*).
IlString(double, const char*).
IlString::IlString ( unsigned long  value,
const char *  format = DefaultUnsignedLongFormat 
)
explicit

Initializes a new IlString from an unsigned long integer.

The conversion is done according to the format string format that follows the same specifications as the format string in the "C" function printf.

Note
This constructor is declared as explicit for compilers that implement this keyword.
Parameters
valueThe value that is used to initialize this new IlString.
formatThe format to use for the conversion. The default value is "%lu".
See Also
IlString(const char*, int).
IlString(const IlString&).
IlString(int, const char*).
IlString(unsigned int, const char*).
IlString(short, const char*).
IlString(unsigned short, const char*).
IlString(long, const char*).
IlString(float, const char*).
IlString(double, const char*).
IlString::IlString ( float  value,
const char *  format = DefaultFloatFormat 
)
explicit

Initializes a new IlString from a float.

The conversion is done according to the format string format that follows the same specifications as the format string in the "C" function printf.

Note
This constructor is declared as explicit for compilers that implement this keyword.
Parameters
valueThe value that is used to initialize this new IlString.
formatThe format to use for the conversion. The default value is "%f".
See Also
IlString(const char*, int).
IlString(const IlString&).
IlString(int, const char*).
IlString(unsigned int, const char*).
IlString(short, const char*).
IlString(unsigned short, const char*).
IlString(long, const char*).
IlString(unsigned long, const char*).
IlString(double, const char*).
IlString::IlString ( double  value,
const char *  format = DefaultDoubleFormat 
)
explicit

Initializes a new IlString from a double.

The conversion is done according to the format string format that follows the same specifications as the format string in the "C" function printf.

Note
This constructor is declared as explicit for compilers that implement this keyword.
Parameters
valueThe value that is used to initialize this new IlString.
formatThe format to use for the conversion. The default value is "%g".
See Also
IlString(const char*, int).
IlString(const IlString&).
IlString(int, const char*).
IlString(unsigned int, const char*).
IlString(short, const char*).
IlString(unsigned short, const char*).
IlString(long, const char*).
IlString(unsigned long, const char*).
IlString(float, const char*).

Member Function Documentation

int IlString::caseCompare ( const IlString string,
int  start1 = 0,
int  end1 = -1,
int  start2 = 0,
int  end2 = -1 
) const

Compares this IlString, or part of it, to another, or part of it, lexicographically, ignoring case differences.

The strings are compared using the "C" function strcasemp (or the equivalent for multi-byte, or its equivalent stricmp), applied to their internal "C" representations. This is locale-dependent. Simply put, if the return value is 0 then this string and string are equal, ignoring case differences. If the return value is positive then this string is lexicographically after string, not considering the case of the characters. If the return value is negative then this string is lexicographically before string, independantly of the character case.

The comparison can be performed on a fragment of the current IlString object using the parameters start1 and end1.

The comparison can be performed on a fragment of string using the parameters start2 and end2.

Example:

IlString string("Lorem ipsum");
int compare1 = string.caseCompare("lorem Ipsum");
// compare1 is 0: strings are equal, ignoring case.
int compare2 = string.caseCompare("Lorem Varius");
// compare2 is <0: 'ipsum' is before 'Varius', ignoring the case.
Parameters
stringThe IlString to compare this IlString against.
start1Index, in the current string, of the first character to consider. The default value is 0, meaning the first character of the string.
end1Index, in the current string, of the last character, exclusive, to consider. The default value is -1, indicating down to the end of the string.
start2Index, in string, of the first character to consider. The default value is 0, meaning the first character of the string.
end2Index, in string, of the last character, exclusive, to consider. The default value is -1, indicating down to the end of the string.
Returns
IlTrue if this IlString (or part of it) is equal to string (or part of it).
See Also
caseCompare(), equals().
IlString& IlString::catenate ( const IlString string,
int  start = 0,
int  end = -1 
)

Appends a string to this IlString.

The string to be appended may be restricted by using the start and end parameters.

Warning
This operator may modify the internal representation of the string. This means that any pointer that was returned by getValue() or operator const char*() may become invalid.
Parameters
stringThe IlString to append to the current object.
startThe index, in string, of the first character to be appended. The default value is 0 (the first character of string).
endThe index, in string, of the last character of the string to be appended. The default value is -1, indicating that we want to append the entire string, starting at index start.
Returns
The current object.
See Also
prepend(), insert(), operator+=().
int IlString::compare ( const IlString string,
int  start1 = 0,
int  end1 = -1,
int  start2 = 0,
int  end2 = -1 
) const

Compares this IlString, or part of it, to another, or part of it, lexicographically.

The strings are compared using the "C" function strcmp (or the equivalent for multi-byte), applied to their internal "C" representations. This is locale-dependent. Simply put, if the return value is 0 then this string and string are equal. If the return value is positive then this string is lexicographically after string. If the return value is negative then this string is lexicographically before string.

The comparison can be performed on a fragment of the current IlString object using the parameters start1 and end1.

The comparison can be performed on a fragment of string using the parameters start2 and end2.

Parameters
stringThe IlString to compare this IlString against.
start1Index, in the current string, of the first character to consider. The default value is 0, meaning the first character of the string.
end1Index, in the current string, of the last character, exclusive, to consider. The default value is -1, indicating down to the end of the string.
start2Index, in string, of the first character to consider. The default value is 0, meaning the first character of the string.
end2Index, in string, of the last character, exclusive, to consider. The default value is -1, indicating down to the end of the string.
Returns
IlTrue if this IlString (or part of it) is equal to string (or part of it).
See Also
compare().
char* IlString::copyValue ( ) const

Returns a copy of the internal C-style string.

This conversion operator returns a pointer to char, in single or multi-byte according to the locale of the application. This value is allocated using the new [] operator, and the caller is responsible for deleting it, using delete [], when the value is not needed this value anymore.

See Also
getValue().
IlBoolean IlString::endsWith ( const IlString suffix,
int  start = 0,
int  end = -1 
) const

Tests if this string ends with the specified suffix.

The searched suffix may be restricted by setting the parameters start and end.

Example:

IlString string("lorem ipsum dolor sit amet");
IlString suffix("integer quis metus vitae");
IlBoolean match1 = string.endsWith(suffix);
// match1 is IlFalse: string does not end with suffix
IlBoolean match2 = string.endsWith(suffix, 13, 16);
// match2 is IlTrue: string ends with the suffix sub-string ("met")
Parameters
suffixThe suffix (or a fragment of it) that is tested.
startThe index in suffix of the first character to consider. The default value is 0, meaning the first character of suffix.
endThe index in suffix of the last character (exclusive) to consider. The default value is -1, meaning the last character of suffix, included.
Returns
IlTrue if this IlString ends with suffix (or a sub-string of it as defined with start and end) and IlFalse if it does not.
See Also
startsWith(), getLastIndexOf().
IlBoolean IlString::equals ( const IlString string,
int  start1 = 0,
int  end1 = -1,
int  start2 = 0,
int  end2 = -1 
) const

Compares this string, or part of it, to another, or part of it, for equality.

The strings are equal if the "C" function strcmp (or the equivalent for multi-byte), applied to their internal "C" representations, returns 0.

The comparison can be performed on a fragment of the current IlString object using the parameters start1 and end1.

The comparison can be performed on a fragment of string using the parameters start2 and end2.

Parameters
stringThe IlString to compare this IlString against.
start1Index, in the current string, of the first character to consider. The default value is 0, meaning the first character of the string.
end1Index, in the current string, of the last character, exclusive, to consider. The default value is -1, indicating down to the end of the string.
start2Index, in string, of the first character to consider. The default value is 0, meaning the first character of the string.
end2Index, in string, of the last character, exclusive, to consider. The default value is -1, indicating down to the end of the string.
Returns
IlTrue if this IlString (or part of it) is equal to string (or part of it).
See Also
compare().
int IlString::getIndexOf ( const IlString subString,
int  start = 0,
int  subStart = 0,
int  subEnd = -1 
) const

Returns the index of the first occurence of a string in this IlString.

The search starts forwards at the character of index start of the current IlString.

You can also search for a sub-string of subString.

Example:

IlString string("Lorem ipsum dolor sit amet");
IlString search("tortor");
int index1 = string.getIndexOf(search);
// index1 is -1: "tortor" cannot be found
int index2 = string.getIndexOf(search, 0, 1, 3);
// index2 is 1: "or", the sub-string defined by (1, 3) is in 'Lorem'
Parameters
subStringThe sub-string that is searched.
startThe start index, inclusive, of the search. The default value is 0, indicating that the search starts at the first character of the current string (and runs forwards).
subStartThe index, in subString, and inclusive, of the first character to search. The default value is 0, meaning the first character of subString.
subEndThe index, in subString, and exclusive, of the last character to search. The default value is -1, meaning the last character of subString, included.
Returns
The index, in the current string, where subString (or a portion of it, depending on subStart and subEnd) was found, or -1 if the sub-string could not be found. Note that if subString is found in string, the returned value is always greater then or equal to start.
See Also
getSubString(), getLastIndexOf().
int IlString::getLastIndexOf ( const IlString subString,
int  end = -1,
int  subStart = 0,
int  subEnd = -1 
) const

Returns the index of the last occurence of a string in this IlString.

The search starts backwards at the character of index end of the current IlString.

You can also search for a sub-string of subString.

Example:

IlString string("Lorem ipsum dolor sit amet");
IlString search("tortor");
int index1 = string.getLastIndexOf(search);
// index1 is -1: "tortor" cannot be found
int index2 = string.getLastIndexOf(search, -1, 1, 3);
// index2 is 15: "or", the sub-string defined by (1, 3) is in 'dolor'
int index3 = string.getLastIndexOf(search, 10, 1, 3);
// index3 is 1: "or", the sub-string defined by (1, 3) is in 'Lorem'
Parameters
subStringThe sub-string that is searched.
endThe start index, inclusive, of the search. The default value is -1, indicating that the search starts at the last character of the current string (and runs backwards).
subStartThe index, in subString, and inclusive, of the first character to search. The default value is 0, meaning the first character of subString.
subEndThe index, in subString, and exclusive, of the last character to search. The default value is -1, meaning the last character of subString, included.
Returns
The index, in the current string, where subString (or a portion of it, depending on subStart and subEnd) was found, or -1 if the sub-string could not be found. Note that if subString is found in string, the returned value is always less than or equal to end.
See Also
getSubString(), getIndexOf().
size_t IlString::getLength ( ) const

Returns the length of the string.

The length of a string is the number of characters it holds.

Returns
The length of the string in characters.
See Also
getSize().
size_t IlString::getSize ( ) const

Returns the size, in bytes, of the string.

This may be different from the number of characters of this string.

Returns
The size in bytes used by this IlString to store the internal representation of its content.
See Also
getLength().
IlString IlString::getSubString ( int  start = 0,
int  end = -1 
) const

Returns a new IlString that is a sub-string of this string.

This method creates and returns a sub-string of the current string, starting at the character index start, inclusive, and ending at the character index end, exclusive.

Example:

IlString string("Lorem ipsum");
IlString subString = string.getSubString(2, 5);
// subString is "rem"
Parameters
startThe index, in the current string, of the first character of the sub-string. The default value is 0 (the first character of the source string).
endThe index, in the current string, of the last character of the sub-string, in the current string. The default value is -1, indicating that we want to copy the entire string, starting at index start.
Returns
An IlString object.
See Also
getIndexOf(), getLastIndexOf().
const char* IlString::getValue ( ) const

Returns the internal C-style string.

This conversion operator returns a pointer to a char, in single or multi-byte according to the locale of the application.

The C string is stored internally. It must never be modified nor deleted.

Returns
the internal C-style string for this IlString.
See Also
copyValue(), operator const char*().
IlString& IlString::insert ( const IlString string,
int  position = 0,
int  start = 0,
int  end = -1 
)

Inserts a string into this IlString at a given position.

The string to be inserted may be restricted by using the start and end parameters.

Warning
This operator may modify the internal representation of the string. This means that any pointer that was returned by getValue() or operator const char*() may become invalid.
Parameters
stringThe IlString to prepend to the current object.
positionThe index of the character in the current string where string (or a part of it) is inserted. The default value is 0 which corresponds to a prepend() operation.
startThe index, in string, of the first character to be inserted. The default value is 0 (the first character of string).
endThe index, in string, of the last character to be inserted. The default value is -1, indicating that we want to append the entire string, starting at index start.
Returns
The current object.
See Also
catenate(), prepend().
IlBoolean IlString::isBlank ( ) const

Tests if this string contains only white-space characters.

A character in the string is considered as a white-space character if the "C" function isspace (or its multi-byte equivalent) returns true.
For the "C" locale, white-spaces are SPC (' ', 0x20), TAB ('\t', 0x09), LF ('\n', 0x0A), VT ('\v', 0x0B), FF ('\f', 0x0C) and CR ('\r', 0x0D).

Returns
IlTrue if this IlString is empty or contains only white-space characters.
See Also
isEmpty().
IlBoolean IlString::isEmpty ( ) const

Tests if this string is empty.

Returns
IlTrue if this IlString is empty (getLength() returns 0) and IlFalse if it is not.
See Also
operator!(), isBlank().
IlString::operator const char * ( ) const

Cast operator to C-style string.

This conversion operator returns a pointer to char, in single or multi-byte according to the locale of the application.

The C string is stored internally. It must never be modified nor deleted.

Returns
the internal C-style string for this IlString.
See Also
getValue(), copyValue().
IlBoolean IlString::operator! ( ) const

The not operator.

Returns
IlTrue when this string is empty and IlFalse otherwise.
See Also
isEmpty().
IlBoolean IlString::operator!= ( const IlString string) const

Inequality operator.

This methods compares the current object with another string.
Two strings are considered not equal when the "C" function strcmp (or equivalent for multi-byte), applied to the internal C string, returns a value that is not 0.

Parameters
stringThe string to compare to.
Returns
IlFalse when the strings are equal and IlTrue otherwise.
See Also
operator==().
IlString& IlString::operator+= ( const IlString string)

Append operator.

This operator catenates the given string to this.

Warning
This operator may modify the internal representation of the string. This means that any pointer that was returned by getValue() or operator const char*() may become invalid.
Parameters
stringThe IlString to append to the current object.
Returns
A reference to the modified current object.
See Also
operator=(const IlString&), operator+().
IlBoolean IlString::operator< ( const IlString string) const

Less-than operator.

Parameters
stringThe string to compare to.
Returns
IlTrue when this string is strictly before string in the lexicographical order and IlFalse otherwise.
See Also
operator>(), operator<=(), compare().
IlBoolean IlString::operator<= ( const IlString string) const

Less-or-equal operator.

Parameters
stringThe string to compare to.
Returns
IlTrue when this string is equal to or strictly before string in the lexicographical order and IlFalse otherwise.
See Also
operator<(), operator>=(), compare().
IlString& IlString::operator= ( const IlString string)

Assignment operator.

This operator assigns the given string to this.

Warning
This operator may modify the internal representation of the string. This means that any pointer that was returned by getValue() or operator const char*() may become invalid.
Parameters
stringThe IlString to be assigned to the current object.
Returns
The current object, modified by the assigment.
See Also
IlString(const IlString&).
IlBoolean IlString::operator== ( const IlString string) const

Equality operator.

This methods compares the current object with another string.
Two strings are considered equal when the "C" function strcmp (or equivalent for multi-byte), applied to the internal C string, returns 0.

Parameters
stringThe string to compare to.
Returns
IlTrue when the strings are equal and IlFalse otherwise.
See Also
operator!=(), equals().
IlBoolean IlString::operator> ( const IlString string) const

Greater-than operator.

Parameters
stringThe string to compare to.
Returns
IlTrue when this string is strictly after string in the lexicographical order and IlFalse otherwise.
See Also
operator<(), operator>=(), compare().
IlBoolean IlString::operator>= ( const IlString string) const

Greater-or-equal operator.

Parameters
stringThe string to compare to.
Returns
IlTrue when this string is equal to or strictly after string in the lexicographical order and IlFalse otherwise.
See Also
operator>(), operator<=(), compare().
IlString& IlString::prepend ( const IlString string,
int  start = 0,
int  end = -1 
)

Prepends a string to this IlString.

The string to be prepended may be restricted by using the start and end parameters.

Warning
This operator may modify the internal representation of the string. This means that any pointer that was returned by getValue() or operator const char*() may become invalid.
Parameters
stringThe IlString to prepend to the current object.
startThe index, in string, of the first character to be prepended. The default value is 0 (the first character of string).
endThe index, in string, of the last character of the string to be prepended. The default value is -1, indicating that we want to append the entire string, starting at index start.
Returns
The current object.
See Also
catenate(), insert(), operator+=().
void IlString::readQuoted ( std::istream &  istr)

Reads this IlString content from and an input stream.

The format is defined in the method writeQuoted().

Warning
This operator may modify the internal representation of the string. This means that any pointer that was returned by getValue() or operator const char*() may become invalid.
Parameters
istrThe input stream where the string is read.
See Also
writeQuoted(), operator>>(std::istream&, IlString&).
IlString& IlString::remove ( int  start = 0,
int  end = -1 
)

Removes a part from the current string.

Warning
This operator may modify the internal representation of the string. This means that any pointer that was returned by getValue() or operator const char*() may become invalid.
Parameters
startThe index of the first character to remove. The default value is 0 which is the first character of the string.
endThe index of the last character to be removed. The default value is -1, indicating that the removal goes down to the end of the string.
Returns
A reference to the current object.
See Also
remove(const IlString&, int, int).
IlString& IlString::remove ( const IlString removed,
int  start = 0,
int  end = -1 
)

Removes a sub-string from the current string.

If removed does not appear in the current string, this method does nothing.

The string to be removed may be restricted by using the start and end parameters.

Warning
This operator may modify the internal representation of the string. This means that any pointer that was returned by getValue() or operator const char*() may become invalid.

Example:

IlString string1("Lorem ipsum");
string1.remove("");
// string1 is unchanged.
IlString string2("Lorem ipsum");
string2.remove("dolor");
// string2 is unchanged.
IlString string3("Lorem ipsum dolor sit amet");
string3.remove("dolor ");
// string3 is now "Lorem ipsum sit amet".
Parameters
removedThe string to be removed.
startThe index, in removed, of the first character to be removed. The default value is 0 (the first character of removed).
endThe index, in string, of the last character of the string to be removed. The default value is -1, indicating that we want to remove the entire string, starting at index start.
Returns
The current object, potentially modified.
See Also
remove(int, int), replace(), substitute().
IlString& IlString::replace ( const IlString replacement,
int  start = 0,
int  end = -1,
int  subStart = 0,
int  subEnd = -1 
)

Replaces a part of the current string by another string.

A porting of the current string is replaced by another string or part of it.
Note that if the caller leaves start, end, subStart and subEnd to their default value, this method is equivalent to a raw assignment (see operator=()).
Similarly, if start and end are equal, this method is equivalent to insert().

Warning
This operator may modify the internal representation of the string. This means that any pointer that was returned by getValue() or operator const char*() may become invalid.

Example:

IlString string("lorem ipsum dolor");
string.replace("varius purus", 6);
// string is now "lorem varius purus".
Parameters
replacementThe string to replace in the current string.
startThe index in the current string of the first character to be replaced. The default value is 0 which is the first character of the string.
endThe index of the last character to be replaced. The default value is -1, indicating that the replacement goes down to the end of the string.
subStartThe index in replacement of the first character that is inserted. The default value is 0 which is the first character of the string.
subEndThe index in replacement of the last character that is inserted. The default value is -1, indicating that the replacement goes down to the end of the string.
Returns
The current object, potentially modified.
See Also
remove(), substitute().
IlBoolean IlString::startsWith ( const IlString prefix,
int  start = 0,
int  end = -1 
) const

Tests if this string starts with the specified prefix.

The searched prefix may be restricted by setting the parameters start and end.

Example:

IlString string("lorem ipsum");
IlString prefix("dolor sit amet");
IlBoolean match1 = string.startsWith(prefix);
// match1 is IlFalse: string does not start with prefix
IlBoolean match2 = string.startsWith(prefix, 2, 5);
// match2 is IlTrue: string begins with the prefix sub-string ("lor")
Parameters
prefixThe prefix (or a fragment of it) that is tested.
startThe index in prefix of the first character to consider. The default value is 0, meaning the first character of prefix.
endThe index in prefix of the last character (exclusive) to consider. The default value is -1, meaning the last character of prefix, included.
Returns
IlTrue if this IlString begins with prefix (or a sub-string of it as defined with start and end) and IlFalse if it does not.
See Also
endsWith(), getIndexOf().
IlString& IlString::substitute ( const IlString target,
const IlString replacement,
int  start = 0,
int  end = -1,
int  targetStart = 0,
int  targetEnd = -1,
int  replacementStart = 0,
int  replacementEnd = -1 
)

Substitutes all the occurrences of a sub-string by another one.

Every occurences of target, in the range [targetStart, targetEnd], that appear in the current string, in the range [start, end], will be replaced by replacement, in the range [replacementStart, replacementEnd].

Warning
This operator may modify the internal representation of the string. This means that any pointer that was returned by getValue() or operator const char*() may become invalid.

Example:

IlString string("Lorem ipsum dolor sit amet... Suspendisse lectus tortor");
string.substitute("dolor", "nunc", 0, -1,
3, -1,
1, 3);
// string is now "Lunem ipsum dolun sit amet... Suspendisse lectus tuntun"
// because "dolor"[3, -1] = "or" and "nunc"[1, 3] = "un"
Parameters
targetA constant reference to an IlString object.
replacementA constant reference to an IlString object.
startThe index in the current object of the first character to start the search for target. The default value is 0 which is the first character of the string.
endThe index in the current object of the last character to stop the search for target. The default value is -1 which is past the last character of the string.
targetStartThe index in target of the first character to search for. The default value is 0 which is the first character of the string.
targetEndThe index in target of the last character to search for. The default value is -1 which is past the last character of the string.
replacementStartThe index in replacement of the first character to insert. The default value is 0 which is the first character of the string.
replacementEndThe index in replacement of the last character to insert. The default value is -1 which is past the last character of the string.
Returns
A reference to the current object, potentially modified.
See Also
IlString::remove, IlString::replace.
IlString& IlString::toLower ( )

Converts all of the characters in this IlString to upper case using the rules of the default locale.

Warning
This operator may modify the internal representation of the string. This means that any pointer that was returned by getValue() or operator const char*() may become invalid.
Returns
The current object, converted to upper case.
See Also
toUpper().
IlString& IlString::toUpper ( )

Converts all of the characters in this IlString to lowe ase using the rules of the default locale.

Warning
This operator may modify the internal representation of the string. This means that any pointer that was returned by getValue() or operator const char*() may become invalid.
Returns
A reference to the current object, converted to lower case.
See Also
toLower().
void IlString::writeQuoted ( std::ostream &  ostr) const

Serializes the string to an output stream, surrounded by double quotes.

Every space and double quote characters are prefixed by a backslash.

Parameters
ostrThe output stream where the string is written.
See Also
readQuoted(), operator<<(std::ostream&, const IlString&).

© Copyright 2015, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.