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.2.2) 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
lexicographic 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 << "The two 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 << "The two 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 with a second C-string // This fails, as 3 chars in stringOne starting at // index 6 are compared with "World" if (!stringOne.compare(6, 3, "World")) 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::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 &istr, 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
instr
. Some notes: getline()
is not a
member function of the class string
; streams can be interpreted as
bool
values as well (cf. section 5.3.1).
The delimiter's default value is '\n'
. It is removed from instr
,
but it is not stored in target
. If the delimiter is not found,
istr.eof()
returns true
(see section 5.3.1). 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.
With many members, default values are available for on, an
and
apos
. Some members accept default values for opos
. By default,
apos
and opos
are 0, while on
and an
can by default be
interpreted as `the required number of characters to reach the end of the
string'; where needed this can be made explicit by providing the
generic value string::npos
.
With members starting their operations at the end of the string object
proceeding backwards, the default value of opos
becomes the index of the
object's last character, while on
refers to the
length of the substring ending at the character at opos
.
In the overview of member functions presented below it can be assumed that all these parameters accept default values unless indicated otherwise.
Of course, no defaults are accepted if a function requires additional arguments beyond the ones normally offering default values.
Some members have specific overloaded versions for an initial argument of type
char const *
. However, note that the first argument can always be of
type char const *
, using promotions to convert the char const *
to
a std::string const &
.
When streams are involved, istr
indicates a stream from which information
is extracted, ostr
indicates a stream into which information is inserted.
Several member functions accept iterators. At this point in the
Annotations it's a bit premature to discuss iterators, but for referential
purposes they nevertheless have to be mentioned. So, a forward reference is
used here: see section 17.2 for a more detailed discussion of
iterators. Like apos
and opos
, iterators must refer to
existing characters, or to a defined range of characters within 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 n, char c)
:
Initializesobject
withn
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)
:
Initializesobject
withargument
.
string object(InputIterator begin, InputIterator end)
:
Initializesobject
with the characters implied by the range of characters defined by the twoInputIterators
.
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
. 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 each 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, each returning abool
result.
ostr
<< object
.
The insertion-operator (cf. section 3.1.2)
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 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,
raising an exception (by default aborting the program) if an invalid index is
passed. No default value for opos
.
string &string::append(InputIterator begin, InputIterator end)
:
using this member function the characters, in the range implied by thebegin
andend InputIterators
are appended to thestring
object.
string &string::append(string argument, size_type apos, size_type
an)
:
argument
(or a substring) is appended to thestring
object.
string &string::append(char const *argument, size_type an)
:
the firstan
characters ofargument
are appended to thestring
object.
string &string::append(size_type n, char c)
:
using this member function,n
charactersc
are appended to thestring
object.
string &string::assign(string argument, size_type apos,
size_type an)
:
argument
(or a substring) is assigned to thestring
object.- if
argument
is of typechar const *
and one additional argument is provided the second argument is interpreted as a value initializingan
, using0
to initializeapos
.
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 in thestring
object. Its return value is at leastsize()
's return value
int string::compare(string argument)
:
this member function is 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 is 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 is 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 is 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 objn, size_type opos)
:
the contents of thestring
object are (partially) copied toargument
. The actual number of characters that were copied is returned. Note that
- the second argument, specifying the number of characters to copy, is required;
- the characters of the object for which this member is called will be copied into
argument
;- following the copy operation no
ASCII-Z
is 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 is used to erase (a sub)string of thestring
object.
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 characters of thestring
object, in the range 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.
size_type string::find(char const *argument, size_type opos, size_type an)
:returns the index in thestring
object whereargument
is found. Note: when three arguments are specified the first argument cannot be astd::string const &
.
size_type string::find(char c, size_type opos)
:returns the index in thestring
object wherec
is found.
size_type string::find_first_of(string argument, size_type opos)
:returns the index in thestring
object where any character inargument
is found.
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.
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.
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.
size_type string::find_first_not_of(char c, size_type opos)
:returns the index in thestring
object where another character thanc
is found.
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.
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.
size_type string::find_last_of(char c, size_type opos)
:returns the last index in thestring
object where characterc
is found.
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.
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.
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.
istream &getline(istream &istr, string object, char delimiter)
:this function (note that it's not a member function of the classstring
) is 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.eof()
returnstrue
(see section 5.3.1). The function returns a reference toistr
. Since streams may be interpreted asbool
values (cf. section 5.3.1) a commonly encountered idiom to read all lines from a stream looks like this:while (getline(istr, line)) process(line);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 is used to insert (a sub)string ofargument
into thestring
object, at thestring
object's index positionopos
. Arguments forapos
andan
must either both be specified or they must both be omitted.
string &string::insert(size_type opos, char const *argument, size_type an)
:ifargument
is of typechar const *
,apos
is not available.
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 characters in the range 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 thestring
object.
size_type string::max_size()
:returns the maximum number of characters that can be stored in thestring
object.
string &string::replace(size_type opos, size_type on, string argument,
size_type apos, size_type an)
:the specified substring of characters inobject
are replaced by the specified subset of characters ofargument
. Ifon
is specified as 0, the member function insertsargument
intoobject
at offsetopos
.
string &string::replace(size_type opos, size_type on,
char const *argument, size_type an)
:the indicated range of characters inobject
will be replaced by an initial subset ofan
characters of the providedchar const *
argument.
string &string::replace(size_type opos, size_type on, size_type n,
char c)
:on
characters of thestring
object, starting at index positionopos
, are replaced byn
characters having valuesc
.
string &string::replace (iterator obegin, iterator oend, string argument)
:here, the string implied by the iteratorsobegin
andoend
is replaced byargument
. Ifargument
is achar const *
, an extra argumentan
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 characters of thestring
object, in the range implied by theiterators obegin
andoend
are replaced byn
characters having valuesc
.
string string::replace(iterator obegin, iterator oend, InputIterator abegin, InputIterator aend)
:here the characters in the range implied by the iteratorsobegin
andoend
are replaced by the characters in the range implied by theInputIterators abegin
andaend
.
void string::reserve(size_type request)
:this member can be used to request the string to change its capacity. After it is called, the return value ofcapacity()
will be at leastrequest
or the value returned bysize()
ifrequest
is specified as a smaller value than the value returned by the string'scapacity()
member. Astd::length_error
exception is thrown ifrequest
exceeds the value returned bymax_size()
(thestd::length_error
is defined in thestdexcept
header). Callingreserve()
has the effect of redefining a string's capacity, not of actually making available the memory to the program. This is illustrated by the exception thrown by the string'sat()
member when trying to access an element exceeding the string'ssize()
but not the string'scapacity()
.
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.
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
specifies the number of characters of ofargument
starting at its beginning.
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
, if specified) 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 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.