cxxlstd$help.HLP
Overview
Name
cxxstdlib_intro - Introduction to the DIGITAL C++ ANSI Standard
Library
This page describes the DIGITAL C++ ANSI Standard Library.
For an overview of the pre-ANSI C++ Class Library, type
help cxxl
DESCRIPTION
The DIGITAL C++ ANSI Standard Library is an implementation of the
C++ Standard Library. It is comprised of a suite of header files
and the run time code needed to implement the following clauses in
the C++ Standard:
____________________________________________
Clause Description
____________________________________________
18 Run time support (new(),exceptions)
21 String Library
22 Localization (locale) Library
23 Container Library
24 Iterator Library
25 Algorithms Library
26 Numerics Library
27 Input/Output (iostream) Library
See Also
iostream_intro
complex
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
complex - C++ complex number library
This page describes ANSI complex class. If you would like information
on the pre-ANSI complex package,use the command:
help cxxl
SPECIALIZATIONS
complex <float>
complex <double>
complex <long double>
SYNOPSIS
#include <complex>
template <class T>
class complex ;
class complex<float>;
class complex<double>;
class complex<long double>;
DESCRIPTION
complex<T> is a class that supports complex numbers. A complex number
has a real part and an imaginary part. The complex class supports
equality,comparison and basic arithmetic operations. In addition,
mathematical functions such as exponents, logarithms, powers, and
square roots are also available.
INTERFACE
template <class T>
class complex {
public:
typedef T value_type;
complex (T = 0 , T = 0);
template <class X> complex
(const complex<X>&);
T real () const;
T imag () const;
complex<T>& operator= (const T&);
complex<T>& operator+=(const T&);
complex<T>& operator-=(const T&);
complex<T>& operator*=(const T&);
complex<T>& operator/=(const T&);
template <class X>
complex<T>& operator= (const complex<X>&);
template <class X>
complex<T>& operator+= (const complex<X>&);
template <class X>
complex<T>& operator-= (const complex<X>&);
template <class X>
complex<T>& operator*= (const complex<X>&);
template <class X>
complex<T>& operator/= (const complex<X>&);
};
// Non-member Operators
template<class T>
complex<T> operator+ (const complex<T>&, const complex<T>&);
template<class T>
complex<T> operator+ (const complex<T>&, T);
template<class T>
complex<T> operator+ (T, const complex<T>&);
template<class T>
complex<T> operator- (const complex<T>&, const complex<T>&);
template<class T>
complex<T> operator- (const complex<T>&, T);
template<classT>
complex<T> operator- (T, const complex<T>&);
template<class T>
complex<T> operator* (const complex<T>&, const complex<T>&);
template<class T>
complex<T> operator* (const complex<T>&, T);
template<class T>
complex<T> operator* (T, const complex<T>&);
template<class T>
complex<T> operator/ (const complex<T>&, const complex<T>&);
template<class T>
complex<T> operator/ (const complex<T>&, T);
template<class T>
complex<T> operator/ (T, const complex<T>&);
template<class T>
complex<T> operator+ (const complex<T>&);
template<class T>
complex<T> operator- (const complex<T>&);
template<class T>
bool operator== (const complex<T>&, const complex<T>&);
template<class T>
bool operator== (const complex<T>&, T);
template<class T>
bool operator== (T, const complex<T>&);
template<class T>
bool operator!= (const complex<T>&, const complex<T>&);
template<class T>
bool operator!= (const complex<T>&, T);
template<class T>
bool operator!= (T, const complex<T>&);
template <class X>
istream& operator>> (istream&, complex<X>&);
template <class X>
ostream& operator<< (ostream&, const complex<X>&);
// Values
template<class T> T real (const complex<T>&);
template<class T> T imag (const complex<T>&);
template<class T> T abs (const complex<T>&);
template<class T> T arg (const complex<T>&);
template<class T> T norm (const complex<T>&);
template<class T> complex<T> conj (const complex<T>&);
template<class T> complex<T> polar (T, T);
// Transcendentals
template<class T> complex<T> cos (const complex<T>&);
template<class T> complex<T> cosh (const complex<T>&);
template<class T> complex<T> exp (const complex<T>&);
template<class T> complex<T> log (const complex<T>&);
template<class T> complex<T> log10 (const complex<T>&);
template<class T> complex<T> pow (const complex<T>&, int);
template<class T> complex<T> pow (const complex<T>&, T);
template<class T> complex<T> pow (const complex<T>&,
const complex<T>&);
template<class T> complex<T> pow (T, const complex<T>&);
template<class T> complex<T> sin (const complex<T>&);
template<class T> complex<T> sinh (const complex<T>&);
template<class T> complex<T> sqrt (const complex<T>&);
template<class T> complex<T> tan (const complex<T>&);
template<class T> complex<T> tanh (const complex<T>&);
CONSTRUCTORS
complex
(const T& re_arg = 0, const T& im_arg = 0);
Constructs an object of class complex, initializing re_arg to
the real part and im_arg to the imaginary part.
ASSIGNMENT OPERATORS
template <class X> complex (const complex<X>&);
Copy constructor. Constructs a complex number from another
complex number.
complex<T>& operator=(const T& v);
Assigns v to the real part of itself, setting the imaginary part
to 0.
complex<T>& operator+=(const T& v);
Adds v to the real part of itself, then returns the result.
complex<T>& operator-=(const T& v);
Subtracts v from the real part of itself, then returns the result.
complex<T>& operator*=(const T& v);
Multiplies v by the real part of itself, then returns the result.
complex<T>& operator/=(const T& v);
Divides v by the real part of itself, then returns the result.
template <class X>
complex<T>
operator=(const complex<X>& c);
Assigns c to itself.
template <class X>
complex<T>
operator+=(const complex<X>& c);
Adds c to itself, then returns the result.
template <class X>
complex<T>
operator-=(const complex<X>& c);
Subtracts c from itself, then returns the result.
template <class X>
complex<T>
operator*=(const complex<X>& c);
Multiplies itself by c then returns the result.
template <class X>
complex<T>
operator/=(const complex<X>& c);
Divides itself by c, then returns the result.
MEMBER FUNCTIONS
T
imag() const;
Returns the imaginary part of the complex number.
T
real() const;
Returns the real part of the complex number.
NON-MEMBER OPERATORS
template<class T> complex<T>
operator+(const complex<T>& lhs,const complex<T>& rhs);
template<class T> complex<T>
operator+(const complex<T>& lhs, T rhs);
template<class T> complex<T>
operator+(T lhs, const complex<T>& rhs);
Returns the sum of lhs and rhs.
template<class T> complex<T>
operator-(const complex<T>& lhs,const complex<T>& rhs);
template<class T> complex<T>
operator-(const complex<T>& lhs, T rhs);
operator-(T lhs, const complex<T>& rhs);
Returns the difference of lhs and rhs.
template<class T> complex<T>
operator*(const complex<T>& lhs,const complex<T>& rhs);
template<class T> complex<T>
operator*(const complex<T>& lhs, T rhs);
template<class T> complex<T>
operator* (T lhs, const complex<T>& rhs);
Returns the product of lhs and rhs.
template<class T> complex<T>
operator/(const complex<T>& lhs,const complex<T>& rhs);
template<class T> complex<T>
operator/(const complex<T>& lhs, T rhs);
template<class T> complex<T>
operator/(T lhs, const complex<T>& rhs);
Returns the quotient of lhs divided by rhs.
template<class T> complex<T>
operator+(const complex<T>& rhs);
Returns rhs.
template<class T> complex<T>
operator-(const complex<T>& lhs);
Returns complex<T>(-lhs.real(), -lhs.imag()).
template<class T> bool
operator==(const complex<T>& x, const complex<T>& y);
Returns true if the real and imaginary parts of x and y are equal.
template<class T> bool
operator==(const complex<T>& x, T y);
Returns true if y is equal to the real part of x and the imaginary
part of x is equal to 0.
template<class T> bool
operator==(T x, const complex<T>& y);
Returns true if x is equal to the real part of y and the imaginary
part of y is equal to 0.
template<class T> bool
operator!=(const complex<T>& x, const complex<T>& y);
Returns true if either the real or the imaginary part of x and y
are not equal.
template<class T> bool
operator!=(const complex<T>& x, T y);
Returns true if y is not equal to the real part of x or the
imaginary part of x is not equal to 0.
template<class T> bool
operator!=(T x, const complex<T>& y);
Returns true if x is not equal to the real part of y or the
imaginary part of y is not equal to 0.
template <class X> istream&
operator>>(istream& is, complex<X>& x);
Reads a complex number x into the input stream is. x may be of
the form u, (u), or (u,v) where u is the real part and v is
the imaginary part. If bad input is encountered, the
ios::badbit flag is set.
template <class X> ostream&
operator<<(ostream& os, const complex<X>& x);
Returns os << "(" << x.real() << "," << x.imag() << ")".
NON-MEMBER FUNCTIONS
template<class T> T
abs(const complex<T>& c);
Returns the absolute value or magnitude of c (the square root
of the norm).
template<class T> complex<T>
conj(const complex<T>& c);
Returns the conjugate of c.
template<class T> complex<T>
cos(const complex<T>& c);
Returns the cosine of c.
template<class T> complex<T>
cosh(const complex<T>& c);
Returns the hyperbolic cosine of c.
template<class T> complex<T>
exp(const complex<T>& x);
Returns e raised to the x power.
template<class T> T
imag(const complex<T>& c) const;
Returns the imaginary part of c.
template<class T> complex<T>
log(const complex<T>& x);
Returns the natural logarithm of x. This function returns the
complex value whose phase angle is greater than -pi and less
than pi.
template<class T> complex<T>
log10(const complex<T>& x);
Returns the logarithm base 10 of x.
template<class T> T
norm(const complex<T>& c);
Returns the squared magnitude of c. (The sum of the squares of
the real and imaginary parts.)
template<class T> complex<T>
polar(const T& m, const T& a);
Returns the complex value of a complex number whose magnitude
is m and phase angle is a, measured in radians.
template<class T> complex<T>
pow(const complex<T>& x, int y);
template<class T> complex<T>
pow(const complex<T>& x, T y);
template<class T> complex<T>
pow(const complex<T>& x, const complex<T>& y);
template<class T> complex<T>
pow(T x, const complex<T>& y);
Returns x raised to the y power.
template<class T> T
real(const complex<T>& c);
Returns the real part of c.
template<class T> complex<T>
sin(const complex<T>& c);
Returns the sine of c.
template<class T> complex<T>
sinh(const complex<T>& c);
Returns the hyperbolic sine of c.
template<class T> complex<T>
sqrt(const complex<T>& x);
Returns the square root of x. This function returns the complex
value whose phase angle is greater than -pi/2 and less than or
equal to
template<class T> complex<T>
tan(const complex<T>& x);
Returns the tangent of x.
template<class T> complex<T>
tanh(const complex<T>& x);
Returns the hyperbolic tangent of x.
EXAMPLE
//
// complex.cpp
//
#include <complex>
#include <iostream.h>
int main()
{
complex<double> a(1.2, 3.4);
complex<double> b(-9.8, -7.6);
a += b;
a /= sin(b) * cos(a);
b *= log(a) + pow(b, a);
cout << "a = " << a << ", b = " << b << endl;
return 0;
}
Output :
a = (1.42804e-06,-0.0002873), b = (58.2199,69.7354)
WARNINGS
On compilers that don't support member function templates, the
arithmetic operators will not work on any arbitrary type. (They
will work only on float, double and long doubles.) You also
will only be able to perform binary arithmetic on types that are the
same.
Compilers that don't support non-converting constructors will permit
unsafe downcasts (i.e., long double to double, double to float,
long double to float).
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
limits
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
limits
Refer to the numeric_limits section of this reference guide.
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Additional Information on:
numeric_limits
Containers
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
Containers - A standard template library (STL) collection.
DESCRIPTION
Within the standard template library, collection classes are often
described as containers. A container stores a collection of other
objects and provides certain basic functionality that supports the
use of generic algorithms. Containers come in two basic flavors:
sequences, and associative containers. They are further
distinguished by the type of iterator they support.
A sequence supports a linear arrangement of single elements. vector,
list,deque, bitset, and string fall into this category. Associative
containers map values onto keys, which provides efficient retrieval
of the values based on the keys. The STL provides the map,
multimap, set and multiset associative containers. map and multimap
store the value and the key separately and allow for fast retrieval
of the value, based upon fast retrieval of the key. set and
multiset store only keys allowing fast retrieval of the key
itself.
CONTAINER REQUIREMENTS
Containers within the STL must meet the following requirements.
Sequences and associative containers must also meet their own
separate sets of requirements. The requirements for containers are:
+ A container allocates all storage for the objects it holds.
+ A container X of objects of type T provides the following types:
X::value_type a T
X::reference lvalue of T
X::const_reference const lvalue of T
X::iterator an iterator type pointing to T. X::iterator
cannot be an output iterator.
X::const_iterator an iterator type pointing to const T
x::iterator cannot be an output iterator.
X::difference_type a signed integral type (must be the same as
the distance type for X::iterator and
X::const_iterator
X::size_type an unsigned integral type representing any non-
negative value of difference_type
X::allocatr_type type of allocator used to obtain storage for
elements stored in the container
+ A container provides a default constructor, a copy
constructor, an assignment operator, and a full complement of
comparison operators (==, !=, <, >, <=, >=).
+ A container provides the following member functions:
begin() Returns an iterator or a const_iterator pointing
to the first element in the collection.
end() Returns an iterator or a const_iterator pointing just
beyond the last element in the collection.
swap(container) Swaps elements between this container and
the swap's argument.
clear() Deletes all the elements in the container.
size() Returns the number of elements in the collection
as a size_type.
max_size() Returns the largest possible number of elements
for this type of container as a size_type.
empty() Returns true if the container is empty, false
otherwise.
get_allocator() Returns the allocator used by this container
REVERSIBLE CONTAINERS
A container may be reversible. Essentially, a reversible container
provides a reverse iterator that allows traversal of the collection
in a direction opposite that of the default iterator. A reversible
container must meet the following requirements in addition to those
listed above:
+ A reversible container provides the following types:
X::reverse_iterator An iterator type pointing to T.
X::const_reverse_iterator An iterator type pointing to
const T
+ A reversible container provides the following member functions:
rbegin() Returns a reverse_iterator or a const_reverse_iterator
pointing past the end of the collection
rend() Returns a reverse_iterator or a const_reverse_iterator
pointing to the first element in the collection.
SEQUENCES
In addition to the requirements for containers, the following
requirements hold for sequences:
+ iterator and const_iterator must be forward iterators,
bidirectional iterators or random access iterators.
+ A sequence provides the following constructors:
X(n, t) Constructs a container with n copies of t.
X(i, j) Constructs a container with elements from the
range [i,j).
+ A sequence provides the following member functions:
insert(p,t) Inserts the element t in front of the position
identified by the iterator p.
insert(p,n,t) Inserts n copies of t in front of the position
identified by the iterator p.
insert(p,i,j) Inserts elements from the range [i,j) in front
of the position identified by the iterator p.
erase(q) Erases the element pointed to by the iterator q.
erase(q1,q2) Erases the elements in the range [q1,q2).
+ A sequence may also provide the following member functions
if they can be implemented with constant time complexity.
front() Returns the element pointed to by begin()
back() Returns the element pointed to by end()
push_front(x) Inserts the element x at begin()
push_back(x) Inserts the element x at end()
pop_front() Erases the element at begin()
pop_back() Erases the element at end() -1
operator[](n) Returns the element at a.begin() + n
ASSOCIATIVE CONTAINERS
In addition to the requirements for a container, the following
requirements hold for associative containers:
+ For an associative container iterator and const_iterator
must be bidirectional iterators. Associative containers
are inherently sorted. Their iterators proceed through
the container in the nondescending order of keys (where
non-descending order is defined by the comparison object
that was used to construct the container).
+ An associative container provides the following types:
X::key_type the type of the Key
X::key_compare the type of the comparison to use to put
the keys in order
X::value_compare the type of the comparison used on values
+ The default constructor and copy constructor for
associative containers use the template parameter
comparison class.
+ An associative container provides the following
additional constructors:
X(c) Construct an empty container using c as the
comparison object
X(i,j,c) Constructs a container with elements from the
range [i,j) and the comparison object c.
X(i, j) Constructs a container with elements from the
range [i,j) using the template parameter comparison
object.
+ An associative container provides the following member
functions:
key_comp() Returns the comparison object used in constructing
the associative container.
value_comp() Returns the value comparison object used in
constructing the associative container.
insert(t) Inserts t if and only if there is no element in
the container with key equal to the key of t.
Returns a pair<iterator,bool>. The bool component
of the returned pair indicates the success or
failure of the operation and the iterator
component points to the element with key equal
to key of t.
insert(p,t) If the container does not support redundant key
values then this function only inserts t if there
is no key present that is equal to the key of t.
If the container does support redundant keys then
this function always inserts the element t. The iterator
p serves as a hint of where to start searching, allowing
for some optimization of the insertion. It does not
restrict the algorithm from inserting ahead of that
location if necessary.
insert(i,j) Inserts elements from the range [i,j).
erase(k) Erases all elements with key equal to k. Returns
number of erased elements.
erase(q) Erases the element pointed to by q.
erase(q1,q2) Erases the elements in the range [q1,q2).
find(k) Returns an iterator pointing to an element with key
equal to k or end() if such an element is not found.
count(k) Returns the number of elements with key equal to k.
lower_bound(k) Returns an iterator pointing to the first
element with a key greater than or equal to k.
upper_bound(k) Returns an iterator pointing to the first
element with a key less than or equal to k.
equal_range(k) Returns a pair of iterators such that the
first element of the pair is equivalent to
lower_bound(k) and the second element equivalent
to upper_bound(k).
SEE ALSO
bitset, deque, list, map, multimap, multiset, priority_queue, queue,
set, stack, vector
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Additional Information on:
Associative Containers
Bitset
deque
list
map
multimap
multiset
priority_queue
queue
set
Sequences
stack
vector
Algorithms
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
Algorithms - Generic algorithms for performing various operations
on containers and sequences.
SYNOPSIS
#include <algorithm>
The synopsis of each algorithm appears in its entry in the reference
guide.
DESCRIPTION
The Standard C++ Library provides a very flexible framework for
applying generic algorithms to containers. The library also
provides a rich set of these algorithms for searching, sorting,
merging, transforming, scanning, and much more.
Each algorithm can be applied to a variety of containers, including
those defined by a user of the library. The following design
features make algorithms generic:
+ Generic algorithms access the collection through iterators
+ Algorithms are templatized on iterator types
+ Each algorithm is designed to require the least number of
services from the iterators it uses
In addition to requiring certain iterator capabilities, algorithms
may require a container to be in a specific state. For example,
some algorithms can only work on previously sorted containers.
Because most algorithms rely on iterators to gain access to data,
they can be grouped according to the type of iterator they require,
as is done in the Algorithms by Iterator section below. They can
also be grouped according to the type of operation they perform.
ALGORITHMS BY MUTATING/NON-MUTATING FUNCTION
The broadest categorization groups algorithms into two main types:
mutating and non-mutating. Algorithms that alter (or mutate) the
contents of a container fall into the mutating group. All
others are considered non-mutating. For example, both fill and
sort are mutating algorithms, while find and for_each are
non-mutating.
Non-mutating operations
accumulate find_end max element
adjacent_find find_first_of min
binary_search find_if min_element
count_min for_each mismatch
count_if includes nth_element
equal lexicographical_compare search
equal_range lower_bound search_n
find max
Mutating operations
copy remove_if
copy_backward replace
fill replace_copy
fill_n replace_copy_if
generate replace_if
generate_n reverse
inplace_merge reverse_copy
iter_swap rotate
make_heap rotate_copy
merge set_difference
nth_element set_symmetric_difference
next_permutation set_intersection
partial_sort set_union
partial_sort_copy sort
partition sort_heap
prev_permutation stable_partition
push_heap stable_sort
pop_heap swap
random_shuffle swap_ranges
remove transform
remove_copy unique
remove_copy_if unique_copy
Note that the library provides both in place and copy versions of
many algorithms, such as replace and replace_copy. The library
also provides versions of algorithms that allow the use of default
comparators and comparators supplied by the user. Often these
functions are overloaded, but in some cases (where
overloading proved impractical or impossible) the names differ
(e.g., replace, which will use equality to determine replacement,
and replace_if, which accesses a user provided compare
function).
ALGORITHMS BY OPERATION
We can further distinguish algorithms by the kind of operations they
perform. The following lists all algorithms by loosely
grouping them into similar operations.
Initializing operations
fill generate
fill_n generate_n
Search operations
adjacent_find find_end search_n
count find_if
count_if find_first_of
find search
Binary search operations (Elements must be sorted)
binary_search lower_bound
equal_range upper_bound
Compare operations
equal mismatch
lexicographical_compare
Copy operations
copy copy_backward
Transforming operations
partition reverse
random_shuffle reverse_copy
replace rotate
replace_copy rotate_copy
replace_copy_if stable_partition
replace_if transform
Swap operations
swap swap_ranges
Scanning operations
accumulate for_each
Remove operations
remove remove_if
remove_copy unique
remove_copy_if unique_copy
Sorting operations
nth_element sort
partial_sort stable_sort
partial_sort_copy
Merge operations (Elements must be sorted)
inplace_merge merge
Set operations (Elements must be sorted)
includes set_symmetric_difference
set_difference set_union
set_intersection
Heap operations
make_heap push_heap
pop_heap sort_heap
Minimum and maximum
max min
max_element min_element
Permutation generators
next_permutation prev_permutation
ALGORITHMS BY CATEGORY
Each algorithm requires certain kinds of iterators (for a
description of the iterators and their capabilities see the
Iterator entry in this manual). The following set of lists
groups the algorithms according to the types of iterators they
require.
Algorithms that use no iterators:
max min swap
Algorithms that require only input iterators:
accumulate find mismatch
count find_if
count_if includes
equal inner_product
for_each lexicographical_compare
Algorithms that require only output iterators:
fill_n generate_n
Algorithms that read from input iterators and write to output
iterators:
adjacent_difference replace_copy transform
copy replace_copy_if unique_copy
merge set_difference
partial_sum set_intersedtion
remove_copy set_symmetric_difference
remove_copy_if set_union
Algorithms that require forward iterators:
adjacent_find iter_swap replace_if
binary_search lower_bound rotate
equal_range max_element search
fill min_element search_n
find_end remove swap_ranges
find_first_of remove_if unique
generate replace upper_bound
Algorithms that read from forward iterators and write to output
iterators:
rotate_copy
Algorithms that require bidirectional iterators
copy_backward partition
inplace_merge prev_permutation
next_permutation reverse
stable_permutation
Algorithms that read from bidirectional iterators and write to output
iterators:
reverse_copy
Algorithms that require random access iterators:
make_heap pop_heap sort
nth_element push_heap sort_heap
partial_sort random_shuffle stable_sort
Algorithms that read from input iterators and write to random access
iterators:
partial_sort_copy
COMPLEXITY
The complexity for each of these algorithms is given in the manual
page for that algorithm.
SEE ALSO
Manual pages for each of the algorithms named in the lists above.
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Additional Information on:
accumulate
adjacent_difference
adjacent_find
advance
binary_search
copy
copy_backward
count
count_if
compare
distance
distance_type
equal
equal_range
equal_to
fill
fill_n
find
find_end
find_first_of
find_if
for_each
generate
generate_n
greater
greater_equal
Heap_Operations
includes
inner_product
inplace_merge
iter_swap
lexicographical_compare
lower_bound
make_heap
max
max_element
merge
min
min_element
mismatch
next_permutation
nth_element
partial_sort
partial_sort_copy
partial_sum
partition
permutation
pop_heap
prev_permutation
push_heap
random_shuffle
remove
remove_copy
remove_copy_if
remove_if
replace
replace_copy
replace_copy_if
replace_if
reverse
reverse_copy
rotate
rotate_copy
search
search_n
set_difference
set_intersection
set_symmetric_difference
set_union
sort
sort_heap
stable_partition
stable_sort
swap
swap_ranges
transform
uninitialized_copy
uninitialized_fill
uninitialized_fill_n
unique
unique_copy
upper_bound
Iterators
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
Iterators - Pointer generalizations for traversal and modification
of collections.
DESCRIPTION
Input Iterator Output Iterator
read only write only
forward moving forward moving
| |
| |
--------------------------------
|
|
Forward Iterator
read and write
forward moving
|
|
Bidirectional Iterator
read and write
moves forward or backward
|
|
Random Access Iterator
read and write
random access
Iterators are a generalization of pointers that allow a C++ program
to uniformly interact with different data structures. The
illustration below displays the five iterator categories
defined by the standard library, and shows their
hierarchical relationship. Because standard library iterator
categories are hierarchical, each category includes all the
requirements of the categories above it.
Because iterators are used to traverse and access containers, the
nature of the container determines what type of iterator it
generates. And, because algorithms require specific iterator
types as arguments, it is iterators that, for the most
part, determine which standard library algorithms can be used with
which standard library containers.
To conform to the C++ standard, all container and sequence classes
must provide their own iterators. An instance of a container or
sequence's iterator may be declared using either of the
following:
class name ::iterator
class name ::const_iterator
Containers and sequences must also provide const iterators to the
beginning and end of their collections. These may be accessed
using the class members, begin() and end().
The semantics of iterators are a generalization of the semantics of
C++ pointers. Every template function that takes iterators will
work using C++ pointers for processing typed contiguous memory
sequences.
Iterators may be constant or mutable depending upon whether the
result of the operator* behaves as a reference or as a
reference to a constant. Constant iterators cannot satisfy the
requirements of an output_iterator.
Every iterator type guarantees that there is an iterator value that
points past the last element of a corresponding container. This
value is called the past-the-end value. No guarantee is made that
this value is dereferencable.
Every function provided by an iterator is required to be realized in
amortized constant time.
KEY TO ITERATOR REQUIREMENTS
The following key pertains to the iterator requirements listed
below:
a and b values of type X
n value of distance type
u, Distance, tmp and m identifiers
r value of type X&
t value of type T
REQUIREMENTS FOR INPUT ITERATORS
The following expressions must be valid for input iterators:
X u(a) copy constructor, u == a
X u = a assignment, u == a
a == b, a != b return value convertible to bool
*a a == b implies *a == *b
a->m equivalent to (*a).m
++r returns X&
r++ return value convertible to const X&
*r++ returns type T
For input iterators, a == b does not imply that ++a == ++b.
Algorithms using input iterators should be single pass algorithms.
That is they should not pass through the same iterator twice.
The value of type T does not have to be an lvalue.
REQUIREMENTS FOR OUTPUT ITERATORS
The following expressions must be valid for output iterators:
X(a) copy constructor, a == X(a)
X u(a) copy constructor, u == a
X u = a assignment, u == a
*a = t result is not used
++r returns X&
r++ return value convertible to const X&
*r++ = t result is not used
The only valid use for the operator* is on the left hand side of the
assignment statement.
Algorithms using output iterators should be single pass algorithms.
That is they should not pass through the same iterator twice.
REQUIREMENTS FOR FORWARD ITERATORS
The following expressions must be valid for forward iterators:
X u u might have a singular value
X() X() might be singular
X(a) copy constructor, a == X(a)
X u(a) copy constructor, u == a
X u = a assignment, u == a
a == b, a != b return value convertible to bool
*a return value convertible to T&
a->m equivalent to (*a).m
++r returns X&
r++ return value convertible to const X&
*r++ returns T&
Forward iterators have the condition that a == b implies *a== *b.
There are no restrictions on the number of passes an algorithm may
make through the structure.
REQUIREMENTS FOR BIDIRECTIONAL ITERATORS
A bidirectional iterator must meet all the requirements for forward
iterators. In addition, the following expressions must be valid:
--r returns X&
r-- return value convertible to const X&
*r-- returns T&
REQUIREMENTS FOR RANDOM ACCESS ITERATORS
A random access iterator must meet all the requirements for
bidirectional iterators. In addition, the following expressions
must be valid:
r += n Semantics of --r or ++r n times depending on the sign of n
a + n, n + a returns type X
r -= n returns X&, behaves as r += -n
a - n returns type X
b - a returns Distance
a[n] *(a+n), return value convertible to T
a < b total ordering relation
a > b total ordering relation opposite to <
a <= b !(a > b)
a >= b !(a < b)
All relational operators return a value convertible to bool.
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Additional Information on:
iterator
iterator_category
iterator_traits
back_inserter
back_insert_iterator
Bidirectional_Iterators
Forward_Iterators
front_inserter
Input_Iterators
inserter
insert_iterator
Insert_Iterators
istream_iterator
istreambuf_iterator
ostream_iterator
ostreambuf_iterator
Output_Iterators
Random_Access_Iterators
raw_storage_iterator
reverse_bidirectional_iterator
reverse_iterator
Stream_Iterators
value_type
Function_Objects
Additional Information on:
Function_Objects
divides
less
less_equal
logical_and
logical_not
logical_or
minus
modulus
multiplies
negate
Negators
not1
not2
not_equal_to
plus
Predicates
times
unary_function
unary_negate
binary_function
binary_negate
Adaptors
Additional Information on:
bind1st
bind2nd
binder1st
binder2nd
mem_fun
mem_fun1
mem_fun_ref
mem_fun_ref1
Operators
Additional Information on:
Operators
pair
pointer_to_binary_function
pointer_to_unary_function
ptr_fun
allocator
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
allocator - The default allocator object for storage management in
Standard Library containers.
SYNOPSIS
#include <memory>
template <class T>
class allocator;
DESCRIPTION
Containers in the Standard Library allow you control of storage
management through the use of allocator objects. Each
container has an allocator template parameter specifying
the type of allocator to be used. Every constructor, except the
copy constructor, provides an allocator parameter, allowing you to
pass in a specific allocator. A container uses that
allocator for all storage management.
The library provides a default allocator, called allocator. This
allocator uses the global new and delete operators. By
default, all containers use this allocator. You can also
design your own allocator, but if you do so it must provide an
appropriate interface. The standard interface is specified below.
STANDARD INTERFACE
template <class T>
class allocator {
typedef size_t size_type;
typedef ptrdiff_t difference_type;
typedef T* pointer;
typedef const T* const_pointer;
typedef T& reference;
typedef const T& const_reference;
typedef T value_type;
template <class U> struct rebind;
allocator () throw();
template <class U> allocator(const allocator<U>&) throw();
template <class U>
allocator& operator=(const allocator<U>&) throw();
~allocator () throw();
pointer address (reference) const;
const_pointer address (const_reference) const;
pointer allocate (size_type,
typename allocator<void> const_pointer = 0);
void deallocate(pointer);
size_type max_size () const;
void construct (pointer, const T&);
void destroy (pointer);
};
// specialize for void:
template <> class allocator<void> {
public:
typedef size_t size_type;
typedef ptrdiff_t difference_type;
typedef void* pointer;
typedef const void* const_pointer;
// reference-to-void members are impossible.
typedef void value_type;
template <class U>
struct rebind { typedef allocator<U> other; };
allocator() throw();
template <class U>
allocator(const allocator<U>&) throw();
template <class U>
allocator operator=(const allocator<U>&) throw();
~allocator() throw();
pointer allocate(size_type, const void* hint);
void deallocate(pointer p);
size_type max_size() const throw();
};
// globals
template <class T>
void* operator new(size_t N, allocator<T>& a);
template <class T, class U>
bool operator==(const allocator<T>&,
const allocator<U>&) throw();
template <class T, class U>
bool operator!=(const allocator<T>&,
const allocator<U>&) throw();
TYPES
size_type
Type used to hold the size of an allocated block of storage.
difference_type
Type used to hold values representing distances between storage
addresses.
pointer
Type of pointer returned by allocator.
const_pointer
Const version of pointer.
reference
Type of reference to allocated objects.
const_reference
Const version of reference.
value_type
Type of allocated object.
template <class U> struct rebind;
Provides a way to convert an allocator templated on one type to
an allocator templated on another type. This struct contains a
single type member: typedef allocator<U> other.
OPERATIONS
allocator()
Default constructor.
template <class U>
allocator(const allocator<U>&)
Copy constructor.
template <class U>
allocator& operator=(const allocator<U>&) throw()>&)
Assignment operator.
~allocator()
Destructor.
pointer address(reference x) const;
Returns the address of the reference x as a pointer.
const_pointer address(const_reference x) const;
Returns the address of the reference x as a const_pointer.
pointer allocate(size_type n,
typename allocator<void>::const_pointer p = 0)
Allocates storage. Returns a pointer to the first element in a
block of storage n*sizeof(T) bytes in size. The block will
be aligned appropriately for objects of type T. Throws the
exception bad_alloc if the storage is unavailable. This function
uses operator new(size_t). The second parameter p can be used
by an allocator to localize memory allocation, but the
default allocator does not use it.
void deallocate(pointer p)
Deallocates the storage indicated by p. The storage must have
been obtained by a call to allocate.
size_type max_size () const;
Returns the largest size for which a call to allocate might
succeed.
void construct (pointer p, const T& val);
Constructs an object of type T2 with the initial value of val at
the location specified by p. This function calls the
placement new operator.
void destroy (pointer p)
Calls the destructor on the object pointed to by p, but does not
delete.
See the container section of the Class Reference for a further
description of how to use the alternate allocator within a
user-defined container.
SEE ALSO
container
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
get_temporary_buffer
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
get_temporary_buffer - Pointer based primitive for handling memory
SYNOPSIS
#include <memory>
template <class T>
pair<T*, ptrdiff_t> get_temporary_buffer (ptrdiff_t, T*);
DESCRIPTION
The get_temporary_buffer templated function reserves from system
memory the largest possible buffer that is less than or equal to
the size requested (n*sizeof(T)), and returns a pair<T*,
ptrdiff_t> containing the address and size of that buffer. The
units used to describe the capacity are in sizeof(T).
SEE ALSO
allocate, construct, deallocate, pair, return_temporary_buffer.
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Additional Information on:
return_temporary_buffer
auto_ptr
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
auto_ptr_ - A simple, smart pointer class.
SYNOPSIS
#include <memory>
template <class X> class auto_ptr;
DESCRIPTION
The template class auto_ptr holds onto a pointer obtained via new
and deletes that object when the auto_ptr object itself is
destroyed (such as when leaving block scope). auto_ptr can be used
to make calls to operator new exception-safe. The auto_ptr class
provides semantics of strict ownership: an object may
be safely pointed to by only one auto_ptr, so copying an
auto_ptr copies the pointer and transfers ownership to the
destination if the source had already had ownership.
INTERFACE
template <class X> class auto_ptr {
public:
// constructor/copy/destroy
explicit auto_ptr (X* = 0) throw();
template <class Y>
auto_ptr (const auto_ptr<Y>&) throw();
template <class Y>
void operator= (const auto_ptr<Y>&) throw();
~auto_ptr ();
// members
X& operator* () const throw();
X* operator-> () const throw();
X* get () const throw();
X* release () throw();
};
CONSTRUCTORS AND DESTRUCTORS
explicit
auto_ptr (X* p = 0);
Constructs an object of class auto_ptr<X>, initializing the held
pointer to p, and acquiring ownership of that pointer. Requires
that p points to an object of class X or a class derived from X
for which delete p is defined and accessible, or that p is a
null pointer.
template <class Y> auto_ptr (const auto_ptr<Y>& a);
Copy constructor. Constructs an object of class auto_ptr<X>, and
copies the argument a to *this. If a owned the underlying
pointer then *this becomes the new owner of that pointer.
~auto_ptr ();
Deletes the underlying pointer.
OPERATORS
template <class Y>
void operator= (const auto_ptr<Y>& a);
Assignment operator. Copies the argument a to *this. If *this
becomes the new owner of the underlying pointer. If a owned the
underlying pointer then *this becomes the new owner of that
pointer. If *this already owned a pointer, then that pointer
is deleted first.
X&
operator* () const;
Returns a reference to the object to which the underlying
pointer points.
X*
operator-> () const;
Returns the underlying pointer.
MEMBER FUNCTIONS
X*
get () const;
Returns the underlying pointer.
X*
release();
Releases ownership of the underlying pointer. Returns that
pointer.
EXAMPLE
//
// auto_ptr.cpp
//
#include <iostream.h>
#include <memory>
//
// A simple structure.
//
struct X
{
X (int i = 0) : m_i(i) { }
int get() const { return m_i; }
int m_i;
};
int main ()
{
//
// b will hold a pointer to an X.
//
auto_ptr<X> b(new X(12345));
//
// a will now be the owner of the underlying pointer.
//
auto_ptr<X> a = b;
//
// Output the value contained by the underlying pointer.
//
cout << a->get() << endl;
//
// The pointer will be deleted when a is destroyed on
// leaving scope.
//
return 0;
}
Output :
12345
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Runtime Support
Additional Information on:
new
new_handler
delete
bad_alloc
type_info
bad_cast
bad_exception
bad_typeid
exception
nothrow
terminate_handler
unexpected_handler
string
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_string,string - A templated class for handling sequences of
character-like entities. string and wstring are specialized
versions of basic_string for chars and wchar_ts, respectively.
This page describes the ANSI basic_string class. If you would like
information on the pre-ANSI string class, use the command:
help cxxl
typedef basic_string <char> string;
typedef basic_string <wchar_t> wstring;
SYNOPSIS
#include <string>
template <class charT,
class traits = char_traits<charT>,
class Allocator = allocator<charT> >
class basic_string;
DESCRIPTION
basic_string<charT, traits, Allocator> is a homogeneous collection
of character-like entities. It provides general string
functionality such as compare, append, assign, insert, remove, and
replace , along with various searches. basic_string also functions
as an STL sequence container, providing random access
iterators. This allows some of the generic algorithms to apply
to strings.
Any underlying character-like type may be used as long as an
appropriate string_char_traits class is provided or the default
traits class is applicable.
INTERFACE
template <class charT,
class traits = char_traits<charT>,
class Allocator = allocator<charT> >
class basic_string {
public:
// Types
typedef traits traits_type;
typedef typename traits::char_type value_type;
typedef Allocator allocator_type;
typename size_type;
typename difference_type;
typename reference;
typename const_reference;
typename pointer;
typename const_pointer;
typename iterator;
typename const_iterator;
typename const_reverse_iterator;
typename reverse_iterator;
static const size_type npos = -1;
// Constructors/Destructors
explicit basic_string(const Allocator& = Allocator());
basic_string (const basic_string<charT, traits, Allocator>&);
basic_string(const basic_string&, size_type, size_type = npos);
basic_string(const charT*, size_type,
const Allocator& = Allocator());
basic_string(const charT*, Allocator& = Allocator());
basic_string(size_type, charT,
const Allocator& = Allocator());
template <class InputIterator>
basic_string(InputIterator, InputIterator,
const Allocator& = Allocator());
~basic_string();
// Assignment operators
basic_string& operator=(const basic_string&);
basic_string& operator=(const charT*);
basic_string& operator=(charT);
// Iterators
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;
// Capacity
size_type size() const;
size_type length() const;
size_type max_size() const;
void resize(size_type, charT);
void resize(size_type);
size_type capacity() const;
void reserve(size_type);
bool empty() const;
// Element access
const_reference operator[](size_type) const;
reference operator[](size_type);
const_reference at(size_type) const;
reference at(size_type);
// Modifiers
basic_string& operator+=(const basic_string&);
basic_string& operator+=(const charT*);
basic_string& operator+=(charT);
basic_string& append(const basic_string&);
basic_string& append(const basic_string&,
size_type, size_type);
basic_string& append(const charT*, size_type);
basic_string& append(const charT*);
basic_string& append(size_type, charT);
template<class InputIterator>
basic_string& append(InputIterator, InputIterator);
basic_string& assign(const basic_string&);
basic_string& assign(const basic_string&,
size_type, size_type);
basic_string& assign(const charT*, size_type);
basic_string& assign(const charT*);
basic_string& assign(size_type, charT);
template<class InputIterator>
basic_string& assign(InputIterator, InputIterator);
basic_string& insert(size_type, const basic_string&);
basic_string& insert(size_type, const basic_string&,
size_type, size_type);
basic_string& insert(size_type, const charT*, size_type);
basic_string& insert(size_type, const charT*);
basic_string& insert(size_type, size_type, charT);
iterator insert(iterator, charT = charT());
void insert(iterator, size_type, charT);
template<class InputIterator>
void insert(iterator, InputIterator,
InputIterator);
basic_string& erase(size_type = 0, size_type= npos);
iterator erase(iterator);
iterator erase(iterator, iterator);
basic_string& replace(size_type, size_type,
const basic_string&);
basic_string& replace(size_type, size_type,
const basic_string&,
size_type, size_type);
basic_string& replace(size_type, size_type,
const charT*, size_type);
basic_string& replace(size_type, size_type,
const charT*);
basic_string& replace(size_type, size_type,
size_type, charT);
basic_string& replace(iterator, iterator,
const basic_string&);
basic_string& replace(iterator, iterator,
const charT*, size_type);
basic_string& replace(iterator, iterator,
const charT*);
basic_string& replace(iterator, iterator,
size_type, charT);
template<class InputIterator>
basic_string& replace(iterator, iterator,
InputIterator, InputIterator);
size_type copy(charT*, size_type, size_type = 0);
void swap(basic_string<charT, traits, Allocator>&);
// String operations
const charT* c_str() const;
const charT* data() const;
const allocator_type& get_allocator() const;
size_type find(const basic_string&,
size_type = 0) const;
size_type find(const charT*,
size_type, size_type) const;
size_type find(const charT*, size_type = 0) const;
size_type find(charT, size_type = 0) const;
size_type rfind(const basic_string&,
size_type = npos) const;
size_type rfind(const charT*,
size_type, size_type) const;
size_type rfind(const charT*,
size_type = npos) const;
size_type rfind(charT, size_type = npos) const;
size_type find_first_of(const basic_string&,
size_type = 0) const;
size_type find_first_of(const charT*,
size_type, size_type) const;
size_type find_first_of(const charT*,
size_type = 0) const;
size_type find_first_of(charT, size_type = 0) const;
size_type find_last_of(const basic_string&,
size_type = npos) const;
size_type find_last_of(const charT*,
size_type, size_type) const;
size_type find_last_of(const charT*, size_type = npos) const;
size_type find_last_of(charT, size_type = npos) const;
size_type find_first_not_of(const basic_string&,
size_type = 0) const;
size_type find_first_not_of(const charT*,
size_type, size_type) const;
size_type find_first_not_of(const charT*, size_type = 0) const;
size_type find_first_not_of(charT, size_type = 0) const;
size_type find_last_not_of(const basic_string&,
size_type = npos) const;
size_type find_last_not_of(const charT*,
size_type, size_type) const;
size_type find_last_not_of(const charT*,
size_type = npos) const;
size_type find_last_not_of(charT, size_type = npos) const;
basic_string substr(size_type = 0, size_type = npos) const;
int compare(const basic_string&) const;
int compare(size_type, size_type, const basic_string&) const;
int compare(size_type, size_type, const basic_string&,
size_type, size_type) const;
int compare(size_type, size_type, charT*) const;
int compare(charT*) const;
int compare(size_type, size_type, const charT*, size_type) const;
};
// Non-member Operators
template <class charT, class traits, class Allocator>
basic_string operator+ (const basic_string&,
const basic_string&);
template <class charT, class traits, class Allocator>
basic_string operator+ (const charT*, const basic_string&);
template <class charT, class traits, class Allocator>
basic_string operator+ (charT, const basic_string&);
template <class charT, class traits, class Allocator>
basic_string operator+ (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
basic_string operator+ (const basic_string&, charT);
template <class charT, class traits, class Allocator>
bool operator== (const basic_string&, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator== (const charT*, const basic_string&);
template <class charT, class traits , class Allocator>
bool operator== (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
bool operator< (const basic_string&, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator< (const charT*, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator< (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
bool operator!= (const basic_string&, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator!= (const charT*, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator!= (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
bool operator> (const basic_&, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator> (const charT*, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator> (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
bool operator<= (const basic_string&, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator<= (const charT*, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator<= (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
bool operator>= (const basic_string&, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator>= (const charT*, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator>= (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
void swap(basic_string<charT,traits,Allocator>& a,
basic_string<charT,traits,Allocator>& b);
template<class charT, class traits, class Allocator>
istream& operator>> (istream&, basic_string&);
template <class charT, class traits, class Allocator>
ostream& operator<< (ostream&, const basic_string&);
template <class Stream, class charT,
class traits, class Allocator>
Stream& getline (Stream&, basic_string&, charT);
CONSTRUCTORS AND DESTRUCTORS
In all cases, the Allocator parameter will be used for storage
management.
explicit
basic_string (const Allocator& a = Allocator());
The default constructor. Creates a basic_string with the following
effects:
data() a non-null pointer that is copyable and can have 0 added
to it
size() 0
capacity() an unspecified value
basic_string (const basic_string<T, traits, Allocator>& str);
Copy constructor. Creates a string that is a copy of str.
basic_string (const basic_string &str, size_type pos,
size_type n= npos);
Creates a string if pos<=size() and determines length
rlen of initial string value as the smaller of n and
str.size() - pos. This has the following effects:
data() points at the first element of an allocated
copy of rlen elements of the string controlled
by str beginning at position pos
size() rlen
capacity() a value at least as large as size()
get_allocator() str.get_allocator()
An out_of_range exception will be thrown if
pos>str.size().
basic_string (const charT* s, size_type n,
const Allocator& a = Allocator());
Creates a string that contains the first n characters
of s. s must not be a NULL pointer. The effects of
this constructor are:
data() points at the first element of an allocated
copy of the array whose first element is
pointed at by s
size() n
capacity() a value at least as large as size()
An out_of_range exception will be thrown if n == npos.
basic_string (const charT * s,
const Allocator& a = Allocator());
Constructs a string containing all characters in s up
to, but not including, a traits::eos() character.
s must not be a null pointer. The effects of this
constructor are:
data() points at the first element of an allocated
copy of the array whose first element is
pointed at by s
size() traits::length(s)
capacity() a value at least as large as size()
basic_string (size_type n, charT c,
const Allocator& a = Allocator());
Constructs a string containing n repetitions of c. A
length_error exception is thrown if n == npos. The
effects of this constructor are:
data() points at the first element of an allocated
array of n elements, each storing the
initial value c
size() n
capacity() a value at least as large as size()
template <class InputIterator>
basic_string (InputIterator first, InputIterator last,
const Allocator& a = Allocator());
Creates a basic_string of length last - first,
filled with all values obtained by dereferencing
the InputIterators on the range [first, last).
The effects of this constructor are:
data() points at the first element of an allocated
copy of the elements in the range
[first,last)
size() distance between first and last
capacity() a value at least as large as size()
~basic_string ();
Releases any allocated memory for this basic_string.
OPERATORS
basic_string&
operator= (const basic_string& str);
Assignment operator. Sets the contents of this string to be the
same as str. The effects of operator= are:
data() points at the first element of an allocated copy of
the array whose first element is pointed at
by str.size()
size() str.size()
capacity() a value at least as large as size()
basic_string&
operator= (const charT * s);
Assignment operator. Sets the contents of this string to be the
same as s up to, but not including, the traits::eos() character.
basic_string&
operator= (charT c);
Assignment operator. Sets the contents of this string to be equal
to the single charT c.
const_reference
operator[] (size_type pos) const;
reference
operator[] (size_type pos);
If pos < size(), returns the element at position pos in this
string. If pos == size(), the const version returns traits::eos(),
the behavior of the non-const version is undefined. The
reference returned by either version is invalidated by any
call to c_str(), data(), or any non-const member function
for the object.
basic_string&
operator+= (const basic_string& s);
basic_string&
operator+= (const charT* s);
basic_string&
operator+= (charT c);
Concatenates a string onto the current contents of this string.
The second member operator uses traits::length() to determine the
number of elements from s to add. The third member operator
adds the single character c. All return a reference to this
string after completion.
ITERATORS
iterator begin ();
const_iterator begin () const;
Return an iterator initialized to the first element of the string.
iterator end ();
const_iterator end () const;
Return an iterator initialized to the position after the last
element of the string.
reverse_iterator rbegin ();
const_reverse_iterator rbegin () const;
Returns an iterator equivalent to reverse_iterator(end()).
reverse_iterator rend ();
const_reverse_iterator rend () const;
Returns an iterator equivalent to reverse_iterator(begin()).
ALLOCATOR
const allocator_type get_allocator () const;
Returns a copy of the allocator used by self for storage management.
MEMBER FUNCTIONS
basic_string&
append (const basic_string& s, size_type pos, size_type npos);
basic_string&
append (const basic_string& s);
basic_string&
append (const charT* s, size_type n);
basic_string&
append (const charT* s);
basic_string&
append (size_type n, charT c );
template<class InputIterator>
basic_string&
append (InputIterator first, InputIterator last);
Append another string to the end of this string. The first two
functions append the lesser of n and s.size() - pos characters of s,
beginning at position pos to this string. The second member will
throw an out_of_range exception if pos > str.size(). The third
member appends n characters of the array pointed to by s. The
fourth variation appends elements from the array pointed to
by s up to, but not including, a traits::eos() character.
The fifth variation appends n repetitions of c. The final
append function appends the elements specified in the
range [first, last).
All functions will throw a length_error exception if the
resulting length will exceed max_size(). All return a
reference to this string after completion.
basic_string&
assign (const basic_string& s);
basic_string&
assign (const basic_string& s,
size_type pos, size_type n);
basic_string&
assign (const charT* s, size_type n);
basic_string&
assign (const charT* s);
basic_string&
assign (size_type n, charT c );
template<class InputIterator>
basic_string&
assign (InputIterator first, InputIterator last);
Replace the value of this string with the value of another.
All versions of the function assign values to this string. The
first two variations assign the lesser of n and s.size() - pos
characters of s, beginning at position pos. The second
variation throws an out_of_range exception if pos > str.size().
The third version of the function assigns n characters of
the array pointed to by s. The fourth version assigns elements
from the array pointed to by s up to, but not including, a
traits::eos() character. The fifth assigns one or n
repetitions of c. The last variation assigns the members
specified by the range [first, last).
All functions will throw a length_error exception if the
resulting length will exceed max_size(). All return a
reference to this string after completion.
const_reference
at (size_type pos) const;
reference
at (size_type pos);
If pos < size(), returns the element at position pos in this
string. Otherwise, an out_of_range exception is thrown.
size_type
capacity () const;
Returns the current storage capacity of the string. This is
guaranteed to be at least as large as size().
int
compare (const basic_string& str);
Returns the result of a lexicographical comparison between
elements of this string and elements of str. The return value
is:
<0 if size() < str.size()
0 if size() == str.size()
>0 if size() > str.size()
int
compare (size_type pos1, size_type n1,
const basic_string& str) const;
int
compare (size_type pos1, size_type n1, const basic_string& str,
size_type pos2, size_type n2) const;
int
compare (charT* s) const;
int
compare (size_type pos, size_type n1, charT* s) const;
int
compare (size_type pos, size_type n1, charT* s,
size_type n2) const;
Return the result of a lexicographical comparison between
elements of this string and a given comparison string. The
members return, respectively:
compare (str)
compare (basic_string (str, pos2, n2))
compare (basic_string(s))
compare (basic_string(s, npos))
compare (basic_string (s,n2))
size_type
copy (charT* s, size_type n, size_type pos = 0) const;
Replaces elements in memory with copies of elements from this
string. An out_of_range exception will be thrown if pos > size().
The lesser of n and size() - pos elements of this string,
starting at position pos are copied into the array pointed
to by s. No terminating null is appended to s.
const charT*
c_str () const;
const charT*
data () const;
Return a pointer to the initial element of an array whose first
size() elements are copies of the elements in this string.
A traits::eos() element is appended to the end. The elements of
the array may not be altered, and the returned pointer is only
valid until a non-const member function of this string is called.
If size() is zero, the data() function returns a NULL pointer.
bool empty () const;
Returns size() == 0.
basic_string&
erase (size_type pos = 0, size_type n = npos);
iterator
erase (iterator p);
iterator
erase (iterator first, iterator last);
This function removes elements from the string, collapsing
the remaining elements, as necessary, to remove any space
left empty. The first version of the function removes the
smaller of n and size() - pos starting at position pos.
An out_of_range exception will be thrown if pos >
size(). The second version requires that p is a valid
iterator on this string, and removes the character referred to
by p. The last version of erase requires that both first and
last are valid iterators on this string, and removes the
characters defined by the range [first,last). The destructors
for all removed characters are called. All versions of erase
return a reference to this string after completion.
size_type
find (const basic_string& str, size_type pos = 0) const;
Searches for the first occurrence of the substring specified by
str in this string, starting at position pos. If found, it
returns the index of the first character of the matching
substring. If not found, returns npos. Equality is defined by
traits::eq().
size_type
find (const charT* s, size_type pos, size_type n) const;
size_type
find (const charT* s, size_type pos = 0) const;
size_type
find (charT c, size_type pos = 0) const;
Search for the first sequence of characters in this string that
match a specified string. The variations of this function
return, respectively:
find(basic_string(s,n), pos)
find(basic_string(s), pos)
find(basic_string(1, c), pos)
size_type
find_first_not_of (const basic_string& str,
size_type pos = 0) const
Searches for the first element of this string at or
after position pos that is not equal to any element of str. If
found, find_first_not_of returns the index of the non-matching
character. If all of the characters match, the function returns
npos. Equality is defined by traits::eq().
size_type
find_first_not_of (const charT* s,
size_type pos, size_type n) const;
size_type
find_first_not_of (const charT* s,
size_type pos = 0) const;
size_type
find_first_not_of (charT c, size_type pos = 0) const;
Search for the first element in this string at or after position
pos that is not equal to any element of a given set of
characters. The members return, respectively:
find_first_not_of(basic_string(s,n), pos)
find_first_not_of(basic_string(s), pos)
find_first_not_of(basic_string(1, c), pos)
size_type
find_first_of(const basic_string& str,
size_type pos = 0) const;
Searches for the first occurrence at or after position pos
of any element of str in this string. If found, the index
of this matching character is returned. If not found, npos is
returned. Equality is defined by traits::eq().
size_type
find_first_of(const charT* s, size_type pos,
size_type n) const;
size_type
find_first_of(const charT* s, size_type pos = 0) const;
size_type
find_first_of (charT c, size_type pos = 0) const;
Search for the first occurrence in this string of any element in
a specified string. The find_first_of variations return,
respectively:
find_first_of(basic_string(s,n), pos)
find_first_of(basic_string(s), pos)
find_first_of(basic_string(1, c), pos)
size_type
find_last_not_of(const basic_string& str,
size_type pos = npos) const;
Searches for the last element of this string at or before
position pos that is not equal to any element of str. If
find_last_not_of finds a non-matching element, it returns the
index of the character. If all the elements match, the
function returns npos. Equality is defined by traits::eq().
size_type
find_last_not_of(const charT* s,
size_type pos, size_type n) const;
size_type
find_last_not_of(const charT* s, size_type pos = npos) const;
size_type
find_last_not_of(charT c, size_type pos = npos) const;
Search for the last element in this string at or before position
pos that is not equal to any element of a given set of
characters. The members return, respectively:
find_last_not_of(basic_string(s,n), pos)
find_last_not_of(basic_string(s), pos)
find_last_not_of(basic_string(1, c), pos)
size_type
find_last_of(const basic_string& str,
size_type pos = npos) const;
Searches for the last occurrence of any element of str at or
before position pos in this string. If found,
find_last_of returns the index of the matching character. If
not found find_last_of returns npos. Equality is defined by
traits::eq().
size_type
find_last_of(const charT* s, size_type pos,
size_type n) const;
size_type
find_last_of(const charT* s, size_type pos = npos) const;
size_type
find_last_of(charT c, size_type pos = npos) const;
Search for the last occurrence in this string of any element
in a specified string. The members return, respectively:
find_last_of(basic_string(s,n), pos)
find_last_of(basic_string(s), pos)
find_last_of(basic_string(1, c), pos)
basic_string&
insert(size_type pos1, const basic_string& s);
basic_string&
insert(size_type pos, const basic_string& s,
size_type pos2 = 0, size_type n = npos);
basic_string&
insert(size_type pos, const charT* s, size_type n);
basic_string&
insert(size_type pos, const charT* s);
basic_string&
insert(size_type pos, size_type n, charT c);
Insert additional elements at position pos in this string. All
of the variants of this function will throw an out_of_range
exception if pos > size(). All variants will also throw a
length_error if the resulting string will exceed max_size().
Elements of this string will be moved apart as necessary to
accommodate the inserted elements. All return a reference to this
string after completion.
The second variation of this function inserts the lesser of n and
s.size() - pos2 characters of s, beginning at position pos2 in
this string. This version will throw an out_of_range
exception if pos2 > s.size(). The third version inserts n
characters of the array pointed to by s. The fourth
inserts elements from the array pointed to by s up
to, but not including, a traits::eos() character.
Finally, the fifth variation inserts n repetitions of c.
iterator
insert(iterator p, charT c = charT());
void
insert(iterator p, size_type n, charT c);
template<class InputIterator>
void
insert(iterator p, InputIterator first, InputIterator last);
Insert additional elements in this string immediately before
the character referred to by p. All of these versions of
insert require that p is a valid iterator on this string. The
first version inserts a copy of c. The second version inserts n
repetitions of c. The third version
inserts characters in the range [first, last). The first version
returns p.
size_type
length() const;
Return the number of elements contained in this string.
size_type
max_size() const;
Returns the maximum possible size of the string.
size_type
rfind (const basic_string& str, size_type pos = npos) const;
Searches for the last occurrence of the substring specified by
str in this string, starting at position pos. Note that only the
first character of the substring must be <= pos; the
remaining characters may extend beyond pos. If found, the index
of the first character of that matches substring is returned.
If not found, npos is returned. Equality is defined by
traits::eq().
size_type
rfind(const charT* s, size_type pos, size_type n) const;
size_type
rfind(const charT* s, size_type pos = npos) const;
size_type
rfind(charT c, size_type pos = npos) const;
Searches for the last sequence of characters in this string
matching a specified string. The rfind variations return,
respectively:
rfind(basic_string(s,n), pos)
rfind(basic_string(s), pos)
rfind(basic_string(1, c), pos)
basic_string&
replace(size_type pos, size_type n1, const basic_string& s);
basic_string&
replace(size_type pos1, size_type n1, const basic_string& str,
size_type pos2, size_type n2);
basic_string&
replace(size_type pos, size_type n1, const charT* s,
size_type n2);
basic_string&
replace(size_type pos, size_type n1, const charT* s);
basic_string&
replace(size_type pos, size_type n1, size_type n2, charT c);
The replace function replaces selected elements of this string
with an alternate set of elements. All of these versions insert
the new elements in place of n1 elements in this string, starting
at position pos. They each throw an out_of_range
exception if pos1 > size()and a length_error exception if the
resulting string size exceeds max_size().
The second version replaces elements of the original string with
n2 characters from string s starting at position pos2. It will
throw the out_of_range exception if pos2 > s.size(). The third
variation of the function replaces elements in the original string
with n2 elements from the array pointed to by s. The fourth
version replaces elements in the string with elements from the
array pointed to by s, up to, but not including, a
traits::eos() character. The fifth replaces n elements with n2
repetitions of character c.
basic_string&
replace(iterator i1, iterator i2,
const basic_string& str);
basic_string&
replace(iterator i1, iterator i2, const charT* s,
size_type n);
basic_string&
replace(iterator i1, iterator i2, const charT* s);
basic_string&
replace(iterator i1, iterator i2, size_type n,
charT c);
template<class InputIterator>
basic_string&
replace(iterator i1, iterator i2,
InputIterator j1, InputIterator j2);
Replace selected elements of this string with an alternative set
of elements. All of these versions of replace require
iterators i1 and i2 to be valid iterators on this string. The
elements specified by the range [i1,i2) are replaced by
the new elements.
The first version shown here replaces with all members in
str. The second version starts at position i1, and replaces
the next n characters with n characters of the array
pointed to by s. The third variation replaces string
elements with elements from the array pointed to by s up
to, but not including, a traits::eos() character. The fourth
version replaces string elements with n repetitions of c.
The last variation shown here replaces string elements with
the members specified in the range [j1, j2).
void
reserve(size_type res_arg);
Assures that the storage capacity is at least res_arg.
void
resize(size_type n, charT c);
void
resize(size_type n);
Changes the capacity of this string to n. If the new capacity is
smaller than the current size of the string, then it is
truncated. If the capacity is larger, then the string is padded
with c characters. The latter resize member pads the string
with default characters specified by traits::eos().
size type
size() const;
Return the number of elements contained in this string.
basic_string
substr(size_type pos = 0, size_type n = npos) const;
Returns a string composed of copies of the lesser of n and size()
characters in this string starting at index pos. Throws an
out_of_range exception if pos <= size().
void
swap(basic_string& s);
Swaps the contents of this string with the contents of s.
NON-MEMBER OPERATORS
template<class charT, class traits, class Allocator>
basic_string
operator+(const basic_string& lhs, const basic_string& rhs);
Returns a string of length lhs.size() + rhs.size(), where
the first lhs.size() elements are copies of the elements
of lhs, and the next rhs.size() elements are copies of
the elements of rhs.
template<class charT, class traits, class Allocator>
basic_string
operator+(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
basic_string
operator+(charT lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
basic_string
operator+(const basic_string& lhs, const charT* rhs);
template<class charT, class traits, class Allocator>
basic_string
operator+(const basic_string& lhs, charT rhs);
Returns a string that represents the concatenation of two
string-like
entities. These functions return, respectively:
basic_string(lhs) + rhs
basic_string(1, lhs) + rhs
lhs + basic_string(rhs)
lhs + basic_string(1, rhs)
template<class charT, class traits, class Allocator>
bool
operator==(const basic_string& lhs, const basic_string& rhs);
Returns a boolean value of true if lhs and rhs are equal,
and false if they are not. Equality is defined by the
compare() member function.
template<class charT, class traits, class Allocator>
bool
operator==(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
bool
operator==(const basic_string& lhs, const charT* rhs);
Returns a boolean value indicating whether lhs and rhs are equal.
Equality is defined by the compare() member function. These
functions return, respectively:
basic_string(lhs) == rhs
lhs == basic_string(rhs)
template<class charT, class traits, class Allocator>
bool
operator!=(const basic_string& lhs,
const basic_string& rhs);
Returns a boolean value representing the inequality of lhs
and rhs. Inequality is defined by the compare()
member function.
template<class charT, class traits, class Allocator>
bool
operator!=(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
bool
operator!=(const basic_string& lhs, const charT* rhs);
Returns a boolean value representing the inequality of lhs
and rhs. Inequality is defined by the compare()
member function. The functions return, respectively:
basic_string(lhs) != rhs
lhs != basic_string(rhs)
template<class charT, class traits, class Allocator>
bool
operator<(const basic_string& lhs, const basic_string& rhs);
Returns a boolean value representing the lexicographical
less-than relationship of lhs and rhs. Less-than is defined
by the compare() member.
template<class charT, class traits, class Allocator>
bool
operator<(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
bool
operator<(const basic_string& lhs, const charT* rhs);
Returns a boolean value representing the lexicographical
less-than relationship of lhs and rhs. Less-than is defined
by the compare() member
function. These functions return, respectively:
basic_string(lhs) < rhs
lhs < basic_string(rhs)
template<class charT, class traits, class Allocator>
bool
operator>(const basic_string& lhs, const basic_string& rhs);
Returns a boolean value representing the lexicographical
greater-than relationship of lhs and rhs. Greater-than
is defined by the compare() member function.
template<class charT, class traits, class Allocator>
bool
operator>(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
bool
operator>(const basic_string& lhs, const charT* rhs);
Returns a boolean value representing the lexicographical
greater-than relationship of lhs and rhs. Greater-than
is defined by the compare() member. The functions return,
respectively:
basic_string(lhs) > rhs
lhs > basic_string(rhs)
template<class charT, class traits, class Allocator>
bool
operator<=(const basic_string& lhs,
const basic_string& rhs);
Returns a boolean value representing the
lexicographical
less-than-or-equal relationship of lhs and rhs.
Less-than-or-equal is defined by the compare()
member function.
template<class charT, class traits, class Allocator>
bool
operator<=(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
bool
operator<=(const basic_string& lhs, const charT* rhs);
Returns a boolean value representing the lexicographical
less-than-or-equal relationship of lhs and rhs.
Less-than-or-equal is defined by the compare() member function.
These functions return, respectively:
basic_string(lhs) <= rhs
lhs <= basic_string(rhs)
template<class charT, class traits, class Allocator>
bool
operator>=(const basic_string& lhs, const basic_string& rhs);
Returns a boolean value representing the lexicographical
greater-than-or-equal relationship of lhs and rhs.
Greater-than-or-equal is defined by the compare() member
function.
template<class charT, class traits, class Allocator>
bool
operator>=(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
bool
operator>=(const basic_string& lhs, const charT* rhs);
Returns a boolean value representing the lexicographical
greater-than-or-equal relationship of lhs and rhs.
Greater-than-or-equal is defined
by the compare() member. The functions return, respectively:
basic_string(lhs) >= rhs
lhs >= basic_string(rhs)
template <class charT, class traits, class Allocator>
void swap(basic_string<charT,traits,Allocator>& a,
basic_string<charT,traits,Allocator>& b);
Swaps the contents of a and b by calling a's swap function on
b.
template<class charT, class traits, class Allocator>
istream&
operator>>(istream& is, basic_string& str);
Reads str from is using traits::char_in until a
traits::is_del() element is read. All elements read,
except the delimiter, are placed in
str. After the read, the function returns is.
template<class charT, class traits, class Allocator>
ostream&
operator<<(ostream& os, const basic_string& str);
Writes all elements of str to os in order from first to last, using
traits::char_out(). After the write, the function returns os.
NON-MEMBER FUNCTION
template <class Stream, class charT, class traits,
class Allocator>
Stream&
getline(Stream& is, basic_string& str, charT delim);
An unformatted input function that extracts characters from is
into str until npos - 1 characters are read, the end of
the input sequence is reached, or the character read is
delim. The characters are read using traits::char_in().
EXAMPLE
//
// string.cpp
//
#include<string>
#include <iostream.h>
int main()
{
string test;
//Type in a string over five characters long
while(test.empty() || test.size() <= 5)
{
cout << "Type a string between 5 and 100 characters long. "
<< endl;
cin >> test;
}
//Test operator[] access
cout << "Changing the third character from " << test[2] <<
" to * " << endl;
test[2] = '*';
cout << "now its: " << test << endl << endl;
//Try the insertion member function
cout << "Identifying the middle: ";
test.insert(test.size() / 2, "(the middle is here!)");
cout << test << endl << endl;
//Try replacement
cout << "I didn't like the word 'middle',so instead,I'll say:"
<< endl;
test.replace(test.find("middle",0), 6, "center");
cout << test << endl;
return 0;
}
Output :
Type a string between 5 and 100 characters long.
roguewave
Changing the third character from g to *
now its: ro*uewave
Identifying the middle: ro*u(the middle is here!)ewave
I didn't like the word 'middle', so instead, I'll say:
ro*u(the center is here!)ewave
SEE ALSO
Allocators, string, wstring
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Additional Information on:
string_char_traits
basic_string
basic_stringbuf
IOStreams
Additional Information on:
iostream_intro
basic_filebuf
basic_fstream
basic_ifstream
basic_ios
basic_iostream
basic_istream
basic_istringstream
basic_ofstream
basic_ostream
basic_ostringstream
basic_streambuf
basic_stringstream
cerr
char_traits
cin
cout
ctype
filebuf
fpos
fstream
ifstream
ios
iosfwd
istream
iostream
ios_base
istringstream
istrstream
ofstream
ostream
ostringstream
ostrstream
smanip
smanip_fill
streambuf
stringbuf
stringstream
strstream
strstreambuf
wcerr
wcin
wclog
wcout
wstring
locales
Additional Information on:
locale
codecvt_byname
code_cvt
collate
collate_byname
facets
has_facet
isalnum
isalpha
iscntrl
isdigit
isgraph
islower
isprint
ispunct
isspace
isupper
isxdigit
messages
messages_byname
moneypunct
moneypunct_byname
money_get
money_put
numpunct
numpunct_byname
num_get
num_put
time_get
time_get_byname
time_put
time_put_byname
tolower
toupper
use_facet
|
