DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
No More String Errors - String(3C++)

Basic Operations


first/last
String::firstX(char&) const; String::lastX(char&) const;

If String s is not empty, s.firstX(c) (s.lastX(c)) assigns its first (last) character to c and returns 1. Otherwise, c is unchanged and the return value is 0. In either case, s is unaffected.


assign
String& String::operator=(const String&);

The semantics of the assignment operator is to copy the value of the right operand into the left operand, destroying its old value. The value of an assignment expression is the object assigned, so s = t = u; works as expected. The right hand side can also be a character pointer or a character or any expression whose value is a String.


catenate
Tmpstring String::operator+(const String&);

The plus operator is used for catenation. If s and t are both Strings, then s + t is a new String whose characters are those of s followed by those of t. Also, + can be used with mixed characters and Strings, and mixed character pointers and Strings so that s + c is a new String whose characters are those of String s followed by character c; and s + p is a new String whose characters are those of String s followed by characters pointed to by p. Also, c + s is a new String whose characters are c followed by the characters of String s; and p + s is a new String whose characters are those pointed to by p followed by the characters of String s.

Tmpstring is an internal class invented to decrease the number of temporary Strings created during concatenation. Tmpstrings are converted to Strings automatically and the user does not have to deal with Tmpstrings directly. However, if the user has defined a conversion from a String to a user-defined type, this conversion will not work on expressions such as s + t, since the compiler will not do the two-step conversion from Tmpstring to String to user- defined type.


append
String& String::operator+=(const String&);

The += operator appends its right argument to its left. If s and t are both Strings, then s += t adds the characters of t to the end of s. The new value of s is returned. Only the right hand argument of += can be a character or character pointer instead of a String.

   void
   String::pad(int n,int pad_char = -1);

Pads this string with n pad_char's. This function is especially handy in two situations. The first is in generating test Strings. Suppose you need a String of 1000 x's; then simply write

      String x;
      ...
      x.pad(1000,'x');

The second situation is when you need a String of a certain length (say 1000), but don't care what characters the String contains:

      String x;
      ...
      x.pad(1000);

Why would a programmer want to do this? This version of the pad operation, used together with the shrink operation, described below under the length heading, gives the programmer the ability to adjust the length of a String very efficiently. This ability is needed to take advantage of knowledge about the implementation to achieve maximum efficiency (see the section, ``Unsafe Programming with Strings''.)


conversion
String::String(char);

String::String(const char*);

Coercions from characters and character pointers to Strings are implemented by the constructor functions for class String. Whenever a character or character pointer is found where a String is expected, the appropriate String constructor function is called to produce the corresponding String.

   String::operator const char*() const;

Returns a pointer to a constant C-style string (that is, a null-terminated character array that the compiler will not allow you to alter). Assuming the value of length() is N, this operator works by stuffing a null character into the N+1st cell of the String's internal storage and then returning a pointer to the first cell. Note that if the String contains null characters anywhere in the first N bytes, then strlen() will not give the same answer as length(). Remember that C-style strings depend on special treatment of the null character, while Strings do not. This operator is often used by the compiler as an implicit conversion when a String occurs where a const char* is expected, allowing you to pass Strings to functions with const char* arguments. Programs that use Strings can therefore take advantage of existing libraries of C-style functions for any operations that Strings do not provide. For other functions, such as printf(), which can take a const char* but do not expect one, the String argument must be explicitly cast to const char*. This function is meant to be used solely as a cast, explicit or implicit, to obtain a temporary pointer to the characters of the String. Since storage relocation may occur due to changes to this String, the pointer should be used right away and then discarded.

Note that if the String is empty, operator const char*() returns a pointer to a null byte. It does not return a NULL pointer.

   String      int_to_str(int);

This function takes an integer as an argument and returns a new String whose contents are the string representation of the digits.

   String      long_to_str(long);

This function takes a long integer as an argument and returns a new String whose contents are the string representation of the digits.


length
unsigned String::length() const;

s.length() (or length(s)) returns the length (number of characters) of the String s.

   int         String::is_empty() const;

s.is_empty() returns 1 if the length of the String s is 0. It returns 0 otherwise.

   void        String::shrink(int n);

If n is less than the current String length, the length is decreased to n, truncating the excess characters. This operation, together with the pad operation, described above under the append heading, give the programmer the ability to adjust the length of a String very efficiently. This ability is needed in order to take advantage of knowledge about the implementation to achieve maximum efficiency (see the section, ``Unsafe Programming with Strings''.)

The following are examples of the use of these basic String functions:

   {
      String s,t,v,w[3];
      s = "not";              // s is "not"
      t = s;                  // t is "not"
      s += "me";              // s is "not me"
      v = s + '?';            // v is "not me?"
      w[0] = t;
      w[1] = s;
      w[2] = v;
      for(int i=0;i<3;i++) {
          char c;
          w[i].lastX(c);
          if(c=='?') w[i] = "Why" + w[i];
          // w[2] is "Why not me?"
      }
   }

Next topic: Queue-Oriented Operations
Previous topic: Operations

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004