<string>
string
· char_allocator
· char_traits
· getline
· operator+
· operator!=
· operator==
· operator<
· operator<<
· operator<=
· operator>
· operator>=
· operator>>
· swap
// DECLARATIONS class char_allocator; class char_traits; class string; // TEMPLATE FUNCTIONS string operator+( const string& lhs, const string& rhs); string operator+( const string& lhs, const char_type *rhs); string operator+( const string& lhs, char_type rhs); string operator+( const char_type *lhs, const string& rhs); string operator+( char_type lhs, const string& rhs); bool operator==( const string& lhs, const string& rhs); bool operator==( const string& lhs, const char_type *rhs); bool operator==( const char_type *lhs, const string& rhs); bool operator!=( const string& lhs, const string& rhs); bool operator!=( const string& lhs, const char_type *rhs); bool operator!=( const char_type *lhs, const string& rhs); bool operator<( const string& lhs, const string& rhs); bool operator<( const string& lhs, const char_type *rhs); bool operator<( const char_type *lhs, const string& rhs); bool operator>( const string& lhs, const string& rhs); bool operator>( const string& lhs, const char_type *rhs); bool operator>( const char_type *lhs, const string& rhs); bool operator<=( const string& lhs, const string& rhs); bool operator<=( const string& lhs, const char_type *rhs); bool operator<=( const char_type *lhs, const string& rhs); bool operator>=( const string& lhs, const string& rhs); bool operator>=( const string& lhs, const char_type *rhs); bool operator>=( const char_type *lhs, const string& rhs); void swap( const string& lhs, const string& rhs); ostream& operator<<( ostream& os, const string& str); istream& operator>>( istream& is, string& str); istream& getline( istream& is, string& str); istream& getline( istream& is, string& str, char_type delim); // END OF DECLARATIONS
Include the standard header <string>
to define the
class
string
and various
supporting classes and functions.
string
string
· allocator_type
· append
· assign
· at
· begin
· c_str
· capacity
· char_type
· clear
· compare
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· copy
· data
· difference_type
· empty
· end
· erase
· find
· find_first_not_of
· find_first_of
· find_last_not_of
· find_last_of
· get_allocator
· insert
· iterator
· length
· max_size
· npos
· operator+=
· operator=
· operator[]
· pointer
· push_back
· rbegin
· reference
· rend
· replace
· reserve
· resize
· reverse_iterator
· rfind
· size
· size_type
· substr
· swap
· traits_type
· value_type
class string { public: typedef char_traits traits_type; typedef char_allocator allocator_type; typedef char *iterator; typedef const char *const_iterator; class const_reverse_iterator; class reverse_iterator; typedef traits_type::char_type char_type; typedef allocator_type::size_type size_type; typedef allocator_type::difference_type difference_type; typedef allocator_type::pointer pointer; typedef allocator_type::const_pointer const_pointer; typedef allocator_type::reference reference; typedef allocator_type::const_reference const_reference; typedef allocator_type::value_type value_type; static const size_type npos = -1; string(); explicit string(const allocator_type& al); string(const string& rhs); string(const string& rhs, size_type pos, size_type n); string(const string& rhs, size_type pos, size_type n, const allocator_type& al); string(const char_type *s, size_type n); string(const char_type *s, size_type n, const allocator_type& al); string(const char_type *s); string(const char_type *s, const allocator_type& al); string(size_type n, char_type c); string(size_type n, char_type c, const allocator_type& al); string(const_iterator first, const_iterator last); string(const_iterator first, const_iterator last, const allocator_type& al); string& operator=(const string& rhs); string& operator=(const char_type *s); string& operator=(char_type c); iterator begin(); const_iterator begin() const; iterator end(); const_iterator end() const; reverse_iterator rbegin(); const_reverse_iterator rbegin() const; reverse_iterator rend(); const_reverse_iterator rend() const; const_reference at(size_type pos) const; reference at(size_type pos); const_reference operator[](size_type pos) const; reference operator[](size_type pos); void push_back(char_type c); const char_type *c_str() const; const char_type *data() const; size_type length() const; size_type size() const; size_type max_size() const; void resize(size_type n, char_type c = char_type()); size_type capacity() const; void reserve(size_type n = 0); bool empty() const; string& operator+=(cosst string& rhs); string& operator+=(const char_type *s); string& operator+=(char_type c);
string& append(const string& str); string& append(const string& str, size_type pos, size_type n); string& append(const char_type *s, size_type n); string& append(const char_type *s); string& append(size_type n, char_type c); string& append(const_iterator first, const_iterator last); string& assign(const string& str); string& assign(const string& str, size_type pos, size_type n); string& assign(const char_type *s, size_type n); string& assign(const char_type *s); string& assign(size_type n, char_type c); string& assign(const_iterator first, const_iterator last); string& insert(size_type p0, const string& str); string& insert(size_type p0, const string& str, size_type pos, size_type n); string& insert(size_type p0, const char_type *s, size_type n); string& insert(size_type p0, const char_type *s); string& insert(size_type p0, size_type n, char_type c); iterator insert(iterator it, char_type c = char_type()); void insert(iterator it, size_type n, char_type c); void insert(iterator it, const_iterator first, const_iterator last); string& erase(size_type p0 = 0, size_type n = npos); iterator erase(iterator it); iterator erase(iterator first, iterator last); void clear(); string& replace(size_type p0, size_type n0, const string& str); string& replace(size_type p0, size_type n0, const string& str, size_type pos, size_type n); string& replace(size_type p0, size_type n0, const char_type *s, size_type n); string& replace(size_type p0, size_type n0, const char_type *s); string& replace(size_type p0, size_type n0, size_type n, char_type c); string& replace(iterator first0, iterator last0, const string& str); string& replace(iterator first0, iterator last0, const char_type *s, size_type n); string& replace(iterator first0, iterator last0, const char_type *s); string& replace(iterator first0, iterator last0, size_type n, char_type c); string& replace(iterator first0, iterator last0, const_iterator first, const_iterator last); size_type copy(char_type *s, size_type n, size_type pos = 0) const; void swap(string& str);
size_type find(const string& str, size_type pos = 0) const; size_type find(const char_type *s, size_type pos, size_type n) const; size_type find(const char_type *s, size_type pos = 0) const; size_type find(char_type c, size_type pos = 0) const; size_type rfind(const string& str, size_type pos = npos) const; size_type rfind(const char_type *s, size_type pos, size_type n = npos) const; size_type rfind(const char_type *s, size_type pos = npos) const; size_type rfind(char_type c, size_type pos = npos) const; size_type find_first_of(const string& str, size_type pos = 0) const; size_type find_first_of(const char_type *s, size_type pos, size_type n) const; size_type find_first_of(const char_type *s, size_type pos = 0) const; size_type find_first_of(char_type c, size_type pos = 0) const; size_type find_last_of(const string& str, size_type pos = npos) const; size_type find_last_of(const char_type *s, size_type pos, size_type n = npos) const; size_type find_last_of(const char_type *s, size_type pos = npos) const; size_type find_last_of(char_type c, size_type pos = npos) const; size_type find_first_not_of(const string& str, size_type pos = 0) const; size_type find_first_not_of(const char_type *s, size_type pos, size_type n) const; size_type find_first_not_of(const char_type *s, size_type pos = 0) const; size_type find_first_not_of(char_type c, size_type pos = 0) const; size_type find_last_not_of(const string& str, size_type pos = npos) const; size_type find_last_not_of(const char_type *s, size_type pos, size_type n) const; size_type find_last_not_of(const char_type *s, size_type pos = npos) const; size_type find_last_not_of(char_type c, size_type pos = npos) const; string substr(size_type pos = 0, size_type n = npos) const; int compare(const string& str) const; int compare(size_type p0, size_type n0, const string& str); int compare(size_type p0, size_type n0, const string& str, size_type pos, size_type n); int compare(const char_type *s) const; int compare(size_type p0, size_type n0, const char_type *s) const; int compare(size_type p0, size_type n0, const char_type *s, size_type pos) const; allocator_type get_allocator() const; protected: allocator_type allocator; };
The class describes an object that controls a
varying-length sequence of elements of type char,
also known as
char_type
.
Various important properties of the elements
in a string
are described by the class
char_traits
,
also known as
traits_type
.
The object allocates and frees storage for the sequence it controls
through a protected
allocator object named
allocator
,
of class
char_allocator
, also known as
allocator_type
.
Note that allocator
is not copied when the
object is assigned.
The sequences controlled by an object of class
string
are usually called
strings. These objects should not be
confused, however, with the null-terminated
C strings used throughout the
Standard C++ library.
Many member functions require an operand sequence of elements. You can specify such an operand sequence several ways:
c
-- one element
with value c
n, c
-- a repetition of n
elements each
with value c
s
-- a null-terminated sequence
(such as a C string) beginning at
s
(which must not be a null pointer),
where the terminating element is the value
char_type()
and is not part of
the operand sequences, n
-- a sequence of n
elements
beginning at s
(which must not be a null pointer)str
-- the sequence specified by the
string
object str
str, pos, n
-- the substring of the
string
object str
with up to n
elements (or through the end of the string, whichever comes first)
beginning at position pos
first, last
-- a sequence of elements delimited
by the iterators first
and last
, in the
range [first, last)
, which must not overlap
the sequence controlled by the string object whose member function
is being calledIf a position argument
(such as pos
above) is beyond the end of the string on a
call to a string
member function, the function
reports an
out-of-range error by
throwing an object of class
out_of_range
.
If a function is asked to generate a sequence longer than
max_size()
elements,
the function reports a
length error by
throwing an object of class
length_error
.
References, pointers, and iterators that designate elements of the
controlled sequence can become invalid after any call to a function
that alters the controlled sequence, or after the first call to the
non-const member functions
at
,
begin
,
end
,
operator[]
,
rbegin
, or
rend
.
(The idea is to permit multiple strings to share the same representation
until one string becomes a candidate for change, at which point that string
makes a private copy of the representation, using a discipline called
copy on write.)
string::allocator_type
typedef char_allocator allocator_type;
The type is a synonym for
char_allocator
.
string::append
string& append(const char_type *s); string& append(const char_type *s, size_type n); string& append(const string& str, size_type pos, size_type n); string& append(const string& str); string& append(size_type n, char_type c); string& append(const_iterator first, const_iterator last);
The
member functions each append the
operand sequence to the end of the
sequence controlled by *this
,
then return *this
.
string::assign
string& assign(const char_type *s); string& assign(const char_type *s, size_type n); string& assign(const string& str, size_type pos, size_type n); string& assign(const string& str); string& assign(size_type n, char_type c); string& assign(const_iterator first, const_iterator last);
The
member functions each replace
the sequence controlled by *this
with the
operand sequence, then return *this
.
string::at
const_reference at(size_type pos) const; reference at(size_type pos);
The member functions each return a reference to the element of the
controlled sequence at position pos
,
or report an out-of-range error.
string::string
string(const char_type *s); string(const char_type *s, const allocator_type& al); string(const char_type *s, size_type n); string(const char_type *s, size_type n, const allocator_type& al); string(const string& rhs); string(const string& rhs, size_type pos, size_type n); string(const string& rhs, size_type pos, size_type n, const allocator_type& al); string(size_type n, char_type c); string(size_type n, char_type c, const allocator_type& al); string(); explicit string(const allocator_type& al); string(const_iterator first, const_iterator last); string(const_iterator first, const_iterator last, const allocator_type& al);
All constructors store an
allocator object in
allocator
and
initialize the controlled sequence. The allocator object is the argument
al
, if present. For the copy constructor, it is
x.get_allocator()
.
Otherwise, it is A()
.
The controlled sequence is initialized to a copy of the operand sequence specified by the remaining operands. A constructor with no operand sequence specifies an empty initial controlled sequence.
string::begin
const_iterator begin() const; iterator begin();
The member functions each return a random-access iterator that points at the first element of the sequence (or just beyond the end of an empty sequence).
string::c_str
const char_type *c_str() const;
The member function returns a pointer to a non-modifiable
C string constructed by adding a
terminating null element
(char_type()
) to the controlled
sequence. Calling any non-const member function for
*this
can invalidate the pointer.
string::capacity
size_type capacity() const;
The member function returns the storage currently allocated to hold
the controlled sequence, a value at least as large as
size()
.
string::char_type
typedef traits_type::char_type char_type;
The type is a synonym for traits_type::char_type
.
string::clear
void clear();
The member function calls
erase(
begin(),
end())
.
string::compare
int compare(const string& str) const; int compare(size_type p0, size_type n0, const string& str); int compare(size_type p0, size_type n0, const string& str, size_type pos, size_type n); int compare(const char_type *s) const; int compare(size_type p0, size_type n0, const char_type *s) const; int compare(size_type p0, size_type n0, const char_type *s, size_type pos) const;
The member functions each compare up to n0
elements of the
controlled sequence beginning with position p0
, or the
entire controlled sequence if these arguments are not supplied,
to the operand sequence.
Each function returns:
traits_type::compare
), or if the
two have a common prefix but the operand sequence is longerstring::const_iterator
typedef const char *const_iterator;
The type is a synonym for const char *
, which can serve as a constant
random-access iterator for the controlled sequence.
string::const_pointer
typedef allocator_type::const_pointer const_pointer;
The type is a synonym for allocator_type::const_pointer
.
string::const_reference
typedef allocator_type::const_reference const_reference;
The type is a synonym for allocator_type::const_reference
.
string::const_reverse_iterator
class const_reverse_iterator;
The type describes an object that can serve as a constant reverse iterator for the controlled sequence. You can, for example, access each of the elements in the controlled sequence in reverse order by writing:
string::const_reverse_iterator p; for (p = rbegin(); p != rend(); ++p) process *p
string::copy
size_type copy(char_type *s, size_type n, size_type pos = 0) const;
The member function copies up to n
elements from the
controlled sequence, beginning at position pos
, to the
array of char_type
beginning at s
. It returns the
number of elements actually copied.
string::data
const char_type *data() const;
The member function returns a pointer to the first element of the sequence (or, for an empty sequence, a non-null pointer that cannot be dereferenced).
string::difference_type
typedef allocator_type::difference_type difference_type;
The type is a synonym for allocator_type::difference_type
.
string::empty
bool empty() const;
The member function returns true for an empty controlled sequence.
string::end
const_iterator end() const; iterator end();
The member functions each return a random-access iterator that points just beyond the end of the sequence.
string::erase
iterator erase(iterator first, iterator last); iterator erase(iterator it); string& erase(size_type p0 = 0, size_type n = npos);
The first member function removes the elements of the controlled
sequence in the range [first, last)
.
The second member function removes the element of the controlled
sequence pointed to by it
.
Both return an iterator that designates the first element remaining
beyond any elements removed, or
end()
if no such element exists.
The third member function removes up to n
elements of
the controlled sequence beginning at position p0
, then
returns *this
.
string::find
size_type find(char_type c, size_type pos = 0) const; size_type find(const char_type *s, size_type pos = 0) const; size_type find(const char_type *s, size_type pos, size_type n) const; size_type find(const string& str, size_type pos = 0) const;
The member functions each find the first (lowest beginning position)
subsequence in the controlled sequence, beginning on or after position
pos
, that matches the
operand sequence specified by the
remaining operands. If it succeeds, it returns the position where the
matching subsequence begins. Otherwise, the function returns
npos
.
string::find_first_not_of
size_type find_first_not_of(char_type c, size_type pos = 0) const; size_type find_first_not_of(const char_type *s, size_type pos = 0) const; size_type find_first_not_of(const char_type *s, size_type pos, size_type n) const; size_type find_first_not_of(const string& str, size_type pos = 0) const;
The member functions each find the first (lowest position) element of the
controlled sequence, at or after position pos
, that
matches none of the elements in the
operand sequence specified by the
remaining operands. If it succeeds, it returns the position. Otherwise,
the function returns
npos
.
string::find_first_of
size_type find_first_of(char_type c, size_type pos = 0) const; size_type find_first_of(const char_type *s, size_type pos = 0) const; size_type find_first_of(const char_type *s, size_type pos, size_type n) const; size_type find_first_of(const string& str, size_type pos = 0) const;
The member functions each find the first (lowest position) element of the
controlled sequence, at or after position pos
, that
matches any of the elements in the
operand sequence specified by the
remaining operands. If it succeeds, it returns the position. Otherwise,
the function returns
npos
.
string::find_last_not_of
size_type find_last_not_of(char_type c, size_type pos = npos) const; size_type find_last_not_of(const char_type *s, size_type pos = npos) const; size_type find_last_not_of(const char_type *s, size_type pos, size_type n) const; size_type find_last_not_of(const string& str, size_type pos = npos) const;
The member functions each find the last (highest position) element of the
controlled sequence, at or before position pos
, that
matches none of the elements in the
operand sequence specified by the
remaining operands. If it succeeds, it returns the position. Otherwise,
the function returns
npos
.
string::find_last_of
size_type find_last_of(char_type c, size_type pos = npos) const; size_type find_last_of(const char_type *s, size_type pos = npos) const; size_type find_last_of(const char_type *s, size_type pos, size_type n = npos) const; size_type find_last_of(const string& str, size_type pos = npos) const;
The member functions each find the last (highest position) element of the
controlled sequence, at or before position pos
, that
matches any of the elements in the
operand sequence specified by the
remaining operands. If it succeeds, it returns the position. Otherwise,
the function returns
npos
.
string::get_allocator
allocator_type get_allocator() const;
The member function returns
allocator
.
string::insert
string& insert(size_type p0, const char_type *s); string& insert(size_type p0, const char_type *s, size_type n); string& insert(size_type p0, const string& str); string& insert(size_type p0, const string& str, size_type pos, size_type n); string& insert(size_type p0, size_type n, char_type c); iterator insert(iterator it, char_type c = char_type()); void insert(iterator it, const_iterator first, const_iterator last); void insert(iterator it, size_type n, char_type c);
The member functions each insert, before position p0
or
before the element pointed to by it
in the controlled
sequence, the
operand sequence specified by the
remaining operands. A function that returns a value returns
*this
.
string::iterator
typedef char *iterator;
The type is a synonym for char *
, which can serve as a
random-access iterator for the controlled sequence.
string::length
size_type length() const;
The member function returns the length of the controlled sequence
(same as size()
).
string::max_size
size_type max_size() const;
The member function returns the length of the longest sequence that the object can control.
string::npos
static const size_type npos = -1;
The constant is the largest representable value of type
size_type
. It is
assuredly larger than
max_size()
, hence
it serves as either a very large value or as a special code.
string::operator+=
string& operator+=(char_type c); string& operator+=(const char_type *s); string& operator+=(const string& rhs);
The operators each append the
operand sequence to the end of the
sequence controlled by *this
, then return *this
.
string::operator=
string& operator=(char_type c); string& operator=(const char_type *s); string& operator=(const string& rhs);
The operators each replace the sequence controlled by *this
with the
operand sequence,
then return *this
.
string::operator[]
const_reference operator[](size_type pos) const; reference operator[](size_type pos);
The member functions each return a reference to the element of the
controlled sequence at position pos
. If that position is
invalid, the behavior is undefined.
string::pointer
typedef allocator_type::pointer pointer;
The type is a synonym for allocator_type::pointer
.
string::push_back
void push_back(char_type c);
The member function effectively calls
insert(
end(), c)
.
string::rbegin
const_reverse_iterator rbegin() const; reverse_iterator rbegin();
The member function returns a reverse iterator that points just beyond the end of the controlled sequence. Hence, it designates the beginning of the reverse sequence.
string::reference
typedef allocator_type::reference reference;
The type is a synonym for allocator_type::reference
.
string::rend
const_reverse_iterator rend() const; reverse_iterator rend();
The member functions each return a reverse iterator that points at the first element of the sequence (or just beyond the end of an empty sequence). Hence, the function designates the end of the reverse sequence.
string::replace
string& replace(size_type p0, size_type n0, const char_type *s); string& replace(size_type p0, size_type n0, const char_type *s, size_type n); string& replace(size_type p0, size_type n0, const string& str); string& replace(size_type p0, size_type n0, const string& str, size_type pos, size_type n); string& replace(size_type p0, size_type n0, size_type n, char_type c); string& replace(iterator first0, iterator last0, const char_type *s); string& replace(iterator first0, iterator last0, const char_type *s, size_type n); string& replace(iterator first0, iterator last0, const string& str); string& replace(iterator first0, iterator last0, size_type n, char_type c); string& replace(iterator first0, iterator last0, const_iterator first, const_iterator last);
The member functions each replace up to n0
elements of the
controlled sequence beginning with position p0
, or the
elements of the controlled sequence beginning with the one pointed to by
first
, up to but not including last
. The
replacement is the
operand sequence specified by the
remaining operands. The function then returns
*this
.
string::reserve
void reserve(size_type n = 0);
The member function ensures that
capacity()
henceforth returns at least n
.
string::resize
void resize(size_type n, char_type c = char_type());
The member function ensures that
size()
henceforth
returns n
. If it must make the controlled sequence longer,
it appends elements with value c
.
To make the controlled sequence shorter, the member function effectively calls
erase(begin() + n, end())
.
string::reverse_iterator
class reverse_iterator;
The type describes an object that can serve as a reverse iterator for the controlled sequence. You can, for example, access each of the elements in the controlled sequence in reverse order by writing:
string::reverse_iterator p; for (p = rbegin(); p != rend(); ++p) process *p
string::rfind
size_type rfind(char_type c, size_type pos = npos) const; size_type rfind(const char_type *s, size_type pos = npos) const; size_type rfind(const char_type *s, size_type pos, size_type n = npos) const; size_type rfind(const string& str, size_type pos = npos) const;
The member functions each find the last
(highest beginning position) subsequence in
the controlled sequence, beginning on or before position pos
,
that matches the
operand sequence specified by the
remaining operands. If it succeeds, the function returns the position where the
matching subsequence begins. Otherwise, it returns
npos
.
string::size
size_type size() const;
The member function returns the length of the controlled sequence.
string::size_type
typedef allocator_type::size_type size_type;
The type is a synonym for allocator_type::size_type
.
string::substr
string substr(size_type pos = 0, size_type n = npos) const;
The member function returns an object whose controlled sequence is a
copy of up to n
elements of the controlled sequence
beginning at position pos
.
string::swap
void swap(string& str);
The member function swaps the controlled sequences between
*this
and str
. If
allocator
== str.allocator
, it does so in constant time. Otherwise,
it performs a number of element assignments and constructor calls
proportional to the number of elements in the two controlled sequences.
string::traits_type
typedef char_traits traits_type;
The type is a synonym for
char_traits
.
string::value_type
typedef allocator_type::value_type value_type;
The type is a synonym for allocator_type::value_type
.
char_allocator
class char_allocator { public: typedef size_t size_type; typedef ptrdiff_t difference_type; typedef char *pointer; typedef const char *const_pointer; typedef char& reference; typedef const char& const_reference; typedef char value_type; char_allocator(); char_allocator(const allocator& x); pointer address(reference x) const; const_pointer address(const_reference x) const; pointer allocate(size_type n, const void *hint); void deallocate(pointer p, size_type n); size_type max_size() const; bool operator==(char_allocator& lhs, char_allocator& rhs) const; };
The class describes an object that manages
storage allocation and freeing for arrays of objects of type char.
An object of class char_allocator
is the
allocator object
used by class
string
.
Class char_allocator
supplies several
type definitions that are rather pedestrian.
They hardly seem worth defining.
But another version of the class
might choose more interesting alternatives.
Constructing a container with an allocator object of such a class
gives individual control over allocation and freeing
of elements controlled by that container.
For example, an allocator object might allocate storage on a
private heap.
Or it might allocate storage on a
far heap, requiring nonstandard
pointers to access the allocated objects. Or it might specify,
through the type definitions it supplies, that elements be
accessed through special
accessor objects that manage
shared memory, or perform automatic
garbage collection.
Hence, a class that allocates storage using an allocator object
should use these types religiously for declaring pointer and
reference objects (as does class
string
).
Thus, an allocator defines the types (among others):
pointer
-- behaves like a pointer to char
const_pointer
-- behaves like a
const pointer to char
reference
-- behaves like a reference to char
const_reference
-- behaves like a
const reference to char
These types specify the form that pointers and references
must take for allocated elements.
(char_allocator::pointer
is not necessarily
the same as char *
for all allocator objects, even though
it has this obvious definition for class char_allocator
.)
char_allocator::address
pointer address(reference x) const; const_pointer address(const_reference x) const;
The member functions return the address of x
,
in the form that pointers must take for allocated elements.
char_allocator::allocate
pointer allocate(size_type n, const void *hint);
The member function allocates storage for
an array of n
elements of type char, by calling
operator new(n)
.
It returns a pointer to the allocated object.
The hint
argument helps some char_allocators
in improving locality of reference -- a valid choice
is the address of an object earlier allocated by the same char_allocator
object, and not yet deallocated. To supply no
hint, use a null pointer argument instead.
char_allocator::char_allocator
char_allocator(); char_allocator(const char_allocator& x);
The constructor does nothing. In general, however, an allocator object constructed from another allocator object should compare equal to it (and hence permit intermixing of object allocation and freeing between the two allocator objects).
char_allocator::const_pointer
typedef const char *pointer;
The pointer type describes an object p
that can
designate, via the expression *p
, any const object
that an object of class
char_allocator
can allocate.
char_allocator::const_reference
typedef const char& const_reference;
The reference type describes an object x
that can
designate any const object that an object of class
char_allocator
can allocate.
char_allocator::deallocate
void deallocate(pointer p, size_type n);
The member function frees storage for
the array of n
objects of type
char beginning at p
, by calling
operator delete(p)
.
The pointer p
must have been earlier returned by a call to
allocate
for an allocator
object that compares equal to *this
, allocating an array object
of the same size and type.
char_allocator::difference_type
typedef ptrdiff_t difference_type;
The signed integer type describes an object that can represent the
difference between the addresses of any two elements in a sequence
that an object of class char_allocator
can allocate.
char_allocator::max_size
size_type max_size() const;
The member function returns the length of the longest sequence
of elements of type char that an object of class
char_allocator
might be able to allocate.
char_allocator::operator=
char_allocator& operator=(const char_allocator& x);
The assignment operator does nothing. In general, however, an allocator object assigned to another allocator object should compare equal to it (and hence permit intermixing of object allocation and freeing between the two allocator objects).
char_allocator::operator==
bool operator==(char_allocator& lhs, char_allocator& rhs) const;
The operator returns true. (Two allocator objects should compare equal only if an object allocated through one can be deallocated through the other. If the value of one object is determined from another by assignment or by construction, the two object should compare equal.)
char_allocator::pointer
typedef char *pointer;
The pointer type describes an object p
that can
designate, via the expression *p
, any object
that an object of class
char_allocator
can allocate.
char_allocator::reference
typedef char& reference;
The reference type describes an object x
that can
designate any object that an object of class
char_allocator
can allocate.
char_allocator::size_type
typedef size_t size_type;
The unsigned integer type describes an object that can represent
the length of any sequence that an object of class
char_allocator
can allocate.
char_allocator::value_type
typedef char value_type;
The type is a synonym for char.
char_traits
class char_traits { public: typedef char char_type; typedef int int_type; typedef streampos pos_type; typedef streamoff off_type; typedef mbstate_t state_type; static void assign(char_type& x, const char_type& y); static char_type *assign(char_type *x, size_t n, const char_type& y); static bool eq(const char_type& x, const char_type& y); static bool lt(const char_type& x, const char_type& y); static int compare(const char_type *x, const char_type *y, size_t n); static size_t length(const char_type *x); static char_type *copy(char_type *x, const char_type *y, size_t n); static char_type *move(char_type *x, const char_type *y, size_t n); static const char_type *find(const char_type *x, size_t n, const char_type& y); static char_type to_char_type(const int_type& ch); static int_type to_int_type(const char_type& c); static bool eq_int_type(const int_type& ch1, const int_type& ch2); static int_type eof(); static int_type not_eof(const int_type& ch); };
The class describes various
character traits
for type char.
The class
string
as well as several iostreams classes, including
ios
, use this information
to manipulate elements of type char.
None of the member functions of class char_traits
may
throw exceptions.
char_traits::assign
static void assign(char_type& x, const char_type& y); static char_type *assign(char_type *x, size_t n, const char_type& y);
The first static member function assigns y
to x
. The second static member function assigns y
to each element X[N]
for N
in the range [0, N)
.
char_traits::char_type
typedef char char_type;
The type is a synonym for char.
char_traits::compare
static int compare(const char_type *x, const char_type *y, size_t n);
The static member function compares the sequence of length n
beginning at x
to the sequence of the same length beginning
at y
. The function returns:
x
(as determined by
eq
) compares less
than the corresponding element in y
(as determined by
lt
) char_traits::copy
static char_type *copy(char_type *x, const char_type *y, size_t n);
The static member function copies the sequence of n
elements beginning at y
to the array beginning at x
,
then returns x
. The source and destination
must not overlap.
char_traits::eof
static int_type eof();
The static member function returns a value that represents
end-of-file (EOF
).
char_traits::eq
static bool eq(const char_type& x, const char_type& y);
The static member function returns true if x
compares
equal to y
.
char_traits::eq_int_type
static bool eq_int_type(const int_type& ch1, const int_type& ch2);
The static member function returns true if
ch1 == ch2
.
char_traits::find
static const char_type *find(const char_type *x, size_t n, const char_type& y);
The static member function determines the lowest N
in the range [0, n)
for which
eq(x[N], y)
is true. If successful, it returns x + N
. Otherwise,
it returns a null pointer.
char_traits::int_type
typedef int int_type;
The type is a synonym for int.
char_traits::length
static size_t length(const char_type *x);
The static member function returns the number of elements
N
in the sequence beginning at x
up to but not including the element x[N]
which
compares equal to char_type()
.
char_traits::lt
static bool lt(const char_type& x, const char_type& y);
The static member function returns true if x
compares
less than y
.
char_traits::move
static char_type *move(char_type *x, const char_type *y, size_t n);
The static member function copies the sequence of n
elements beginning at y
to the array beginning at x
,
then returns x
. The source and destination may overlap.
char_traits::not_eof
static int_type not_eof(const int_type& ch);
If
!eq_int_type(
eof(), ch)
,
the static member function returns ch
.
Otherwise, it returns a value other than
eof()
.
char_traits::off_type
typedef streamoff off_type;
The type is a synonym for
streamoff
.
char_traits::pos_type
typedef streampos pos_type;
The type is a synonym for
streampos
.
char_traits::state_type
typedef mbstate_t state_type;
The type is a synonym for
mbstate_t
.
char_traits::to_char_type
static char_type to_char_type(const int_type& ch);
The static member function returns ch
, represented as
type E
. A value of ch
that cannot be so
represented yields an unspecified result.
char_traits::to_int_type
static int_type to_int_type(const char_type& c);
The static member function returns ch
, represented as
type int_type
. It should always be true that
to_char_type(to_int_type(c)
== c
for any value of c
.
getline
istream& getline(istream& is, string& str); istream& getline(istream& is, string& str, char delim);
The first function returns getline(is, str, is.widen('\n'))
.
The second function replaces the sequence controlled by
str
with a sequence of elements extracted from the stream
is
. In order of testing, extraction stops:
delim
, in which case the element is neither put back nor
appended to the controlled sequencestr.max_size()
elements, in which case the function calls
setstate(ios_base::failbit)
.If the function extracts no elements, it calls
setstate(failbit)
.
In any case, it returns *this
.
operator+
string operator+( const string& lhs, const string& rhs); string operator+( const string& lhs, const char *rhs); string operator+( const string& lhs, char rhs); string operator+( const char *lhs, const string& rhs); string operator+( char lhs, const string& rhs);
The functions each overload operator+
to
concatenate two objects of class
string
.
All effectively return
string(lhs).append(rhs)
.
operator!=
bool operator!=( const string& lhs, const string& rhs); bool operator!=( const string& lhs, const char *rhs); bool operator!=( const char *lhs, const string& rhs);
The functions each overload operator!=
to compare
two objects of class
string
. All effectively
return string(lhs).compare(rhs)
!= 0
.
operator==
bool operator==( const string& lhs, const string& rhs); bool operator==( const string& lhs, const char *rhs); bool operator==( const char *lhs, const string& rhs);
The functions each overload operator==
to compare
two objects of class
string
. All effectively
return string(lhs).compare(rhs)
== 0
.
operator<
bool operator<( const string& lhs, const string& rhs); bool operator<( const string& lhs, const char *rhs); bool operator<( const char *lhs, const string& rhs);
The functions each overload operator<
to
compare two objects of class
string
. All effectively
return string(lhs).compare(rhs)
< 0
.
operator<<
ostream& operator<<( ostream& os, const string& str);
The function is a
formatted output functions
that overloads operator<<
to
determine the length n =
str.size()
of the sequence controlled by str
, and insert the sequence. If
n < os.width()
,
then the function also inserts a repetition of os.width() - n
fill characters.
The repetition precedes the sequence if
(os.flags() &
adjustfield !=
left
.
Otherwise, the repetition follows the sequence.
The function returns os
.
operator<=
bool operator<=( const string& lhs, const string& rhs); bool operator<=( const string& lhs, const char *rhs); bool operator<=( const char *lhs, const string& rhs);
The functions each overload operator<=
to
compare two objects of class
string
. All effectively
return string(lhs).compare(rhs)
<= 0
.
operator>
bool operator>( const string& lhs, const string& rhs); bool operator>( const string& lhs, const char *rhs); bool operator>( const char *lhs, const string& rhs);
The functions each overload operator>
to
compare two objects of class
string
. All effectively
return string(lhs).compare(rhs)
> 0
.
operator>=
bool operator>=( const string& lhs, const string& rhs); bool operator>=( const string& lhs, const char *rhs); bool operator>=( const char *lhs, const string& rhs);
The functions each overload operator>=
to
compare two objects of class
string
. All effectively
return string(lhs).compare(rhs)
>= 0
.
operator>>
istream& operator>>( istream& is, const string& str);
The template function overloads operator>>
to
replace the sequence controlled by str
with a sequence of
elements extracted from the stream is
. Extraction stops:
is.width()
elements, if that value is nonzerois.max_size()
elementsc
for which
isspace(c)
is true, in which case the character is put backIf the function extracts no elements, it calls
setstate(ios_base::failbit)
.
In any case, it calls is.width(0)
and
returns *this
.
swap
template<class T, class A> void swap( const string& lhs, const string& rhs);
The template function executes
swap(lhs, rhs)
.
See also the Table of Contents and the Index.
Copyright © 1992-1996 by P.J. Plauger. All rights reserved.