|
|
<string>
basic_string , char_traits , char_traits<char> , char_traits<wchar_t> , getline , operator+ , operator!= , operator== , operator< , operator<< , operator<= , operator> , operator>= , operator>> , string , swap , wstring - defines a template class that implements a string container
namespace std { template<class E> class char_traits; template<> class char_traits<char>; template<> class char_traits<wchar_t>; template<class E, class T = char_traits<E>, class A = allocator<E> > class basic_string; typedef basic_string<char> string; typedef basic_string>wchar_t> wstring; // TEMPLATE FUNCTIONS template<class E, class T, class A> basic_string<E, T, A> operator+( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> basic_string<E, T, A> operator+( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> basic_string<E, T, A> operator+( const basic_string<E, T, A>& lhs, E rhs); template<class E, class T, class A> basic_string<E, T, A> operator+( const E *lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> basic_string<E, T, A> operator+( E lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator==( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator==( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> bool operator==( const E *lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator!=( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator!=( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> bool operator!=( const E *lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator<( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator<( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> bool operator<( const E *lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator>( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator>( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> bool operator>( const E *lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator<=( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator<=( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> bool operator<=( const E *lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator>=( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator>=( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> bool operator>=( const E *lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> void swap( basic_string<E, T, A>& lhs, basic_string<E, T, A>& rhs); template<class E, class T, class A> basic_ostream<E>& operator<<( basic_ostream<E>& os, const basic_string<E, T, A>& str); template<class E, class T, class A> basic_istream<E>& operator>>( basic_istream<E>& is, basic_string<E, T, A>& str); template<class E, class T, class A> basic_istream<E, T>& getline( basic_istream<E, T>& is, basic_string<E, T, A>& str); template<class E, class T, class A> basic_istream<E, T>& getline( basic_istream<E, T>& is, basic_string<E, T, A>& str, E delim); };
Include the standard header <string>
to define the
container
template class
basic_string
and various
supporting templates.
basic_string , allocator_type , append , assign , at , begin , c_str , capacity , 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
template<class E, class T = char_traits<E>, class A = allocator<T> > class basic_string { public: typedef T traits_type; typedef A allocator_type; typedef T0 iterator; typedef T1 const_iterator; typedef T2 size_type; typedef T3 difference_type; typedef reverse_iterator<const_iterator> const_reverse_iterator; typedef reverse_iterator<iterator> reverse_iterator; typedef typename allocator_type::pointer pointer; typedef typename allocator_type::const_pointer const_pointer; typedef typename allocator_type::reference reference; typedef typename allocator_type::const_reference const_reference; typedef typename allocator_type::value_type value_type; static const size_type npos = -1; basic_string(); explicit basic_string(const allocator_type& al); basic_string(const basic_string& rhs); basic_string(const basic_string& rhs, size_type pos, size_type n = npos); basic_string(const basic_string& rhs, size_type pos, size_type n, const allocator_type& al); basic_string(const value_type *s, size_type n); basic_string(const value_type *s, size_type n, const allocator_type& al); basic_string(const value_type *s); basic_string(const value_type *s, const allocator_type& al); basic_string(size_type n, value_type c); basic_string(size_type n, value_type c, const allocator_type& al); template <class InIt> basic_string(InIt first, InIt last); template <class InIt> basic_string(InIt first, InIt last, const allocator_type& al); basic_string& operator=(const basic_string& rhs); basic_string& operator=(const value_type *s); basic_string& operator=(value_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(value_type c); const value_type *c_str() const; const value_type *data() const; size_type length() const; size_type size() const; size_type max_size() const; void resize(size_type n, value_type c = value_type()); size_type capacity() const; void reserve(size_type n = 0); bool empty() const; basic_string& operator+=(const basic_string& rhs); basic_string& operator+=(const value_type *s); basic_string& operator+=(value_type c);
basic_string& append(const basic_string& str); basic_string& append(const basic_string& str, size_type pos, size_type n); basic_string& append(const value_type *s, size_type n); basic_string& append(const value_type *s); basic_string& append(size_type n, value_type c); template<class InIt> basic_string& append(InIt first, InIt last); basic_string& assign(const basic_string& str); basic_string& assign(const basic_string& str, size_type pos, size_type n); basic_string& assign(const value_type *s, size_type n); basic_string& assign(const value_type *s); basic_string& assign(size_type n, value_type c); template<class InIt> basic_string& assign(InIt first, InIt last); basic_string& insert(size_type p0, const basic_string& str); basic_string& insert(size_type p0, const basic_string& str, size_type pos, size_type n); basic_string& insert(size_type p0, const value_type *s, size_type n); basic_string& insert(size_type p0, const value_type *s); basic_string& insert(size_type p0, size_type n, value_type c); iterator insert(iterator it, value_type c = value_type()); void insert(iterator it, size_type n, value_type c); template<class InIt> void insert(iterator it, InIt first, InIt last); basic_string& erase(size_type p0 = 0, size_type n = npos); iterator erase(iterator it); iterator erase(iterator first, iterator last); void clear(); basic_string& replace(size_type p0, size_type n0, const basic_string& str); basic_string& replace(size_type p0, size_type n0, const basic_string& str, size_type pos, size_type n); basic_string& replace(size_type p0, size_type n0, const value_type *s, size_type n); basic_string& replace(size_type p0, size_type n0, const value_type *s); basic_string& replace(size_type p0, size_type n0, size_type n, value_type c); basic_string& replace(iterator first0, iterator last0, const basic_string& str); basic_string& replace(iterator first0, iterator last0, const value_type *s, size_type n); basic_string& replace(iterator first0, iterator last0, const value_type *s); basic_string& replace(iterator first0, iterator last0, size_type n, value_type c); template<class InIt> basic_string& replace(iterator first0, iterator last0, InIt first, InIt last); size_type copy(value_type *s, size_type n, size_type pos = 0) const; void swap(basic_string& str);
size_type find(const basic_string& str, size_type pos = 0) const; size_type find(const value_type *s, size_type pos, size_type n) const; size_type find(const value_type *s, size_type pos = 0) const; size_type find(value_type c, size_type pos = 0) const; size_type rfind(const basic_string& str, size_type pos = npos) const; size_type rfind(const value_type *s, size_type pos, size_type n = npos) const; size_type rfind(const value_type *s, size_type pos = npos) const; size_type rfind(value_type c, size_type pos = npos) const; size_type find_first_of(const basic_string& str, size_type pos = 0) const; size_type find_first_of(const value_type *s, size_type pos, size_type n) const; size_type find_first_of(const value_type *s, size_type pos = 0) const; size_type find_first_of(value_type c, size_type pos = 0) const; size_type find_last_of(const basic_string& str, size_type pos = npos) const; size_type find_last_of(const value_type *s, size_type pos, size_type n = npos) const; size_type find_last_of(const value_type *s, size_type pos = npos) const; size_type find_last_of(value_type c, size_type pos = npos) const; size_type find_first_not_of(const basic_string& str, size_type pos = 0) const; size_type find_first_not_of(const value_type *s, size_type pos, size_type n) const; size_type find_first_not_of(const value_type *s, size_type pos = 0) const; size_type find_first_not_of(value_type c, size_type pos = 0) const; size_type find_last_not_of(const basic_string& str, size_type pos = npos) const; size_type find_last_not_of(const value_type *s, size_type pos, size_type n) const; size_type find_last_not_of(const value_type *s, size_type pos = npos) const; size_type find_last_not_of(value_type c, size_type pos = npos) const; basic_string substr(size_type pos = 0, size_type n = npos) const; int compare(const basic_string& str) const; int compare(size_type p0, size_type n0, const basic_string& str); int compare(size_type p0, size_type n0, const basic_string& str, size_type pos, size_type n); int compare(const value_type *s) const; int compare(size_type p0, size_type n0, const value_type *s) const; int compare(size_type p0, size_type n0, const value_type *s, size_type pos) const; allocator_type get_allocator() const; };
The template class describes an object that controls a
varying-length sequence of elements of type E
,
also known as
value_type
.
Such an element type must not require explicit construction or
destruction, and it must be suitable for use as the E
parameter to
basic_istream
or
basic_ostream
.
(A ``plain old data structure,'' or
POD, from C generally meets
this criterion.)
The Standard C++ library provides two specializations of this template
class, with the type definitions
string
,
for elements of type char, and
wstring
, for elements of type
wchar_t
.
Various important properties of the elements
in a basic_string
specialization are described by the class T
, also known as
traits_type
.
A class that specifies these
character traits must
have the same external interface as an object of template class
char_traits
.
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class A
, also known as
allocator_type
.
Such an allocator object must have
the same external interface as an object of template class
allocator
.
(Class
char_traits
has
no provision for alternate addressing schemes, such as might be required
to implement a
far heap.)
Note that the stored allocator object is not copied when the container
object is assigned.
The sequences controlled by an object of template class
basic_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,
for E
of type char) beginning at
s
(which must not be a null pointer),
where the terminating element is the value
value_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
basic_string
object str
str, pos, n
-- the substring of the
basic_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 basic_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.)
typedef A allocator_type;
The type is a synonym for the template parameter A
.
basic_string& append(const value_type *s); basic_string& append(const value_type *s, size_type n); basic_string& append(const basic_string& str, size_type pos, size_type n); basic_string& append(const basic_string& str); basic_string& append(size_type n, value_type c); template<class InIt> basic_string& append(InIt first, InIt last);
If InIt
is an integer type, the template member
function behaves the same as append((size_type)first, (value_type)last)
.
Otherwise, the
member functions each append the
operand sequence to the end of the
sequence controlled by *this
,
then return *this
.
In this implementation, if a translator does not support member template functions, the template:
template<class InIt> basic_string& append(InIt first, InIt last);
is replaced by:
basic_string& append(const_pointer first, const_pointer last);
basic_string& assign(const value_type *s); basic_string& assign(const value_type *s, size_type n); basic_string& assign(const basic_string& str, size_type pos, size_type n); basic_string& assign(const basic_string& str); basic_string& assign(size_type n, value_type c); template<class InIt> basic_string& assign(InIt first, InIt last);
If InIt
is an integer type, the template member
function behaves the same as assign((size_type)first, (value_type)last)
.
Otherwise, the
member functions each replace
the sequence controlled by *this
with the
operand sequence, then return *this
.
In this implementation, if a translator does not support member template functions, the template:
template<class InIt> basic_string& assign(InIt first, InIt last);
is replaced by:
basic_string& assign(const_pointer first, const_pointer last);
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.
basic_string(const value_type *s); basic_string(const value_type *s, const allocator_type& al); basic_string(const value_type *s, size_type n); basic_string(const value_type *s, size_type n, const allocator_type& al); basic_string(const basic_string& rhs); basic_string(const basic_string& rhs, size_type pos, size_type n = npos); basic_string(const basic_string& rhs, size_type pos, size_type n, const allocator_type& al); basic_string(size_type n, value_type c); basic_string(size_type n, value_type c, const allocator_type& al); basic_string(); explicit basic_string(const allocator_type& al); template <class InIt> basic_string(InIt first, InIt last); template <class InIt> basic_string(InIt first, InIt last, const allocator_type& al);
All constructors store an
allocator object 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.
If InIt
is an integer type in a template constructor,
the operand sequence first, last
behaves the same as
(size_type)first, (value_type)last
.
In this implementation, if a translator does not support member template functions, the templates:
template <class InIt> basic_string(InIt first, InIt last); template <class InIt> basic_string(InIt first, InIt last, const allocator_type& al);
are replaced by:
basic_string(const_pointer first, const_pointer last); basic_string(const_pointer first, const_pointer last, const allocator_type& al);
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).
const value_type *c_str() const;
The member function returns a pointer to a non-modifiable
C string constructed by adding a
terminating null element
(value_type()
) to the controlled
sequence. Calling any non-const member function for
*this
can invalidate the pointer.
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()
.
void clear();
The member function calls
erase(
begin(),
end())
.
int compare(const basic_string& str) const; int compare(size_type p0, size_type n0, const basic_string& str); int compare(size_type p0, size_type n0, const basic_string& str, size_type pos, size_type n); int compare(const value_type *s) const; int compare(size_type p0, size_type n0, const value_type *s) const; int compare(size_type p0, size_type n0, const value_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 longertypedef T1 const_iterator;
The type describes an object that can serve as a constant
random-access iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T1
.
typedef typename allocator_type::const_pointer const_pointer;
The type is a synonym for allocator_type::const_pointer
.
typedef typename allocator_type::const_reference const_reference;
The type is a synonym for allocator_type::const_reference
.
typedef reverse_iterator<const_iterator> const_reverse_iterator;
The type describes an object that can serve as a constant reverse iterator for the controlled sequence.
size_type copy(value_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 value_type
beginning at s
. It returns the
number of elements actually copied.
const value_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).
typedef T3 difference_type;
The signed integer type describes an object that can represent the
difference between the addresses of any two elements in the controlled
sequence. It is described here as a
synonym for the implementation-defined type T3
.
bool empty() const;
The member function returns true for an empty controlled sequence.
const_iterator end() const; iterator end();
The member functions each return a random-access iterator that points just beyond the end of the sequence.
iterator erase(iterator first, iterator last); iterator erase(iterator it); basic_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
.
size_type find(value_type c, size_type pos = 0) const; size_type find(const value_type *s, size_type pos = 0) const; size_type find(const value_type *s, size_type pos, size_type n) const; size_type find(const basic_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
.
size_type find_first_not_of(value_type c, size_type pos = 0) const; size_type find_first_not_of(const value_type *s, size_type pos = 0) const; size_type find_first_not_of(const value_type *s, size_type pos, size_type n) const; size_type find_first_not_of(const basic_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
.
size_type find_first_of(value_type c, size_type pos = 0) const; size_type find_first_of(const value_type *s, size_type pos = 0) const; size_type find_first_of(const value_type *s, size_type pos, size_type n) const; size_type find_first_of(const basic_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
.
size_type find_last_not_of(value_type c, size_type pos = npos) const; size_type find_last_not_of(const value_type *s, size_type pos = npos) const; size_type find_last_not_of(const value_type *s, size_type pos, size_type n) const; size_type find_last_not_of(const basic_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
.
size_type find_last_of(value_type c, size_type pos = npos) const; size_type find_last_of(const value_type *s, size_type pos = npos) const; size_type find_last_of(const value_type *s, size_type pos, size_type n = npos) const; size_type find_last_of(const basic_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
.
allocator_type get_allocator() const;
The member function returns the stored allocator object.
basic_string& insert(size_type p0, const value_type *s); basic_string& insert(size_type p0, const value_type *s, size_type n); basic_string& insert(size_type p0, const basic_string& str); basic_string& insert(size_type p0, const basic_string& str, size_type pos, size_type n); basic_string& insert(size_type p0, size_type n, value_type c); iterator insert(iterator it, value_type c = value_type()); template<class InIt> void insert(iterator it, InIt first, InIt last); void insert(iterator it, size_type n, value_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
.
If InIt
is an integer type in the template member function,
the operand sequence first, last
behaves the same as
(size_type)first, (value_type)last
.
In this implementation, if a translator does not support member template functions, the template:
template<class InIt> void insert(iterator it, InIt first, InIt last);
is replaced by:
void insert(iterator it, const_pointer first, const_pointer last);
typedef T0 iterator;
The type describes an object that can serve as a random-access
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T0
.
size_type length() const;
The member function returns the length of the controlled sequence
(same as size()
).
size_type max_size() const;
The member function returns the length of the longest sequence that the object can control.
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.
basic_string& operator+=(value_type c); basic_string& operator+=(const value_type *s); basic_string& operator+=(const basic_string& rhs);
The operators each append the
operand sequence to the end of the
sequence controlled by *this
, then return *this
.
basic_string& operator=(value_type c); basic_string& operator=(const value_type *s); basic_string& operator=(const basic_string& rhs);
The operators each replace the sequence controlled by *this
with the
operand sequence,
then return *this
.
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.
typedef typename allocator_type::pointer pointer;
The type is a synonym for allocator_type::pointer
.
void push_back(value_type c);
The member function effectively calls
insert(
end(), c)
.
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.
typedef typename allocator_type::reference reference;
The type is a synonym for allocator_type::reference
.
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.
basic_string& replace(size_type p0, size_type n0, const value_type *s); basic_string& replace(size_type p0, size_type n0, const value_type *s, size_type n); basic_string& replace(size_type p0, size_type n0, const basic_string& str); basic_string& replace(size_type p0, size_type n0, const basic_string& str, size_type pos, size_type n); basic_string& replace(size_type p0, size_type n0, size_type n, value_type c); basic_string& replace(iterator first0, iterator last0, const value_type *s); basic_string& replace(iterator first0, iterator last0, const value_type *s, size_type n); basic_string& replace(iterator first0, iterator last0, const basic_string& str); basic_string& replace(iterator first0, iterator last0, size_type n, value_type c); template<class InIt> basic_string& replace(iterator first0, iterator last0, InIt first, InIt 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
.
If InIt
is an integer type in the template member function,
the operand sequence first, last
behaves the same as
(size_type)first, (value_type)last
.
In this implementation, if a translator does not support member template functions, the template:
template<class InIt> basic_string& replace(iterator first0, iterator last0, InIt first, InIt last);
is replaced by:
basic_string& replace(iterator first0, iterator last0, const_pointer first, const_pointer last);
void reserve(size_type n = 0);
The member function ensures that
capacity()
henceforth returns at least n
.
void resize(size_type n, value_type c = value_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())
.
typedef reverse_iterator<iterator> reverse_iterator;
The type describes an object that can serve as a reverse iterator for the controlled sequence.
size_type rfind(value_type c, size_type pos = npos) const; size_type rfind(const value_type *s, size_type pos = npos) const; size_type rfind(const value_type *s, size_type pos, size_type n = npos) const; size_type rfind(const basic_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
.
size_type size() const;
The member function returns the length of the controlled sequence.
typedef T2 size_type;
The unsigned integer type describes an object that can represent the
length of any controlled sequence. It is described here as a
synonym for the implementation-defined type T2
.
basic_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
.
void swap(basic_string& str);
The member function swaps the controlled sequences between
*this
and str
. If
get_allocator()
== str.get_allocator()
, it does so in constant time,
it throws no exceptions, and it invalidates no references, pointers,
or iterators that designate elements in the two controlled sequences.
Otherwise, it performs a number of element assignments and constructor calls
proportional to the number of elements in the two controlled sequences.
typedef T traits_type;
The type is a synonym for the template parameter T
.
typedef typename allocator_type::value_type value_type;
The type is a synonym for allocator_type::value_type
.
assign , char_type , compare , copy , eof , eq , eq_int_type , find , int_type , length , lt , move , not_eof , off_type , pos_type , state_type , to_char_type , to_int_type
template<class E> class char_traits { public: typedef E char_type; typedef T1 int_type; typedef T2 pos_type; typedef T3 off_type; typedef T4 state_type; static void assign(char_type& x, const char_type& y); static char_type *assign(char_type *x, size_t n, 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 template class describes various
character traits
for type E
.
The template class
basic_string
as well as several iostreams template classes, including
basic_ios
, use this information
to manipulate elements of type E
.
Such an element type must not require explicit construction or
destruction. It must supply a default constructor, a copy constructor,
and an assignment operator, with the expected semantics.
A bitwise copy must have the same effect as an assignment.
Not all parts of the Standard C++ Library rely completely upon the member
functions of char_traits<E>
to manipulate an element.
Specifically,
formatted input functions and
formatted output functions
make use of the following additional operations,
also with the expected semantics:
operator==(E)
and operator!=(E)
to compare elements(char)ch
to convert an element ch
to its corresponding single-byte character code,
or '\0'
if no such code exists(E)c
to convert a char
value c
to
its correponding character code of type E
None of the member functions of class char_traits
may
throw exceptions.
static void assign(char_type& x, const char_type& y); static char_type *assign(char_type *x, size_t n, 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)
.
typedef E char_type;
The type is a synonym for the template parameter E
.
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
)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.
static int_type eof();
The static member function returns a value that represents
end-of-file (such as EOF
or
WEOF
). If the value is also
representable as type E
,
it must correspond to no valid value of that type.
static bool eq(const char_type& x, const char_type& y);
The static member function returns true if x
compares
equal to y
.
static bool eq_int_type(const int_type& ch1, const int_type& ch2);
The static member function returns true if
ch1 == ch2
.
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.
typedef T1 int_type;
The type is (typically) an integer type T1
that
describes an object that can represent any element of the controlled
sequence as well as the value returned by
eof()
. It must be possible to type cast a value of type
E
to int_type
then back to E
without altering the original value.
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()
.
static bool lt(const char_type& x, const char_type& y);
The static member function returns true if x
compares
less than y
.
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.
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()
.
typedef T3 off_type;
The type is a signed integer type T3
that describes an
object that can store a byte offset involved in various stream
positioning operations. It is typically a synonym for
streamoff
, but in any case it
has essentially the same properties as that type.
typedef T2 pos_type;
The type is an opaque type T2
that describes an object
that can store all the information needed to restore an arbitrary
file-position indicator
within a stream. It is typically a synonym for
streampos
, but in any case it
has essentially the same properties as that type.
typedef T4 state_type;
The type is an opaque type T4
that describes an object
that can represent a
conversion state. It is
typically a synonym for
mbstate_t
, but in any
case it has essentially the same properties as that 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.
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
.
template<> class char_traits<char>;
The class is an explicit specialization of template class
char_traits
for elements of type char, (so that it
can take advantage of library functions that manipulate objects of this
type).
template<> class char_traits<wchar_t>;
The class is an explicit specialization of template class
char_traits
for elements of type wchar_t
(so
that it can take advantage of library functions that manipulate objects
of this type).
template<class E, class T, class A> basic_istream<E, T>& getline( basic_istream<E, T>& is, basic_string<E, T, A>& str); template<class E, class T, class A> basic_istream<E, T>& getline( basic_istream<E, T>& is, basic_string<E, T, A>& str, E 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
.
template<class E, class T, class A> basic_string<E, T, A> operator+( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> basic_string<E, T, A> operator+( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> basic_string<E, T, A> operator+( const basic_string<E, T, A>& lhs, E rhs); template<class E, class T, class A> basic_string<E, T, A> operator+( const E *lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> basic_string<E, T, A> operator+( E lhs, const basic_string<E, T, A>& rhs);
The functions each overload operator+
to
concatenate two objects of template class
basic_string
.
All effectively return basic_string<E, T,
A>(lhs).append(rhs)
.
template<class E, class T, class A> bool operator!=( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator!=( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> bool operator!=( const E *lhs, const basic_string<E, T, A>& rhs);
The template functions each overload operator!=
to compare
two objects of template class
basic_string
. All effectively
return basic_string<E, T,
A>(lhs).compare(rhs) != 0
.
template<class E, class T, class A> bool operator==( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator==( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> bool operator==( const E *lhs, const basic_string<E, T, A>& rhs);
The template functions each overload operator==
to compare
two objects of template class
basic_string
. All effectively
return basic_string<E, T,
A>(lhs).compare(rhs) == 0
.
template<class E, class T, class A> bool operator<( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator<( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> bool operator<( const E *lhs, const basic_string<E, T, A>& rhs);
The template functions each overload operator<
to
compare two objects of template class
basic_string
. All effectively
return basic_string<E, T,
A>(lhs).compare(rhs)
< 0
.
template<class E, class T, class A> basic_ostream<E, T>& operator<<( basic_ostream<E, T>& os, const basic_string<E, T, A>& str);
The template function overloads operator<<
to
insert an object str
of template class
basic_string
into the stream
os
The function effectively returns
os.write(
str.c_str(),
str.size())
.
template<class E, class T, class A> bool operator<=( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator<=( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> bool operator<=( const E *lhs, const basic_string<E, T, A>& rhs);
The template functions each overload operator<=
to
compare two objects of template class
basic_string
. All effectively
return basic_string<E, T,
A>(lhs).compare(rhs)
<= 0
.
template<class E, class T, class A> bool operator>( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator>( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> bool operator>( const E *lhs, const basic_string<E, T, A>& rhs);
The template functions each overload operator>
to
compare two objects of template class
basic_string
. All effectively
return basic_string<E, T,
A>(lhs).compare(rhs)
> 0
.
template<class E, class T, class A> bool operator>=( const basic_string<E, T, A>& lhs, const basic_string<E, T, A>& rhs); template<class E, class T, class A> bool operator>=( const basic_string<E, T, A>& lhs, const E *rhs); template<class E, class T, class A> bool operator>=( const E *lhs, const basic_string<E, T, A>& rhs);
The template functions each overload operator>=
to
compare two objects of template class
basic_string
. All effectively
return basic_string<E, T,
A>(lhs).compare(rhs)
>= 0
.
template<class E, class T, class A> basic_istream<E, T>& operator>>( basic_istream<E, T>& is, const basic_string<E, T, A>& 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
use_facet<
ctype<E> >(
getloc()).
is(
ctype<E>::space, 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
.
typedef basic_string<char> string;
The type describes a specialization of template class
basic_string
specialized for
elements of type char.
template<class T, class A> void swap( basic_string<E, T, A>& lhs, basic_string<E, T, A>& rhs);
The template function executes
lhs.swap(rhs)
.
typedef basic_string<wchar_t> wstring;
The type describes a specialization of template class
basic_string
for
elements of type wchar_t
.
Copyright © 1992-1996 by P.J. Plauger. Portions derived from work copyright © 1994 by Hewlett-Packard Company. All rights reserved.