String Class Reference

This class offers a set of low and high-level operations for safe and convenient handling of character strings, including commonly used operators (==,=. More...

Inherited Class(es)

• public Object

Detailed Description

This class offers a set of low and high-level operations for safe and convenient handling of character strings, including commonly used operators (==,=...) and conversion functions to numeric types.

The strings are managed like conventional C-style null-terminated ASCII strings (char *). Input or output const char* values are therefore always assumed to be null-terminated. If not so, the results are undefined.

The cast operator to const char* is useful for getting the raw C-style string.

Some of the functions are also compatible with the handling of binary buffers, even if these buffers may contain null or non-printable chars. This peculiarity is always documented for the matching functions.

This class is especially optimised for high performance and combines internally static and dynamic memory buffering. A string instance always holds a deep and private copy of its string. String instances never share memory buffers.

Files Included

Functions Documentation

Memory Buffer management function.

Re-allocates the buffer if necessary to ensure that at least uMinCapacity are allocated

If the bufffer must be re-allocated, by default the new size is (old_size+1)*2. Otherwise it is uMinCapacity.

Selects the static or dynamic buffer according to the required size.

See also:

Default void constructor.

Constructs an empty string.

Example:

 String s; // s == ""

See also:

Copy constructor.

Constructs a copy of the passed rStr string.

Example:

 String s("Michel");
 String s2(s);  // s2 == "Michel"

See also:

Constructs a string which copies the iLen first chars of pszSource.

If the size iLen is unspecified (< 0), the whole input string is copied till end of string is encountered (\0).

This function is compatible with the handling of binary buffers. If a length is specified, the string will store the iLen bytes of the passed buffer, inclusive all null and non-printable chars. The value of the buffer can then be got back using the str() operation.

In all cases, the string is ended with a null char.

iLen is optional, by default iLen = -1.

See also:

Example:

 String s("Michel");  // s == "Michel"
 String s2("Michel", 2);  // s2 == "Mi"

Constructs a string which just contains c.

See also:

Constructs a string which just contains c.

See also:

Constructs a string holding the string represention of int iValue.

lpszFormat is optional and contains the conversion format as given in in ::printf().

If lpszFormat is not specified (lpszFormat = NULL by default), operator=() is used for the conversion (safe). Otherwise, ::sprintf() with the specified formation is used (not safe).

Note:

This function is not recommended wherever safety is critical. When ::sprintf() is used, a limited buffer of size 100 is used. Moreover There is no consistency check made between the format and the passed value to convert.

See also:

Behaves like the above function but takes unsigned int uValue as argument.

Note:

Please read the notes of the first referenced function.

See also:

Behaves like the above function but takes long iValue as argument.

Note:

Please read the notes of the first referenced function.

See also:

Behaves like the above function but takes unsigned long uValue as argument.

Note:

Please read the notes of the first referenced function.

See also:

Behaves like the above function but takes float fValue as argument.

Note:

Please read the notes of the first referenced function.

See also:

Behaves like the above function but takes double dValue as argument.

Note:

Please read the notes of the first referenced function.

See also:

Destructor.

Delete any memory allocated on the heap and resets pointers to null.

See also:

Returns a hashcode for the string.

See also:

Tells whether the string is empty (zero char).

See also:

Returns the length of the string (0 or positive value).

See also:

Returns the actual buffer capacity of the string (at least as great than the string length).

See also:

Copies the chars between positions srcBegin and srcEnd to the target char array dst, starting at position dstBegin. The char of index "srcEnd" is not included !

See also:

Copies the chars from pszSource to this string, starting at position uDstBegin. Ensures the string has enougth capacity.

See also:

Returns the raw const char* pointer to the string buffer. The string can't be modified using the pointer. It is read-only.

See also:

Equivalent to operator=() but does not return a reference to itself.

Example:

  String s;
  s.set("Dog"); // s == "Dog"

See also:

Empties string (zero char). length() returns zero after that. Is equivalent to set("").

See also:

Sets this string as case less or not depending on bCaseLess. bCaseLess is optional and true by default.

This will be taken into account within any search and comparison functions.

See also:

Tells whether the string is case less.

See also:

Assigns the string to pszSource. pszValue must end with '\0' (end of string). Previous string value is lost and overwritten by a copy of pszSource.

Returns a reference to itself.

Example:

  String s;
  s = "Dog"; // s == "Dog"

See also:

Assigns the value of the passed string to this one. In all cases, the number of bytes copied is always that number returned by length() of the passed string.

This function is compatible with the handling of binary buffers. The passed string may contain a binary buffer for which length() returns the size.

Example:

  String s("Dog");
  String s2;
  s2 = s; // s2 == "Dog"

See also:

Equivalent to the function referenced below, except that it takes a char as argument. After this operator, the string will just hold the passed char.

Example:

  String s;
  s = 'c'; // s == "c"

See also:

Equivalent to the function referenced below.

See also:

Assigns the string to the string representation of the passed int iSource. The conversion function mentioned below is used to realise the conversion.

Example:

  String s;
  int i = 345;
  s = i; // s == "345"
  i = -1;
  s = i; // s == "-1"

See also:

Equivalent to the function mentioned above, except that it takes unsigned int uiSource as argument and that the conversion function used is the one mentioned below.

See also:

Equivalent to the function mentioned above, except that it takes long lSource as argument and that the conversion function used is the one mentioned below.

See also:

Equivalent to the function mentioned above, except that it takes unsigned long uSource as argument and that the conversion function used is the one mentioned below.

See also:

Equivalent to the function mentioned above, except that it takes float fSource as argument and that the conversion function used is the one mentioned below.

See also:

Equivalent to the function mentioned above, except that it takes double dSource as argument and that the conversion function used is the one mentioned below.

See also:

Equivalent to the function mentioned above, except that it takes short sSource as argument and that the conversion function used is the one mentioned below.

See also:

Equivalent to the function mentioned above, except that it takes unsigned short usSource as argument and that the conversion function used is the one mentioned below.

See also:

Inverts the chars of the string.

Returns a reference to itself.

Example:

  String s = "Reverse";
  s.reverse(); // s == "esreveR"

See also:

Uppers case of string.

Returns a reference to itself.

Example:

  String s = "Upper";
  s.toUpperCase(); // s == "UPPER"

See also:

Lowers case of string.

Returns a reference to itself.

Example:

  String s = "LoWer";
  s.toLowerCase(); // s == "lower"

See also:

Removes all starting c. By default c = ' ' (space char).

bLessToo is optional. It tells whether all chars whose ASCII value is less than c shall also be removed. By default it is not the case.

Returns a reference to itself.

Example:

  String s = "   My sentence.  ";
  s.trimLeft(); // s == "My sentence."

See also:

Removes all ending c chars. By default c = ' ' (space char).

bLessToo is optional. It tells whether all chars whose ASCII value is less than c shall also be removed. By default it is not the case.

Returns a reference to itself.

Example:

  String s = "  My sentence.  ";
  s.trimRight(); // s == "  My sentence."

See also:

Removes both all starting and ending c chars. By default c = ' ' (space char).

bLessToo is optional. It tells whether all chars whose ASCII value is less than c shall also be removed. By default it is not the case.

Returns a reference to itself.

Relies on trimLeft() and trimRight().

Example:

  String s = "  My sentence.  ";
  s.trim(); // s == "My sentence."

See also:

Replaces any tabulation char by usTabLen space chars. usTabLen is optional. By default usTabLen = 8.

Additionally, this function computes the new position in the result string of the char that was initially at position uPos in the string. The new position is returned in uPos.

Returns a reference to itself.

Example:

  String s = "Name:\tMehl";
  unsigned long uPos = 6;
  s.untabifyWithCursor(uPos); // s == "Name:        Mehl"  uPos = 13.

See also:

Behaves like the function referred to below, except that it does not manage a char position conversion. s.trim(); // s == "My sentence."

Example:

  String s = "Name:\tMehl";
  s.untabifyWithCursor(4); // s == "Name:    Mehl"

See also:

Replaces any character that can't be represented as is in a C string constant with the matching escape sequence.

The following table gives the correspondence between the chars and their escape sequence.

simple quote ' => \'

double quote " => \"

backslash \ => \\

horizontal tab => \t"

new line => \n

vertical tab => \v

backspace => \b

carriage return => \r

formfeed => \f

audible alert => \a

question mark => \?

octal number => \ooo

hexadecimal number => \xhh

See also:

Replaces string pszOld with pszNew.

All occurrences are replaced only if the optional parameter bAll is true, . By default bAll = false and only one occurrence is replaced.

This function is case sensitive.

Returns true is something was replaced, false otherwise.

Example:

  String s = "This is a integer";
  s.replace("is", "ee", true); // s == "Thee ee a integer"

See also:

Overloaded function provided for convenience. Behaves like the function referred to below, except that it replaces a char with another char.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below, except that it replaces a char by a string.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below, except that it replaces a string with a char.

See also:

Inserts string rStr at uOffset. The chars inclusive char at uOffset are shifted to the right.

Returns true if insertion was successful. False if uOffset is invalid.

Example:

  String s = "This is a integer";
  s.insert(9, "n unsigned"); // s == "This is an unsigned integer"

See also:

Overloaded function provided for convenience. Behaves like the function referred to below, except that it just permits to insert a char.

See also:

Shifts the string uHowMuch times to the left. The uHowMuch first chars are lost.

uHowMuch is optional. Its default value is 1.

Relies on the function referred to below.

Returns a reference to itself.

Example:

  String s = "Complete String";
  s.shift(9); // s == "String"

See also:

Shifts the string uHowMuch times to the right setting the inserted uHowMuch first chars to rightc.

uHowMuch is optional. Its default value is 1. rightc is optional. Its default value is ' '.

Relies on the two last functions referred to below.

Returns a reference to itself.

Example:

  String s = "Complete String";
  s.shift(7); // s == "       Complete String"

See also:

Fills the string with uLen char(s) fillc.

fillc is optional. By default fillc = ' '.

uFrom is optional and set to 0xFFFFFFFF by default. In that case, the filling chars are appended to the current string.

If uFrom is specified, the filling chars overwrite the uLen first chars from position uFrom and overflowing chars are appended to the current string.

This function is compatible with the handling of binary buffers. The string can be filled with any byte value inclusive all null and non-printable chars. The value of the buffer can then be got back using the str() operation.

Returns a reference to itself.

Example:

  String s = "Original String";
  s.fill(9); // s == "Original String         "

See also:

Removes chars between whose offset is between start and end. The char of offset end is not removed.

end is optional. By default end = -1 which means that all chars starting from start offset until the end of the string are removed.

Returns true if the removal was successful, false in those cases:

end is negative and is not -1, start or end is an invalid offset, start > end.

Note:

This function assumes that the string length is not greater than the maximum value of a long. Otherwise this function returns false.

Example:

  String s = "Original String";
  s.eraseRange(6,8); // s == "Origin String"

See also:

Removes nb chars from index start.

nb is optional. By default nb = -1 which means that all chars until the end of the string are removed.

Returns true if the removal was successful, false in those cases:

nb is negative and is not -1, start + nb is greater that the string length.

Equivalent to eraseRange(start, (long)(start+nb))

Note:

This function assumes that the string length is not greater than the maximum value of a long. Otherwise this function returns false.

Example:

  String s = "Original String";
  s.erase(6,2); // s == "Origin String"

See also:

Rubs off string c_s and replace the empty space with cEraseChar chars.

In constrast with the erase() function, this function does not modify the string size. It just replaces any occurrence of c_s with as many cEraseChar needed to rub off c_s from the string.

It is much less time-consuming than other functions like erase() or replace() as no memory allocation and freeing is needed at all. Therefore it may sometimes be a better choice with regard to the result or the performance sought.

cEraseChar is optional and is the space char by default.

uFrom is optional and set to 0 by default. It gives the char index relative to c_s from which the erasing should actually take place. If the uFrom is greater than the size of c_s, nothing is done!

As return value, tells whether the string was changed.

Example:

 String s = "Original String";
 s.rubout("Original"); // s == "         String"
 s.rubout("Str", ' ', 1); // s == "         S  ing"

See also:

Appends string rStr terminated with a new line char. Convenient when generating lines of source code files for example.

Returns a reference to itself.

Example:

  String s = "Begin";
  String s2 = "End";
  s.append(s2).escapeSequence(); // s == "BeginEnd\n"

See also:

Appends string rStr.

Returns a reference to itself.

Example:

  String s = "Begin";
  String s2 = "End";
  s.append(s2); // s == "BeginEnd"

See also:

Overloaded function provided for convenience. Behaves like the function referred to below, except that it takes directly a C string (const char*) instead of a String object as parameter.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below, except that it just appends c.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below, except that it just appends unsigned c.

See also:

Appends the string representation of the passed unsigned int uN.

Returns a reference to itself.

Note:

Constructor String(unsigned int) is used for conversion.

Example:

  String s = "rfc";
  unsigned int i = 1913;
  s.append(i); // s == "rfc1913"

See also:

Overloaded function provided for convenience. Behaves like the function referred to below, except that it appends the string representation of the passed int iN.

Note:

Constructor String(int) is used for conversion.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below, except that it appends the string representation of the passed unsigned long uN.

Note:

Constructor String(unsigned long) is used for conversion.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below, except that it appends the string representation of the passed long iN.

Note:

Constructor String(long) is used for conversion.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below, except that it appends the string representation of the passed float fN.

Note:

Constructor String(float) is used for conversion.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below, except that it appends the string representation of the passed double dN.

Note:

Constructor String(double) is used for conversion.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below.

See also:

Overloaded function provided for convenience. Behaves like the function referred to below.

See also: