Rogue Wave Views |
Rogue Wave Views Documentation Home |
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... | |
IlString & | catenate (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... | |
IlString & | insert (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... | |
IlString & | operator+= (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... | |
IlString & | operator= (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... | |
IlString & | prepend (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... | |
IlString & | remove (int start=0, int end=-1) |
Removes a part from the current string. More... | |
IlString & | remove (const IlString &removed, int start=0, int end=-1) |
Removes a sub-string from the current string. More... | |
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. More... | |
IlBoolean | startsWith (const IlString &prefix, int start=0, int end=-1) const |
Tests if this string starts with the specified prefix. More... | |
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. More... | |
IlString & | toLower () |
Converts all of the characters in this IlString to upper case using the rules of the default locale. More... | |
IlString & | toUpper () |
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... | |
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.
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 "".
cstring | The source string that is copied to initialize this new IlString . |
length | The 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. |
IlString::IlString | ( | const IlString & | string | ) |
|
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
.
explicit
for compilers that implement this keyword.value | The value that is used to initialize this new IlString . |
format | The format to use for the conversion. The default value is "%d" . |
|
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
.
explicit
for compilers that implement this keyword.value | The value that is used to initialize this new IlString . |
format | The format to use for the conversion. The default value is "%u" . |
|
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
.
explicit
for compilers that implement this keyword.value | The value that is used to initialize this new IlString . |
format | The format to use for the conversion. The default value is "%hd" . |
|
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
.
explicit
for compilers that implement this keyword.value | The value that is used to initialize this new IlString . |
format | The format to use for the conversion. The default value is "%hu" . |
|
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
.
explicit
for compilers that implement this keyword.value | The value that is used to initialize this new IlString . |
format | The format to use for the conversion. The default value is "%ld" . |
|
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
.
explicit
for compilers that implement this keyword.value | The value that is used to initialize this new IlString . |
format | The format to use for the conversion. The default value is "%lu" . |
|
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
.
explicit
for compilers that implement this keyword.value | The value that is used to initialize this new IlString . |
format | The format to use for the conversion. The default value is "%f" . |
|
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
.
explicit
for compilers that implement this keyword.value | The value that is used to initialize this new IlString . |
format | The format to use for the conversion. The default value is "%g" . |
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:
string | The IlString to compare this IlString against. |
start1 | Index, in the current string, of the first character to consider. The default value is 0 , meaning the first character of the string. |
end1 | Index, in the current string, of the last character, exclusive, to consider. The default value is -1 , indicating down to the end of the string. |
start2 | Index, in string, of the first character to consider. The default value is 0 , meaning the first character of the string. |
end2 | Index, in string, of the last character, exclusive, to consider. The default value is -1 , indicating down to the end of the string. |
IlTrue
if this IlString
(or part of it) is equal to string (or part of it). caseCompare()
, equals()
. Appends a string to this IlString
.
The string to be appended may be restricted by using the start and end parameters.
getValue()
or operator const char*()
may become invalid. string | The IlString to append to the current object. |
start | The index, in string, of the first character to be appended. The default value is 0 (the first character of string ). |
end | The 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. |
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.
string | The IlString to compare this IlString against. |
start1 | Index, in the current string, of the first character to consider. The default value is 0 , meaning the first character of the string. |
end1 | Index, in the current string, of the last character, exclusive, to consider. The default value is -1 , indicating down to the end of the string. |
start2 | Index, in string, of the first character to consider. The default value is 0 , meaning the first character of the string. |
end2 | Index, in string, of the last character, exclusive, to consider. The default value is -1 , indicating down to the end of the string. |
IlTrue
if this IlString
(or part of it) is equal to string (or part of it). 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.
getValue()
. Tests if this string ends with the specified suffix.
The searched suffix may be restricted by setting the parameters start and end.
Example:
suffix | The suffix (or a fragment of it) that is tested. |
start | The index in suffix of the first character to consider. The default value is 0 , meaning the first character of suffix. |
end | The index in suffix of the last character (exclusive) to consider. The default value is -1 , meaning the last character of suffix, included. |
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. 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.
string | The IlString to compare this IlString against. |
start1 | Index, in the current string, of the first character to consider. The default value is 0 , meaning the first character of the string. |
end1 | Index, in the current string, of the last character, exclusive, to consider. The default value is -1 , indicating down to the end of the string. |
start2 | Index, in string, of the first character to consider. The default value is 0 , meaning the first character of the string. |
end2 | Index, in string, of the last character, exclusive, to consider. The default value is -1 , indicating down to the end of the string. |
IlTrue
if this IlString
(or part of it) is equal to string (or part of it). 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:
subString | The sub-string that is searched. |
start | The 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). |
subStart | The index, in subString, and inclusive, of the first character to search. The default value is 0 , meaning the first character of subString. |
subEnd | The index, in subString, and exclusive, of the last character to search. The default value is -1 , meaning the last character of subString, included. |
-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. 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:
subString | The sub-string that is searched. |
end | The 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). |
subStart | The index, in subString, and inclusive, of the first character to search. The default value is 0 , meaning the first character of subString. |
subEnd | The index, in subString, and exclusive, of the last character to search. The default value is -1 , meaning the last character of subString, included. |
-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. 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.
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.
IlString
to store the internal representation of its content. 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:
start | The 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). |
end | The 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. |
IlString
object. 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.
IlString
. 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.
getValue()
or operator const char*()
may become invalid. string | The IlString to prepend to the current object. |
position | The 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. |
start | The index, in string, of the first character to be inserted. The default value is 0 (the first character of string ). |
end | The 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. |
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).
IlTrue
if this IlString
is empty or contains only white-space characters. isEmpty()
. IlBoolean IlString::isEmpty | ( | ) | const |
Tests if this string is empty.
IlTrue
if this IlString
is empty (getLength()
returns 0
) and IlFalse
if it is not. 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.
IlString
. getValue()
, copyValue()
. IlBoolean IlString::operator! | ( | ) | const |
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
.
string | The string to compare to. |
IlFalse
when the strings are equal and IlTrue
otherwise. operator==()
. Append operator.
This operator catenates the given string to this
.
getValue()
or operator const char*()
may become invalid. string | The IlString to append to the current object. |
operator=(const IlString&)
, operator+()
. Less-than operator.
string | The string to compare to. |
IlTrue
when this string is strictly before string in the lexicographical order and IlFalse
otherwise. operator>()
, operator<=()
, compare()
. Less-or-equal operator.
string | The string to compare to. |
IlTrue
when this string is equal to or strictly before string in the lexicographical order and IlFalse
otherwise. operator<()
, operator>=()
, compare()
. Assignment operator.
This operator assigns the given string to this
.
getValue()
or operator const char*()
may become invalid. string | The IlString to be assigned to the current object. |
IlString(const IlString&)
. 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
.
string | The string to compare to. |
IlTrue
when the strings are equal and IlFalse
otherwise. operator!=()
, equals()
. Greater-than operator.
string | The string to compare to. |
IlTrue
when this string is strictly after string in the lexicographical order and IlFalse
otherwise. operator<()
, operator>=()
, compare()
. Greater-or-equal operator.
string | The string to compare to. |
IlTrue
when this string is equal to or strictly after string in the lexicographical order and IlFalse
otherwise. operator>()
, operator<=()
, compare()
. Prepends a string to this IlString
.
The string to be prepended may be restricted by using the start and end parameters.
getValue()
or operator const char*()
may become invalid. string | The IlString to prepend to the current object. |
start | The index, in string, of the first character to be prepended. The default value is 0 (the first character of string ). |
end | The 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. |
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()
.
getValue()
or operator const char*()
may become invalid. istr | The input stream where the string is read. |
IlString& IlString::remove | ( | int | start = 0 , |
int | end = -1 |
||
) |
Removes a part from the current string.
getValue()
or operator const char*()
may become invalid. start | The index of the first character to remove. The default value is 0 which is the first character of the string. |
end | The 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. |
remove(const IlString&, int, int)
. 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.
getValue()
or operator const char*()
may become invalid.Example:
removed | The string to be removed. |
start | The index, in removed, of the first character to be removed. The default value is 0 (the first character of removed ). |
end | The 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. |
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()
.
getValue()
or operator const char*()
may become invalid.Example:
replacement | The string to replace in the current string. |
start | The 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. |
end | The 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. |
subStart | The index in replacement of the first character that is inserted. The default value is 0 which is the first character of the string. |
subEnd | The 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. |
remove()
, substitute()
. Tests if this string starts with the specified prefix.
The searched prefix may be restricted by setting the parameters start and end.
Example:
prefix | The prefix (or a fragment of it) that is tested. |
start | The index in prefix of the first character to consider. The default value is 0 , meaning the first character of prefix. |
end | The index in prefix of the last character (exclusive) to consider. The default value is -1 , meaning the last character of prefix, included. |
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. 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].
getValue()
or operator const char*()
may become invalid.Example:
target | A constant reference to an IlString object. |
replacement | A constant reference to an IlString object. |
start | The 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. |
end | The 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. |
targetStart | The index in target of the first character to search for. The default value is 0 which is the first character of the string. |
targetEnd | The index in target of the last character to search for. The default value is -1 which is past the last character of the string. |
replacementStart | The index in replacement of the first character to insert. The default value is 0 which is the first character of the string. |
replacementEnd | The index in replacement of the last character to insert. The default value is -1 which is past the last character of the string. |
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.
getValue()
or operator const char*()
may become invalid. toUpper()
. IlString& IlString::toUpper | ( | ) |
Converts all of the characters in this IlString
to lowe ase using the rules of the default locale.
getValue()
or operator const char*()
may become invalid. 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.
ostr | The output stream where the string is written. |
© 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.