void rpl(size_t pos, const cstr & oldstr, const cstr & newstr)
Replace a sub-string within the string object with the contents of another string object.
| Parameter | Description |
|---|---|
| pos | The start position of the sub-string to replace. |
| oldstr | The sub-string to replace. |
| newstr | The new string. |
This example shows how to implement "search and replace" using str() and rpl():
cstr str("ABCABCABC");
cstr search("BC");
cstr replace("bc");
size_t pos = 0;
while(str.str(search,pos))
str.rpl(pos,search,replace);
assert(str=="AbcAbcAbc");
void rpl(char old_c, char new_c)
Replace all old_c characters in the string object with new_c.
| Parameter | Description |
|---|---|
| old_c | The character to be replaced. |
| new_c | The character to replace with. |
Example:
cstr str("ABCABCABC");
str.rpl('A','X');
assert(str=="XBCXBCXBC");
void rev()
Reverse the contents of the string object.
This function is not available on all operating systems!
Example:
cstr str("ABC");
str.rev();
assert(str=="CBA");
cstr mid(size_t from, size_t to) const
Create a copy of a sub-string in the string object. The specified bounds are inclusive.
| Parameter | Description |
|---|---|
| from | Index of the first character to copy. |
| to | Index of the last character to copy. |
| Return value | A string object containing the copy. |
Example:
cstr str1("ABCABCABC");
cstr str2 = str1.mid(2,5);
assert(str2=="CABC");
cstr left(size_t len) const
Create a copy of the first len characters in the string object.
| Parameter | Description |
|---|---|
| len | Number of character to copy. |
| Return value | A string object containing the copy. |
Example:
cstr str1("ABCABCABC");
cstr str2 = str1.left(2);
assert(str2=="AB");
cstr right(size_t len) const
Create a copy of the last len characters in the string object.
| Parameter | Description |
|---|---|
| len | Number of character to copy. |
| Return value | A string object containing the copy. |
Example:
cstr str1("ABCABCABC");
cstr str2 = str1.right(2);
assert(str2=="BC");
bool chr(char c, size_t & pos) const
Search for the first occurrence of a character in the string object,
starting at the specified position. The search is case sensitive.
| Parameter | Description |
|---|---|
| c | The character to search for. |
| pos | The search will start at this index. If the function returns true, pos will contain the index where the character was found. |
| Return value | True if the character was found, false if not. |
Example:
cstr str("abcdeabcde");
size_t pos = 0;
while(str.chr('c',pos))
str.del(pos,pos);
assert(str=="abdeabde");
bool rchr(char c, size_t & pos) const
Search backwards for the first occurrence of a character in the string object,
starting at the specified position. The search is case sensitive.
| Parameter | Description |
|---|---|
| c | The character to search for. |
| pos | The search will start at this index. If the function returns true, pos will contain the index where the character was found. |
| Return value | True if the character was found, false if not. |
Example:
cstr str("abcabc");
size_t pos = str.len();
if(str.rchr('b',pos))
str.set(pos,'B');
assert(str=="abcaBc");
bool str(const char * pstr, size_t & pos) const
Search for the first occurrence of a sub-string in the string object,
starting at the specified position. The search is case sensitive.
| Parameter | Description |
|---|---|
| pstr | A zero terminated sub-string to search for. |
| pos | The search will start at this index. If the function returns true, pos will contain the start index of the sub-string. |
| Return value | True if the sub-string was found, false if not. |
This example shows how to implement "search and replace" using str() and rpl():
cstr str("ABCABCABC");
cstr search("BC");
cstr replace("bc");
size_t pos = 0;
while(str.str(search,pos))
str.rpl(pos,search,replace);
assert(str=="AbcAbcAbc");
bool tok(const char * pdelim, cstr & tok, size_t & pos) const
This function is used to extract tokens from a delimited string.
When the function is called it will search for the next token starting at the specified position.
If a token is found, it is copied to the specified string object.
| Parameter | Description |
|---|---|
| pdelim | A zero terminated string of characters that shall be treated as delimiters. |
| tok | If the function returns true, tok will contain a copy of the next token. |
| pos | The search for the next token will start at this index. If the function returns true, pos will contain the index of the last found delimiter. |
| Return value | True if a token was found, false if not. |
Example:
cstr str("1:75;125");
cstr token;
size_t pos = 0;
int result = 0;
while(str.tok(":;",token,pos))
result += token.toi();
assert(result==201);
bool has(char c) const
Check if the string object contains the specified character.
The check is case sensitive.
| Parameter | Description |
|---|---|
| c | The character to check for. |
| Return value | True if the string object contains the character, false if not. |
Example:
cstr str("ABC");
assert(str.has('B'));
assert(str.has('b')==false);
bool has(const char * pstr) const
Check if the string object contains the specified sub-string.
The check is case sensitive.
| Parameter | Description |
|---|---|
| pstr | A zero terminated sub-string to search for. |
| Return value | True if the sub-string was found, false if not. |
Example:
cstr str("ABCD");
assert(str.has("BC"));
assert(str.has("bc")==false);
bool cspn(const char * pset, size_t & pos) const
Find the first occurrence in the string object of a character from the specified set.
The search starts at the specified position and is case sensitive.
| Parameter | Description |
|---|---|
| pset | A zero terminated string of characters to search for. |
| pos | The search will start at this index. If the function returns true, pos will contain the index of the character found. |
| Return value | True if a character from the set was found, false if not. |
Example:
cstr str("Hello World");
size_t pos = 0;
if(str.cspn("abcde",pos))
str.set(pos,'X');
assert(str=="HXllo World");
bool spn(const char * pset, size_t & pos) const
Find the first occurrence in the string object of a character that does NOT exist in the specified set.
The search starts at the specified position and is case sensitive.
| Parameter | Description |
|---|---|
| pset | A zero terminated string of characters to avoid. |
| pos | The search will start at this index. If the function returns true, pos will contain the index of the character found. |
| Return value | True if a character that does not exist in the set was found, false if not. |
Example:
cstr str("abcdef");
size_t pos = 0;
if(str.spn("abc",pos))
str.set(pos,'X');
assert(str=="abcXef");
int toi() const
This function is used to convert the content of the string object to an integer.
The function stops reading the string at the first character that it cannot recognize
as part of a decimal integer.
The result depends on the current locale
as well as the content of the string.
The string must have the following form:
[whitespace] [sign] digits
Whitespace and sign are optional. A whitespace consists of space and/or tab characters, which are ignored. Sign is either a plus (+) or a minus (–) character. The function does not recognize decimal points or exponents.
| Parameter | Description |
|---|---|
| Return value | The integer value of the string. The return value is 0 if the conversion failed. The return value is undefined in case of overflow. |
Example:
cstr str("123");
assert(str.toi()==123);
long tol(size_t & pos, int base = 10) const
This function is used to convert the content of the string object to a long integer.
The function stops reading the string at the first character that it cannot recognize
as part of a number.
The result depends on the current locale
as well as the content of the string.
The string must have the following form:
[whitespace] [{+ | –}] [0 [{ x | X }]] [digits]
A whitespace may consist of space and tab characters, which are ignored; digits are one or more decimal digits, or letters if base > 10. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than base are permitted.
| Parameter | Description |
|---|---|
| pos | The conversion will start at this index in the string object. When the function returns, pos will contain the index of the character that stopped the conversion. This can be used for error detection. |
| base | If base is between 2 and 36, then it is used as the base of the number. The default is decimal (base = 10). If base is 0, the initial characters of the string are used to determine the base. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer (base = 16). If the first character is '0' and the second character is not 'x' or 'X', the string is interpreted as an octal integer (base = 8). If the first character is '1' through '9', the string is interpreted as a decimal integer. |
| Return value | The value represented in the string, except when the representation would cause an overflow, in which case it returns LONG_MAX or LONG_MIN. 0 is returned if no conversion can be performed at all. |
Example:
cstr str("-123456");
size_t pos = 0;
long no = str.tol(pos);
assert(pos==str.len());
assert(no==-123456);
long toul(size_t & pos, int base = 10) const
This function is used to convert the content of the string object to an unsigned long integer.
The function stops reading the string at the first character that it cannot recognize
as part of a number.
The result depends on the current locale
as well as the content of the string.
The string must have the following form:
[whitespace] [{+ | –}] [0 [{ x | X }]] [digits]
A whitespace may consist of space and tab characters, which are ignored; digits are one or more decimal digits, or letters if base > 10. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than base are permitted. A plus (+) or minus (–) sign prefix is allowed. A leading minus sign indicates that the return value is negated.
| Parameter | Description |
|---|---|
| pos | The conversion will start at this index in the string object. When the function returns, pos will contain the index of the character that stopped the conversion. This can be used for error detection. |
| base | If base is between 2 and 36, then it is used as the base of the number. The default is decimal (base = 10). If base is 0, the initial characters of the string are used to determine the base. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer (base = 16). If the first character is '0' and the second character is not 'x' or 'X', the string is interpreted as an octal integer (base = 8). If the first character is '1' through '9', the string is interpreted as a decimal integer. |
| Return value | The value represented in the string, if any, or ULONG_MAX on overflow. 0 is returned if no conversion can be performed at all. |
Example:
cstr str("123456");
size_t pos = 0;
unsigned long no = str.toul(pos);
assert(pos==str.len());
assert(no==123456);
double tod() const
This function is used to convert the content of the string object
to a double-precision floating-point value.
The string must not contain more than 100 characters.
The function stops reading the string at the first character that it cannot recognize
as part of a floating-point value.
The result depends on the current locale
as well as the content of the string.
The string must have the following form:
[whitespace] [sign] [digits][radix][digits] [ {d | D | e | E }[sign]digits]
A whitespace consists of space and/or tab characters, which are ignored; sign is either plus (+) or minus (–); digits are one or more decimal digits; and radix is a decimal separator. Which character is used as decimal separator depends on the current locale. If no digits appear before the decimal separator, at least one must appear after the decimal separator. The decimal digits may be followed by an exponent, which consists of an introductory letter ( d, D, e, or E) and an optionally signed decimal integer.
| Parameter | Description |
|---|---|
| Return value | The floating-point value of the string. The return value is 0.0 if the conversion failed. The return value is undefined in case of overflow. |
Example:
// This example assumes that the current locale uses comma (,) as decimal separator.
cstr str("-123,456");
assert(str.tod()==-123.456);
double tod(size_t & pos) const
This function is used to convert the content of the string object
to a double-precision floating-point value.
The function stops reading the string at the first character that it cannot recognize
as part of a floating-point value.
The result depends on the current locale
as well as the content of the string.
The string must have the following form:
[whitespace] [sign] [digits][radix][digits] [ {d | D | e | E }[sign]digits]
A whitespace consists of space and/or tab characters, which are ignored; sign is either plus (+) or minus (–); digits are one or more decimal digits; and radix is a decimal separator. Which character is used as decimal separator depends on the current locale. If no digits appear before the decimal separator, at least one must appear after the decimal separator. The decimal digits may be followed by an exponent, which consists of an introductory letter ( d, D, e, or E) and an optionally signed decimal integer.
| Parameter | Description |
|---|---|
| pos | The conversion will start at this index in the string object. When the function returns, pos will contain the index of the character that stopped the conversion. This can be used for error detection. |
| Return value | The value of the floating-point number, except when the representation would cause an overflow, in which case the function returns +/–HUGE_VAL. The sign of HUGE_VAL matches the sign of the value that cannot be represented. 0.0 is returned if no conversion can be performed or an underflow occurs. |
Example:
// This example assumes that the current locale uses comma (,) as decimal separator.
cstr str("#-123,456");
size_t pos = 1;
double no = str.tod(pos);
assert(pos==str.len());
assert(no==-123.456);
int sprintf(const char * pFmt, ...)
This function works like the sprintf() function in the standard C library.
You can look it up in any book on C, or simply
Google it.
By nature sprintf() is slow and can consume a lot of stack space, especially if
you use it to format floating-point values.
Because of the variable parameter list sprintf() is also difficult to learn and
it is easy to make fatal misstakes.
However, since sprintf() is so very flexible it is sometimes the best alternative.
Use it with caution!
| Parameter | Description |
|---|---|
| pFmt | Format-control string. |
| ... | Optional parameter list. |
| Return value | The new length of the string. |
Example:
cstr str;
str.sprintf("The result is %d.",42);
assert(str=="The result is 42.");
static cstr decstr(int value)
Creates a string object that contains a decimal representation of the specified value.
If the integer is negative the first character in the string will be a minus (-) character.
| Parameter | Description |
|---|---|
| value | The value to convert to a string. |
| Return value | The new string. |
Example:
cstr str = cstr::decstr(17);
assert(str=="17");
static cstr hexstr(unsigned value)
Creates a string object that contains a hexadecimal representation of the specified value.
| Parameter | Description |
|---|---|
| value | The value to convert to a string. |
| Return value | The new string. |
Example:
cstr str = cstr::hexstr(17);
assert(str=="11");
static cstr fpstr(double value, size_t digits)
Creates a string object that contains a decimal representation of the specified floating-point value.
The format of the string depends on the current locale.
Exponential format may be used. Trailing zeros may be suppressed in the conversion.
| Parameter | Description |
|---|---|
| value | The value to convert to a string. |
| digits | The desired number of digits excluding decimal separator. |
| Return value | The new string. |
Example:
cstr str = cstr::fpstr(17.423,4);
// This example assumes that the current locale uses comma (,) as decimal separator.
assert(str=="17,42");