Don't hesitate to send in feedback: send an e-mail if you like the C++ Annotations; if you think that important material was omitted; if you find errors or typos in the text or the code examples; or if you just feel like e-mailing. Send your e-mail to Frank B. Brokken.Please state the document version you're referring to, as found in the title (in this document: 7.0.0) and please state chapter and paragraph name or number you're referring to.
All received mail is processed conscientiously, and received suggestions for improvements will usually have been processed by the time a new version of the Annotations is released. Except for the incidental case I will normally not acknowledge the receipt of suggestions for improvements. Please don't interpret this as me not appreciating your efforts.
C++ offers a large number of facilities to implement solutions for common problems. Most of these facilities are part of the Standard Template Library or they are implemented as generic algorithms (see chapter 17).
Among the facilities C++ programmers have developed over and over again
are those for manipulating chunks of text,
commonly called strings. The C programming language offers
rudimentary string support: the
ASCII-Z
terminated series of characters is the foundation on which a large amount of
code has been built (We define an
ASCII-Z string as a series of ASCII-characters terminated by the
ASCII-character zero (hence -Z), which has the value zero, and should not be
confused with character
'0'
, which usually has the value
0x30
).
Standard C++ now offers a
string
type. In order to use
string
-type objects, the header file string
must be included in
sources.
Actually, string
objects are class type variables, and the class
is formally introduced in chapter 6. However, in order to use a
string, it is not necessary to know what a class is. In this section the
operators that are available for strings and several other operations are
discussed. The operations that can be performed on strings take the form
stringVariable.operation(argumentList)For example, if
string1
and string2
are variables of type string
,
then
string1.compare(string2)can be used to compare both strings. A function like
compare()
, which is part of the string
-class is called a
member function. The string
class offers a large number of these
member functions, as well as extensions of some well-known operators, like the
assignment (=
) and the comparison operator (==
). These operators and
functions are discussed in the following sections.
string::npos
is returned. This value is a (symbolic) value
of type
string::size_type
, which is (for all practical purposes) an
(unsigned
) int
.
Note that in all operations with strings
both string
objects
and char const *
values and variables can be used.
Some string
-members use iterators. Iterators will be
covered in section 17.2. The member functions using iterators are
listed in the next section (4.2), they are not further
illustrated below.
The following operations can be performed on strings:
ASCII-Z
string, another
string
object, or an implicit initialization can be used. In the example,
note that the implicit initialization does not have an argument, and may not
use an argument list. Not even empty.
#include <string> using namespace std; int main() { string stringOne("Hello World"); // using plain ascii-Z string stringTwo(stringOne); // using another string object string stringThree; // implicit initialization to "". Do // not use the form `stringThree()' return 0; }
=
operator) can be
used, which accepts both a string
object and a C-style character
string as its right-hand argument:
#include <string> using namespace std; int main() { string stringOne("Hello World"); string stringTwo; stringTwo = stringOne; // assign stringOne to stringTwo stringTwo = "Hello world"; // assign a C-string to StringTwo return 0; }
string
-object. The reverse conversion (converting a
string
object to a standard C-string) is not performed
automatically. In order to obtain the C
-string that is stored within the
string
object itself, the member function c_str()
, which returns a
char const *
, can be used:
#include <iostream> #include <string> using namespace std; int main() { string stringOne("Hello World"); char const *cString = stringOne.c_str(); cout << cString << endl; return 0; }
[]
) is available, but there is no
string pointer dereferencing operator (*
). The subscript operator
does not perform range-checking.
If range
checking is required the
string::at()
member function should be used:
#include <iostream> #include <string> using namespace std; int main() { string stringOne("Hello World"); stringOne[6] = 'w'; // now "Hello world" if (stringOne[0] == 'H') stringOne[0] = 'h'; // now "hello world" // *stringOne = 'H'; // THIS WON'T COMPILE stringOne = "Hello World"; // Now using the at() // member function: stringOne.at(6) = stringOne.at(0); // now "Hello Horld" if (stringOne.at(0) == 'H') stringOne.at(0) = 'W'; // now "Wello Horld" return 0; }When an illegal index is passed to the
at()
member function, the
program aborts (actually, an exception is generated, which could be
caught. Exceptions are covered in chapter 8).
==, !=, <, <=, >
and >=
operators
or the
string::compare()
member function. The compare()
member
function comes in several flavors (see section 4.2.4 for
details). E.g.:
int string::compare(string const &other)
: this variant offers
a bit more information than the comparison-operators do. The return value of
the string::compare()
member function may be used for
lexicographical ordering: a negative value is returned if the string
stored in the string object using the compare()
member function (in the
example: stringOne
) is located earlier in the
ASCII collating sequence than the string stored in the string
object passed as argument.
#include <iostream> #include <string> using namespace std; int main() { string stringOne("Hello World"); string stringTwo; if (stringOne != stringTwo) stringTwo = stringOne; if (stringOne == stringTwo) stringTwo = "Something else"; if (stringOne.compare(stringTwo) > 0) cout << "stringOne after stringTwo in the alphabet\n"; else if (stringOne.compare(stringTwo) < 0) cout << "stringOne before stringTwo in the alphabet\n"; else cout << "Both strings are the same\n"; // Alternatively: if (stringOne > stringTwo) cout << "stringOne after stringTwo in the alphabet\n"; else if (stringOne < stringTwo) cout << "stringOne before stringTwo in the alphabet\n"; else cout << "Both strings are the same\n"; return 0; }Note that there is no member function to perform a case insensitive comparison of strings.
int string::compare(string::size_type pos, size_t n, string
const &other)
: the first argument indicates the position in the current
string that should be compared; the second argument indicates the number of
characters that should be compared (if this value exceeds the number of
characters that are actually available, only the available characters are
compared); the third argument indicates the string which is compared to the
current string.
string::compare()
are available. As stated,
refer to section 4.2.4 for details.
compare()
function:
#include <iostream> #include <string> using namespace std; int main() { string stringOne("Hello World"); // comparing from a certain offset in stringOne if (!stringOne.compare(1, stringOne.length() - 1, "ello World")) cout << "comparing 'Hello world' from index 1" " to 'ello World': ok\n"; // the number of characters to compare (2nd arg.) // may exceed the number of available characters: if (!stringOne.compare(1, string::npos, "ello World")) cout << "comparing 'Hello world' from index 1" " to 'ello World': ok\n"; // comparing from a certain offset in stringOne over a // certain number of characters in "World and more" // This fails, as all of the chars in stringOne // starting at index 6 are compared, not just // 3 chars in "World and more" if (!stringOne.compare(6, 3, "World and more")) cout << "comparing 'Hello World' from index 6 over" " 3 positions to 'World and more': ok\n"; else cout << "Unequal (sub)strings\n"; // This one will report a match, as only 5 characters are // compared of the source and target strings if (!stringOne.compare(6, 5, "World and more", 0, 5)) cout << "comparing 'Hello World' from index 6 over" " 5 positions to 'World and more': ok\n"; else cout << "Unequal (sub)strings\n"; } /* Generated output: comparing 'Hello world' from index 1 to 'ello World': ok comparing 'Hello world' from index 1 to 'ello World': ok Unequal (sub)strings comparing 'Hello World' from index 6 over 5 positions to 'World and more': ok */
string
can be appended to
another string. For this the +=
operator can be used, as well as the
string &string::append()
member function.
Like the compare()
function, the append()
member function may have
extra arguments. The first argument is the string to be appended, the
second argument specifies the index position of the first character that will
be appended. The third argument specifies the number of characters that will
be appended. If the first argument is of type char const *
, only a second
argument may be specified. In that case, the second argument specifies the
number of characters of the first argument that are appended to the string
object. Furthermore, the +
operator can be used to append two strings
within an expression:
#include <iostream> #include <string> using namespace std; int main() { string stringOne("Hello"); string stringTwo("World"); stringOne += " " + stringTwo; stringOne = "hello"; stringOne.append(" world"); // append 5 characters: stringOne.append(" ok. >This is not used<", 5); cout << stringOne << endl; string stringThree("Hello"); // append " world": stringThree.append(stringOne, 5, 6); cout << stringThree << endl; }The
+
operator can be used in cases where at least one term of the
+
operator is a string
object (the other term can be a string, char
const *
or char
).
When neither operand of the +
operator is a string
, at least one
operand must be converted to a string
object first. An easy way
to do this is to use an
anonymous string object:
string("hello") + " world";
string &string::insert()
member
function to insert (parts of) a string
has at least two, and at most four
arguments:
string
object
where another string should be inserted.
string
-argument that will be inserted.
char const *
, the fourth argument is
not available. In that case, the third argument indicates the number of
characters of the provided char const *
value that will be inserted.
#include <string> int main() { string stringOne("Hell ok."); // Insert "o " at position 4 stringOne.insert(4, "o "); string world("The World of C++"); // insert "World" into stringOne stringOne.insert(6, world, 4, 5); cout << "Guess what ? It is: " << stringOne << endl; }Several variants of
string::insert()
are available. See section
4.2 for details.
string
objects must be replaced by other information. To replace parts of
the contents of a string
object by another string the member function
string &string::
replace()
can be used.
The member function has at least three and possibly five arguments, having
the following meanings
(see section 4.2 for overloaded versions of
replace()
, using different types of arguments):
string
or char const *
).
string
-argument that will be inserted.
char const *
, the fifth argument is
not available. In that case, the fourth argument indicates the number of
characters of the provided char const *
value that will be inserted.
The following example shows a very simple file changer: it reads lines
from cin
, and replaces occurrences of a `searchstring' by a
`replacestring'. Simple tests for the correct number of arguments and the
contents of the provided strings (they should be unequal) are applied as well.
#include <iostream> #include <string> using namespace std; int main(int argc, char **argv) { if (argc != 3) { cerr << "Usage: <searchstring> <replacestring> to process " "stdin\n"; return 1; } string search(argv[1]); string replace(argv[2]); if (search == replace) { cerr << "The replace and search texts should be different\n"; return 1; } string line; while (getline(cin, line)) { string::size_type idx = 0; while (true) { idx = line.find(search, idx); // find(): another string member // see `searching' below if (idx == string::npos) break; line.replace(idx, search.size(), replace); idx += replace.length(); // don't change the replacement } cout << line << endl; } return 0; }
string &string::swap(string &other)
swaps the contents of two string
-objects. For example:
#include <iostream> #include <string> using namespace std; int main() { string stringOne("Hello"); string stringTwo("World"); cout << "Before: stringOne: " << stringOne << ", stringTwo: " << stringTwo << endl; stringOne.swap(stringTwo); cout << "After: stringOne: " << stringOne << ", stringTwo: " << stringTwo << endl; }
string
&string::erase()
removes characters from a string
. The standard form has
two optional arguments:
string()
or string("")
).
erase()
. An
example of the use of erase()
is given below:
#include <iostream> #include <string> using namespace std; int main() { string stringOne("Hello Cruel World"); stringOne.erase(5, 6); cout << stringOne << endl; stringOne.erase(); cout << "'" << stringOne << "'\n"; }
string
the member function string::size_type
string::find()
can be used. This function looks for the string that is
provided as its first argument in the string
object calling find()
and
returns the index of the first character of the substring if found. If the
string is not found string::npos
is returned. The member function
rfind()
looks for the substring from the end of the string
object back
to its beginning. An example using find()
was given
earlier.
string
object,
the member function string
string::substr()
is
available. The returned string
object contains a copy of the substring in
the string
-object calling substr()
The substr()
member function
has two optional arguments:
string
itself is returned.
#include <iostream> #include <string> using namespace std; int main() { string stringOne("Hello World"); cout << stringOne.substr(0, 5) << endl << stringOne.substr(6) << endl << stringOne.substr() << endl; }
find()
is used to find a
substring, the functions find_first_of(), find_first_not_of(),
find_last_of()
and find_last_not_of()
can be used to find sets of
characters (Unfortunately, regular expressions are not supported here). The
following program reads a line of text from the standard input stream, and
displays the substrings starting at the first vowel, starting at the last
vowel, and starting at the first non-digit:
#include <iostream> #include <string> using namespace std; int main() { string line; getline(cin, line); string::size_type pos; cout << "Line: " << line << endl << "Starting at the first vowel:\n" << "'" << ( (pos = line.find_first_of("aeiouAEIOU")) != string::npos ? line.substr(pos) : "*** not found ***" ) << "'\n" << "Starting at the last vowel:\n" << "'" << ( (pos = line.find_last_of("aeiouAEIOU")) != string::npos ? line.substr(pos) : "*** not found ***" ) << "'\n" << "Starting at the first non-digit:\n" << "'" << ( (pos = line.find_first_not_of("1234567890")) != string::npos ? line.substr(pos) : "*** not found ***" ) << "'\n"; }
size()
member function, which, like
the standard C function
strlen()
does not include the terminating
ASCII-Z character. For example:
#include <iostream> #include <string> using namespace std; int main() { string stringOne("Hello World"); cout << "The length of the stringOne string is " << stringOne.size() << " characters\n"; }
size()
member function
can be used to determine whether a string holds no characters. Alternatively,
the
string::empty()
member function can be used:
#include <iostream> #include <string> using namespace std; int main() { string stringOne; cout << "The length of the stringOne string is " << stringOne.size() << " characters\n" "It is " << (stringOne.empty() ? "" : " not ") << "empty\n"; stringOne = ""; cout << "After assigning a \"\"-string to a string-object\n" "it is " << (stringOne.empty() ? "also" : " not") << " empty\n"; }
void
string::resize()
can be used to make it longer or shorter. Note that
operators like +=
automatically resize a string
when needed.
istream &getline(istream &instream, string &target, char delimiter)may be used to read a line of text (up to the first delimiter or the end of the stream) from
instream
(note that getline()
is not a
member function of the class string
).
The delimiter has a default value '\n'
. It is removed from instream
,
but it is not stored in target
. The member istream::eof()
may be
called to determine whether the delimiter was found. If it returns true
the delimiter was not found (see chapter 5 for details about
istream
objects). The function getline()
was used in several earlier
examples (e.g., with the replace() member function).
string
variables may be extracted from
a stream. Using the construction
istr >> str;where
istr
is an istream
object, and str
is a string
, the
next consecutive series of non-blank characters will be assigned to
str
. Note that by default the extraction operation will skip any
blanks that precede the characters that are extracted from the stream.
string
-initializers, the string
-iterators, the
string
-operators and the string
-member functions.
The member functions are ordered alphabetically by the name of the
operation. Below, object
is a string
-object, and argument
is
either a string const &
or a char const *
, unless overloaded versions
tailored to string
and char const *
parameters are explicitly
mentioned. Object
is used in cases where a string
object is
initialized or given a new value. The entity referred to by argument
always remains unchanged.
Furthermore, opos
indicates an offset into the object
string, apos
indicates an offset into the argument
string. Analogously, on
indicates a number of characters in the object
string, and an
indicates a number of characters in the argument
string. Both opos
and
apos
must refer to existing offsets, or an exception will be generated. In
contrast to this, an
and on
may exceed the number of available
characters, in which case only the available characters will be considered.
When streams are involved, istr
indicates a stream from which information
is extracted, ostr
indicates a stream into which information is inserted.
With member functions the types of the parameters are given in a
function-prototypical way. With several member functions iterators are
used. At this point in the Annotations it's a bit premature to discuss
iterators, but for referential purposes they have to be mentioned
nevertheless. So, a forward reference is used here: see section 17.2
for a more detailed discussion of iterators. Like apos
and opos
,
iterators must also refer to an existing character, or to an available
iterator range of the string to which they refer.
Finally, note that all string
-member functions returning indices in
object
return the predefined constant
string::npos
if no
suitable index could be found.
string
constructors
are
available:
string object
:
Initializes object
to an empty string.
string object(string::size_type no, char c)
:
Initializesobject
withno
charactersc
.
string object(string argument)
:
Initializesobject
withargument
.
string object = argument
:
Initializesobject
withargument
. This is an alternative form of the previous initialization.
string object(string argument, string::size_type apos,
string::size_type an = string::npos)
:
Initializesobject
withargument
, usingan
characters ofargument
, starting at indexapos
. Ifan
is not specified, all characters ofargument
starting at offsetapos
are used.
string object(InputIterator begin, InputIterator end)
:
Initializesobject
with the range of characters implied by the providedInputIterators
. Iterators are covered in detail in section 17.2, but can (for the time being) be interpreted as pointers to characters. See also the next section.
object = argument
.
Assignment ofargument
to an existing stringobject
.
object = c
.
Assignment ofchar c
toobject
.
object += argument
.
Appendsargument
toobject
.Argument
may also be achar
expression.
argument1 + argument2
.
Within expressions,strings
may be added. At least one term of the expression (the left-hand term or the right-hand term) should be astring
object. The other term may be astring
, achar const *
value or achar
expression, as illustrated by the following example:
void fun() { char const *asciiz = "hello"; string first = "first"; string second; // all expressions compile ok: second = first + asciiz; second = asciiz + first; second = first + 'a'; second = 'a' + first; }
object[string::size_type opos]
.
The subscript-operator may be used to retrieveobject
's individual characters, or to assign new values to individual characters ofobject
or to retrieve these characters. There is no range-checking. If range checking is required, use theat()
member function.
argument1 == argument2
.
The equality operator (==
) may be used to compare astring
object to anotherstring
orchar const *
value. The!=
operator is available as well. The return value for both is abool
. For two identical strings==
returnstrue
, and!=
returnsfalse
.
argument1 < argument2
.
The less-than operator may be used to compare the ordering within the Ascii-character set ofargument1
andargument2
. The operators<=, >
and>=
are available as well.
ostr
<< object
.
The insertion-operator may be used with string
objects.
istr
>> object
.
The extraction-operator may be used withstring
objects. It operates analogously to the extraction of characters into a character array, butobject
is automatically resized to the required number of characters.
string
-class is given first. Then the full prototype and a
description are given. Values of the type
string::size_type
represent
index positions within a string
. For all practical purposes, these values
may be interpreted as unsigned
.
The special value
string::npos
, defined by the string class, represents a
non-existing index. This value is returned by all members returning indices
when they could not perform their requested tasks. Note that the string's
length is not returned as a valid index. E.g., when calling a member
`find_first_not_of(" ")
' (see below) on a string
object holding 10
blank space characters, npos
is returned, as the string only contains
blanks. The final 0-byte that is used in C to indicate the end of a
ASCII-Z
string is not considered part of a C++ string, and so the
member function will return npos
, rather than length()
.
In the following overview, `size_type
' should always be read as
`
string::size_type
'.
char &string::at(size_type opos)
:
The character (reference) at the indicated position is returned (it may be reassigned). The member function performs range-checking, aborting the program if an invalid index is passed.
string &string::append(InputIterator begin, InputIterator end)
:
Using this member function the range of characters implied by thebegin
andend InputIterators
are appended to thestring
object.
string &string::append(string argument, size_type apos, size_type
an)
:
If
- If only
argument
is provided, it is appended to thestring
object.- If
apos
is provided as well,argument
is appended from index positionapos
until the end ofargument
.- If
an
is provided too,an
characters ofargument
, starting at index positionapos
are appended to thestring
object.argument
is of typechar const *
, the second parameterapos
is not available. So, withchar const *
arguments, either all characters or an initial subset of the characters of the providedchar const *
argument are appended to thestring
object. Of course, ifapos
andan
are specified in this case,append()
can still be used: thechar const *
argument will then implicitly be converted to astring const &
.
string &string::append(size_type n, char c)
:
Using this member function,n
charactersc
can be appended to thestring
object.
string &string::assign(string argument, size_type apos,
size_type an)
:
If
- If only
argument
is provided, it is assigned to thestring
object.- If
apos
is specified as well, a substring ofargument
object, starting at offset positionapos
, is assigned to thestring
object calling this member.- If
an
is provided too, a substring ofargument
object, starting at offset positionapos
, containing at mostan
characters, is assigned to thestring
object calling this member.argument
is of typechar const *
, no parameterapos
is available. So, withchar const *
arguments, either all characters or an initial subset of the characters of the providedchar const *
argument are assigned to thestring
object. As with thestring::append()
member, achar const *
argument may be used, but it will be converted to astring
object first.
string &string::assign(size_type n, char c)
:
Using this member function,n
charactersc
can be assigned to thestring
object.
size_type string::capacity()
:
returns the number of characters that can currently be
stored inside the string
object.
int string::compare(string argument)
:
This member function can be used to compare (according to the ASCII-character set) the text stored in thestring
object and inargument
. Theargument
may also be a (non-0)char const *
. 0 is returned if the characters in thestring
object and inargument
are the same; a negative value is returned if the text instring
is lexicographically before the text inargument
; a positive value is returned if the text instring
is lexicographically beyond the text inargument
.
int string::compare(size_type opos, size_type on, string
argument)
:
This member function can be used to compare a substring of the text stored in thestring
object with the text stored inargument
. At moston
characters, starting at offsetopos
, are compared with the text inargument
. Theargument
may also be a (non-0)char const *
.
int string::compare(size_type opos, size_type on, string
argument,
size_type apos, size_type an)
:
This member function can be used to compare a substring of the text stored in thestring
object with a substring of the text stored inargument
. At moston
characters of thestring
object, starting at offsetopos
, are compared with at mostan
characters ofargument
, starting at offsetapos
. Note thatargument
must also be astring
object.
int string::compare(size_type opos, size_type on,
char const *argument,
size_type an)
:
This member function can be used to compare a substring of the text stored in thestring
object with a substring of the text stored inargument
. At moston
characters of thestring
object, starting at offsetopos
, are compared with at mostan
characters ofargument
.Argument
must have at leastan
characters. However, the characters may have arbitrary values: the ASCII-Z value has no special meaning.
size_type string::copy(char *argument, size_type on, size_type opos)
:
The contents of thestring
object is (partially) copied toargument
.The actual number of characters that were copied is returned. Note: following the copying, no
- If
on
is provided, it refers to the maximum number of characters that will be copied. If omitted, all thestring
's characters, starting at offsetopos
, will be copied toargument
. Also,string::npos
may be specified to indicate that all available characters should be copied.- If both
on
andopos
are provided,opos
refers to the offset in thestring
object where copying should start.ASCII-Z
will be appended to the copied string. A final ASCII-Z character can be appended to the copied text using the following construction:buffer[s.copy(buffer)] = 0;
char const *string::c_str()
:
the member function returns the contents of thestring
object as anASCII-Z
C-string.
char const *string::data()
:
returns the raw text stored in thestring
object. Since this member does not return an ascii-Z string (asc_str()
does), it can be used to store and retrieve any kind of information, including, e.g., series of 0-bytes:string s; s.resize(2); cout << static_cast<int>(s.data()[1]) << endl;
bool string::empty()
:
returnstrue
if thestring
object contains no data.
string &string::erase(size_type opos; size_type on)
:
This member function can be used to erase (a sub)string of thestring
object.
- If no arguments are provided, the contents of the
string
object are completely erased.- If
opos
is specified, the contents of thestring
object are erased, starting from index positionopos
until (including) the object's final character.- If
on
is provided as well,on
characters of thestring
object, starting at index positionopos
are erased.
iterator string::erase(iterator obegin, iterator oend)
:
The iterator
- If only
obegin
is provided, thestring
object's character at iterator positionobegin
is erased.- If
oend
is provided as well, the range of characters of thestring
object, implied by theiterators obegin
andoend
are erased.obegin
is returned, pointing to the character immediately following the last erased character.
size_type string::find(string argument, size_type opos)
:
Returns the index in thestring
object whereargument
is found.
- If
opos
is provided, it refers to the index in thestring
object where the search forargument
should start. Ifopos
is omitted, searching starts at the beginning of thestring
object.
size_type string::find(char const *argument, size_type opos,
size_type an)
:
Returns the index in thestring
object whereargument
is found.
- If
opos
is provided, it refers to the index in thestring
object where the search forargument
should start. If omitted, thestring
object is scanned completely.- If
an
is provided as well, it indicates the number of characters ofargument
that should be used in the search: it defines a partial string starting at the beginning ofargument
. If omitted, all characters inargument
are used.
size_type string::find(char c, size_type opos)
:
Returns the index in thestring
object wherec
is found.
- If
opos
is provided it refers to the index in thestring
object where the search for the character should start. If omitted, searching starts at the beginning of thestring
object.
size_type string::find_first_of(string argument,
size_type opos)
:
Returns the index in thestring
object where any character inargument
is found.
- If
opos
is provided, it refers to the index in thestring
object where the search forargument
should start. If omitted, searching starts at the beginning of thestring
object.
size_type string::find_first_of(char const *argument,
size_type opos,
size_type an)
:
Returns the index in thestring
object where a character ofargument
is found, no matter which character.
- If
opos
is provided it refers to the index in thestring
object where the search forargument
should start. If omitted, thestring
object is scanned completely.- If
an
is provided it indicates the number of characters of thechar const *
argument that should be used in the search: it defines a partial string starting at the beginning of thechar const *
argument. If omitted, all ofargument
's characters are used.
size_type string::find_first_of(char c, size_type opos)
:
Returns the index in thestring
object where characterc
is found.
- If
opos
is provided, it refers to the index in thestring
object where the search forc
should start. If omitted, searching starts at the beginning of thestring
object.
size_type string::find_first_not_of(string argument,
size_type opos)
:
Returns the index in thestring
object where a character not appearing inargument
is found.
- If
opos
is provided, it refers to the index in thestring
object where the search forargument
should start. If omitted, searching starts at the beginning of thestring
object.
size_type string::find_first_not_of(char const *argument,
size_type opos, size_type an)
:
Returns the index in thestring
object where any character not appearing inargument
is found.
- If
opos
is provided it refers to the index in thestring
object where the search for characters not specified inargument
should start. If omitted, thestring
object is scanned completely.- If
an
is provided it indicates the number of characters of thechar const *
argument that should be used in the search: it defines a partial string starting at the beginning of thechar const *
argument. If omitted, all ofargument
's characters are used.
size_type string::find_first_not_of(char c, size_type opos)
:
Returns the index in thestring
object where another character thanc
is found.
- If
opos
is provided, it refers to the index in thestring
object where the search forc
should start. If omitted, searching starts at the beginning of thestring
object.
size_type string::find_last_of(string argument, size_type opos)
:
Returns the last index in thestring
object where one ofargument
's characters is found.
- If
opos
is provided it refers to the index in thestring
object where the search forargument
should start, proceeding backwards to thestring
's first character. If omitted, searching starts at the thestring
object's last character.
size_type string::find_last_of(char const* argument,
size_type opos,
size_type an)
:
Returns the last index in thestring
object where one ofargument
's characters is found.
- If
opos
is provided it refers to the index in thestring
object where the search forargument
should start, proceeding backwards to thestring
's first character. If omitted, searching starts at the thestring
object's last character.- If
an
is provided it indicates the number of characters ofargument
that should be used in the search: it defines a partial string starting at the beginning of thechar const *
argument. If omitted, all ofargument
's characters are used.
size_type string::find_last_of(char c, size_type opos)
:
Returns the last index in thestring
object where characterc
is found.
- If
opos
is provided it refers to the index in thestring
object where the search for characterc
should start, proceeding backwards to thestring
's first character. If omitted, searching starts at the thestring
object's last character.
size_type string::find_last_not_of(string argument,
size_type opos)
:
Returns the last index in thestring
object where any character not appearing inargument
is found.
- If
opos
is provided it refers to the index in thestring
object where the search for characters not appearing inargument
should start, proceeding backwards to thestring
's first character. If omitted, searching starts at the thestring
object's last character.
size_type string::find_last_not_of(char const *argument,
size_type
opos, size_type an)
:
Returns the last index in thestring
object where any character not appearing inargument
is found.
- If
opos
is provided it refers to the index in thestring
object where the search for characters not appearing inargument
should start, proceeding backwards to thestring
's first character. If omitted, searching starts at the thestring
object's last character.- If
an
is provided it indicates the number of characters ofargument
that should be used in the search: it defines a partial string starting at the beginning of thechar const *
argument. If omitted, all ofargument
's characters are used.
size_type string::find_last_not_of(char c, size_type opos)
:
Returns the last index in thestring
object where another character thanc
is found.
- If
opos
is provided it refers to the index in thestring
object where the search for a character unequal to characterc
should start, proceeding backwards to thestring
's first character. If omitted, searching starts at the thestring
object's last character.
istream &getline(istream &istr, string object, char delimiter)
:
This function (note that it's not a member function of the classstring
) can be used to read a line of text fromistr
. All characters untildelimiter
(or the end of the stream, whichever comes first) are read fromistr
and are stored inobject
. The delimiter, when present, is removed from the stream, but is not stored inline
. The delimiter's default value is'\n'
.
If the delimiter is not found,istr.fail()
returns 1 (see section 5.3.1). Note that the contents of the last line, whether or not it was terminated by a delimiter, will always be assigned toobject
.
string &string::insert(size_type opos, string argument,
size_type
apos, size_type an)
:
This member function can be used to insert (a sub)string ofargument
into thestring
object, at thestring
object's index positionopos
. The argumentsapos
andan
must either be specified or they must both be omitted. If specified,an
characters ofargument
, starting at index positionapos
are inserted into thestring
object.
Ifargument
is of typechar const *
, no parameterapos
is available. So, withchar const *
arguments, either all characters or an initial subset ofan
characters of the providedchar const *
argument are inserted into thestring
object. In this case, the prototype of the member function is:string &string::insert(size_type opos, char const *argument, size_type an)(As before, an implicit conversion fromchar const *
tostring
will occur ifapos
andan
are provided).
string &string::insert(size_type opos, size_type n, char c)
:
Using this member function,n
charactersc
can be inserted to thestring
object.
iterator string::insert(iterator obegin, char c)
:
The characterc
is inserted at the (iterator) positionobegin
in thestring
object. The iteratorobegin
is returned.
iterator string::insert(iterator obegin, size_type n, char c)
:
At the (iterator) positionobegin
ofobject
n
charactersc
are inserted. The iteratorobegin
is returned.
iterator string::insert(iterator obegin,
InputIterator abegin,
InputIterator aend)
:
The range of characters implied by theInputIterators abegin
andaend
are inserted at the (iterator) positionobegin
inobject
. The iteratorobegin
is returned.
size_type string::length()
:
returns the number of characters stored in the string
object.
size_type string::max_size()
:
returns the maximum number of characters that can be stored
in the string
object.
string &string::replace(size_type opos, size_type on, string
argument,
size_type apos, size_type an)
:
The argumentsapos
andan
are optional. If omitted,argument
is considered completely. The substring ofon
characters of thestring
object, starting at positionopos
is replaced byargument
. Ifon
is set to 0, the member function insertsargument
intoobject
.
If
- If
apos
andan
are provided,an
characters ofargument
, starting at index positionapos
will replace the indicated range of characters ofobject
.argument
is of typechar const *
, no parameterapos
is available. So, withchar const *
arguments, either all characters or an initial subset of the characters ofan
characters of the providedchar const *
argument will replace the indicated range of characters inobject
. In that case, the prototype of the member function is:string &string::replace(size_type opos, size_type on, char const *argument, size_type an)
string &string::replace(size_type opos, size_type on,
size_type n,
char c)
:
This member function can be used to replaceon
characters of thestring
object, starting at index positionopos
, byn
characters having valuesc
.
string &string::replace (iterator obegin, iterator oend, string
argument)
:
Here, the string implied by the iteratorsobegin
andoend
are replaced byargument
. Ifargument
is achar const *
, an extra argumentn
may be used, specifying the number of characters ofargument
that are used in the replacement.
string &string::replace(iterator obegin, iterator oend,
size_type n, char c)
:
The range of characters of thestring
object, implied by theiterators obegin
andoend
are replaced byn
characters having valuesc
.
string string::replace(iterator obegin, iterator oend,
InputIterator abegin, InputIterator aend)
:
Here the range of characters implied by the iteratorsobegin
andoend
is replaced by the range of characters implied by theInputIterators abegin
andaend
.
void string::resize(size_type n, char c)
:
The string stored in thestring
object is resized ton
characters. The second argument is optional, in which case the valuec = 0
is used. If provided and the string is enlarged, the extra characters are initialized toc
.
size_type string::rfind(string argument, size_type opos)
:
Returns the index in thestring
object whereargument
is found. Searching proceeds either from the end of thestring
object or from its offsetopos
back to the beginning. If the argumentopos
is omitted, searching starts at the end ofobject
.
size_type string::rfind(char const *argument, size_type opos,
size_type an)
:
Returns the index in thestring
object whereargument
is found. Searching proceeds either from the end of thestring
object or from offsetopos
back to the beginning. The parameteran
indicates the number of characters ofargument
that should be used in the search: it defines a partial string starting at the beginning ofargument
. If omitted, all characters inargument
are used.
size_type string::rfind(char c, size_type opos)
:
Returns the index in thestring
object wherec
is found. Searching proceeds either from the end of thestring
object or from offsetopos
back to the beginning.
size_type string::size()
:
returns the number of characters stored in thestring
object. This member is a synonym ofstring::length()
.
string string::substr(size_type opos, size_type on)
:
Returns (using a value return type) a substring of thestring
object. The parameteron
may be used to specify the number of characters ofobject
that are returned. The parameteropos
may be used to specify the index of the first character ofobject
that is returned. Eitheron
or both arguments may be omitted. The stringobject
itself is not modified bysubstr()
.
size_type string::swap(string argument)
:
swaps the contents of thestring
object andargument
. In this case,argument
must be astring
and cannot be achar const *
. Of course, both strings (object
andargument
) are modified by this member function.