|
|
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.
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.
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.
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''.)
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.
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?"
}
}