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.

ParameterDescription
posThe start position of the sub-string to replace.
oldstrThe sub-string to replace.
newstrThe 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.

ParameterDescription
old_cThe character to be replaced.
new_cThe 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.

ParameterDescription
fromIndex of the first character to copy.
toIndex of the last character to copy.
Return valueA 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.

ParameterDescription
lenNumber of character to copy.
Return valueA 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.

ParameterDescription
lenNumber of character to copy.
Return valueA 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.

ParameterDescription
cThe character to search for.
posThe search will start at this index. If the function returns true, pos will contain the index where the character was found.
Return valueTrue 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.

ParameterDescription
cThe character to search for.
posThe search will start at this index. If the function returns true, pos will contain the index where the character was found.
Return valueTrue 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.

ParameterDescription
pstrA zero terminated sub-string to search for.
posThe search will start at this index. If the function returns true, pos will contain the start index of the sub-string.
Return valueTrue 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.

ParameterDescription
pdelimA zero terminated string of characters that shall be treated as delimiters.
tokIf the function returns true, tok will contain a copy of the next token.
posThe 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 valueTrue 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.

ParameterDescription
cThe character to check for.
Return valueTrue 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.

ParameterDescription
pstrA zero terminated sub-string to search for.
Return valueTrue 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.

ParameterDescription
psetA zero terminated string of characters to search for.
posThe search will start at this index. If the function returns true, pos will contain the index of the character found.
Return valueTrue 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.

ParameterDescription
psetA zero terminated string of characters to avoid.
posThe search will start at this index. If the function returns true, pos will contain the index of the character found.
Return valueTrue 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.

ParameterDescription
Return valueThe 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.

ParameterDescription
posThe 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.
baseIf 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 valueThe 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.

ParameterDescription
posThe 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.
baseIf 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 valueThe 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.

ParameterDescription
Return valueThe 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.

ParameterDescription
posThe 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 valueThe 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!

ParameterDescription
pFmtFormat-control string.
...Optional parameter list.
Return valueThe 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.

ParameterDescription
valueThe value to convert to a string.
Return valueThe 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.

ParameterDescription
valueThe value to convert to a string.
Return valueThe 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.

ParameterDescription
valueThe value to convert to a string.
digitsThe desired number of digits excluding decimal separator.
Return valueThe 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");