1 - algorith
<algorithm>
adjacent_find
· binary_search
· copy
· copy_backward
· count
· count_if
· equal
· equal_range
· fill
· fill_n
· find
· find_end
· find_first_of
· find_if
· for_each
· generate
· generate_n
· includes
· 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
· partition
· 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
· unique
· unique_copy
· upper_bound
Include the STL
standard header <algorithm>
to define numerous template functions that perform
useful algorithms. The descriptions that follow
make extensive use of common template parameter names
(or prefixes) to indicate the least powerful category
of iterator permitted as an actual argument type:
OutIt --
to indicate an output iteratorInIt --
to indicate an input iteratorFwdIt --
to indicate a forward iteratorBidIt --
to indicate a bidirectional iteratorRanIt --
to indicate a random-access iterator
The descriptions of these templates employ a number of
conventions
common to all algorithms.
namespace std {
template<class InIt, class Fn1>
Fn1 for_each(InIt first, InIt last, Fn1 func);
template<class InIt, class Ty>
InIt find(InIt first, InIt last, const Ty& val);
template<class InIt, class Pr>
InIt find_if(InIt first, InIt last, Pr pred);
template<class FwdIt1, class FwdIt2>
FwdIt1 find_end(FwdIt1 first1, FwdIt1 last1,
FwdIt2 first2, FwdIt2 last2);
template<class FwdIt1, class FwdIt2, class Pr>
FwdIt1 find_end(FwdIt1 first1, FwdIt1 last1,
FwdIt2 first2, FwdIt2 last2, Pr pred);
template<class FwdIt1, class FwdIt2>
FwdIt1 find_first_of(FwdIt1 first1, FwdIt1 last1,
FwdIt2 first2, FwdIt2 last2);
template<class FwdIt1, class FwdIt2, class Pr>
FwdIt1 find_first_of(FwdIt1 first1, FwdIt1 last1,
FwdIt2 first2, FwdIt2 last2, Pr pred);
template<class FwdIt>
FwdIt adjacent_find(FwdIt first, FwdIt last);
template<class FwdIt, class Pr>
FwdIt adjacent_find(FwdIt first, FwdIt last, Pr pred);
template<class InIt, class Ty, class Dist>
typename iterator_traits<InIt>::difference_type
count(InIt first, InIt last,
const Ty& val);
template<class InIt, class Pr, class Dist>
typename iterator_traits<InIt>::difference_type
count_if(InIt first, InIt last,
Pr pred);
template<class InIt1, class InIt2>
pair<InIt1, InIt2> mismatch(InIt1 first1, InIt1 last1,
InIt2 first2);
template<class InIt1, class InIt2, class Pr>
pair<InIt1, InIt2> mismatch(InIt1 first1, InIt1 last1,
InIt2 first2, Pr pred);
template<class InIt1, class InIt2>
bool equal(InIt1 first1, InIt1 last1, InIt2 first2);
template<class InIt1, class InIt2, class Pr>
bool equal(InIt1 first1, InIt1 last1, InIt2 first2, Pr pred);
template<class FwdIt1, class FwdIt2>
FwdIt1 search(FwdIt1 first1, FwdIt1 last1,
FwdIt2 first2, FwdIt2 last2);
template<class FwdIt1, class FwdIt2, class Pr>
FwdIt1 search(FwdIt1 first1, FwdIt1 last1,
FwdIt2 first2, FwdIt2 last2, Pr pred);
template<class FwdIt1, class Diff2, class Ty>
FwdIt1 search_n(FwdIt1 first1, FwdIt1 last1,
Diff2 count, const Ty& val);
template<class FwdIt1, class Diff2, class Ty, class Pr>
FwdIt1 search_n(FwdIt1 first1, FwdIt1 last1,
Diff2 count, const Ty& val, Pr pred);
template<class InIt, class OutIt>
OutIt copy(InIt first, InIt last, OutIt dest);
template<class BidIt1, class BidIt2>
BidIt2 copy_backward(BidIt1 first, BidIt1 last,
BidIt2 dest);
template<class Ty>
void swap(Ty& left, Ty& right);
template<class FwdIt1, class FwdIt2>
FwdIt2 swap_ranges(FwdIt1 first1, FwdIt1 last1,
FwdIt2 last2);
template<class FwdIt1, class FwdIt2>
void iter_swap(FwdIt1 left, FwdIt2 right);
template<class InIt, class OutIt, class Fn1>
OutIt transform(InIt first, InIt last, OutIt dest,
Fn1 func);
template<class InIt1, class InIt2, class OutIt,
class Fn2>
OutIt transform(InIt1 first1, InIt1 last1,
InIt2 first2, OutIt dest, Fn2 func);template<class FwdIt, class Ty>
void replace(FwdIt first, FwdIt last,
const Ty& oldval, const Ty& newval);
template<class FwdIt, class Pr, class Ty>
void replace_if(FwdIt first, FwdIt last,
Pr pred, const Ty& val);
template<class InIt, class OutIt, class Ty>
OutIt replace_copy(InIt first, InIt last, OutIt dest,
const Ty& oldval, const Ty& newval);
template<class InIt, class OutIt, class Pr, class Ty>
OutIt replace_copy_if(InIt first, InIt last, OutIt dest,
Pr pred, const Ty& val);
template<class FwdIt, class Ty>
void fill(FwdIt first, FwdIt last, const Ty& val);
template<class OutIt, class Diff, class Ty>
void fill_n(OutIt first, Diff count, const Ty& val);
template<class FwdIt, class Fn0>
void generate(FwdIt first, FwdIt last, Fn0 func);
template<class OutIt, class Diff, class Fn0>
void generate_n(OutIt first, Diff count, Fn0 func);
template<class FwdIt, class Ty>
FwdIt remove(FwdIt first, FwdIt last, const Ty& val);
template<class FwdIt, class Pr>
FwdIt remove_if(FwdIt first, FwdIt last, Pr pred);
template<class InIt, class OutIt, class Ty>
OutIt remove_copy(InIt first, InIt last, OutIt dest,
const Ty& val);
template<class InIt, class OutIt, class Pr>
OutIt remove_copy_if(InIt first, InIt last, OutIt dest,
Pr pred);
template<class FwdIt>
FwdIt unique(FwdIt first, FwdIt last);
template<class FwdIt, class Pr>
FwdIt unique(FwdIt first, FwdIt last, Pr pred);
template<class InIt, class OutIt>
OutIt unique_copy(InIt first, InIt last, OutIt dest);
template<class InIt, class OutIt, class Pr>
OutIt unique_copy(InIt first, InIt last, OutIt dest,
Pr pred);
template<class BidIt>
void reverse(BidIt first, BidIt last);
template<class BidIt, class OutIt>
OutIt reverse_copy(BidIt first, BidIt last, OutIt dest);
template<class FwdIt>
void rotate(FwdIt first, FwdIt mid, FwdIt last);
template<class FwdIt, class OutIt>
OutIt rotate_copy(FwdIt first, FwdIt mid,
FwdIt last, OutIt dest);
template<class RanIt>
void random_shuffle(RanIt first, RanIt last);
template<class RanIt, class Fn1>
void random_shuffle(RanIt first, RanIt last, Fn1& func);
template<class BidIt, class Pr>
BidIt partition(BidIt first, BidIt last, Pr pred);
template<class BidIt, class Pr>
BidIt stable_partition(BidIt first, BidIt last,
Pr pred);
template<class RanIt>
void sort(RanIt first, RanIt last);
template<class RanIt, class Pr>
void sort(RanIt first, RanIt last, Pr pred);
template<class BidIt>
void stable_sort(BidIt first, BidIt last);
template<class BidIt, class Pr>
void stable_sort(BidIt first, BidIt last, Pr pred);
template<class RanIt>
void partial_sort(RanIt first, RanIt mid,
RanIt last);
template<class RanIt, class Pr>
void partial_sort(RanIt first, RanIt mid,
RanIt last, Pr pred);
template<class InIt, class RanIt>
RanIt partial_sort_copy(InIt first1, InIt last1,
RanIt first2, RanIt last2);
template<class InIt, class RanIt, class Pr>
RanIt partial_sort_copy(InIt first1, InIt last1,
RanIt first2, RanIt last2, Pr pred);template<class RanIt>
void nth_element(RanIt first, RanIt nth, RanIt last);
template<class RanIt, class Pr>
void nth_element(RanIt first, RanIt nth, RanIt last,
Pr pred);
template<class FwdIt, class Ty>
FwdIt lower_bound(FwdIt first, FwdIt last,
const Ty& val);
template<class FwdIt, class Ty, class Pr>
FwdIt lower_bound(FwdIt first, FwdIt last,
const Ty& val, Pr pred);
template<class FwdIt, class Ty>
FwdIt upper_bound(FwdIt first, FwdIt last,
const Ty& val);
template<class FwdIt, class Ty, class Pr>
FwdIt upper_bound(FwdIt first, FwdIt last,
const Ty& val, Pr pred);
template<class FwdIt, class Ty>
pair<FwdIt, FwdIt> equal_range(FwdIt first,
FwdIt last, const Ty& val);
template<class FwdIt, class Ty, class Pr>
pair<FwdIt, FwdIt> equal_range(FwdIt first,
FwdIt last, const Ty& val, Pr pred);
template<class FwdIt, class Ty>
bool binary_search(FwdIt first, FwdIt last,
const Ty& val);
template<class FwdIt, class Ty, class Pr>
bool binary_search(FwdIt first, FwdIt last,
const Ty& val, Pr pred);
template<class InIt1, class InIt2, class OutIt>
OutIt merge(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest);
template<class InIt1, class InIt2, class OutIt,
class Pr>
OutIt merge(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest, Pr pred);
template<class BidIt>
void inplace_merge(BidIt first, BidIt mid,
BidIt last);
template<class BidIt, class Pr>
void inplace_merge(BidIt first, BidIt mid,
BidIt last, Pr pred);
template<class InIt1, class InIt2>
bool includes(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2);
template<class InIt1, class InIt2, class Pr>
bool includes(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, Pr pred);
template<class InIt1, class InIt2, class OutIt>
OutIt set_union(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest);
template<class InIt1, class InIt2, class OutIt,
class Pr>
OutIt set_union(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest, Pr pred);
template<class InIt1, class InIt2, class OutIt>
OutIt set_intersection(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest);
template<class InIt1, class InIt2, class OutIt,
class Pr>
OutIt set_intersection(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest, Pr pred);
template<class InIt1, class InIt2, class OutIt>
OutIt set_difference(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest);
template<class InIt1, class InIt2, class OutIt,
class Pr>
OutIt set_difference(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest, Pr pred);
template<class InIt1, class InIt2, class OutIt>
OutIt set_symmetric_difference(InIt1 first1,
InIt1 last1, InIt2 first2, InIt2 last2, OutIt dest);
template<class InIt1, class InIt2, class OutIt,
class Pr>
OutIt set_symmetric_difference(InIt1 first1,
InIt1 last1, InIt2 first2, InIt2 last2, OutIt dest,
Pr pred);
template<class RanIt>
void push_heap(RanIt first, RanIt last);
template<class RanIt, class Pr>
void push_heap(RanIt first, RanIt last, Pr pred);
template<class RanIt>
void pop_heap(RanIt first, RanIt last);
template<class RanIt, class Pr>
void pop_heap(RanIt first, RanIt last, Pr pred);
template<class RanIt>
void make_heap(RanIt first, RanIt last);
template<class RanIt, class Pr>
void make_heap(RanIt first, RanIt last, Pr pred);
template<class RanIt>
void sort_heap(RanIt first, RanIt last);
template<class RanIt, class Pr>
void sort_heap(RanIt first, RanIt last, Pr pred);
template<class Ty>
const Ty& max(const Ty& left, const Ty& right);
template<class Ty, class Pr>
const Ty& max(const Ty& left, const Ty& right, Pr pred);
template<class Ty>
const Ty& min(const Ty& left, const Ty& right);
template<class Ty, class Pr>
const Ty& min(const Ty& left, const Ty& right, Pr pred);
template<class FwdIt>
FwdIt max_element(FwdIt first, FwdIt last);
template<class FwdIt, class Pr>
FwdIt max_element(FwdIt first, FwdIt last, Pr pred);
template<class FwdIt>
FwdIt min_element(FwdIt first, FwdIt last);
template<class FwdIt, class Pr>
FwdIt min_element(FwdIt first, FwdIt last, Pr pred);
template<class InIt1, class InIt2>
bool lexicographical_compare(InIt1 first1,
InIt1 last1, InIt2 first2, InIt2 last2);
template<class InIt1, class InIt2, class Pr>
bool lexicographical_compare(InIt1 first1,
InIt1 last1, InIt2 first2, InIt2 last2, Pr pred);
template<class BidIt>
bool next_permutation(BidIt first, BidIt last);
template<class BidIt, class Pr>
bool next_permutation(BidIt first, BidIt last,
Pr pred);
template<class BidIt>
bool prev_permutation(BidIt first, BidIt last);
template<class BidIt, class Pr>
bool prev_permutation(BidIt first, BidIt last,
Pr pred);
};template<class FwdIt>
FwdIt adjacent_find(FwdIt first, FwdIt last);
template<class FwdIt, class Pr>
FwdIt adjacent_find(FwdIt first, FwdIt last, Pr pred);The first template function determines the lowest N
in the range [0, last - first) for which
N + 1 < last - first and the predicate
*(first + N) == *(first + N + 1) is true.
Here, operator== must perform a
pairwise comparison
between its operands.
It then returns first + N.
If no such value exists, the function returns last.
If the sequence contains fewer than two elements, the function
never evaluates the predicate. Otherwise, if it returns
last, it evaluates the predicate exactly
last - first - 1 times. Otherwise,
it evaluates the predicate exactly N + 1 times.
The second template function behaves the same, except that
the predicate is pred(*(first + N), *(first + N + 1)).
template<class FwdIt, class Ty>
bool binary_search(FwdIt first, FwdIt last,
const Ty& val);
template<class FwdIt, class Ty, class Pr>
bool binary_search(FwdIt first, FwdIt last,
const Ty& val, Pr pred);The first template function determines whether
a value of N exists
in the range [0, last - first) for which
*(first + N) has
equivalent ordering
to val, where the elements designated by iterators
in the range [first, last) form a sequence
ordered by operator<.
If so, the function returns true.
If no such value exists, it returns false.
Yhe function evaluates the ordering predicate X < Y at most
ceil(log(last - first)) + 2 times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class InIt, class OutIt>
OutIt copy(InIt first, InIt last, OutIt dest);The template function evaluates *(dest + N) = *(first + N))
once for each N in the range [0, last - first),
for strictly increasing values of N beginning with
the lowest value. It then returns dest + N.
If dest and first designate regions of storage,
dest must not be in the range [first, last).
template<class BidIt1, class BidIt2>
BidIt2 copy_backward(BidIt1 first, BidIt1 last,
BidIt2 dest);The template function evaluates
*(dest - N - 1) = *(last - N - 1)) once for
each N in the range [0, last - first),
for strictly oncreasing values of N beginning with
the lowest value. It then returns dest - (last - first).
If dest and first designate regions of storage,
dest must not be in the range [first, last).
template<class InIt, class Ty>
typename iterator_traits<InIt>::difference_type
count(InIt first, InIt last, const Ty& val);The template function sets a count count to zero. It then
executes ++count for
each N in the range [0, last - first)
for which the predicate *(first + N) == val is true.
Here, operator== must perform a
pairwise comparison
between its operands.
The function returns count.
It evaluates the predicate exactly last - first times.
template<class InIt, class Pr, class Dist>
typename iterator_traits<InIt>::difference_type
count_if(InIt first, InIt last,
Pr pred);The template function sets a count count to zero. It then
executes ++count for
each N in the range [0, last - first)
for which the predicate pred(*(first + N)) is true.
The function returns count.
It evaluates the predicate exactly last - first times.
template<class InIt1, class InIt2>
bool equal(InIt1 first1, InIt1 last1, InIt2 first2);
template<class InIt1, class InIt2, class Pr>
bool equal(InIt1 first1, InIt1 last1, InIt2 first2, Pr pred);The first template function returns true only if, for
each N in the range [0, last1 - first1),
the predicate *(first1 + N) == *(first2 + N) is true.
Here, operator== must perform a
pairwise comparison
between its operands.
The function evaluates the predicate at most once
for each N.
The second template function behaves the same, except that
the predicate is pred(*(first1 + N), *(first2 + N)).
template<class FwdIt, class Ty>
pair<FwdIt, FwdIt> equal_range(FwdIt first,
FwdIt last, const Ty& val);
template<class FwdIt, class Ty, class Pr>
pair<FwdIt, FwdIt> equal_range(FwdIt first,
FwdIt last, const Ty& val, Pr pred);The first template function effectively returns
pair(
lower_bound(first, last, val),
upper_bound(first, last, val)),
where the elements designated by iterators
in the range [first, last) form a sequence
ordered by operator<.
Thus, the function determines the largest range of positions
over which val can be inserted in the sequence
and still preserve its ordering.
The function evaluates the ordering predicate X < Y at most
ceil(2 * log(last - first)) + 1.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class FwdIt, class Ty>
void fill(FwdIt first, FwdIt last, const Ty& val);The template function evaluates *(first + N) = val once for
each N in the range [0, last - first).
template<class OutIt, class Diff, class Ty>
void fill_n(OutIt first, Diff count, const Ty& val);The template function evaluates *(first + N) = val once for
each N in the range [0, count).
template<class InIt, class Ty>
InIt find(InIt first, InIt last, const Ty& val);The template function determines the lowest value of N
in the range [0, last - first) for which the predicate
*(first + N) == val is true.
Here, operator== must perform a
pairwise comparison
between its operands.
It then returns first + N.
If no such value exists, the function returns last.
It evaluates the predicate at most once
for each N.
template<class FwdIt1, class FwdIt2>
FwdIt1 find_end(FwdIt1 first1, FwdIt1 last1,
FwdIt2 first2, FwdIt2 last2);
template<class FwdIt1, class FwdIt2, class Pr>
FwdIt1 find_end(FwdIt1 first1, FwdIt1 last1,
FwdIt2 first2, FwdIt2 last2, Pr pred);The first template function determines the highest value of
N in the range [0,
last1 - first1 - (last2 - first2))
such that for each M in the range
[0, last2 - first2),
the predicate *(first1 + N + M) == *(first2 + N + M) is true.
Here, operator== must perform a
pairwise comparison
between its operands.
It then returns first1 + N.
If no such value exists, the function returns last1.
It evaluates the predicate at most (last2 - first2) *
(last1 - first1 - (last2 - first2) + 1) times.
The second template function behaves the same, except that
the predicate is pred(*(first1 + N + M), *(first2 + N + M)).
template<class FwdIt1, class FwdIt2>
FwdIt1 find_first_of(FwdIt1 first1, FwdIt1 last1,
FwdIt2 first2, FwdIt2 last2);
template<class FwdIt1, class FwdIt2, class Pr>
FwdIt1 find_first_of(FwdIt1 first1, FwdIt1 last1,
FwdIt2 first2, FwdIt2 last2, Pr pred);The first template function determines the lowest value of
N in the range [0, last1 - first1) such that
for some M in the range [0, last2 - first2),
the predicate *(first1 + N) == *(first2 + M) is true.
Here, operator== must perform a
pairwise comparison
between its operands.
It then returns first1 + N.
If no such value exists, the function returns last1.
It evaluates the predicate at most
(last1 - first1) * (last2 - first2) times.
The second template function behaves the same, except that
the predicate is pred(*(first1 + N), *(first2 + M)).
template<class InIt, class Pr>
InIt find_if(InIt first, InIt last, Pr pred);The template function determines the lowest value of N
in the range [0, last - first) for which the predicate
pred(*(first + N)) is true.
It then returns first + N.
If no such value exists, the function returns last.
It evaluates the predicate at most once
for each N.
template<class InIt, class Fn1>
Fn1 for_each(InIt first, InIt last, Fn1 func);The template function evaluates func(*(first + N)) once for
each N in the range [0, last - first).
It then returns func.
template<class FwdIt, class Fn0>
void generate(FwdIt first, FwdIt last, Fn0 func);The template function evaluates *(first + N) = func() once for
each N in the range [0, last - first).
template<class OutIt, class Pr, class Fn0>
void generate_n(OutIt first, Diff count, Fn0 func);The template function evaluates *(first + N) = func() once for
each N in the range [0, count).
template<class InIt1, class InIt2>
bool includes(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2);
template<class InIt1, class InIt2, class Pr>
bool includes(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, Pr pred);The first template function determines whether
a value of N exists
in the range [0, last2 - first2) such that,
for each M in the range [0, last1 - first1),
*(first1 + M) and *(first2 + N) do not have
equivalent ordering,
where the elements designated by iterators
in the ranges [first1, last1)
and [first2, last2) each form a sequence
ordered by operator<.
If so, the function returns false.
If no such value exists, it returns true.
Thus, the function determines whether the ordered sequence
designated by iterators in the range
[first2, last2) all have equivalent ordering with some
element designated by iterators in the range
[first1, last1).
The function evaluates the predicate at most
2 * ((last1 - first1) + (last2 - first2)) - 1 times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class BidIt>
void inplace_merge(BidIt first, BidIt mid,
BidIt last);
template<class BidIt, class Pr>
void inplace_merge(BidIt first, BidIt mid,
BidIt last, Pr pred);The first template function reorders the
sequences designated by iterators in the ranges [first, mid)
and [mid, last), each
ordered by operator<,
to form a merged sequence of length last - first
beginning at first also ordered by operator<.
The merge occurs without altering the relative order of
elements within either original sequence. Moreover, for any two elements
from different original sequences that have
equivalent ordering,
the element from the ordered range [first, mid)
precedes the other.
The function evaluates the ordering predicate
X < Y at most
ceil((last - first) * log(last - first)) times.
(Given enough temporary storage, it can evaluate the predicate at most
(last - first) - 1 times.)
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class FwdIt1, class FwdIt2>
void iter_swap(FwdIt1 left, FwdIt2 right);The template function leaves the value originally stored in
*right subsequently stored in *left,
and the value originally stored in *left
subsequently stored in *right.
template<class InIt1, class InIt2>
bool lexicographical_compare(InIt1 first1,
InIt1 last1, InIt2 first2, InIt2 last2);
template<class InIt1, class InIt2, class Pr>
bool lexicographical_compare(InIt1 first1,
InIt1 last1, InIt2 first2, InIt2 last2, Pr pred);The first template function determines K,
the number of elements to compare as the smaller of
last1 - first1 and last2 - first2.
It then determines the lowest value of N
in the range [0, K) for which
*(first1 + N) and *(first2 + N) do not have
equivalent ordering.
If no such value exists, the function returns true only if
K < (last2 - first2). Otherwise, it returns
true only if *(first1 + N) < *(first2 + N).
Thus, the function returns true only if the sequence designated
by iterators in the range [first1, last1) is
lexicographically less than the other sequence.
The function evaluates the ordering predicate
X < Y at most 2 * K times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class FwdIt, class Ty>
FwdIt lower_bound(FwdIt first, FwdIt last,
const Ty& val);
template<class FwdIt, class Ty, class Pr>
FwdIt lower_bound(FwdIt first, FwdIt last,
const Ty& val, Pr pred);The first template function determines the highest value of N
in the range (0, last - first] such that,
for each M in the range [0, N)
the predicate *(first + M) < val is true,
where the elements designated by iterators
in the range [first, last) form a sequence
ordered by operator<.
It then returns first + N.
Thus, the function determines the lowest position
before which val can be inserted in the sequence
and still preserve its ordering.
The function evaluates the ordering predicate X < Y at most
ceil(log(last - first)) + 1 times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class RanIt>
void make_heap(RanIt first, RanIt last);
template<class RanIt, class Pr>
void make_heap(RanIt first, RanIt last, Pr pred);The first template function reorders the sequence
designated by iterators in the
range [first, last) to form a heap
ordered by operator<.
The function evaluates the ordering predicate
X < Y at most
3 * (last - first) times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class Ty>
const Ty& max(const Ty& left, const Ty& right);
template<class Ty, class Pr>
const Ty& max(const Ty& left, const Ty& right, Pr pred);The first template function returns right if
left < right. Otherwise it returns left.
Ty need supply only a single-argument constructor and a
destructor.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class FwdIt>
FwdIt max_element(FwdIt first, FwdIt last);
template<class FwdIt, class Pr>
FwdIt max_element(FwdIt first, FwdIt last, Pr pred);The first template function determines the lowest value of N
in the range [0, last - first) such that,
for each M in the range [0, last - first)
the predicate *(first + N) < *(first + M) is false.
It then returns first + N.
Thus, the function determines the lowest position
that contains the largest value in the sequence.
The function evaluates the ordering predicate
X < Y exactly
max((last - first) - 1, 0) times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class InIt1, class InIt2, class OutIt>
OutIt merge(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest);
template<class InIt1, class InIt2, class OutIt,
class Pr>
OutIt merge(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest, Pr pred);The first template function determines K,
the number of elements to copy as (last1 - first1) +
(last2 - first2). It then alternately
copies two sequences, designated by iterators
in the ranges [first1, last1)
and [first2, last2) and each
ordered by operator<,
to form a merged sequence of length K beginning
at dest, also ordered by operator<.
The function then returns dest + K.
The merge occurs without altering the relative order of
elements within either sequence. Moreover, for any two elements
from different sequences that have
equivalent ordering,
the element from the ordered range [first1, last1)
precedes the other. Thus, the function merges two ordered
sequences to form another ordered sequence.
If dest and first1 designate regions of storage,
the range [dest, dest + K) must not
overlap the range [first1, last1).
If dest and first2 designate regions of storage,
the range [dest, dest + K) must not
overlap the range [first2, last2).
The function evaluates the ordering predicate X < Y at most
K - 1 times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class Ty>
const Ty& min(const Ty& left, const Ty& right);
template<class Ty, class Pr>
const Ty& min(const Ty& left, const Ty& right, Pr pred);The first template function returns right if
right < left. Otherwise it returns left.
Ty need supply only a single-argument constructor and a
destructor.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class FwdIt>
FwdIt min_element(FwdIt first, FwdIt last);
template<class FwdIt, class Pr>
FwdIt min_element(FwdIt first, FwdIt last, Pr pred);The first template function determines the lowest value of N
in the range [0, last - first) such that,
for each M in the range [0, last - first)
the predicate *(first + M) < *(first + N) is false.
It then returns first + N.
Thus, the function determines the lowest position
that contains the smallest value in the sequence.
The function evaluates the ordering predicate
X < Y exactly
max((last - first) - 1, 0) times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class InIt1, class InIt2>
pair<InIt1, InIt2> mismatch(InIt1 first1, InIt1 last1,
InIt2 first2);
template<class InIt1, class InIt2, class Pr>
pair<InIt1, InIt2> mismatch(InIt1 first1, InIt1 last1,
InIt2 first2, Pr pred);The first template function determines the lowest value of
N in the range [0, last1 - first1)
for which the predicate
!(*(first1 + N) == *(first2 + N)) is true.
Here, operator== must perform a
pairwise comparison
between its operands.
It then returns
pair(first1 + N, first2 + N).
If no such value exists, N has the value last1 - first1.
The function evaluates the predicate at most once
for each N.
The second template function behaves the same, except that
the predicate is pred(*(first1 + N), *(first2 + N)).
template<class BidIt>
bool next_permutation(BidIt first, BidIt last);
template<class BidIt, class Pr>
bool next_permutation(BidIt first, BidIt last,
Pr pred);The first template function determines a repeating
sequence of permutations, whose initial permutation occurs when
the sequence designated by iterators
in the range [first, last) is
ordered by operator<.
(The elements are sorted in ascending order.)
It then reorders the elements in the sequence, by evaluating
swap(X, Y) for the elements
X and Y zero or more times,
to form the next permutation. The function returns true only if the resulting
sequence is not the initial permutation. Otherwise, the resultant
sequence is the one next larger lexicographically than the original
sequence. No two elements may have
equivalent ordering.
The function evaluates swap(X, Y)
at most (last - first) / 2.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class RanIt>
void nth_element(RanIt first, RanIt nth, RanIt last);
template<class RanIt, class Pr>
void nth_element(RanIt first, RanIt nth, RanIt last,
Pr pred);The first template function reorders the sequence
designated by iterators in the
range [first, last) such that for each N
in the range [0, nth - first) and for each M
in the range [nth - first, last - first) the predicate
!(*(first + M) < *(first + N))
is true. Moreover, for N equal to
nth - first and for each M
in the range (nth - first, last - first) the predicate
!(*(first + M) < *(first + N))
is true. Thus, if nth != last the element *nth
is in its proper position if elements of the entire sequence
were sorted in ascending order,
ordered by operator<.
Any elements before this one belong before it in the sort sequence,
and any elements after it belong after it.
The function evaluates the ordering predicate X < Y
a number of times proportional to
last - first, on average.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class RanIt>
void partial_sort(RanIt first, RanIt mid,
RanIt last);
template<class RanIt, class Pr>
void partial_sort(RanIt first, RanIt mid,
RanIt last, Pr pred);The first template function reorders the sequence
designated by iterators in the
range [first, last) such that for each N
in the range [0, mid - first) and for each M
in the range (N, last - first) the predicate
!(*(first + M) < *(first + N))
is true. Thus, the smallest mid - first
elements of the entire sequence are sorted in ascending order,
ordered by operator<.
The order of the remaining elements is otherwise unspecified.
The function evaluates
the ordering predicate X < Y
a number of times proportional to at most
ceil((last - first) * log(mid - first)).
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class InIt, class RanIt>
RanIt partial_sort_copy(InIt first1, InIt last1,
RanIt first2, RanIt last2);
template<class InIt, class RanIt, class Pr>
RanIt partial_sort_copy(InIt first1, InIt last1,
RanIt first2, RanIt last2, Pr pred);The first template function determines K,
the number of elements to copy as the smaller of
last1 - first1 and last2 - first2. It then
copies and reorders K elements of the sequence
designated by iterators in the
range [first1, last1) such that
the K elements copied to first2 are
ordered by operator<.
Moreover, for each N
in the range [0, K) and for each M
in the range (0, last1 - first1) corresponding
to an uncopied element, the predicate
!(*(first2 + M) < *(first1 + N))
is true. Thus, the smallest K
elements of the entire sequence designated by iterators
in the range [first1, last1)
are copied and sorted in ascending order to the range
[first2, first2 + K).
The function evaluates
the ordering predicate X < Y
a number of times proportional to at most
ceil((last - first) * log(K)).
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class BidIt, class Pr>
BidIt partition(BidIt first, BidIt last, Pr pred);The template function reorders the sequence designated by iterators in the
range [first, last) and determines the value
K such that for each N in the range
[0, K) the predicate pred(*(first + N))
is true, and for each N in the range
[K, last - first) the predicate pred(*(first + N))
is false. The function then returns first + K.
The predicate must not alter its operand.
The function evaluates pred(*(first + N)) exactly
last - first times, and swaps at most
(last - first) / 2 pairs of elements.
template<class RanIt>
void pop_heap(RanIt first, RanIt last);
template<class RanIt, class Pr>
void pop_heap(RanIt first, RanIt last, Pr pred);The first template function reorders the sequence
designated by iterators in the
range [first, last) to form a new heap,
ordered by operator< and
designated by iterators in the range
[first, last - 1), leaving the original
element at *first subsequently at *(last - 1).
The original sequence must designate an existing heap,
also ordered by operator<. Thus, first !=
last must be true and *(last - 1) is the
element to remove from (pop off) the heap.
The function evaluates the ordering predicate
X < Y at most
ceil(2 * log(last - first)) times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class BidIt>
bool prev_permutation(BidIt first, BidIt last);
template<class BidIt, class Pr>
bool prev_permutation(BidIt first, BidIt last,
Pr pred);The first template function determines a repeating
sequence of permutations, whose initial permutation occurs when
the sequence designated by iterators
in the range [first, last) is the reverse of one
ordered by operator<.
(The elements are sorted in descending order.)
It then reorders the elements in the sequence, by evaluating
swap(X, Y) for the elements
X and Y zero or more times,
to form the previous permutation.
The function returns true only if the resulting
sequence is not the initial permutation. Otherwise, the resultant
sequence is the one next smaller lexicographically than the original
sequence. No two elements may have
equivalent ordering.
The function evaluates swap(X, Y)
at most (last - first) / 2.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class RanIt>
void push_heap(RanIt first, RanIt last);
template<class RanIt, class Pr>
void push_heap(RanIt first, RanIt last, Pr pred);The first template function reorders the sequence
designated by iterators in the
range [first, last) to form a new heap
ordered by operator<.
Iterators in the range
[first, last - 1) must designate an existing heap,
also ordered by operator<. Thus, first !=
last must be true and *(last - 1) is the
element to add to (push on) the heap.
The function evaluates the ordering predicate
X < Y at most
ceil(log(last - first)) times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class RanIt>
void random_shuffle(RanIt first, RanIt last);
template<class RanIt, class Fn1>
void random_shuffle(RanIt first, RanIt last, Fn1& func);The first template function evaluates
swap(*(first + N), *(first + M)) once for
each N in the range [1, last - first),
where M is a value from some uniform random distribution
over the range [0, N].
Thus, the function randomly shuffles
the order of elements in the sequence.
The function evaluates M and calls swap
exactly last - first - 1 times.
The second template function behaves the same, except that
M is (Diff)func((Diff)N), where
Diff is the type
iterator_traits<RanIt>::
difference_type.
template<class FwdIt, class Ty>
FwdIt remove(FwdIt first, FwdIt last, const Ty& val);The template function effectively assigns first to
X, then executes the statement:
if (!(*(first + N) == val))
*X++ = *(first + N);once for each N in the range
[0, last - first).
Here, operator== must perform a
pairwise comparison
between its operands.
It then returns X.
Thus, the function removes from the resulting sequence all elements for
which the predicate *(first + N) == val is true,
without altering the relative order of remaining elements,
and returns the iterator value that designates the end of the
resulting sequence.
template<class InIt, class OutIt, class Ty>
OutIt remove_copy(InIt first, InIt last, OutIt dest,
const Ty& val);The template function effectively executes the statement:
if (!(*(first + N) == val))
*dest++ = *(first + N);once for each N in the range
[0, last - first).
Here, operator== must perform a
pairwise comparison
between its operands.
It then returns dest.
Thus, the function removes from the resulting sequence all elements for
which the predicate *(first + N) == val is true,
without altering the relative order of remaining elements,
and returns the iterator value that designates the end of the
resulting sequence.
If dest and first designate regions of storage,
the range [dest, dest + (last - first)) must not
overlap the range [first, last).
template<class InIt, class OutIt, class Pr>
OutIt remove_copy_if(InIt first, InIt last, OutIt dest,
Pr pred);The template function effectively executes the statement:
if (!pred(*(first + N)))
*dest++ = *(first + N);once for each N in the range
[0, last - first). It then returns dest.
Thus, the function removes from the resulting sequence all elements for
which the predicate pred(*(first + N)) is true,
without altering the relative order of remaining elements,
and returns the iterator value that designates the end of the
resulting sequence.
If dest and first designate regions of storage,
the range [dest, dest + (last - first)) must not
overlap the range [first, last).
template<class FwdIt, class Pr>
FwdIt remove_if(FwdIt first, FwdIt last, Pr pred);The template function effectively assigns first to
X, then executes the statement:
if (!pred(*(first + N)))
*X++ = *(first + N);once for each N in the range
[0, last - first). It then returns X.
Thus, the function removes from the resulting sequence all elements for
which the predicate pred(*(first + N)) is true,
without altering the relative order of remaining elements,
and returns the iterator value that designates the end of the
resulting sequence.
template<class FwdIt, class Ty>
void replace(FwdIt first, FwdIt last,
const Ty& oldval, const Ty& newval);The template function executes the statement:
if (*(first + N) == oldval)
*(first + N) = newval;once for each N in the range
[0, last - first).
Here, operator== must perform a
pairwise comparison
between its operands.
template<class InIt, class OutIt, class Ty>
OutIt replace_copy(InIt first, InIt last, OutIt dest,
const Ty& oldval, const Ty& newval);The template function executes the statement:
if (*(first + N) == oldval)
*(dest + N) = newval;
else
*(dest + N) = *(first + N)once for each N in the range
[0, last - first).
Here, operator== must perform a
pairwise comparison
between its operands. The function returns the iterator value that
designates the end of the resulting sequence.
If dest and first designate regions of storage,
the range [dest, dest + (last - first)) must not
overlap the range [first, last).
template<class InIt, class OutIt, class Pr, class Ty>
OutIt replace_copy_if(InIt first, InIt last, OutIt dest,
Pr pred, const Ty& val);The template function executes the statement:
if (pred(*(first + N)))
*(dest + N) = val;
else
*(dest + N) = *(first + N)once for each N in the range
[0, last - first).
If dest and first designate regions of storage,
the range [dest, dest + (last - first)) must not
overlap the range [first, last). The function returns the iterator
value that designates the end of the resulting sequence.
template<class FwdIt, class Pr, class Ty>
void replace_if(FwdIt first, FwdIt last,
Pr pred, const Ty& val);The template function executes the statement:
if (pred(*(first + N)))
*(first + N) = val;once for each N in the range
[0, last - first).
template<class BidIt>
void reverse(BidIt first, BidIt last);The template function evaluates
swap(*(first + N), *(last - 1 - N) once for
each N in the range [0, (last - first) / 2).
Thus, the function reverses the order of elements in the sequence.
template<class BidIt, class OutIt>
OutIt reverse_copy(BidIt first, BidIt last, OutIt dest);The template function evaluates
*(dest + N) = *(last - 1 - N) once for
each N in the range [0, last - first).
It then returns dest + (last - first).
Thus, the function reverses the order of elements in the sequence
that it copies.
If dest and first designate regions of storage,
the range [dest, dest + (last - first)) must not
overlap the range [first, last).
template<class FwdIt>
void rotate(FwdIt first, FwdIt mid, FwdIt last);The template function leaves the value originally stored in
*(first + (N + (mid - first)) % (last - first))
subsequently stored in *(first + N) for
each N in the range [0, last - first).
Thus, if a ``left'' shift by one element leaves the element
originally stored in *(first + (N + 1) % (last - first))
subsequently stored in *(first + N), then the function
can be said to rotate the sequence either left by
mid - first elements or right by last - mid
elements. Both [first, mid) and [mid, last)
must be valid ranges. The function swaps at most last - first
pairs of elements.
template<class FwdIt, class OutIt>
OutIt rotate_copy(FwdIt first, FwdIt mid,
FwdIt last, OutIt dest);The template function evaluates
*(dest + N) = *(first + (N + (mid - first)) % (last - first))
once for each N in the range [0, last - first).
Thus, if a ``left'' shift by one element leaves the element
originally stored in *(first + (N + 1) % (last - first))
subsequently stored in *(first + N), then the function
can be said to rotate the sequence either left by
mid - first elements or right by last - mid
elements as it copies.
Both [first, mid) and [mid, last)
must be valid ranges. The function returns the iterator value
that designates the end of the resulting sequence.
If dest and first designate regions of storage,
the range [dest, dest + (last - first)) must not
overlap the range [first, last).
template<class FwdIt1, class FwdIt2>
FwdIt1 search(FwdIt1 first1, FwdIt1 last1,
FwdIt2 first2, FwdIt2 last2);
template<class FwdIt1, class FwdIt2, class Pr>
FwdIt1 search(FwdIt1 first1, FwdIt1 last1,
FwdIt2 first2, FwdIt2 last2, Pr pred);The first template function determines the lowest value of
N in the range [0,
(last1 - first1) - (last2 - first2)) such that
for each M in the range [0, last2 - first2),
the predicate *(first1 + N + M) == *(first2 + M) is true.
Here, operator== must perform a
pairwise comparison
between its operands.
It then returns first1 + N.
If no such value exists, the function returns last1.
It evaluates the predicate at most (last2 - first2) *
(last1 - first1) times.
The second template function behaves the same, except that
the predicate is pred(*(first1 + N + M), *(first2 + M)).
template<class FwdIt1, class Diff2, class Ty>
FwdIt1 search_n(FwdIt1 first1, FwdIt1 last1,
Diff2 count, const Ty& val);
template<class FwdIt1, class Diff2, class Ty, class Pr>
FwdIt1 search_n(FwdIt1 first1, FwdIt1 last1,
Diff2 count, const Ty& val, Pr pred);The first template function determines the lowest value of
N in the range [0,
(last - first) - count) such that
for each M in the range [0, count),
the predicate *(first + N + M) == val is true.
Here, operator== must perform a
pairwise comparison
between its operands.
It then returns first + N.
If no such value exists, the function returns last.
It evaluates the predicate at most count * (last - first) times.
The second template function behaves the same, except that
the predicate is pred(*(first + N + M), val).
template<class InIt1, class InIt2, class OutIt>
OutIt set_difference(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest);
template<class InIt1, class InIt2, class OutIt,
class Pr>
OutIt set_difference(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest, Pr pred);The first template function alternately
copies values from two sequences designated by iterators in the ranges
[first1, last1) and [first2, last2), both
ordered by operator<,
to form a merged sequence of length K beginning
at dest, also ordered by operator<.
The function then returns dest + K.
The merge occurs without altering the relative order of
elements within either sequence. Moreover, for two elements
from different sequences that have
equivalent ordering
that would otherwise be copied to adjacent elements,
the function copies only
the element from the ordered range [first1, last1)
and skips the other. An element from one sequence that has
equivalent ordering with no element from the other sequence
is copied from the ordered range [first1, last1)
and skipped from the other.
Thus, the function merges two ordered
sequences to form another ordered sequence that is effectively
the difference of two sets.
If dest and first1 designate regions of storage,
the range [dest, dest + K) must not
overlap the range [first1, last1).
If dest and first2 designate regions of storage,
the range [dest, dest + K) must not
overlap the range [first2, last2).
The function evaluates the ordering predicate X < Y at most
2 * ((last1 - first1) + (last2 - first2)) - 1 times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class InIt1, class InIt2, class OutIt>
OutIt set_intersection(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest);
template<class InIt1, class InIt2, class OutIt,
class Pr>
OutIt set_intersection(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest, Pr pred);The first template function alternately
copies values from two sequences designated by iterators in the ranges
[first1, last1) and [first2, last2), both
ordered by operator<,
to form a merged sequence of length K beginning
at dest, also ordered by operator<.
The function then returns dest + K.
The merge occurs without altering the relative order of
elements within either sequence. Moreover, for two elements
from different sequences that have
equivalent ordering
that would otherwise be copied to adjacent elements,
the function copies only
the element from the ordered range [first1, last1)
and skips the other. An element from one sequence that has
equivalent ordering with no element from the other sequence
is also skipped.
Thus, the function merges two ordered
sequences to form another ordered sequence that is effectively
the intersection of two sets.
If dest and first1 designate regions of storage,
the range [dest, dest + K) must not
overlap the range [first1, last1).
If dest and first2 designate regions of storage,
the range [dest, dest + K) must not
overlap the range [first2, last2).
The function evaluates the ordering predicate X < Y at most
2 * ((last1 - first1) + (last2 - first2)) - 1 times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class InIt1, class InIt2, class OutIt>
OutIt set_symmetric_difference(InIt1 first1,
InIt1 last1, InIt2 first2, InIt2 last2, OutIt dest);
template<class InIt1, class InIt2, class OutIt,
class Pr>
OutIt set_symmetric_difference(InIt1 first1,
InIt1 last1, InIt2 first2, InIt2 last2, OutIt dest,
Pr pred);The first template function alternately
copies values from two sequences designated by iterators in the ranges
[first1, last1) and [first2, last2), both
ordered by operator<,
to form a merged sequence of length K beginning
at dest, also ordered by operator<.
The function then returns dest + K.
The merge occurs without altering the relative order of
elements within either sequence. Moreover, for two elements
from different sequences that have
equivalent ordering
that would otherwise be copied to adjacent elements,
the function copies neither element. An element from one sequence that has
equivalent ordering with no element from the other sequence
is copied. Thus, the function merges two ordered
sequences to form another ordered sequence that is effectively
the symmetric difference of two sets.
If dest and first1 designate regions of storage,
the range [dest, dest + K) must not
overlap the range [first1, last1).
If dest and first2 designate regions of storage,
the range [dest, dest + K) must not
overlap the range [first2, last2).
The function evaluates the ordering predicate X < Y at most
2 * ((last1 - first1) + (last2 - first2)) - 1 times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class InIt1, class InIt2, class OutIt>
OutIt set_union(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest);
template<class InIt1, class InIt2, class OutIt,
class Pr>
OutIt set_union(InIt1 first1, InIt1 last1,
InIt2 first2, InIt2 last2, OutIt dest, Pr pred);The first template function alternately
copies values from two sequences designated by iterators in the ranges
[first1, last1) and [first2, last2), both
ordered by operator<,
to form a merged sequence of length K beginning
at dest, also ordered by operator<.
The function then returns dest + K.
The merge occurs without altering the relative order of
elements within either sequence. Moreover, for two elements
from different sequences that have
equivalent ordering
that would otherwise be copied to adjacent elements,
the function copies only
the element from the ordered range [first1, last1)
and skips the other.
Thus, the function merges two ordered
sequences to form another ordered sequence that is effectively
the union of two sets.
If dest and first1 designate regions of storage,
the range [dest, dest + K) must not
overlap the range [first1, last1).
If dest and first2 designate regions of storage,
the range [dest, dest + K) must not
overlap the range [first2, last2).
The function evaluates the ordering predicate X < Y at most
2 * ((last1 - first1) + (last2 - first2)) - 1 times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class RanIt>
void sort(RanIt first, RanIt last);
template<class RanIt, class Pr>
void sort(RanIt first, RanIt last, Pr pred);The first template function reorders the sequence
designated by iterators in the
range [first, last) to form a sequence
ordered by operator<.
Thus, the elements are sorted in ascending order.
The function evaluates
the ordering predicate X < Y
a number of times proportional to at most
ceil((last - first) * log(last - first)).
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class RanIt>
void sort_heap(RanIt first, RanIt last);
template<class RanIt, class Pr>
void sort_heap(RanIt first, RanIt last, Pr pred);The first template function reorders the sequence
designated by iterators in the
range [first, last) to form a sequence
that is
ordered by operator<.
The original sequence must designate a heap, also
ordered by operator<.
Thus, the elements are sorted in ascending order.
The function evaluates the ordering predicate
X < Y at most
ceil((last - first) * log(last - first)) times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class BidIt, class Pr>
BidIt stable_partition(BidIt first, BidIt last,
Pr pred);The template function reorders the sequence designated by iterators in the
range [first, last) and determines the value
K such that for each N in the range
[0, K) the predicate pred(*(first + N))
is true, and for each N in the range
[K, last - first) the predicate pred(*(first + N))
is false. It does so without altering the relative order of either
the elements designated by indexes
in the range [0, K) or
the elements designated by indexes
in the range [K, last - first).
The function then returns first + K.
The predicate must not alter its operand.
The function evaluates pred(*(first + N)) exactly
last - first times, and swaps at most
ceil((last - first) * log(last - first))
pairs of elements. (Given enough temporary storage, it can
replace the swaps with at most
2 * (last - first) assignments.)
template<class BidIt>
void stable_sort(BidIt first, BidIt last);
template<class BidIt, class Pr>
void stable_sort(BidIt first, BidIt last, Pr pred);The first template function reorders the sequence
designated by iterators in the
range [first, last) to form a sequence
ordered by operator<.
It does so without altering the relative order of
elements that have
equivalent ordering.
Thus, the elements are sorted in ascending order.
The function evaluates
the ordering predicate X < Y
a number of times proportional to at most
ceil((last - first) * (log(last - first))^2).
(Given enough temporary storage, it can evaluate the predicate
a number of times proportional to at most
ceil((last - first) * log(last - first)).
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
template<class Ty>
void swap(Ty& left, Ty& right);The template function leaves the value originally stored in
right subsequently stored in left,
and the value originally stored in left
subsequently stored in right.
template<class FwdIt1, class FwdIt2>
FwdIt2 swap_ranges(FwdIt1 first1, FwdIt1 last1,
FwdIt2 first2);The template function evaluates
swap(*(first1 + N), *(first2 + N)) once for
each N in the range [0, last1 - first1).
It then returns first2 + (last1 - first1).
If first2 and first1 designate regions of storage,
the range [first2, first2 + (last1 - first1)) must not
overlap the range [first1, last1).
template<class InIt, class OutIt, class Fn1>
OutIt transform(InIt first, InIt last, OutIt dest,
Fn1 func);
template<class InIt1, class InIt2, class OutIt,
class Fn2>
OutIt transform(InIt1 first1, InIt1 last1,
InIt2 first2, OutIt dest, Fn2 func);The first template function evaluates
*(dest + N) = func(*(first + N))
once for each N in the range [0, last - first).
It then returns dest + (last - first). The call
func(*(first + N)) must not alter
*(first + N).
The second template function evaluates
*(dest + N) = func(*(first1 + N), *(first2 + N))
once for each N in the range [0, last1 - first1).
It then returns dest + (last1 - first1). The call
func(*(first1 + N), *(first2 + N)) must not alter
either *(first1 + N) or *(first2 + N).
template<class FwdIt>
FwdIt unique(FwdIt first, FwdIt last);
template<class FwdIt, class Pr>
FwdIt unique(FwdIt first, FwdIt last, Pr pred);The first template function effectively assigns first to
X, then executes the statement:
if (N == 0)
++X;
else if (!(*X == *(first + N)))
*X++ = V;once for each N in the range
[0, last - first). It then returns X.
Thus, the function repeatedly removes from the resulting sequence
the second of a pair of elements for
which the predicate *(first + N) == *(first + N + 1) is true,
until only the first of a sequence of elements survives
that satisfies the comparison.
Here, operator== must perform a
pairwise comparison
between its operands.
It does so without altering the relative order of remaining elements,
and returns the iterator value that designates the end of the
resulting sequence. For a non-empty sequence,
the function evaluates the predicate
last - first - 1 times.
The second template function behaves the same, except that
it executes the statement:
if (N == 0)
++X;
else if (!pred(*X, *(first + N)))
*X++ = V;Note that for a sequence designated by the range [first, last)
and ordered by pred,
you can remove all but the first of a sequence of elements that have
equivalent ordering by calling
unique(first, last,
not2(pred)).
template<class InIt, class OutIt>
OutIt unique_copy(InIt first, InIt last, OutIt dest);
template<class InIt, class OutIt, class Pr>
OutIt unique_copy(InIt first, InIt last, OutIt dest,
Pr pred);The first template function effectively executes the statement:
if (N == 0 || !(*(first + N) == V))
V = *(first + N), *dest++ = V;once for each N in the range
[0, last - first). It then returns dest.
Thus, the function repeatedly removes from the resulting sequence
the second of a pair of elements for
which the predicate *(first + N) == *(first + N - 1) is true,
until only the first of a sequence of equal elements survives.
Here, operator== must perform a
pairwise comparison
between its operands.
It does so without altering the relative order of remaining elements,
and returns the iterator value that designates the end of the
copied sequence. For a non-empty sequence,
the function evaluates the predicate
last - first - 1 times.
If dest and first designate regions of storage,
the range [dest, dest + (last - first)) must not
overlap the range [first, last).
The second template function behaves the same, except that
it executes the statement:
if (N == 0 || !pred(*(first + N), V))
V = *(first + N), *dest++ = V;template<class FwdIt, class Ty>
FwdIt upper_bound(FwdIt first, FwdIt last,
const Ty& val);
template<class FwdIt, class Ty, class Pr>
FwdIt upper_bound(FwdIt first, FwdIt last,
const Ty& val, Pr pred);The first template function determines the highest value of N
in the range (0, last - first] such that,
for each M in the range [0, N)
the predicate !(val < *(first + M)) is true,
where the elements designated by iterators
in the range [first, last) form a sequence
ordered by operator<.
It then returns first + N.
Thus, the function determines the highest position
before which val can be inserted in the sequence
and still preserve its ordering.
The function evaluates the ordering predicate X < Y at most
ceil(log(last - first)) + 1 times.
The second template function behaves the same, except that
it replaces operator<(X, Y) with
pred(X, Y).
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
2 - assert
<assert.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
3 - bitset
<bitset>
bitset
· operator&
· operator|
· operator^
· operator>>
· operator<<
Include the standard header <bitset>
to define the template class bitset
and two supporting templates.
namespace std {
template<size_t Bits>
class bitset;
// TEMPLATE FUNCTIONS
template<size_t Bits>
bitset<Bits>
operator&(const bitset& left,
const bitset& right);
template<size_t Bits>
bitset<Bits>
operator|(const bitset& left,
const bitset& right);
template<size_t Bits>
bitset<Bits>
operator&(const bitset& left,
const bitset& right);
template<class Elem, class Tr, size_t Bits>
basic_istream<Elem, Tr>&
operator>>(basic_istream<Elem, >& istr,
bitset<Bits>& right);
template<class Elem, class Tr, size_t Bits>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
const bitset<Bits>& right);
};
any
· bitset
· count
· element_type
· flip
· none
· operator!=
· operator&=
· operator<<
· operator<<=
· operator==
· operator>>
· operator>>=
· operator[]
· operator^=
· operator|=
· operator~
· reference
· reset
· set
· size
· test
· to_string
· to_ulong
template<size_t Bits>
class bitset {
public:
typedef bool element_type;
class reference;
bitset();
bitset(unsigned long val);
template<class Elem, class Tr, class Alloc>
explicit bitset(const string& str,
typename string::size_type pos = 0,
typename string::size_type count = string::npos);
bitset<Bits>& operator&=(const bitset<Bits>& right);
bitset<Bits>& operator|=(const bitset<Bits>& right);
bitset<Bits>& operator^=(const bitset<Bits>& right);
bitset<Bits>& operator<<=(const bitset<Bits>& pos);
bitset<Bits>& operator>>=(const bitset<Bits>& pos);
bitset<Bits>& set();
bitset<Bits>& set(size_t pos, bool val = true);
bitset<Bits>& reset();
bitset<Bits>& reset(size_t pos);
bitset<Bits>& flip();
bitset<Bits>& flip(size_t pos);
reference operator[](size_t pos);
bool operator[](size_t pos) const;
unsigned long to_ulong() const;
template<class Elem, class Tr, class Alloc>
string to_string() const;
size_t count() const;
size_t size() const;
bool operator==(const bitset<Bits>& right) const;
bool operator!=(const bitset<Bits>& right) const;
bool test(size_t pos) const;
bool any() const;
bool none() const;
bitset<Bits> operator<<(size_t pos) const;
bitset<Bits> operator>>(size_t pos) const;
bitset<Bits> operator~() const;
};The template class describes an object that stores a
sequence of Bits bits. A bit is
set if its value is 1,
reset if its value is 0.
To flip a bit is to change its value
from 1 to 0 or from 0 to 1.
When converting between an object of
class bitset<Bits> and an object of some integral type,
bit position J corresponds to the bit value
1 << J. The integral value corresponding to two
or more bits is the sum of their bit values.
bool any() const;
The member function returns true if any bit is set in the
bit sequence.
bitset();
bitset(unsigned long val);
template<class Elem, class Tr, class Alloc>
explicit bitset(const string& str,
typename string::size_type pos = 0,
typename string::size_type count = string::npos);The first constructor resets all bits in the bit sequence.
The second constructor sets only those bits at position J
for which val & 1 << J is nonzero.
The third constructor determines the initial bit values from
elements of a string determined from str. If
str.size()
< pos, the constructor throws an object of class
out_of_range.
Otherwise, the effective length of the string rlen
is the smaller of count and
str.size() - pos. If any of the rlen
elements beginning at position pos is other than
0 or 1, the constructor throws an object of class
invalid_argument.
Otherwise, the constructor sets only those bits at position J
for which the element at position pos + J is 1.
size_t count() const;
The member function returns the number of bits set in the
bit sequence.
typedef bool element_type;
The type is a synonym for bool.
bitset<Bits>& flip();
bitset<Bits>& flip(size_t pos);
The first member function flips all bits in the bit sequence,
then returns *this.
The second member function throws
out_of_range if
size()
<= pos. Otherwise, it flips the bit
at position pos, then returns *this.
bool none() const;
The member function returns true if none of the bits are set
in the bit sequence.
bool operator !=(const bitset<Bits>& right) const;
The member operator function returns true
only if the bit sequence stored in
*this differs from the one stored in right.
bitset<Bits>& operator&=(const bitset<Bits>& right);
The member operator function replaces each element of the bit sequence stored
in *this with the logical AND of its previous value and
the corresponding bit in right.
The function returns *this.
bitset<Bits> operator<<(const bitset<Bits>& pos);
The member operator function returns bitset(*this)
<<= pos.
bitset<Bits>& operator<<=(const bitset<Bits>& pos);
The member operator function replaces
each element of the bit sequence stored
in *this with the element pos positions earlier
in the sequence. If no such earlier element exists, the function clears
the bit. The function returns *this.
bool operator ==(const bitset<Bits>& right) const;
The member operator function returns true
only if the bit sequence stored in
*this is the same as the one stored in right.
bitset<Bits> operator>>(const bitset<Bits>& pos);
The member operator function returns bitset(*this)
>>= pos.
bitset<Bits>& operator>>=(const bitset<Bits>& pos);
The member function replaces each element of the bit sequence stored
in *this with the element pos positions later
in the sequence. If no such later element exists, the function clears
the bit. The function returns *this.
bool operator[](size_type pos) const;
reference operator[](size_type pos);
The member function returns an object of class
reference,
which designates the bit at position pos,
if the object can be modified. Otherwise, it returns
the value of the bit at position pos
in the bit sequence. If that position is
invalid, the behavior is undefined.
bitset<Bits>& operator^=(const bitset<Bits>& right);
The member operator function replaces each element of the bit sequence stored
in *this with the logical
EXCLUSIVE OR of its previous value and
the corresponding bit in right.
The function returns *this.
bitset<Bits>& operator|=(const bitset<Bits>& right);
The member operator function replaces each element of the bit sequence stored
in *this with the logical OR of its previous value and
the corresponding bit in right.
The function returns *this.
bitset<Bits> operator~() const;
The member operator function returns
bitset(*this).flip().
class reference {
public:
reference& operator=(bool val};
reference& operator=(const reference& bitref);
bool operator~() const;
operator bool() const;
reference& flip();
};The member class describes an object that designates an
individual bit within the bit sequence. Thus, for val
an object of type bool, bs and bs2
objects of type bitset<Bits>, and
I and J
valid positions within such an object, the member functions
of class reference ensure that (in order):
bs[I] = val stores val at bit position
I in bsbs[I] = bs2[J] stores the value of the bit
bs2[J] at bit position
I in bsval = ~bs[I] stores the flipped value of the bit
bs[I] in valval = bs[I] stores the value of the bit
bs[I] in valbs[I].flip() stores the flipped value of the bit
bs[I] back at bit position
I in bs
bitset<Bits>& reset();
bitset<Bits>& reset(size_t pos);
The first member function resets (or clears) all bits in the bit sequence,
then returns *this.
The second member function throws
out_of_range if
size()
<= pos. Otherwise, it resets the bit
at position pos, then returns *this.
bitset<Bits>& set();
bitset<Bits>& set(size_t pos, bool val = true);
The first member function sets all bits in the bit sequence,
then returns *this.
The second member function throws
out_of_range if
size()
<= pos. Otherwise, it stores val in the bit
at position pos, then returns *this.
size_t size() const;
The member function returns Bits.
bool test(size_t pos);
The member function throws
out_of_range if
size()
<= pos. Otherwise, it returns true only if the bit
at position pos is set.
template<class Elem, class Tr, class Alloc>
string to_string() const;The member function constructs str, an object of class
string.
For each bit in the bit sequence, the function
appends 1 if the bit is set, otherwise 0.
The last element appended to str corresponds to
bit position zero. The function returns str.
unsigned long to_ulong() const;
The member function throws
overflow_error
if any bit in the bit sequence has a bit value that cannot be
represented as a value of type unsigned long. Otherwise,
it returns the sum of the bit values in the bit sequence.
template<size_t Bits>
bitset<Bits>
operator&(const bitset& left,
const bitset& right);The template function returns (temp = left) &= right,
where temp has type bitset<Bits>.
template<size_t Bits>
bitset<Bits>
operator|(const bitset& left,
const bitset& right);The template function returns (temp = left) |= right,
where temp has type bitset<Bits>.
template<size_t Bits>
bitset<Bits>
operator^(const bitset& left,
const bitset& right);The template function returns (temp = left) ^= right,
where temp has type bitset<Bits>.
template<class Elem, class Tr, size_t Bits>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
const bitset<Bits>& right);The template function overloads operator<<
to insert a text representation of the bit sequence in ostr.
It effectively executes ostr <<
right.to_string<Elem,
Tr, allocator<Elem> >(),
then returns ostr.
template<class Elem, class Tr, size_t Bits>
basic_istream<Elem, Tr>&
operator>>(basic_istream<Elem, Tr>& istr,
bitset<Bits>& right);The template function overloads operator>>
to store in right the value
bitset(str), where
str is an object of type
string& extracted
from istr. The function extracts elements and appends
them to str until:
Bits elements have been extracted and stored- end-of-file occurs on the input sequence
- the next input element is neither
0 nor 1,
in which case the input element is not extracted
If the function stores no characters in str, it calls
istr.setstate(ios_base::failbit).
In any case, it returns istr.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
4 - cassert
<cassert>
Include the standard header <cassert>
to effectively include the Standard C library header
<assert.h>.
#include <assert.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
5 - cctype
<cctype>
Include the standard header <cctype>
to effectively include the standard header
<ctype.h>.
#include <ctype.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
6 - cerrno
<cerrno>
Include the standard header <cerrno>
to effectively include the Standard C library header
<errno.h>.
#include <errno.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
7 - cfloat
<cfloat>
Include the standard header <cfloat>
to effectively include the Standard C library header
<float.h>.
#include <float.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
8 - charset
Characters
Character Sets
· Character Sets and Locales
· Escape Sequences
· Numeric Escape Sequences
· Trigraphs
· Multibyte Characters
· Wide-Character Encoding
Characters play a central role in Standard C. You represent
a C program as one or more
source files.
The translator reads a source file as a
text stream
consisting of characters that you can read when you
display the stream on a terminal screen or produce hard copy with a
printer. You often manipulate text when a C program executes. The
program might produce a text stream that people can read, or it might
read a text stream entered by someone typing at a keyboard
or from a file modified using a text editor.
This document describes the characters that you
use to write C source files and that you manipulate as streams
when executing C programs.
When you write a program, you express C source files as
text lines
containing characters from the
source character set.
When a program executes in the
target environment,
it uses characters from the
target character set.
These character sets are related, but need not have
the same encoding or all the same members.
Every character set contains a distinct code value for each
character in the
basic C character set.
A character set can also contain additional characters
with other code values. For example:
- The
character constant
'x' becomes the value of
the code for the character corresponding to x in the target
character set. - The
string literal
"xyz" becomes a sequence of
character constants stored in successive bytes of memory, followed
by a byte containing the value zero:
{'x', 'y', 'z', '\0'}
A string literal is one way to specify a
null-terminated string,
an array of zero or more bytes followed by a byte containing the
value zero.
Visible graphic characters
in the basic C character set:
Form Members
letter A B C D E F G H I J K L M
N O P Q R S T U V W X Y Z
a b c d e f g h i j k l m
n o p q r s t u v w x y z
digit 0 1 2 3 4 5 6 7 8 9
underscore _
punctuation ! " # % & ' ( ) * + , - . / :
; < = > ? [ \ ] ^ { | } ~Additional
graphic characters in the basic C character set:
Character Meaning
space leave blank space
BEL signal an alert (BELl)
BS go back one position (BackSpace)
FF go to top of page (Form Feed)
NL go to start of next line (NewLine)
CR go to start of this line (Carriage Return)
HT go to next Horizontal Tab stop
VT go to next Vertical Tab stop
The code value zero is reserved for the
null character
which is always in the target character set. Code values for the basic
C character set are positive when stored in an object of type char.
Code values for the digits are contiguous, with increasing value.
For example, '0' + 5 equals '5'.
Code values for any
two letters are not necessarily contiguous.
An implementation can support multiple
locales, each
with a different character set. A locale summarizes conventions particular
to a given culture, such as how to format dates or how to sort names.
To change locales and, therefore, target character sets while the
program is running, use the function
setlocale.
The translator encodes character constants and
string literals for the
"C" locale,
which is the locale in effect at program startup.
Within character constants and string literals, you can write
a variety of escape sequences. Each escape sequence determines
the code value for a single character. You use escape sequences
to represent character codes:
- you cannot otherwise write (such as
\n) - that can be difficult to read properly (such as
\t) - that might change value in different target character sets (such
as
\a) - that must not change in value among different target environments
(such as
\0)
An escape sequence takes the form shown in the diagram.
Mnemonic escape sequences
help you remember the characters they represent:
Character Escape Sequence
" \"
' \'
? \?
\ \\
BEL \a
BS \b
FF \f
NL \n
CR \r
HT \t
VT \v
You can also write numeric escape sequences using either
octal or hexadecimal digits. An
octal escape sequence
takes one of the forms:
\d or \dd or \ddd
The escape sequence yields a code value that is the numeric
value of the 1-, 2-, or 3-digit octal number following the backslash
(\). Each d can be
any digit in the range 0-7.
A
hexadecimal escape sequence takes one of the forms:
\xh or \xhh or ...
The escape sequence yields a code value that is the numeric
value of the arbitrary-length hexadecimal number following the backslash
(\). Each h can be any
decimal digit 0-9, or
any of the letters a-f or A-F.
The letters represent
the digit values 10-15, where either a or A has
the value 10.
A numeric escape sequence terminates with the first character
that does not fit the digit pattern. Here are some examples:
- You can write the
null character
as
'\0'. - You can write a newline character (
NL)
within a string literal by writing:
"hi\n" which becomes the array
{'h', 'i', '\n', 0} - You can write a string literal that begins with a specific numeric
value:
"\3abc" which becomes the array
{3, 'a', 'b', 'c', 0} - You can write a string literal that contains the hexadecimal
escape sequence
\xF followed by
the digit 3 by writing
two string literals:
"\xF" "3" which becomes the array
{0xF, '3', 0}
A trigraph is a sequence of three characters that begins
with two question marks (??). You use trigraphs to write C
source files with a character set that does not contain convenient
graphic representations for some punctuation characters. (The resultant
C source file is not necessarily more readable, but it is unambiguous.)
The list of all
defined trigraphs is:
Character Trigraph
[ ??(
\ ??/
] ??)
^ ??'
{ ??<
| ??!
} ??>
~ ??-
# ??=These are the only trigraphs. The translator does not alter any other
sequence that begins with two question marks.
For example, the expression statements:
printf("Case ??=3 is done??/n");
printf("You said what????/n");are equivalent to:
printf("Case #3 is done\n");
printf("You said what??\n");The translator replaces each trigraph with its equivalent single
character representation in an early
phase of translation.
You can always treat a trigraph as a single source character.
A source character set or target character set can also contain
multibyte characters (sequences of one or more bytes). Each
sequence represents a single character in the
extended character set.
You use multibyte characters to represent large sets of characters,
such as Kanji. A multibyte character can be a one-byte sequence that
is a character from the
basic C character set,
an additional one-byte sequence that is implementation defined,
or an additional sequence of two or more bytes that is
implementation defined.
Any multibyte encoding that contains sequences of two or more
bytes depends, for its interpretation between bytes, on a
conversion state determined
by bytes earlier in the sequence of characters. In the
initial conversion state
if the byte immediately following matches one of the characters
in the basic C character set, the byte must represent that character.
For example, the
EUC encoding is a superset of ASCII.
A byte value in the interval [0xA1, 0xFE] is the first of a two-byte
sequence (whose second byte value is in the interval [0x80, 0xFF]).
All other byte values are one-byte sequences. Since all members of the
basic C character set
have byte values in the range [0x00, 0x7F] in ASCII,
EUC meets the requirements
for a multibyte encoding in Standard C. Such a sequence is not
in the initial conversion state immediately after a byte value in
the interval [0xA1, 0xFe]. It is ill-formed if a second byte
value is not in the interval [0x80, 0xFF].
Multibyte characters can also have a
state-dependent encoding.
How you interpret a byte in such an encoding depends on a
conversion state that involves both a
parse state, as before, and a
shift state, determined
by bytes earlier in the sequence of characters. The
initial shift state,
at the beginning of a new multibyte character, is also the
initial conversion state. A subsequent
shift sequence can determine an
alternate shift state,
after which all byte sequences (including one-byte sequences) can have
a different interpretation. A byte containing the value zero,
however, always represents the
null character.
It cannot occur as any of the bytes of another multibyte character.
For example, the
JIS encoding is another superset of ASCII.
In the initial shift state, each byte represents a single character,
except for two three-byte shift sequences:
- The three-byte sequence
"\x1B$B" shifts to two-byte mode.
Subsequently, two successive bytes (both with values
in the range [0x21, 0x7E]) constitute a single multibyte character. - The three-byte sequence
"\x1B(B" shifts back
to the initial shift state.
JIS also meets the requirements for a multibyte encoding in Standard C.
Such a sequence is not in the initial conversion state
when partway through a three-byte shift sequence
or when in two-byte mode.
You can write multibyte characters in C source text as part
of a comment, a character constant, a string literal, or a filename in an
include directive.
How such characters print is implementation
defined. Each sequence of multibyte characters that you write must
begin and end in the initial shift state.
The program can also include multibyte characters in
null-terminated
C strings
used by several library functions, including the
format strings for
printf and
scanf.
Each such character string must begin and end
in the initial shift state.
Each character in the extended character set also has an integer
representation, called a wide-character encoding.
Each extended character has a unique wide-character value.
The value zero always corresponds to the
null wide character.
The type definition
wchar_t
specifies the integer type that represents wide characters.
You write a
wide-character constant
as L'mbc', where mbc represents
a single multibyte character.
You write a
wide-character string literal as L"mbs",
where mbs represents
a sequence of zero or more multibyte characters.
The wide-character string literal
L"xyz" becomes a sequence of
wide-character constants stored in successive bytes of memory, followed
by a null wide character:
{L'x', L'y', L'z', L'\0'}
The following library functions
help you convert between the multibyte
and wide-character representations of extended characters:
mblen,
mbstowcs,
mbtowc,
wcstombs,
wctomb.
The macro
MB_LEN_MAX
specifies the length of the longest possible multibyte sequence required
to represent a single character defined by the implementation across
supported locales. And the macro
MB_CUR_MAX
specifies the length of the longest possible multibyte sequence required
to represent a single character defined for the current
locale.
For example, the
string literal
"hello" becomes an array of six char:
{'h', 'e', 'l', 'l', 'o', 0}while the wide-character string literal
L"hello" becomes
an array of six integers of type
wchar_t:
{L'h', L'e', L'l', L'l', L'o', 0}
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
9 - climits
<climits>
Include the standard header <climits>
to effectively include the Standard C library header
<limits.h>.
#include <limits.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
10 - clocale
<clocale>
Include the standard header <clocale>
to effectively include the standard header
<locale.h>.
#include <locale.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
11 - cmath
<cmath>
Include the standard header <cmath>
to effectively include the standard header
<math.h>.
#include <math.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
12 - complex
<complex>
abs
· arg
· complex
· conj
· cos
· cosh
· double_complex
· exp
· float_complex
· imag
· log
· log10
· norm
· operator!=
· operator*
· operator+
· operator-
· operator/
· operator<<
· operator==
· operator>>
· polar
· pow
· real
· sin
· sinh
· sqrt
· tan
· tanh
· __STD_COMPLEX
Include the standard header <complex>
to define classes double_complex and float_complex and a host of
supporting functions.
Unless otherwise specified,
functions that can return multiple values return an imaginary
part in the half-open interval (-pi, pi].
// DECLARATIONS
#define __STD_COMPLEX
// CLASSES
class double_complex;
class float_complex;
// double_complex FUNCTIONS
double_complex operator+(const double_complex& left,
const double_complex& right);
double_complex operator+(const double_complex& left,
const double& right);
double_complex operator+(const double& left,
const double_complex& right);
double_complex operator-(const double_complex& left,
const double_complex& right);
double_complex operator-(const double_complex& left,
const double& right);
double_complex operator-(const double& left,
const double_complex& right);
double_complex operator*(const double_complex& left,
const double_complex& right);
double_complex operator*(const double_complex& left,
const double& right);
double_complex operator*(const double& left,
const double_complex& right);
double_complex operator/(const double_complex& left,
const double_complex& right);
double_complex operator/(const double_complex& left,
const double& right);
double_complex operator/(const double& left,
const double_complex& right);
double_complex operator+(const double_complex& left);
double_complex operator-(const double_complex& left);
bool operator==(const double_complex& left,
const double_complex& right);
bool operator==(const double_complex& left,
const double& right);
bool operator==(const double& left,
const double_complex& right);
bool operator!=(const double_complex& left,
const double_complex& right);
bool operator!=(const double_complex& left,
const double& right);
bool operator!=(const double& left,
const double_complex& right);
istream& operator>>(istream& istr, double_complex& right);
ostream& operator<<(ostream& ostr, const double_complex& right);
double real(const double_complex& left);
double imag(const double_complex& left);
double abs(const double_complex& left);
double arg(const double_complex& left);
double norm(const double_complex& left);
double_complex conj(const double_complex& left);
double_complex polar(const double& rho,
const double& theta = 0);
double_complex cos(const double_complex& left);
double_complex cosh(const double_complex& left);
double_complex exp(const double_complex& left);
double_complex log(const double_complex& left);
double_complex log10(const double_complex& left);
double_complex pow(const double_complex& left, int right);
double_complex pow(const double_complex& left,
const double& right);
double_complex pow(const double_complex& left,
const double_complex& right);
double_complex pow(const double& left,
const double_complex& right);
double_complex sin(const double_complex& left);
double_complex sinh(const double_complex& left);
double_complex sqrt(const double_complex& left);
// float_complex FUNCTIONS
bool operator==(const float& left,
const float_complex& right);
bool operator!=(const float_complex& left,
const float_complex& right);
bool operator!=(const float_complex& left,
const float& right);
bool operator!=(const float& left,
const float_complex& right);
istream& operator>>(istream& istr, float_complex& right);
ostream& operator<<(ostream& ostr, const float_complex& right);
float real(const float_complex& left);
float imag(const float_complex& left);
float abs(const float_complex& left);
float arg(const float_complex& left);
float norm(const float_complex& left);
float_complex conj(const float_complex& left);
float_complex polar(const float& rho,
const float& theta = 0);
float_complex cos(const float_complex& left);
float_complex cosh(const float_complex& left);
float_complex exp(const float_complex& left);
float_complex log(const float_complex& left);
float_complex log10(const float_complex& left);
float_complex pow(const float_complex& left, int right);
float_complex pow(const float_complex& left,
const float& right);
float_complex pow(const float_complex& left,
const float_complex& right);
float_complex pow(const float& left,
const float_complex& right);
float_complex sin(const float_complex& left);
float_complex sinh(const float_complex& left);
float_complex sqrt(const float_complex& left);
// END OF DECLARATIONSdouble abs(const double_complex& left);
float abs(const float_complex& left);
The function returns the magnitude of left.
double arg(const double_complex& left);
float arg(const float_complex& left);
The function returns the phase angle of left.
template<class Ty>
class complex {
public:
typedef Ty value_type;
Ty real() const;
Ty imag() const;
complex(const Ty& realval = 0, const Ty& imagval = 0);
complex(const complex& right);
complex& operator=(const complex& right);
complex& operator+=(const complex& right);
complex& operator-=(const complex& right);
complex& operator*=(const complex& right);
complex& operator/=(const complex& right);
complex& operator=(const Ty& right);
complex& operator=(const Ty& right);
complex& operator+=(const Ty& right);
complex& operator-=(const Ty& right);
complex& operator*=(const Ty& right);
complex& operator/=(const Ty& right);
};The template class doesn't really exist. It is a convenient fiction
for describing the behavior common to the two types:
The template class describes an object that stores two objects
of type Ty, one that represents the real part
of a complex number and one that represents the imaginary part.
complex(const Ty& realval = 0, const Ty& imagval = 0);
complex(const complex& right);
The first constructor initializes the stored real part to
realval and the stored imaginary part to imagval.
The second constructor initializes the stored real part to
right.real() and the stored imaginary part to
right.imag().
Ty imag() const;
The member function returns the stored imaginary part.
complex& operator*=(const complex& right);
complex& operator*=(const Ty& right);
The first member function replaces the stored real and imaginary parts
with those corresponding to the complex product of *this
and right. It then returns *this.
The second member function multiplies both the stored real part
and the stored imaginary part with right.
It then returns *this.
complex& operator+=(const complex& right);
complex& operator+=(const Ty& right);
The first member function replaces the stored real and imaginary parts
with those corresponding to the complex sum of *this
and right. It then returns *this.
The second member function adds right to the stored real part.
It then returns *this.
complex& operator-=(const complex& right);
complex& operator-=(const Ty& right);
The first member function replaces the stored real and imaginary parts
with those corresponding to the complex difference of *this
and right. It then returns *this.
The second member function subtracts right from
the stored real part. It then returns *this.
complex& operator/=(const complex& right);
complex& operator/=(const Ty& right);
The first member function replaces the stored real and imaginary parts
with those corresponding to the complex quotient of *this
and right. It then returns *this.
The second member function multiplies both the stored real part
and the stored imaginary part with right.
It then returns *this.
complex& operator=(const complex& right);
complex& operator=(const Ty& right);
The first member function replaces the stored real part with
right.real() and the stored imaginary part
with right.imag(). It then returns *this.
The second member function replaces the stored real part with
right and the stored imaginary part
with zero. It then returns *this.
Ty real() const;
The member function returns the stored real part.
typedef Ty value_type;
The type is a synonym for the template parameter Ty.
double_complex conj(const double_complex& left);
float_complex conj(const float_complex& left);
The function returns the conjugate of left.
double_complex cos(const double_complex& left);
float_complex cos(const float_complex& left);
The function returns the cosine of left.
double_complex cosh(const double_complex& left);
float_complex cosh(const float_complex& left);
The function returns the hyperbolic cosine of left.
class double_complex : public complex<double> {
public:
double_complex(double realval = 0, double imagval = 0);
double_complex(const float_complex& right);
double_complex& operator=(const double right);
};The class describes an object that stores two objects
of type double, one that represents the real part
of a complex number and one that represents the imaginary part.
The class differs from its fictitious base class
complex<double>
only in the constructors it defines.
The first constructor initializes the stored real part to
realval and the stored imaginary part to imagval.
The second constructor initializes the stored real part to
right.real() and the stored imaginary part to
right.imag().
The assignment operator stores right in the stored real part
and zero in the stored imaginary part.
double_complex exp(const double_complex& left);
float_complex exp(const float_complex& left);
The function returns the exponential of left.
class float_complex : public complex<float> {
public:
float_complex(float realval = 0, float imagval = 0);
explicit float_complex(const double_complex& right);
float_complex& operator=(const float right);
};The class describes an object that stores two objects
of type float, one that represents the real part
of a complex number and one that represents the imaginary part.
The class differs from its fictitious base class
complex<float>
only in the constructors it defines.
The first constructor initializes the stored real part to
realval and the stored imaginary part to imagval.
The second constructor initializes the stored real part to
right.real() and the stored imaginary part to
right.imag().
The assignment operator stores right in the stored real part
and zero in the stored imaginary part.
double imag(const double_complex& left);
float imag(const float_complex& left);
The function returns the imaginary part of left.
double_complex log(const double_complex& left);
float_complex log(const float_complex& left);
The function returns the logarithm of left.
The branch cuts are along the negative real axis.
double_complex log10(const double_complex& left);
float_complex log10(const float_complex& left);
The function returns the base 10
logarithm of left.
The branch cuts are along the negative real axis.
double norm(const double_complex& left);
float norm(const float_complex& left);
The function returns the squared magnitude of left.
bool operator!=(const double_complex& left,
const double_complex& right);
bool operator!=(const double_complex& left,
const double& right);
bool operator!=(const double& left,
const double_complex& right);
bool operator!=(const float_complex& left,
const float_complex& right);
bool operator!=(const float_complex& left,
const float& right);
bool operator!=(const float& left,
const float_complex& right);The operators each return true only if
real(left) != real(right) ||
imag(left) != imag(right).
double_complex operator*(const double_complex& left,
const double_complex;& right);
double_complex operator*(const double_complex& left,
const double& right);
double_complex operator*(const double& left,
const double_complex& right);
float_complex operator*(const float_complex& left,
const float_complex;& right);
float_complex operator*(const float_complex& left,
const float& right);
float_complex operator*(const float& left,
const float_complex& right);The operators each convert both operands to the return type,
then return the complex product
of the converted left and right.
double_complex operator+(const double_complex& left,
const double_complex;& right);
double_complex operator+(const double_complex& left,
const double& right);
double_complex operator+(const double& left,
const double_complex& right);
double_complex operator+(const double_complex& left);
float_complex operator+(const float_complex& left,
const float_complex;& right);
float_complex operator+(const float_complex& left,
const float& right);
float_complex operator+(const float& left,
const float_complex& right);
float_complex operator+(const float_complex& left);The binary operators each convert both operands to the return type,
then return the complex sum
of the converted left and right.
The unary operator returns left.
double_complex operator-(const double_complex& left,
const double_complex;& right);
double_complex operator-(const double_complex& left,
const double& right);
double_complex operator-(const double& left,
const double_complex& right);
double_complex operator-(const double_complex& left);
float_complex operator-(const float_complex& left,
const float_complex;& right);
float_complex operator-(const float_complex& left,
const float& right);
float_complex operator-(const float& left,
const float_complex& right);
float_complex operator-(const float_complex& left);The binary operators each convert both operands to the return type,
then return the complex difference
of the converted left and right.
The unary operator returns a value whose real part is
-real(left) and whose imaginary part is
-imag(left).
double_complex operator/(const double_complex& left,
const double_complex;& right);
double_complex operator/(const double_complex& left,
const double& right);
double_complex operator/(const double& left,
const double_complex& right);
float_complex operator/(const float_complex& left,
const float_complex;& right);
float_complex operator/(const float_complex& left,
const float& right);
float_complex operator/(const float& left,
const float_complex& right);The operators each convert both operands to the return type,
then return the complex quotient
of the converted left and right.
ostream& operator<<(ostream& ostr,
const double_complex& right);
ostream& operator<<(ostream& ostr,
const float_complex& right);The template function inserts the complex value right
in the output stream ostr, effectively by executing:
ostringstream osstr;
osstr.flags(ostr.flags());
osstr.precision(ostr.precision());
osstr << '(' << real(right) << ','
<< imag(right) << ')';
ostr << osstr.str().c_str();Thus, if
ostr.width() is
greater than zero, any padding occurs either before or after the
parenthesized pair of values, which itself contains no padding.
The function returns ostr.
bool operator==(const double_complex& left,
const double_complex& right);
bool operator==(const double_complex& left,
const double& right);
bool operator==(const double& left,
const double_complex& right);
bool operator==(const float_complex& left,
const float_complex& right);
bool operator==(const float_complex& left,
const float& right);
bool operator==(const float& left,
const float_complex& right);The operators each return true only if
real(left) == real(right) &&
imag(left) == imag(right).
istream& operator>>(istream& istr,
double_complex& right);
istream& operator>>(istream& istr,
float_complex& right);The template function attempts to extract a complex value
from the input stream istr, effectively by executing:
istr >> ch && ch == '('
&& istr >> re >> ch && ch == ','
&& istr >> im >> ch && ch == ')'Here, ch is an object of type char,
and re and im are objects of the same type
as right.real().
If the result of this expression is true, the function stores
re in the real part and im in the
imaginary part of right. In any event, the function
returns istr.
double_complex polar(const double& rho,
const double& theta = 0);
float_complex polar(const float& rho,
const float& theta);The function returns the complex value whose magnitude
is rho and whose phase angle is theta.
double_complex pow(const double_complex& left, int right);
double_complex pow(const double_complex& left, const Ty& right);
double_complex pow(const double_complex& left,
const double_complex& right);
double_complex pow(const Ty& left, const double_complex& right);
float_complex pow(const float_complex& left, int right);
float_complex pow(const float_complex& left, const Ty& right);
float_complex pow(const float_complex& left,
const float_complex& right);
float_complex pow(const Ty& left, const float_complex& right);The functions each effectively convert both operands to
the return type, then return the converted
left to the power right.
The branch cut for left is along the negative real axis.
double real(const double_complex& left);
float real(const float_complex& left);
The function returns the real part of left.
double_complex sin(const double_complex& left);
float_complex sin(const float_complex& left);
The function returns the sine of left.
double_complex sinh(const double_complex& left);
float_complex sinh(const float_complex& left);
The function returns the hyperbolic sine of left.
double_complex sqrt(const double_complex& left);
float_complex sqrt(const float_complex& left);
The function returns the square root of left,
with phase angle in the half-open interval (-pi/2, pi/2].
The branch cuts are along the negative real axis.
#define __STD_COMPLEX
The macro is defined, with an unspecified expansion, to indicate
compliance with the specifications of this header.
double_complex tan(const double_complex& left);
float_complex tan(const float_complex& left);
The function returns the tangent of left.
double_complex tanh(const double_complex& left);
float_complex tanh(const float_complex& left);
The function returns the hyperbolic tangent of left.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
13 - crit_pb
Dinkumware, Ltd. Copyright and License NoticeDinkumware, Ltd.
Genuine Software
Copyright and License Notice
Dinkumware, Ltd.
398 Main Street
Concord MA 01742
USA
+1-978-371-2773
Dinkum C Library developed by P.J. Plauger
Dinkum C Library Reference developed by P.J. Plauger and Jim Brodie
The Dinkum C Library in machine-readable or printed form
(“Dinkum Library”) and the Dinkum C Library Reference in
machine-readable or printed form (“Dinkum Reference”), hereafter
in whole or in part the “Product,” are all copyright © 1992-2002 by
P.J. Plauger. ALL RIGHTS RESERVED. The Product is derived in part
from books copyright © 1989-1996 by P.J. Plauger, or by P.J. Plauger
and Jim Brodie.
Dinkumware, Ltd. and P.J. Plauger (“Licensor”) retain exclusive
ownership of this Product. It is licensed to you (“Licensee”) in
accordance with the terms specifically stated in this Notice. If you have
obtained this Product from a third party or under a special license from
Dinkumware, Ltd., additional restrictions may also apply. You
must otherwise treat the Product the same as other copyrighted
material, such as a book or recording. You may also exercise
certain rights particular to computer software under copyright law.
In particular:
- You may use the Library portion of the Product (if present)
to compile and link with C/C++ code to produce executable files.
- You may freely distribute such executable files for no additional
license fee to Licensor.
- You may make one or more backup copies of the Product for
archival purposes.
- You may permanently transfer ownership of the Product to another
party only if the other party agrees to the terms stated in this
Notice and you transfer or destroy all copies of the Product that
are in your posession.
- You must preserve this Notice and all copyright notices with
any copy you make of the Product.
- You may not loan, rent, or sublicense the Product.
- You may not copy or distribute, in any form, any part of this
Product for any purpose not specifically permitted by this Notice.
This copy of the Product is licensed for use by a limited number of
developers, which is specified as part of the packaging for this
Product. A license for up to ten users, for example, limits to ten
the number of developers reasonably able to use the Product at any
instant of time. Thus, ten is the maximum number of possible
concurrent users, not the number of actual concurrent users. A
single-user license is for use by just one developer.
Anyone who accesses this software has a moral responsibility not to
aid or abet illegal copying by others. Licensor recognizes that the
machine-readable format of the Product makes it particularly
conducive to sharing within multi-user systems and across networks.
Such use is permitted only so long as Licensee does not exceed the
maximum number of possible concurrent users and takes reasonable
precautions to protect the Product against unauthorized copying and
against public access. In particular, please note that the ability
to access this copy does not imply permission to use
it or to copy it.
Please note also that Licensor has expended considerable
professional effort in the production of this Product, and continues
to do so to keep it current.
Licensor warrants that the Product as shipped performs substantially
in accordance with its documented purpose, and that the medium on
which the Product is provided is free from defects in material and
workmanship. To the extent permitted by law, any implied warranties
on the Product are limited to 90 days.
Licensor's entire liability under this warranty shall be, at
Licensor's option, either to refund the license fee paid by
Licensee or to replace the medium on which the Product is provided.
This is also Licensee's exclusive remedy. To qualify for this
remedy, Licensee must demonstrate satisfactory proof of purchase to
Licensor and return the Product in reasonably good condition to
Licensor.
LICENSOR OTHERWISE MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE
SUITABILITY OF THIS PRODUCT, EITHER EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. LICENSOR
SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A
RESULT OF USING THIS PRODUCT, EVEN IF LICENSOR HAS BEEN ADVISED OF
THE POSSIBILITY OF SUCH DAMAGES. TO THE EXTENT PERMITTED BY LAW,
LICENSOR SHALL NOT BE LIABLE FOR CONSEQUENTIAL OR INCIDENTAL
DAMAGES.
By using this Product, you agree to abide by the intellectual
property laws and all other applicable laws of the USA, and the
terms described above. You may be held legally responsible for any
infringement that is caused or encouraged by your failure to abide
by the terms of this Notice.
RESTRICTED RIGHTS: Use, duplication, or disclosure by the government
is subject to the restrictions as set forth in subparagraph
(c)(1)(ii) of the Rights in Technical Data and Computer Software
Clause as DFARS 52.227-7013 and FAR 52.227-19. Unpublished rights
are reserved under the Copyright Laws of the USA. Contractor/
Manufacturer is DINKUMWARE, LTD., 398 Main Street, Concord MA 01742.
The terms of this notice shall be governed by the laws of the
Commonwealth of Massachusetts. THE RIGHTS AND OBLIGATIONS OF THE
PARTIES SHALL NOT BE GOVERNED BY THE PROVISIONS OF THE U.N.
CONVENTION FOR THE INTERNATIONAL SALE OF GOODS, 1980.
This Copyright and License Notice is the entire agreement of the
parties with respect to the matters set forth herein, and supersedes
any other oral or written agreements or communications relating
thereto, and shall alone be binding. No provision appearing on any
purchase order, quotation form, or other form originated by either
party shall be applicable.
Dinkumware and Dinkum are registered trademarks of Dinkumware, Ltd.
End of Copyright and License Notice
- ANSI Standard X3.159-1989
(New York NY: American National Standards Institute, 1989).
The original C Standard, developed by
the ANSI-authorized committee X3J11. The Rationale that accompanies
the C Standard explains many of the decisions that went into it, if
you can get your hands on a copy.
- ISO/IEC Standard 9899:1990
(Geneva: International Standards Organization, 1990).
Until 1999, the official C Standard around the world. Aside
from formatting details and section numbering, the ISO C Standard
is identical to the ANSI C Standard.
- ISO/IEC Amendment 1 to Standard 9899:1990
(Geneva: International Standards Organization, 1995).
The first (and only) amendment to the C Standard.
It provides substantial support for manipulating large character sets.
- ISO/IEC Standard 9899:1999
(Geneva: International Standards Organization, 1999).
The official C Standard around the world, replacing ISO/IEC
Standard 9899:1990.
- P.J. Plauger, The Standard C Library (Englewood Cliffs
NJ: Prentice Hall, 1992). Contains a complete implementation of the
Standard C library, as of 1992 at least,
as well as text from the library portion of the
C Standard and guidance in using the Standard C library.
- P.J. Plauger and Jim Brodie, Standard C: A Programmer's
Reference (Redmond WA: Microsoft Press, 1989).
The first complete but succinct reference to the entire C Standard.
It covers both the language and the library.
- P.J. Plauger and Jim Brodie, ANSI and ISO Standard C:
Programmer's Reference (Redmond WA: Microsoft Press, 1992).
An update to the above book.
- P.J. Plauger and Jim Brodie, Standard C (Englewood Cliffs NJ:
PTR Prentice Hall, 1996). An update to the above two books and
a principal source book for this material. It includes a
complete description of Amendment 1.
The authors welcome reports of any errors or omissions.
Please report any bugs or difficulties to:
Dinkumware Support
Dinkumware, Ltd.
398 Main Street
Concord MA 01742-2321
USA
+1-978-371-2773 (UTC -4 hours, -5 November through March)
+1-978-371-9014 (FAX)
support@dinkumware.com
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
14 - crit_pjp
Dinkumware, Ltd. Copyright and License NoticeDinkumware, Ltd.
Genuine Software
Copyright and License Notice
Dinkumware, Ltd.
398 Main Street
Concord MA 01742
USA
+1-978-371-2773
Dinkum C++ Library developed by P.J. Plauger
Dinkum C++ Library Reference developed by P.J. Plauger
The Dinkum C++ Library in machine-readable or printed form
(“Dinkum Library”) and the Dinkum C++ Library Reference in
machine-readable or printed form (“Dinkum Reference”), hereafter
in whole or in part the “Product,” are all copyright © 1989-2002 by
P.J. Plauger. ALL RIGHTS RESERVED. The Product is derived in part
from books copyright © 1992-2002 by P.J. Plauger.
Dinkumware, Ltd. and P.J. Plauger (“Licensor”) retain exclusive
ownership of this Product. It is licensed to you (“Licensee”) in
accordance with the terms specifically stated in this Notice. If you have
obtained this Product from a third party or under a special license from
Dinkumware, Ltd., additional restrictions may also apply. You
must otherwise treat the Product the same as other copyrighted
material, such as a book or recording. You may also exercise
certain rights particular to computer software under copyright law.
In particular:
- You may use the Library portion of the Product (if present)
to compile and link with C/C++ code to produce executable files.
- You may freely distribute such executable files for no additional
license fee to Licensor.
- You may make one or more backup copies of the Product for
archival purposes.
- You may permanently transfer ownership of the Product to another
party only if the other party agrees to the terms stated in this
Notice and you transfer or destroy all copies of the Product that
are in your posession.
- You must preserve this Notice and all copyright notices with
any copy you make of the Product.
- You may not loan, rent, or sublicense the Product.
- You may not copy or distribute, in any form, any part of this
Product for any purpose not specifically permitted by this Notice.
This copy of the Product is licensed for use by a limited number of
developers, which is specified as part of the packaging for this
Product. A license for up to ten users, for example, limits to ten
the number of developers reasonably able to use the Product at any
instant of time. Thus, ten is the maximum number of possible
concurrent users, not the number of actual concurrent users. A
single-user license is for use by just one developer.
Anyone who accesses this software has a moral responsibility not to
aid or abet illegal copying by others. Licensor recognizes that the
machine-readable format of the Product makes it particularly
conducive to sharing within multi-user systems and across networks.
Such use is permitted only so long as Licensee does not exceed the
maximum number of possible concurrent users and takes reasonable
precautions to protect the Product against unauthorized copying and
against public access. In particular, please note that the ability
to access this copy does not imply permission to use
it or to copy it.
Please note also that Licensor has expended considerable
professional effort in the production of this Product, and continues
to do so to keep it current.
Licensor warrants that the Product as shipped performs substantially
in accordance with its documented purpose, and that the medium on
which the Product is provided is free from defects in material and
workmanship. To the extent permitted by law, any implied warranties
on the Product are limited to 90 days.
Licensor's entire liability under this warranty shall be, at
Licensor's option, either to refund the license fee paid by
Licensee or to replace the medium on which the Product is provided.
This is also Licensee's exclusive remedy. To qualify for this
remedy, Licensee must demonstrate satisfactory proof of purchase to
Licensor and return the Product in reasonably good condition to
Licensor.
LICENSOR OTHERWISE MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE
SUITABILITY OF THIS PRODUCT, EITHER EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. LICENSOR
SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A
RESULT OF USING THIS PRODUCT, EVEN IF LICENSOR HAS BEEN ADVISED OF
THE POSSIBILITY OF SUCH DAMAGES. TO THE EXTENT PERMITTED BY LAW,
LICENSOR SHALL NOT BE LIABLE FOR CONSEQUENTIAL OR INCIDENTAL
DAMAGES.
By using this Product, you agree to abide by the intellectual
property laws and all other applicable laws of the USA, and the
terms described above. You may be held legally responsible for any
infringement that is caused or encouraged by your failure to abide
by the terms of this Notice.
RESTRICTED RIGHTS: Use, duplication, or disclosure by the government
is subject to the restrictions as set forth in subparagraph
(c)(1)(ii) of the Rights in Technical Data and Computer Software
Clause as DFARS 52.227-7013 and FAR 52.227-19. Unpublished rights
are reserved under the Copyright Laws of the USA. Contractor/
Manufacturer is DINKUMWARE, LTD., 398 Main Street, Concord MA 01742.
The terms of this notice shall be governed by the laws of the
Commonwealth of Massachusetts. THE RIGHTS AND OBLIGATIONS OF THE
PARTIES SHALL NOT BE GOVERNED BY THE PROVISIONS OF THE U.N.
CONVENTION FOR THE INTERNATIONAL SALE OF GOODS, 1980.
This Copyright and License Notice is the entire agreement of the
parties with respect to the matters set forth herein, and supersedes
any other oral or written agreements or communications relating
thereto, and shall alone be binding. No provision appearing on any
purchase order, quotation form, or other form originated by either
party shall be applicable.
Dinkumware and Dinkum are registered trademarks of Dinkumware, Ltd.
End of Copyright and License Notice
- ANSI Standard X3.159-1989
(New York NY: American National Standards Institute, 1989).
The original C Standard, developed by
the ANSI-authorized committee X3J11. The Rationale that accompanies
the C Standard explains many of the decisions that went into it, if
you can get your hands on a copy.
- ISO/IEC Standard 9899:1990
(Geneva: International Standards Organization, 1990).
Until 1999, the official C Standard around the world. Aside
from formatting details and section numbering, the ISO C Standard
is identical to the ANSI C Standard.
- ISO/IEC Amendment 1 to Standard 9899:1990
(Geneva: International Standards Organization, 1995).
The first (and only) amendment to the C Standard.
It provides substantial support for manipulating large character sets.
- ISO/IEC Standard 9899:1999
(Geneva: International Standards Organization, 1999).
The official C Standard around the world, replacing ISO/IEC
Standard 9899:1990.
- ISO/IEC Standard 14882:1998
(Geneva: International Standards Organization, 1998). The official
C++ Standard around the world.
The ISO C++ Standard is identical to the ANSI C++ Standard.
- P.J. Plauger, The Standard C Library (Englewood Cliffs
NJ: Prentice Hall, 1992). Contains a complete implementation of the
Standard C library, as of 1992 at least,
as well as text from the library portion of the
C Standard and guidance in using the Standard C library.
- P.J. Plauger, The Draft Standard C++ Library
(Englewood Cliffs NJ: Prentice Hall, 1995).
Contains a complete implementation
of the draft Standard C++ library as of early 1994.
- P.J. Plauger, Alexander Stepanov, Meng Lee, and David R. Musser,
The Standard Template Library (Englewood Cliffs NJ: Prentice
Hall, 2001). Contains a complete implementation of the Standard
Template Library as incorporated into the C++ Standard.
The author welcomes reports of any errors or omissions.
Please report any bugs or difficulties to:
Dinkumware Support
Dinkumware, Ltd.
398 Main Street
Concord MA 01742-2321
USA
+1-978-371-2773 (UTC -4 hours, -5 November through March)
+1-978-371-9014 (FAX)
support@dinkumware.com
See also the
Table of Contents and the
Index.
Copyright © 1989-2002 by P.J. Plauger. All rights reserved.
15 - csetjmp
<csetjmp>
Include the standard header <csetjmp>
to effectively include the standard header
<setjmp.h>.
#include <setjmp.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
16 - csignal
<csignal>
Include the standard header <csignal>
to effectively include the standard header
<signal.h>.
#include <signal.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
17 - cstdarg
<cstdarg>
Include the standard header <cstdarg>
to effectively include the standard header
<stdarg.h>.
#include <stdarg.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
18 - cstddef
<cstddef>
Include the standard header <cstddef>
to effectively include the standard header
<stddef.h>.
#include <stddef.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
19 - cstdio
<cstdio>
Include the standard header <cstdio>
to effectively include the standard header
<stdio.h>.
#include <stdio.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
20 - cstdlib
<cstdlib>
Include the standard header <cstdlib>
to effectively include the standard header
<stdlib.h>.
#include <stdlib.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
21 - cstring
<cstring>
Include the standard header <cstring>
to effectively include the standard header
<string.h>.
#include <string.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
22 - ctime
<ctime>
Include the standard header <ctime>
to effectively include the standard header
<time.h>.
#include <time.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
23 - ctype
<ctype.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
24 - cwchar
<cwchar>
Include the standard header <cwchar>
to define the macros traditionally defined in the Standard C library header
<wchar.h>.
Including this header also ensures that the names declared
with external linkage in the Standard C library header
are declared in the
std namespace.
In this implementation,
the names may or may not also be declared in the global namespace,
depending on the specific translation environment.
#if <TRADITIONAL C HEADERS>
#include <wchar.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
25 - cwctype
<cwctype>
Include the standard header <cwctype>
to define the macros traditionally defined in the Standard C library header
<wctype.h>.
Including this header also ensures that the names declared
with external linkage in the Standard C library header
are declared in the
std namespace.
In this implementation,
the names may or may not also be declared in the global namespace,
depending on the specific translation environment.
#if <TRADITIONAL C HEADERS>
#include <wctype.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
26 - deque
<deque>
Include the STL
standard header <deque> to define the
container
template class deque and several supporting
templates.
namespace std {
template<class Ty, class Alloc>
class deque;
// TEMPLATE FUNCTIONS
template<class Ty, class Alloc>
bool operator==(
const deque<Ty, Alloc>& left,
const deque<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator!=(
const deque<Ty, Alloc>& left,
const deque<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator<(
const deque<Ty, Alloc>& left,
const deque<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator>(
const deque<Ty, Alloc>& left,
const deque<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator<=(
const deque<Ty, Alloc>& left,
const deque<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator>=(
const deque<Ty, Alloc>& left,
const deque<Ty, Alloc>& right);
template<class Ty, class Alloc>
void swap(
deque<Ty, Alloc>& left,
deque<Ty, Alloc>& right);
};
allocator_type
· assign
· at
· back
· begin
· clear
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· deque
· difference_type
· empty
· end
· erase
· front
· get_allocator
· insert
· iterator
· max_size
· operator[]
· pointer
· pop_back
· pop_front
· push_back
· push_front
· rbegin
· reference
· rend
· resize
· reverse_iterator
· size
· size_type
· swap
· value_type
template<class Ty, class Alloc = allocator<Ty> >
class deque {
public:
typedef Alloc allocator_type;
typedef typename Alloc::pointer pointer;
typedef typename Alloc::const_pointer const_pointer;
typedef typename Alloc::reference reference;
typedef typename Alloc::const_reference const_reference;
typedef typename Alloc::value_type value_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;
deque();
explicit deque(const Alloc& al);
explicit deque(size_type count);
deque(size_type count, const Ty& val);
deque(size_type count, const Ty& val,
const Alloc& al);
deque(const deque& right);
template<class InIt>
deque(InIt first, InIt last);
template<class InIt>
deque(InIt first, InIt last, const Alloc& al);
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;
void resize(size_type newsize);
void resize(size_type newsize, Ty val);
size_type size() const;
size_type max_size() const;
bool empty() const;
Alloc get_allocator() const;
reference at(size_type pos);
const_reference at(size_type pos) const;
reference operator[](size_type pos);
const_reference operator[](size_type pos);
reference front();
const_reference front() const;
reference back();
const_reference back() const;
void push_front(const Ty& val);
void pop_front();
void push_back(const Ty& val);
void pop_back();
template<class InIt>
void assign(InIt first, InIt last);
void assign(size_type count, const Ty& val);
iterator insert(iterator where, const Ty& val);
void insert(iterator where, size_type count, const Ty& val);
template<class InIt>
void insert(iterator where, InIt first, InIt last);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
void clear();
void swap(deque& right);
};The template class describes an object that controls a
varying-length sequence of elements of type Ty.
The sequence is represented in a way that permits insertion
and removal of an element at either end with a single element copy
(constant time).
Such operations in the middle of the sequence require element
copies and assignments proportional to the number of elements
in the sequence (linear time).
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class Alloc. Such an allocator object must have
the same external interface as an object of template class
allocator.
Note that the stored allocator object is not copied when the container
object is assigned.
Deque reallocation
occurs when a member function must insert or erase elements of
the controlled sequence:
- If an element is inserted into an empty sequence,
or if an element is erased to leave an empty sequence, then
iterators earlier returned by
begin() and
end() become
invalid. - If an element is inserted at
begin() or at
end(),
then all iterators become invalid, but no references
that designate existing elements become invalid. - If an element is erased at
begin() or at
end(),
then only iterators and references that designate the erased element
become invalid. - Otherwise, inserting or erasing an element invalidates
all iterators and references.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
template<class InIt>
void assign(InIt first, InIt last);
void assign(size_type count, const Ty& val);If InIt is an integer type, the first member
function behaves the same as assign((size_type)first, (Ty)last).
Otherwise, the
first member function replaces the sequence
controlled by *this with the sequence
[first, last), which must not overlap
the initial controlled sequence.
The second member function replaces the sequence
controlled by *this with a repetition of count
elements of value val.
const_reference at(size_type pos) const;
reference at(size_type pos);
The member function returns a reference to the element of the
controlled sequence at position pos. If that position is
invalid, the function throws an object of class
out_of_range.
reference back();
const_reference back() const;
The member function returns a reference to the last element of the
controlled sequence, which must be non-empty.
const_iterator begin() const;
iterator begin();
The member function returns a random-access iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
void clear();
The member function calls
erase(
begin(),
end()).
typedef 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 Alloc::const_pointer const_pointer;
The type describes an object that can serve as a constant pointer
to an element of the controlled sequence.
typedef typename Alloc::const_reference const_reference;
The type describes an object that can serve as a constant reference
to an element of the controlled sequence.
typedef reverse_iterator<const_iterator>
const_reverse_iterator;The type describes an object that can serve as a constant reverse
random-access iterator for the controlled sequence.
deque();
explicit deque(const Alloc& al);
explicit deque(size_type count);
deque(size_type count, const Ty& val);
deque(size_type count, const Ty& val,
const Alloc& al);
deque(const deque& right);
template<class InIt>
deque(InIt first, InIt last);
template<class InIt>
deque(InIt first, InIt last, const Alloc& 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
right.get_allocator().
Otherwise, it is Alloc().
The first two constructors specify an
empty initial controlled sequence. The third constructor specifies
a repetition of count elements of value Ty().
The fourth and fifth constructors specify
a repetition of count elements of value val.
The sixth constructor specifies a copy of the sequence controlled by
right.
If InIt is an integer type, the last two constructors
specify a repetition of (size_type)first elements of value
(Ty)last. Otherwise, the
last two constructors specify the sequence
[first, last).
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 function returns a random-access iterator that points
just beyond the end of the sequence.
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
The first member function removes the element of the controlled
sequence pointed to by where. The second member function
removes the elements of the controlled sequence
in the range [first, last).
Both return an iterator that designates the first element remaining
beyond any elements removed, or
end() if no such element exists.
Removing N elements causes N destructor calls
and an assignment for each of the elements between the insertion
point and the nearer end of the sequence.
Removing an element at either end
invalidates only iterators and
references that designate the erased elements. Otherwise,
erasing an element invalidates all iterators and references.
The member functions throw an exception only if a copy operation
throws an exception.
reference front();
const_reference front() const;
The member function returns a reference to the first element of the
controlled sequence, which must be non-empty.
Alloc get_allocator() const;
The member function returns the stored
allocator object.
iterator insert(iterator where, const Ty& val);
void insert(iterator where, size_type count, const Ty& val);
template<class InIt>
void insert(iterator where, InIt first, InIt last);Each of the member functions inserts, before the element pointed to
by where in the controlled sequence, a sequence
specified by the remaining operands.
The first member function inserts
a single element with value val and returns an iterator
that designates the newly inserted element.
The second member function
inserts a repetition of count elements of value val.
If InIt is an integer type, the last member
function behaves the same as insert(where, (size_type)first, (Ty)last).
Otherwise, the
last member function inserts the sequence
[first, last), which must not overlap
the initial controlled sequence.
When inserting a single element, the number of
element copies is linear in the number of elements between the insertion
point and the nearer end of the sequence. When inserting a single element
at either end of the sequence, the amortized number of element copies
is constant. When inserting N elements,
the number of element copies is linear in
N plus the number of elements between the insertion
point and the nearer end of the sequence -- except when the template member
is specialized for InIt an input or forward iterator, which
behaves like N single insertions.
Inserting an element at either end
invalidates all iterators,
but no references, that designate existing elements. Otherwise,
inserting an element invalidates all iterators and references.
If an exception is thrown during the
insertion of one or more elements, and the exception is not thrown while
copying an element, the container is left unaltered
and the exception is rethrown.
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 max_size() const;
The member function returns the length of the longest sequence that
the object can control.
const_reference operator[](size_type pos) const;
reference operator[](size_type pos);
The member function returns a reference to the element of the
controlled sequence at position pos. If that position is
invalid, the behavior is undefined.
typedef typename Alloc::pointer pointer;
The type describes an object that can serve as a pointer to an
element of the controlled sequence.
void pop_back();
The member function removes the last element of the
controlled sequence, which must be non-empty.
Removing the element
invalidates only iterators and
references that designate the erased element.
The member function never throws an exception.
void pop_front();
The member function removes the first element of the
controlled sequence, which must be non-empty.
Removing the element
invalidates only iterators and
references that designate the erased element.
The member function never throws an exception.
void push_back(const Ty& val);
The member function inserts an element with value val
at the end of the controlled sequence. Inserting the element
invalidates all iterators,
but no references, to existing elements.
If an exception is thrown, the container is left unaltered
and the exception is rethrown.
void push_front(const Ty& val);
The member function inserts an element with value val
at the beginning of the controlled sequence. Inserting the element
invalidates all iterators,
but no references, to existing elements.
If an exception is thrown, the container is left unaltered
and the exception is rethrown.
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 Alloc::reference reference;
The type describes an object that can serve as a reference to an
element of the controlled sequence.
const_reverse_iterator rend() const;
reverse_iterator rend();
The member function returns a reverse iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, it designates the end of the reverse sequence.
void resize(size_type newsize);
void resize(size_type newsize, Ty val);
The member functions both ensure that
size() henceforth
returns newsize. If it must make the controlled sequence longer,
the first member function
appends elements with value Ty(), while the second member function
appends elements with value val.
To make the controlled sequence shorter, both member functions call
erase(begin() + newsize, end()).
typedef reverse_iterator<iterator>
reverse_iterator;The type describes an object that can serve as a reverse
random-access iterator for the controlled sequence.
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.
void swap(deque& right);
The member function swaps the controlled sequences between
*this and right. If
get_allocator()
== right.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 typename Alloc::value_type value_type;
The type is a synonym for the template parameter Ty.
template<class Ty, class Alloc>
bool operator!=(
const deque <Ty, Alloc>& left,
const deque <Ty, Alloc>& right);The template function returns !(left == right).
template<class Ty, class Alloc>
bool operator==(
const deque <Ty, Alloc>& left,
const deque <Ty, Alloc>& right);The template function overloads operator== to compare
two objects of template class
deque. The function returns
left.size() == right.size() &&
equal(left.
begin(), left.
end(), right.begin()).
template<class Ty, class Alloc>
bool operator<(
const deque <Ty, Alloc>& left,
const deque <Ty, Alloc>& right);The template function overloads operator< to compare
two objects of template class
deque. The function returns
lexicographical_compare(left.
begin(), left.
end(), right.begin(), right.end()).
template<class Ty, class Alloc>
bool operator<=(
const deque <Ty, Alloc>& left,
const deque <Ty, Alloc>& right);The template function returns !(right < left).
template<class Ty, class Alloc>
bool operator>(
const deque <Ty, Alloc>& left,
const deque <Ty, Alloc>& right);The template function returns right < left.
template<class Ty, class Alloc>
bool operator>=(
const deque <Ty, Alloc>& left,
const deque <Ty, Alloc>& right);The template function returns !(left < right).
template<class Ty, class Alloc>
void swap(
deque <Ty, Alloc>& left,
deque <Ty, Alloc>& right);The template function executes
left.swap(right).
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
27 - errno
<errno.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
28 - exceptio
<exception>
Include the standard header <exception>
to define several types and functions related to the handling
of exceptions.
// DECLARATIONS
class exception;
class bad_exception;
// FUNCTIONS
typedef void (*terminate_handler)();
typedef void (*unexpected_handler)();
terminate_handler
set_terminate(terminate_handler pnew) throw();
unexpected_handler
set_unexpected(unexpected_handler pnew) throw();
void terminate();
void unexpected();
bool uncaught_exception();
// END OF DECLARATIONSclass bad_exception
: public exception {
};The class describes an exception that can be thrown from an
unexpected handler.
The value returned by
what()
is an implementation-defined
C string.
None of the member functions throw any exceptions.
class exception {
public:
exception() throw();
exception(const exception& right) throw();
exception& operator=(const exception& right) throw();
virtual ~exception() throw();
virtual const char *what() const throw();
};The class serves as the base class for all exceptions thrown
by certain expressions and by the Standard C++ library. The
C string value returned by
what()
is left unspecified by the default constructor,
but may be defined by the constructors for certain derived classes
as an implementation-defined
C string.
None of the member functions throw any exceptions.
terminate_handler
set_terminate(terminate_handler pnew) throw();The function establishes a new
terminate handler
as the function *pnew. Thus, pnew must
not be a null pointer. The function returns the address of the
previous terminate handler.
unexpected_handler
set_unexpected(unexpected_handler pnew) throw();The function establishes a new
unexpected handler
as the function *pnew. Thus, pnew must
not be a null pointer. The function returns the address of the
previous unexpected handler.
void terminate();
The function calls a
terminate handler,
a function of type void ().
If terminate is called directly by the program,
the terminate handler is the one most recently set by a call to
set_terminate.
If terminate is called for any of several other
reasons during evaluation of a throw expression,
the terminate handler is the one in effect immediately after
evaluating the throw expression.
A terminate handler may not return to its caller. At
program startup,
the terminate handler is a function that calls
abort().
typedef void (*terminate_handler)();
The type describes a pointer to a function suitable for use as a
terminate handler.
bool uncaught_exception();
The function returns true only if a thrown exception is being currently
processed. Specifically, it returns true after completing evaluation of a
throw expression and before completing initialization of the exception
declaration in the matching handler or calling
unexpected as a result of the
throw expression.
void unexpected();
The function calls an
unexpected handler,
a function of type void ().
If unexpected is called directly by the program,
the unexpected handler is the one most recently set by a call to
set_unexpected.
If unexpected is called when control
leaves a function by a thrown exception of a type not permitted by an
exception specification
for the function, as in:
void func() throw() // function may throw no exceptions
{throw "bad"; } // throw calls unexpected()the unexpected handler is the one in effect immediately after
evaluating the throw expression.
An unexpected handler may not return to its caller. It may
terminate execution by:
- throwing an object of a type listed in the exception specification
(or an object of any type if the unexpected handler is called directly
by the program)
- throwing an object of type
bad_exception - calling
terminate(),
abort(), or
exit(int)
At program startup,
the unexpected handler is a function that calls
terminate().
typedef void (*unexpected_handler)();
The type describes a pointer to a function suitable for use as an
unexpected handler.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
29 - express
Expressions
You write expressions to determine values, to alter values stored
in objects, and to call functions that perform input and output. In
fact, you express all computations in the program by writing expressions.
The translator must evaluate some of the expressions you write
to determine properties of the program. The translator or the target
environment must evaluate other expressions prior to program startup
to determine the initial values stored in objects with static duration.
The program evaluates the remaining expressions when it executes.
This document describes briefly just those aspect
of expressions most relevant to the use of the Standard C library:
An
address constant expression
specifies a value that has a pointer type
and that the translator or target environment can determine
prior to program startup.
A constant expression
specifies a value that the translator or target environment can determine
prior to program startup.
An
integer constant expression
specifies a value that has an integer type
and that the translator can determine at the point in
the program where you write the expression.
(You cannot write a function call, assigning operator,
or comma operator except as part of the operand of a
sizeof operator.)
In addition, you must write only subexpressions
that have integer type. You can, however,
write a floating-point constant expression as the operand of an integer
type cast operator.
A
floating-point constant expression
specifies a value that has a floating-point type
and that the translator can determine at the point in
the program where you write the expression.
(You cannot write a function call, assigning operator,
or comma operator except as part of the operand of a
sizeof operator.)
In addition, you must write only subexpressions
that have integer or floating-point type.
An lvalue expression
An lvalue expression designates an object that has
an object type other than an array type. Hence, you can access the
value stored in the object.
A modifiable lvalue expression designates an object that has
an object type other than an array type or a const type. Hence,
you can alter the value stored in the object.
You can also designate objects with an lvalue expression
that has an array type or an incomplete type,
but you can only take the address of such an expression.
Promoting occurs for an
expression whose integer type is not one of the ``computational'' types.
Except when it is the operand of the
sizeof operator,
an integer
rvalue expression
has one of four types:
int, unsigned int, long, or unsigned long.
When you write an expression in an rvalue context and the expression
has an integer type that is not one of these types, the translator
promotes its type to one of these.
If all of the values representable in the
original type are also representable as type int, then the
promoted type is int. Otherwise, the promoted type is
unsigned int. Thus, for signed char, short,
and any signed bitfield type, the promoted type is int.
For each of the remaining integer types (char, unsigned char,
unsigned short, any plain bitfield type,
or any unsigned bitfield type), the effect of these rules
is to favor promoting to int wherever possible, but to promote
to unsigned int if necessary to preserve the original value
in all possible cases.
An rvalue expression
is an expression whose value can be determined only when the program executes.
The term also applies to expressions which need not
be determined until program execution.
You use the sizeof operator,
as in the expression sizeof X
to determine the size in bytes of an object whose type
is the type of X. The translator uses the expression
you write for X only to determine a type;
it is not evaluated.
A void expression
has type void.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
30 - float
<float.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
31 - fstream
<fstream>
Include the iostreams
standard header <fstream>
to define several classes that support
iostreams operations on
sequences stored in external
files.
// DECLARATIONS
class filebuf;
class ifstream;
class ofstream;
// END OF DECLARATIONSclass filebuf : public streambuf {
public:
typedef typename streambuf<Elem, Tr>::char_type
char_type;
typedef typename streambuf<Elem, Tr>::traits_type
traits_type;
typedef typename streambuf<Elem, Tr>::int_type
int_type;
typedef typename streambuf<Elem, Tr>::pos_type
pos_type;
typedef typename streambuf<Elem, Tr>::off_type
off_type;
filebuf();
bool is_open() const;
filebuf *open(const char *filename,
ios_base::openmode mode);
filebuf *close();
protected:
virtual pos_type seekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual pos_type seekpos(pos_type pos,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual int_type underflow();
virtual int_type pbackfail(int_type meta =
traits_type::eof());
virtual int_type overflow(int_type meta =
traits_type::eof());
virtual int sync();
virtual streambuf
*setbuf(Elem *buffer, streamsize count);
};The class
describes a stream buffer that controls
the transmission of elements to and from a sequence of elements
stored in an external
file.
An object of class
filebuf stores a
file pointer, which designates the
FILE object
that controls the stream
associated with an
open file.
filebuf();
The constructor stores a null pointer in all the pointers
controlling the
input buffer and the
output buffer. It
also stores a null pointer in the
file pointer.
typedef char char_type;
The type is a synonym for char.
filebuf *close();
The member function returns a null pointer if the
file pointer fp
is a null pointer. Otherwise, it calls
fclose(fp).
If that function returns a nonzero value, the function
returns a null pointer. Otherwise, it returns this
to indicate that the file was successfully
closed.
typedef traits_type::int_type int_type;
The type is a synonym for
traits_type::int_type.
bool is_open();
The member function returns true if the
file pointer is not a null pointer.
typedef traits_type::off_type off_type;
The type is a synonym for
traits_type::off_type.
filebuf *open(const char *filename,
ios_base::openmode mode);The member function endeavors to open the file with
filename filename, by calling
fopen(filename, strmode). Here
strmode is determined from mode &
~(ate & |
binary):
ios_base::in
becomes "r" (open existing file for reading).ios_base::out or
ios_base::out |
ios_base::trunc
becomes "w" (truncate existing file or create for writing).ios_base::out |
ios_base::app
becomes "a" (open existing file for appending all writes).ios_base::in | ios_base::out
becomes "r+" (open existing file for reading and writing).ios_base::in | ios_base::out |
ios_base::trunc becomes "w+"
(truncate existing file or create for reading and writing).ios_base::in | ios_base::out |
ios_base::app becomes "a+"
(open existing file for reading and for appending all writes).
If mode & ios_base::binary is nonzero,
the function appends b to strmode
to open a binary stream
instead of a text stream.
It then stores the value returned by fopen in the
file pointer fp. If
mode & ios_base::ate is nonzero and the
file pointer is not a null pointer, the function calls
fseek(fp, 0,
SEEK_END) to
position the stream at end-of-file. If that positioning operation
fails, the function calls
close(fp) and
stores a null pointer in the file pointer.
If the file pointer is a null pointer, the function returns
a null pointer. Otherwise, it returns this.
virtual int_type overflow(int_type meta =
traits_type::eof());If meta !=
traits_type::eof(),
the protected virtual member function endeavors to insert the element
ch = traits_type::to_char_type(meta)
into the
output buffer.
It can do so in various ways:
- If a write position
is available, it can store the element into the write position
and increment the next pointer for the output buffer.
- It can make a write position available by allocating
new or additional storage for the output buffer.
- It can write any pending output in the output buffer, followed
by
ch, to the associated stream designated by the
file pointer fp
as if by successive calls of the form
fputc(ch, fp).
If any conversion or write fails, the function does not succeed.
If the function cannot succeed, it returns traits_type::eof().
Otherwise, it returns
traits_type::not_eof(meta).
virtual int_type pbackfail(int_type meta =
traits_type::eof());The protected virtual member function endeavors to put back an element
into the
input buffer,
then make it the current element (pointed to
by the next pointer). If meta ==
traits_type::eof(),
the element to push back is effectively the one already in the stream
before the current element. Otherwise, that element is replaced by
ch =
traits_type::to_char_type(meta).
The function can put back an element in various ways:
- If a putback position
is available, and the element stored there compares equal to
ch,
it can simply decrement the next pointer for the input buffer. - If the function can make a putback position available,
it can do so, set the next pointer to point at that position,
and store
ch in that position. - If the function can push back an element onto the input stream,
it can do so, such as by calling
ungetc for an element
of type char.
If the function cannot succeed, it returns
traits_type::eof(). Otherwise, it returns
traits_type::not_eof(meta).
typedef traits_type::pos_type pos_type;
The type is a synonym for
traits_type::pos_type.
virtual pos_type seekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
filebuf, a stream position can be represented
by an object of type
fpos_t.
Offset zero designates the first element of the stream.
(An object of type
pos_type
stores at least an fpos_t object.)
For a file opened for both reading and writing,
both the input and output streams are positioned in tandem. To
switch
between inserting and extracting, you must call either
pubseekoff
or
pubseekpos.
Calls to pubseekoff (and hence to seekoff)
have various limitations for
text streams
and binary streams.
If the
file pointer fp
is a null pointer, the function fails. Otherwise, it endeavors
to alter the stream position by calling
fseek(fp, off, way).
If that function succeeds and the resultant position
fposn can be determined by calling
fgetpos(fp, &fposn),
the function succeeds. If the function succeeds, it returns
a value of type pos_type containing fposn.
Otherwise, it returns an invalid stream position.
virtual pos_type seekpos(pos_type pos,
ios_base::openmode which =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
filebuf, a stream position can be represented
by an object of type
fpos_t.
Offset zero designates the first element of the stream.
(An object of type
pos_type
stores at least an fpos_t object.)
For a file opened for both reading and writing,
both the input and output streams are positioned in tandem. To
switch
between inserting and extracting, you must call either
pubseekoff
or
pubseekpos.
Calls to pubseekoff (and hence to seekoff)
have various limitations for
both text streams
and binary streams.
If the
file pointer fp
is a null pointer, the function fails. Otherwise, it endeavors
to alter the stream position by calling
fsetpos(fp, &fposn),
where fposn is the fpos_t object stored
in pos. If that function succeeds, the function returns
pos. Otherwise, it returns an invalid stream position.
virtual streambuf
*setbuf(Elem *buffer, streamsize count);The protected member function returns zero if the
file pointer fp
is a null pointer. Otherwise, it calls
setvbuf(fp, (char *)buffer,
_IOFBF, count * sizeof (Elem))
to offer the array of count elements beginning at buffer
as a buffer for the stream. If that function returns a nonzero value,
the function returns a null pointer. Otherwise, it returns this
to signal success.
int sync();
The protected member function returns zero if the
file pointer fp
is a null pointer. Otherwise, it returns zero only if calls to both
overflow() and
fflush(fp)
succeed in flushing any pending output to the stream.
typedef char_traits traits_type;
The type is a synonym for
char_traits.
virtual int_type underflow();
The protected virtual member function endeavors to extract the current
element ch from the input stream, and return the element as
traits_type::to_int_type(ch).
It can do so in various ways:
- If a read position is available,
it takes
ch as the element stored in the read position
and advances the next pointer for the
input buffer. - It can read one or more elements of type char,
as if by successive calls of the form
fgetc(fp).
If any read or conversion fails,
the function does not succeed.
If the function cannot succeed, it returns
traits_type::eof(). Otherwise,
it returns ch, converted as described above.
class ifstream : public istream {
public:
filebuf *rdbuf() const;
ifstream();
explicit ifstream(const char *filename,
ios_base::openmode mode = ios_base::in);
bool is_open() const;
void open(const char *filename,
ios_base::openmode mode = ios_base::in);
void close();
};The class describes an object that controls
extraction of elements and encoded objects from a
stream buffer of class
filebuf.
The object stores an object of class
filebuf.
ifstream();
explicit ifstream(const char *filename,
ios_base::openmode mode = ios_base::in);The first constructor initializes the base class by calling
istream(sb),
where sb is the stored object of class
filebuf.
It also initializes sb by calling
filebuf().
The second constructor initializes the base class by calling
istream(sb).
It also initializes sb by calling
filebuf(),
then sb.open(filename, mode
| ios_base::in). If the latter function returns a null
pointer, the constructor calls
setstate(failbit).
void close();
The member function calls
rdbuf()->
close().
bool is_open();
The member function returns
rdbuf()->
is_open().
void open(const char *filename,
ios_base::openmode mode = ios_base::in);The member function calls
rdbuf()->
open(filename, mode | ios_base::in).
If that function returns a null pointer, the function calls
setstate(failbit).
filebuf *rdbuf() const
The member function returns the address of the stored stream buffer.
class ofstream : public ostream {
public:
filebuf *rdbuf() const;
ofstream();
explicit ofstream(const char *filename,
ios_base::openmode mode = ios_base::out);
bool is_open() const;
void open(const char *filename,
ios_base::openmode mode = ios_base::out);
void close();
};The class describes an object that controls
insertion of elements and encoded objects into a
stream buffer of class
filebuf.
The object stores an object of class
filebuf.
ofstream();
explicit ofstream(const char *filename,
ios_base::openmode which = ios_base::out);The first constructor initializes the base class by calling
ostream(sb),
where sb is the stored object of class
filebuf<Elem, Tr>.
It also initializes sb by calling
filebuf().
The second constructor initializes the base class by calling
ostream(sb).
It also initializes sb by calling
filebuf(),
then sb.open(filename, mode
| ios_base::out). If the latter function returns a null
pointer, the constructor calls
setstate(failbit).
void close();
The member function calls
rdbuf()->
close().
bool is_open();
The member function returns
rdbuf()->
is_open().
void open(const char *filename,
ios_base::openmode mode = ios_base::out);The member function calls
rdbuf()->
open(filename, mode | ios_base::out).
If that function returns a null pointer, the function calls
setstate(failbit).
filebuf *rdbuf() const
The member function returns the address of the stored
stream buffer.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
32 - fstream2
<fstream.h>
Include the traditional header <fstream.h>
to effectively include the standard header
<fstream>.
#include <fstream>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
33 - functio2
<functional>
binary_function
· binary_negate
· binder1st
· binder2nd
· const_mem_fun_t
· const_mem_fun_ref_t
· const_mem_fun1_t
· const_mem_fun1_ref_t
· divides
· equal_to
· greater
· greater_equal
· less
· less_equal
· logical_and
· logical_not
· logical_or
· mem_fun_t
· mem_fun_ref_t
· mem_fun1_t
· mem_fun1_ref_t
· minus
· modulus
· multiplies
· negate
· not_equal_to
· plus
· pointer_to_binary_function
· pointer_to_unary_function
· unary_function
· unary_negate
bind1st
· bind2nd
· mem_fun
· mem_fun_ref
· not1
· not2
· ptr_fun
Include the STL
standard header <functional>
to define several templates that help construct
function objects,
objects of a type that defines operator().
A function object can thus be a function pointer, but in
the more general case the object can store additional information
that can be used during a function call.
namespace std {
template<class Arg, class Result>
struct unary_function;
template<class Arg1, class Arg2, class Result>
struct binary_function;
template<class Ty>
struct plus;
template<class Ty>
struct minus;
template<class Ty>
struct multiplies;
template<class Ty>
struct divides;
template<class Ty>
struct modulus;
template<class Ty>
struct negate;
template<class Ty>
struct equal_to;
template<class Ty>
struct not_equal_to;
template<class Ty>
struct greater;
template<class Ty>
struct less;
template<class Ty>
struct greater_equal;
template<class Ty>
struct less_equal;
template<class Ty>
struct logical_and;
template<class Ty>
struct logical_or;
template<class Ty>
struct logical_not;
template<class Fn1>
struct unary_negate;
template<class Fn2>
struct binary_negate;
template<class Fn2>
class binder1st;
template<class Fn2>
class binder2nd;
template<class Arg, class Result>
class pointer_to_unary_function;
template<class Arg1, class Arg2, class Result>
class pointer_to_binary_function;
template<class Result, class Ty>
struct mem_fun_t;
template<class Result, class Ty, class Arg>
struct mem_fun1_t;
template<class Result, class Ty>
struct const_mem_fun_t;
template<class Result, class Ty, class Arg>
struct const_mem_fun1_t;
template<class Result, class Ty>
struct mem_fun_ref_t;
template<class Result, class Ty, class Arg>
struct mem_fun1_ref_t;
template<class Result, class Ty>
struct const_mem_fun_ref_t;
template<class Result, class Ty, class Arg>
struct const_mem_fun1_ref_t;
// TEMPLATE FUNCTIONS
template<class Fn1>
unary_negate<Fn1> not1(const Fn1& func);
template<class Fn2>
binary_negate<Fn2> not2(const Fn2& func);
template<class Fn2, class Ty>
binder1st<Fn2> bind1st(const Fn2& func, const Ty& left);
template<class Fn2, class Ty>
binder2nd<Fn2> bind2nd(const Fn2& func, const Ty& right);
template<class Arg, class Result>
pointer_to_unary_function<Arg, Result>
ptr_fun(Result (*)(Arg));
template<class Arg1, class Arg2, class Result>
pointer_to_binary_function<Arg1, Arg2, Result>
ptr_fun(Result (*)(Arg1, Arg2));
template<class Result, class Ty>
mem_fun_t<Result, Ty> mem_fun(Result (Ty::*pm)());
template<class Result, class Ty, class Arg>
mem_fun1_t<Result, Ty, Arg> mem_fun(Result (Ty::*pm)(Arg left));
template<class Result, class Ty>
const_mem_fun_t<Result, Ty> mem_fun(Result (Ty::*pm)() const);
template<class Result, class Ty, class Arg>
const_mem_fun1_t<Result, Ty, Arg> mem_fun(Result (Ty::*pm)(Arg left) const);
template<class Result, class Ty>
mem_fun_ref_t<Result, Ty> mem_fun_ref(Result (Ty::*pm)());
template<class Result, class Ty, class Arg>
mem_fun1_ref_t<Result, Ty, Arg>
mem_fun_ref(Result (Ty::*pm)(Arg left));
template<class Result, class Ty>
const_mem_fun_ref_t<Result, Ty> mem_fun_ref(Result (Ty::*pm)() const);
template<class Result, class Ty, class Arg>
const_mem_fun1_ref_t<Result, Ty, Arg>
mem_fun_ref(Result (Ty::*pm)(Arg left) const);
};template<class Arg1, class Arg2, class Result>
struct binary_function {
typedef Arg1 first_argument_type;
typedef Arg2 second_argument_type;
typedef Result result_type;
};The template class serves as a base for classes that define
a member function of the form:
result_type operator()(const first_argument_type&,
const second_argument_type&) constor a similar form taking two arguments.
Hence, all such
binary functions
can refer to their first argument type as
first_argument_type,
their second argument type as
second_argument_type,
and their return type as
result_type.
template<class Fn2>
class binary_negate
: public binary_function<
typename Fn2::first_argument_type,
typename Fn2::second_argument_type, bool> {
public:
explicit binary_negate(const Fn2& func);
bool operator()(
const typename Fn2::first_argument_type& left,
const typename Fn2::second_argument_type& right) const;
};The template class stores a copy of func, which
must be a binary function object.
It defines its member function operator()
as returning !func(left, right).
template<class Fn2, class Ty>
binder1st<Fn2> bind1st(const Fn2amp; func, const Ty& left);The function returns
binder1st<Fn2>(func,
typename Fn2::first_argument_type(left)).
template<class Fn2, class Ty>
binder2nd<Fn2> bind2nd(const Fn2& func, const Ty& right);The function returns
binder2nd<Fn2>(func,
typename Fn2::second_argument_type(right)).
template<class Fn2>
class binder1st
: public unary_function<
typename Fn2::second_argument_type,
typename Fn2::result_type> {
public:
typedef typename Fn2::second_argument_type argument_type;
typedef typename Fn2::result_type result_type;
binder1st(const Fn2& func,
const typename Fn2::first_argument_type& left);
result_type operator()(const argument_type& right) const;
protected:
Fn2 op;
typename Fn2::first_argument_type value;
};The template class stores a copy of func, which
must be a binary function object, in
op,
and a copy of left in
value.
It defines its member function operator()
as returning op(value, right).
template<class Fn2>
class binder2nd
: public unary_function<
typename Fn2::first_argument_type,
typename Fn2::result_type> {
public:
typedef typename Fn2::first_argument_type argument_type;
typedef typename Fn2::result_type result_type;
binder2nd(const Fn2& func,
const typename Fn2::second_argument_type& right);
result_type operator()(const argument_type& left) const;
protected:
Fn2 op;
typename Fn2::second_argument_type value;
};The template class stores a copy of func, which
must be a binary function object, in
op,
and a copy of right in
value.
It defines its member function operator()
as returning op(left, value).
template<class Result, class Ty>
struct const_mem_fun_t
: public unary_function<const Ty *, Result> {
explicit const_mem_fun_t(Result (Ty::*pm)() const);
Result operator()(const Ty *pleft) const;
};The template class stores a copy of pm, which
must be a pointer to a member function of class Ty, in
a private member object.
It defines its member function operator()
as returning (pleft->*pm)() const.
template<class Result, class Ty>
struct const_mem_fun_ref_t
: public unary_function<Ty, Result> {
explicit const_mem_fun_t(Result (Ty::*pm)() const);
Result operator()(const Ty& left) const;
};The template class stores a copy of pm, which
must be a pointer to a member function of class Ty, in
a private member object.
It defines its member function operator()
as returning (left.*pm)() const.
template<class Result, class Ty, class Arg>
struct const_mem_fun1_t
: public binary_function<const Ty *, Arg, Result> {
explicit const_mem_fun1_t(Result (Ty::*pm)(Arg) const);
Result operator()(const Ty *pleft, Arg right) const;
};The template class stores a copy of pm, which
must be a pointer to a member function of class Ty, in
a private member object.
It defines its member function operator()
as returning (pleft->*pm)(right) const.
template<class Result, class Ty, class Arg>
struct const_mem_fun1_ref_t
: public binary_function<Ty, Arg, Result> {
explicit const_mem_fun1_ref_t(Result (Ty::*pm)(Arg) const);
Result operator()(const Ty& left, Arg right) const;
};The template class stores a copy of pm, which
must be a pointer to a member function of class Ty, in
a private member object.
It defines its member function operator()
as returning (left.*pm)(right) const.
template<class Ty>
struct divides : public binary_function<Ty, Ty, Ty> {
Ty operator()(const Ty& left, const Ty& right) const;
};The template class defines its member function as returning
left / right.
template<class Ty>
struct equal_to
: public binary_function<Ty, Ty, bool> {
bool operator()(const Ty& left, const Ty& right) const;
};The template class defines its member function as returning
left == right.
template<class Ty>
struct greater : public binary_function<Ty, Ty, bool> {
bool operator()(const Ty& left, const Ty& right) const;
};The template class defines its member function as returning
left > right. The member function defines a
total ordering
if Ty is an object pointer type. (It will compare two pointer values
consistently even if they don't point into the same array.)
template<class Ty>
struct greater_equal
: public binary_function<Ty, Ty, bool> {
bool operator()(const Ty& left, const Ty& right) const;
};The template class defines its member function as returning
left >= right. The member function defines a
total ordering
if Ty is an object pointer type. (It will compare two pointer values
consistently even if they don't point into the same array.)
template<class Ty>
struct less : public binary_function<Ty, Ty, bool> {
bool operator()(const Ty& left, const Ty& right) const;
};The template class defines its member function as returning
left < right. The member function defines a
total ordering
if Ty is an object pointer type. (It will compare two pointer values
consistently even if they don't point into the same array.)
template<class Ty>
struct less_equal
: public binary_function<Ty, Ty, bool> {
bool operator()(const Ty& left, const Ty& right) const;
};The template class defines its member function as returning
left <= right. The member function defines a
total ordering
if Ty is an object pointer type. (It will compare two pointer values
consistently even if they don't point into the same array.)
template<class Ty>
struct logical_and
: public binary_function<Ty, Ty, bool> {
bool operator()(const Ty& left, const Ty& right) const;
};The template class defines its member function as returning
left && right.
template<class Ty>
struct logical_not : public unary_function<Ty, bool> {
bool operator()(const Ty& left) const;
};The template class defines its member function as returning
!left.
template<class Ty>
struct logical_or
: public binary_function<Ty, Ty, bool> {
bool operator()(const Ty& left, const Ty& right) const;
};The template class defines its member function as returning
left || right.
template<class Result, class Ty>
mem_fun_t<Result, Ty> mem_fun(Result (Ty::*pm)());
template<class Result, class Ty, class Arg>
mem_fun1_t<Result, Ty, Arg> mem_fun(Result (Ty::*pm)(Arg));
template<class Result, class Ty>
const_mem_fun_t<Result, Ty>
mem_fun(Result (Ty::*pm)() const);
template<class Result, class Ty, class Arg>
const_mem_fun1_t<Result, Ty, Arg>
mem_fun(Result (Ty::*pm)(Arg) const);The template function returns pm cast to the return type.
template<class Result, class Ty>
mem_fun_ref_t<Result, Ty> mem_fun_ref(Result (Ty::*pm)());
template<class Result, class Ty, class Arg>
mem_fun1_ref_t<Result, Ty, Arg> mem_fun_ref(Result (Ty::*pm)(Arg));
template<class Result, class Ty>
const_mem_fun_ref_t<Result, Ty> mem_fun_ref(Result (Ty::*pm)() const);
template<class Result, class Ty, class Arg>
const_mem_fun1_ref_t<Result, Ty, Arg> mem_fun_ref(Result (Ty::*pm)(Arg) const);The template function returns pm cast to the return type.
template<class Result, class Ty>
struct mem_fun_t : public unary_function<Ty *, Result> {
explicit mem_fun_t(Result (Ty::*pm)());
Result operator()(Ty *pleft) const;
};The template class stores a copy of pm, which
must be a pointer to a member function of class Ty, in
a private member object.
It defines its member function operator()
as returning (pleft->*pm)().
template<class Result, class Ty>
struct mem_fun_ref_t
: public unary_function<Ty, Result> {
explicit mem_fun_t(Result (Ty::*pm)());
Result operator()(Ty& left) const;
};The template class stores a copy of pm, which
must be a pointer to a member function of class Ty, in
a private member object.
It defines its member function operator()
as returning (left.*pm)().
template<class Result, class Ty, class Arg>
struct mem_fun1_t
: public binary_function<Ty *, Arg, Result> {
explicit mem_fun1_t(Result (Ty::*pm)(Arg));
Result operator()(Ty *pleft, Arg right) const;
};The template class stores a copy of pm, which
must be a pointer to a member function of class Ty, in
a private member object.
It defines its member function operator()
as returning (pleft->*pm)(right).
template<class Result, class Ty, class Arg>
struct mem_fun1_ref_t
: public binary_function<Ty, Arg, Result> {
explicit mem_fun1_ref_t(Result (Ty::*pm)(Arg));
Result operator()(Ty& left, Arg right) const;
};The template class stores a copy of pm, which
must be a pointer to a member function of class Ty, in
a private member object.
It defines its member function operator()
as returning (left.*pm)(right).
template<class Ty>
struct minus : public binary_function<Ty, Ty, Ty> {
Ty operator()(const Ty& left, const Ty& right) const;
};The template class defines its member function as returning
left - right.
template<class Ty>
struct modulus : public binary_function<Ty, Ty, Ty> {
Ty operator()(const Ty& left, const Ty& right) const;
};The template class defines its member function as returning
left % right.
template<class Ty>
struct multiplies : public binary_function<Ty, Ty, Ty> {
Ty operator()(const Ty& left, const Ty& right) const;
};The template class defines its member function as returning
left * right.
template<class Ty>
struct negate : public unary_function<Ty, Ty> {
Ty operator()(const Ty& left) const;
};The template class defines its member function as returning
-left.
template<class Fn1>
unary_negate<Fn1> not1(const Fn1& func);The template function returns
unary_negate<Fn1>(func).
template<class Fn2>
binary_negate<Fn2> not2(const Fn2& func);The template function returns
binary_negate<Fn2>(func).
template<class Ty>
struct not_equal_to
: public binary_function<Ty, Ty, bool> {
bool operator()(const Ty& left, const Ty& right) const;
};The template class defines its member function as returning
left != right.
template<class Ty>
struct plus : public binary_function<Ty, Ty, Ty> {
Ty operator()(const Ty& left, const Ty& right) const;
};The template class defines its member function as returning
left + right.
template<class Arg1, class Arg2, class Result>
class pointer_to_binary_function
: public binary_function<Arg1, Arg2, Result> {
public:
explicit pointer_to_binary_function(
Result (*pfunc)(Arg1, Arg2));
Result operator()(const Arg1 left, const Arg2 right) const;
};The template class stores a copy of pfunc.
It defines its member function operator()
as returning (*pfunc)(left, right).
template<class Arg, class Result>
class pointer_to_unary_function
: public unary_function<Arg, Result> {
public:
explicit pointer_to_unary_function(
Result (*pfunc)(Arg));
Result operator()(const Arg left) const;
};The template class stores a copy of pfunc.
It defines its member function operator()
as returning (*pfunc)(left).
template<class Arg, class Result>
pointer_to_unary_function<Arg, Result>
ptr_fun(Result (*pfunc)(Arg));
template<class Arg1, class Arg2, class Result>
pointer_to_binary_function<Arg1, Arg2, Result>
ptr_fun(Result (*pfunc)(Arg1, Arg2));The first template function returns
pointer_to_unary_function<Arg, Result>(pfunc).
The second template function returns
pointer_to_binary_function<Arg1, Arg2, Result>(pfunc).
template<class Arg, class Result>
struct unary_function {
typedef Arg argument_type;
typedef Result result_type;
};The template class serves as a base for classes that define
a member function of the form:
result_type operator()(const argument_type&) const
or a similar form taking one argument.
Hence, all such
unary functions
can refer to their sole argument type as
argument_type
and their return type as
result_type.
template<class Fn1>
class unary_negate
: public unary_function<
typename Fn1::argument_type,
bool> {
public:
explicit unary_negate(const Fn1& Func);
bool operator()(
const typename Fn1::argument_type& left) const;
};The template class stores a copy of func, which
must be a unary function object.
It defines its member function operator()
as returning !func(left).
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
34 - function
Functions
You write functions to specify all the actions that a program
performs when it executes. The type of a function tells you the type
of result it returns (if any). It can also tell you the types of any
arguments that the function expects when you call it from within an
expression.
This document describes briefly just those aspect
of functions most relevant to the use of the Standard C library:
Argument promotion
occurs when the type of the function fails to provide any information
about an argument. Promotion occurs if the function declaration
is not a function prototype or if the argument is one of
the unnamed arguments in a
varying number
of arguments. In this instance, the argument must be an
rvalue expression. Hence:
- An integer argument type is promoted.
- An lvalue of type array of
Ty becomes an rvalue of type
pointer to Ty. - A function designator of type function returning
Ty becomes
an rvalue of type pointer to function returning Ty. - An argument of type float is converted to double.
A do statement
executes a statement one or more times, while its
test-context expression
has a nonzero value:
do
statement
while (test);An expression statement
evaluates an expression in a
side-effects context:
printf("hello\n"); call a function
y = m * x + b; store a value
++count; alter a stored valueA for statement
executes a statement zero or more times, while the optional
test-context expression
test has a nonzero value.
You can also write two expressions, se-1
and se-2, in a for statement that are each in a
side-effects context:
for (se-1; test; se-2)
statementAn if statement
executes a statement only if the
test-context expression
has a nonzero value:
if (test)
statementAn if-else statement
executes one of two statements, depending on whether the
test-context expression
has a nonzero value:
if (test)
statement-1
else
statement-2A return statement
terminates execution of the function and transfers control
to the expression that called the function. If you write the optional
rvalue expression
within the return statement,
the result must be assignment-compatible with the type returned
by the function. The program converts the value of the expression
to the type returned and returns it as the value of the function call:
return expression;
An expression that occurs in a
side-effects context
specifies no value and designates no object or function.
Hence, it can have type void.
You typically evaluate such an expression for its
side effects
-- any change in the state of the program that occurs when evaluating
an expression. Side effects occur when the program
stores a value in an object, accesses a value from an object
of volatile qualified type, or alters the state of a file.
A switch statement
jumps to a place within a controlled statement, depending
on the value of an integer expression:
switch (expr)
{
case val-1:
stat-1;
break;
case val-2:
stat-2; falls through to next
default:
stat-n
}In a
test-context expression
the value of an expression causes control
to flow one way within the statement if the computed value is nonzero
or another way if the computed value is zero. You can write only an
expression that has a scalar rvalue result, because only scalars can
be compared with zero.
A while statement
executes a statement zero or more times, while the test-context
expression has a nonzero value:
while (test)
statement
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
35 - hash_map
<hash_map>
Include the STL
standard header <hash_map> to define the
container
template classes hash_map and
hash_multimap, and their supporting
templates.
namespace std {
template<class Key, class Pr>
class hash_compare;
template<class Key, class Ty, class Tr, class Alloc>
class hash_map;
template<class Key, class Ty, class Tr, class Alloc>
class hash_multimap;
// TEMPLATE FUNCTIONS
template<class Key, class Ty, class Tr, class Alloc>
bool operator==(
const hash_map<Key, Ty, Tr, Alloc>& left,
const hash_map<Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator==(
const hash_multimap<Key, Ty, Tr, Alloc>& left,
const hash_multimap<Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator!=(
const hash_map<Key, Ty, Tr, Alloc>& left,
const hash_map<Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator!=(
const hash_multimap<Key, Ty, Tr, Alloc>& left,
const hash_multimap<Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator<(
const hash_map<Key, Ty, Tr, Alloc>& left,
const hash_map<Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator<(
const hash_multimap<Key, Ty, Tr, Alloc>& left,
const hash_multimap<Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator>(
const hash_map<Key, Ty, Tr, Alloc>& left,
const hash_map<Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator>(
const hash_multimap<Key, Ty, Tr, Alloc>& left,
const hash_multimap<Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator<=(
const hash_map<Key, Ty, Tr, Alloc>& left,
const hash_map<Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator<=(
const hash_multimap<Key, Ty, Tr, Alloc>& left,
const hash_multimap<Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator>=(
const hash_map<Key, Ty, Tr, Alloc>& left,
const hash_map<Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator>=(
const hash_multimap<Key, Ty, Tr, Alloc>& left,
const hash_multimap<Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
void swap(
hash_map<Key, Ty, Tr, Alloc>& left,
hash_map<Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
void swap(
hash_multimap<Key, Ty, Tr, Alloc>& left,
hash_multimap<Key, Ty, Tr, Alloc>& right);
};template<class Key,
class Pr = less<Key> >
class hash_compare {
Pr comp;
public:
const size_t bucket_size = 4;
const size_t min_buckets = 8;
hash_compare();
hash_compare(Pr pred);
size_t operator()(const Key& Key) const;
bool operator()(const Key& keyval1,
const Key& keyval2) const;
};The template class describes an object that can be used by
any of the containers
hash_map,
hash_multimap,
hash_set, or
hash_multiset as a
hash traits object
to order the sequence it controls.
Each of these stores hash traits object of type Tr
(a template parameter). You can derive a class from a specialization of
hash_compare, to selectively override certain functions
and objects. Or you can supply your own version of this class,
provided you meet certain minimum requirements.
Specifically, for an object hash_comp of type
hash_compare<Key, Pr>,
the following behavior is required by the above containers:
- For all values
keyval of type Key,
the call hash_comp(keyval) serves as a
hash function,
which yields a distribution of values of type size_t.
The function supplied by hash_compare simply
returns keyval. - For any value
keyval1 of
type Key that precedes keyval2 in the sequence
and has the same hash value (value returned by the hash function),
hash_comp(keyval2, keyval1) is false. The function must impose a
strict weak ordering
on values of type Key.
The function supplied by hash_compare returns
comp(keyval1, keyval2) where comp is a stored
object of type Pr that you can specify when you construct
the object hash_comp. For the default Pr parameter type
less<Key>,
sort keys never decrease in value. - The integer constant
bucket_size
specifies the mean number of elements per ``bucket'' (hash-table
entry) that the container should endeavor not to exceed. It must
be greater than zero. The value supplied by
hash_compare is 4. - The integer constant
min_buckets
specifies the minimum number of buckets to maintain in the hash table.
It must be a power of two and greater than zero. The value supplied by
hash_compare is 8.
allocator_type
· begin
· clear
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· count
· difference_type
· empty
· end
· equal_range
· erase
· find
· get_allocator
· insert
· iterator
· key_comp
· key_compare
· key_type
· lower_bound
· hash_map
· mapped_type
· max_size
· operator[]
· pointer
· rbegin
· reference
· rend
· reverse_iterator
· size
· size_type
· swap
· upper_bound
· value_comp
· value_compare
· value_type
template<class Key, class Ty,
class Tr = hash_compare<Key, less<Key> >,
class Alloc = allocator<pair<const Key, Ty> > >
class hash_map {
public:
typedef Key key_type;
typedef Ty mapped_type;
typedef Tr key_compare;
typedef Alloc allocator_type;
typedef pair<const Key, Ty> value_type;
class value_compare;
typedef Alloc::pointer pointer;
typedef Alloc::const_pointer const_pointer;
typedef Alloc::reference reference;
typedef Alloc::const_reference const_reference;
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;
hash_map();
explicit hash_map(const Tr& traits);
hash_map(const Tr& traits, const Alloc& al);
hash_map(const hash_map& right);
template<class InIt>
hash_map(InIt first, InIt last);
template<class InIt>
hash_map(InIt first, InIt last,
const Tr& traits);
template<class InIt>
hash_map(InIt first, InIt last,
const Tr& traits, const Alloc& al);
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;
size_type size() const;
size_type max_size() const;
bool empty() const;
Alloc get_allocator() const;
mapped_type operator[](const Key& keyval);
pair<iterator, bool> insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
void clear();
void swap(hash_map& right);
key_compare key_comp() const;
value_compare value_comp() const;
iterator find(const Key& keyval);
const_iterator find(const Key& keyval) const;
size_type count(const Key& keyval) const;
iterator lower_bound(const Key& keyval);
const_iterator lower_bound(const Key& keyval) const;
iterator upper_bound(const Key& keyval);
const_iterator upper_bound(const Key& keyval) const;
pair<iterator, iterator> equal_range(const Key& keyval);
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;
};The template class describes an object that controls a
varying-length sequence of elements of type
pair<const Key, Ty>.
The sequence is
ordered by the
hash traits object
Tr, which includes both a two-operand function for imposing a
strict weak ordering
and a one-operand hash function.
The first element of each pair is the sort key and the
second is its associated value.
The sequence is represented in a way that permits lookup, insertion,
and removal of an arbitrary element with a number of operations that can be
independent of the number of elements in the sequence (constant time).
In the worst case, the number of operations is
proportional to the number of elements
in the sequence (linear time). Moreover, inserting an element
invalidates no iterators, and removing an element
invalidates only those iterators which point at the removed element.
The object orders the sequence it controls by calling a stored
hash traits object of type Tr.
You access this stored object by calling the member function
key_comp().
Such a traits object must behave the same as an object of class
hash_compare<Key, Pr>.
Specifically, for all values keyval of type Key,
the call key_comp()(keyval) yields a distribution
of values of type size_t.
Moreover, class Pr imposes a
strict weak ordering
on sort keys of type Key.
For any element X that precedes
Y in the sequence and has the same hash value,
key_comp()(Y.first,
X.first) is false. (For the default function object
less<Key>,
sort keys never decrease in value.)
Unlike template class hash_multimap,
an object of template class hash_map ensures that
key_comp()(X.first, Y.first) is true.
(Each key is unique.)
The actual order of elements in the controlled sequence depends on the
hash function, the ordering function, and the current size of the hash
table stored in the container object. You cannot determine the current size
of the hash table, so you cannot in general predict the order of elements
in the controlled sequence.
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class Alloc. Such an allocator object must have
the same external interface as an object of template class
allocator.
Note that the stored allocator object is not copied when the container
object is assigned.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
const_iterator begin() const;
iterator begin();
The member function returns a bidirectional iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
void clear();
The member function calls
erase(
begin(),
end()).
typedef T1 const_iterator;
The type describes an object that can serve as a constant
bidirectional iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T1.
typedef Alloc::const_pointer const_pointer;
The type describes an object that can serve as a constant pointer
to an element of the controlled sequence.
typedef Alloc::const_reference const_reference;
The type describes an object that can serve as a constant reference
to an element of the controlled sequence.
typedef reverse_iterator<const_iterator>
const_reverse_iterator;The type describes an object that can serve as a constant reverse
bidirectional iterator for the controlled sequence.
size_type count(const Key& keyval) const;
The member function returns the number of elements in the range
[lower_bound(keyval),
upper_bound(keyval)).
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 function returns a bidirectional iterator that points
just beyond the end of the sequence.
pair<iterator, iterator> equal_range(const Key& keyval);
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;The member function returns a pair of iterators X
such that X.first ==
lower_bound(keyval)
and X.second ==
upper_bound(keyval).
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
The first member function removes the element of the controlled
sequence pointed to by where.
The second member function removes the elements
in the interval [first, last).
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
the elements with sort keys in the range
[lower_bound(keyval),
upper_bound(keyval)).
It returns the number of elements it removes.
The member functions never throw an exception.
iterator find(const Key& keyval);
const_iterator find(const Key& keyval) const;
The member function returns
lower_bound(keyval).
Alloc get_allocator() const;
The member function returns the stored
allocator object.
hash_map();
explicit hash_map(const Tr& traits);
hash_map(const Tr& traits, const Alloc& al);
hash_map(const hash_map& right);
template<class InIt>
hash_map(InIt first, InIt last);
template<class InIt>
hash_map(InIt first, InIt last,
const Tr& traits);
template<class InIt>
hash_map(InIt first, InIt last,
const Tr& traits, const Alloc& 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
right.get_allocator().
Otherwise, it is Alloc().
All constructors also store a
hash traits object that can later
be returned by calling
key_comp().
The hash traits object is the argument traits, if present.
For the copy constructor, it is
right.key_comp()).
Otherwise, it is Tr().
The first three constructors specify an
empty initial controlled sequence. The fourth constructor specifies
a copy of the sequence controlled by right.
The last three constructors specify the sequence of element values
[first, last).
pair<iterator, bool> insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);The first member function determines whether an element X
exists in the sequence whose key has
equivalent ordering
to that of val. If not, it creates such
an element X and initializes it with val.
The function then determines the iterator where that
designates X. If an insertion occurred, the function
returns pair(iter, true).
Otherwise, it returns pair(where, false).
The second member function returns insert(val).first,
using where as a starting place within the controlled
sequence to search for the insertion point. (Insertion can
possibly occur somewhat faster, if the
insertion point immediately precedes or follows where.)
The third member function
inserts the sequence of element values,
for each where in the range [first, last),
by calling insert(*where).
If an exception is thrown during the
insertion of a single element, the container is left unaltered
and the exception is rethrown.
If an exception is thrown during the
insertion of multiple elements, the container is left in a stable
but unspecified state and the exception is rethrown.
typedef T0 iterator;
The type describes an object that can serve as a bidirectional
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T0.
key_compare key_comp() const;
The member function returns the stored
hash traits object that
determines the order of elements in the controlled sequence.
In particular, the stored object defines the member function:
bool operator()(const Key& left, const Key& right);
which returns true if left strictly
precedes right in the sort order.
typedef Tr key_compare;
The type describes a traits object that behaves much like an object of class
hash_compare<Key, Pr>.
In particular, it can compare two
sort keys to determine the relative order of two
elements in the controlled sequence.
typedef Key key_type;
The type describes the sort key object stored in each
element of the controlled sequence.
iterator lower_bound(const Key& keyval);
const_iterator lower_bound(const Key& keyval) const;
The member function returns an iterator that designates the
earliest element X in the controlled sequence
for which X.first has
equivalent ordering
to keyval.
If no such element exists, the function returns
end().
typedef Ty mapped_type;
The type is a synonym for the template parameter Ty.
size_type max_size() const;
The member function returns the length of the longest sequence that
the object can control.
Ty& operator[](const Key& keyval);
The member function determines the iterator where
as the return value of
insert(
value_type(keyval, Ty()).
(It inserts an element with the specified key if no such element
exists.) It then returns a reference to
(*where).second.
typedef Alloc::pointer pointer;
The type describes an object that can serve as a pointer to an
element of the controlled sequence.
const_reverse_iterator rbegin() const;
reverse_iterator rbegin();
The member function returns a reverse bidirectional
iterator that points just
beyond the end of the controlled sequence. Hence, it designates the
beginning of the reverse sequence.
typedef Alloc::reference reference;
The type describes an object that can serve as a reference to an
element of the controlled sequence.
const_reverse_iterator rend() const;
reverse_iterator rend();
The member function returns a reverse bidirectional
iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, it designates the end of the reverse sequence.
typedef reverse_iterator<iterator> reverse_iterator;
The type describes an object that can serve as a reverse
bidirectional iterator for the controlled sequence.
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.
void swap(hash_map& right);
The member function swaps the controlled sequences between
*this and right. If
get_allocator()
== right.get_allocator(), it does so in constant time,
it throws an exception only as a result of copying the stored
traits object of type Tr, 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.
iterator upper_bound(const Key& keyval);
const_iterator upper_bound(const Key& keyval) const;
The member function returns an iterator
just beyond the iterator that designates the
latest element X in the controlled sequence
for which X.first has
equivalent ordering
to keyval.
If no such element exists, the function returns
end().
value_compare value_comp() const;
The member function returns a function object that
determines the order of elements in the controlled sequence.
class value_compare
: public binary_function<value_type, value_type,
bool> {
public:
bool operator()(const value_type& left,
const value_type& right) const
{return (comp(left.first, right.first)); }
protected:
value_compare(key_compare pr)
: comp(pr) {}
key_compare comp;
};The type describes a function object that can compare the
sort keys in two elements to determine their relative order
in the controlled sequence. The function object stores an object
comp
of type key_type.
The member function operator() uses this
object to compare the sort-key components of two element.
typedef pair<const Key, Ty> value_type;
The type describes an element of the controlled sequence.
allocator_type
· begin
· clear
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· count
· difference_type
· empty
· end
· equal_range
· erase
· find
· get_allocator
· insert
· iterator
· key_comp
· key_compare
· key_type
· lower_bound
· mapped_type
· max_size
· hash_multimap
· rbegin
· reference
· rend
· reverse_iterator
· size
· size_type
· swap
· upper_bound
· value_comp
· value_compare
· value_type
template<class Key, class Ty,
class Tr = hash_compare<Key, less<Key> >,
class Alloc = allocator<pair<const Key, Ty> > >
class hash_multimap {
public:
typedef Key key_type;
typedef Ty mapped_type;
typedef Tr key_compare;
typedef Alloc allocator_type;
typedef pair<const Key, Ty> value_type;
class value_compare;
typedef Alloc::pointer pointer;
typedef Alloc::const_pointer const_pointer;
typedef Alloc::reference reference;
typedef Alloc::const_reference const_reference;
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;
hash_multimap();
explicit hash_multimap(const Tr& traits);
hash_multimap(const Tr& traits, const Alloc& al);
hash_multimap(const hash_multimap& right);
template<class InIt>
hash_multimap(InIt first, InIt last);
template<class InIt>
hash_multimap(InIt first, InIt last,
const Tr& traits);
template<class InIt>
hash_multimap(InIt first, InIt last,
const Tr& traits, const Alloc& al);
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;
size_type size() const;
size_type max_size() const;
bool empty() const;
Alloc get_allocator() const;
iterator insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
void clear();
void swap(hash_multimap& right);
key_compare key_comp() const;
value_compare value_comp() const;
iterator find(const Key& keyval);
const_iterator find(const Key& keyval) const;
size_type count(const Key& keyval) const;
iterator lower_bound(const Key& keyval);
const_iterator lower_bound(const Key& keyval) const;
iterator upper_bound(const Key& keyval);
const_iterator upper_bound(const Key& keyval) const;
pair<iterator, iterator> equal_range(const Key& keyval);
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;
};The template class describes an object that controls a
varying-length sequence of elements of type
pair<const Key, Ty>.
The sequence is
ordered by the
hash traits object
Tr, which includes both a two-operand function for imposing a
strict weak ordering
and a one-operand hash function.
The first element of each pair is the sort key and the
second is its associated value.
The sequence is represented in a way that permits lookup, insertion,
and removal of an arbitrary element with a number of operations that can be
independent of the number of elements in the sequence (constant time).
In the worst case, the number of operations is
proportional to the number of elements
in the sequence (linear time). Moreover, inserting an element
invalidates no iterators, and removing an element
invalidates only those iterators which point at the removed element.
The object orders the sequence it controls by calling a stored
hash traits object of type Tr.
You access this stored object by calling the member function
key_comp().
Such a traits object must behave the same as an object of class
hash_compare<Key, Pr>.
Specifically, for all values keyval of type Key,
the call key_comp()(keyval) yields a distribution
of values of type size_t.
Moreover, class Pr imposes a
strict weak ordering
on sort keys of type Key.
For any element X that precedes
Y in the sequence and has the same hash value,
key_comp()(Y.first,
X.first) is false. (For the default function object
less<Key>,
sort keys never decrease in value.)
Unlike template class hash_map,
an object of template class hash_multimap does not ensure that
key_comp()(X.first, Y.first) is true.
(Keys need not be unique.)
The actual order of elements in the controlled sequence depends on the
hash function, the ordering function, and the current size of the hash
table stored in the container object. You cannot determine the current size
of the hash table, so you cannot in general predict the order of elements
in the controlled sequence. You can always be assured, however, that any
subset of elements that have
equivalent ordering
are adjacent in the controlled sequence.
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class Alloc. Such an allocator object must have
the same external interface as an object of template class
allocator.
Note that the stored allocator object is not copied when the container
object is assigned.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
const_iterator begin() const;
iterator begin();
The member function returns a bidirectional iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
void clear();
The member function calls
erase(
begin(),
end()).
typedef T1 const_iterator;
The type describes an object that can serve as a constant
bidirectional iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T1.
typedef Alloc::const_pointer const_pointer;
The type describes an object that can serve as a constant pointer
to an element of the controlled sequence.
typedef Alloc::const_reference const_reference;
The type describes an object that can serve as a constant reference
to an element of the controlled sequence.
typedef reverse_iterator<const_iterator>
const_reverse_iterator;The type describes an object that can serve as a constant reverse
bidirectional iterator for the controlled sequence.
size_type count(const Key& keyval) const;
The member function returns the number of elements in the range
[lower_bound(keyval),
upper_bound(keyval)).
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 function returns a bidirectional iterator that points
just beyond the end of the sequence.
pair<iterator, iterator> equal_range(const Key& keyval);
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;The member function returns a pair of iterators X
such that X.first ==
lower_bound(keyval)
and X.second ==
upper_bound(keyval).
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
The first member function removes the element of the controlled
sequence pointed to by where.
The second member function removes the elements
in the range [first, last).
Both return an iterator that designates the first element remaining
beyond any elements removed, or
end() if no such element exists.
The third member removes
the elements with sort keys in the range
[lower_bound(keyval),
upper_bound(keyval)).
It returns the number of elements it removes.
The member functions never throw an exception.
iterator find(const Key& keyval);
const_iterator find(const Key& keyval) const;
The member function returns
lower_bound(keyval).
Alloc get_allocator() const;
The member function returns the stored
allocator object.
hash_multimap();
explicit hash_multimap(const Tr& traits);
hash_multimap(const Tr& traits, const Alloc& al);
hash_multimap(const hash_multimap& right);
template<class InIt>
hash_multimap(InIt first, InIt last);
template<class InIt>
hash_multimap(InIt first, InIt last,
const Tr& traits);
template<class InIt>
hash_multimap(InIt first, InIt last,
const Tr& traits, const Alloc& 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
right.get_allocator().
Otherwise, it is Alloc().
All constructors also store a
hash traits object that can later
be returned by calling
key_comp().
The hash traits object is the argument traits, if present.
For the copy constructor, it is
right.key_comp()).
Otherwise, it is Tr().
The first three constructors specify an
empty initial controlled sequence. The fourth constructor specifies
a copy of the sequence controlled by right.
The last three constructors specify the sequence of element values
[first, last).
iterator insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);The first member function inserts the element val
in the controlled sequence, then returns
the iterator that designates the inserted element.
The second member function returns insert(val),
using where as a starting place within the controlled
sequence to search for the insertion point. (Insertion can
possibly occur somewhat faster, if the
insertion point immediately precedes or follows where.)
The third member function
inserts the sequence of element values,
for each where in the range [first, last),
by calling insert(*where).
If an exception is thrown during the
insertion of a single element, the container is left unaltered
and the exception is rethrown.
If an exception is thrown during the
insertion of multiple elements, the container is left in a stable
but unspecified state and the exception is rethrown.
typedef T0 iterator;
The type describes an object that can serve as a bidirectional
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T0.
key_compare key_comp() const;
The member function returns the stored
hash traits object that
determines the order of elements in the controlled sequence.
In particular, the stored object defines the member function:
bool operator()(const Key& left, const Key& right);
which returns true if left strictly
precedes right in the sort order.
typedef Tr key_compare;
The type describes a traits object that behaves much like an object of class
hash_compare<Key, Pr>.
In particular, it can compare two
sort keys to determine the relative order of two
elements in the controlled sequence.
typedef Key key_type;
The type describes the sort key object stored in each
element of the controlled sequence.
iterator lower_bound(const Key& keyval);
const_iterator lower_bound(const Key& keyval) const;
The member function returns an iterator that designates the
earliest element X in the controlled sequence for which
key_comp()(X.
first, keyval) is
false.
If no such element exists, the function returns
end().
typedef Ty mapped_type;
The type is a synonym for the template parameter Ty.
size_type max_size() const;
The member function returns the length of the longest sequence that
the object can control.
typedef Alloc::pointer pointer;
The type describes an object that can serve as a pointer to an
element of the controlled sequence.
const_reverse_iterator rbegin() const;
reverse_iterator rbegin();
The member function returns a reverse bidirectional
iterator that points just
beyond the end of the controlled sequence. Hence, it designates the
beginning of the reverse sequence.
typedef Alloc::reference reference;
The type describes an object that can serve as a reference to an
element of the controlled sequence.
const_reverse_iterator rend() const;
reverse_iterator rend();
The member function returns a reverse bidirectional
iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, it designates the end of the reverse sequence.
typedef reverse_iterator<iterator> reverse_iterator;
The type describes an object that can serve as a reverse
bidirectional iterator for the controlled sequence.
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.
void swap(hash_multimap& right);
The member function swaps the controlled sequences between
*this and right. If
get_allocator()
== right.get_allocator(), it does so in constant time,
it throws an exception only as a result of copying the stored
traits object of type Tr, 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.
iterator upper_bound(const Key& keyval);
const_iterator upper_bound(const Key& keyval) const;
The member function returns an iterator
just beyond the iterator that designates the
latest element X in the controlled sequence
for which X.first has
equivalent ordering
to keyval.
If no such element exists, the function returns
end().
value_compare value_comp() const;
The member function returns a function object that
determines the order of elements in the controlled sequence.
class value_compare
: public binary_function<value_type, value_type,
bool> {
public:
bool operator()(const value_type& left,
const value_type& right) const
{return (comp(left.first, right.first)); }
protected:
value_compare(key_compare pr)
: comp(pr) {}
key_compare comp;
};The type describes a function object that can compare the
sort keys in two elements to determine their relative order
in the controlled sequence. The function object stores an object
comp
of type key_type.
The member function operator() uses this
object to compare the sort-key components of two element.
typedef pair<const Key, Ty> value_type;
The type describes an element of the controlled sequence.
template<class Key, class Ty, class Tr, class Alloc>
bool operator!=(
const hash_map <Key, Ty, Tr, Alloc>& left,
const hash_map <Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator!=(
const hash_multimap <Key, Ty, Tr, Alloc>& left,
const hash_multimap <Key, Ty, Tr, Alloc>& right);The template function returns !(left == right).
template<class Key, class Ty, class Tr, class Alloc>
bool operator==(
const hash_map <Key, Ty, Tr, Alloc>& left,
const hash_map <Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator==(
const hash_multimap <Key, Ty, Tr, Alloc>& left,
const hash_multimap <Key, Ty, Tr, Alloc>& right);The first template function overloads operator==
to compare two objects of template class
hash_map.
The second template function overloads operator==
to compare two objects of template class
hash_multimap.
Both functions return
left.size() == right.size() &&
equal(left.
begin(), left.
end(), right.begin()).
template<class Key, class Ty, class Tr, class Alloc>
bool operator<(
const hash_map <Key, Ty, Tr, Alloc>& left,
const hash_map <Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator<(
const hash_multimap <Key, Ty, Tr, Alloc>& left,
const hash_multimap <Key, Ty, Tr, Alloc>& right);The first template function overloads operator<
to compare two objects of template class
hash_map.
The second template function overloads operator<
to compare two objects of template class
hash_multimap.
Both functions return
lexicographical_compare(left.
begin(), left.
end(), right.begin(), right.end(),
left.value_comp()).
template<class Key, class Ty, class Tr, class Alloc>
bool operator<=(
const hash_map <Key, Ty, Tr, Alloc>& left,
const hash_map <Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator<=(
const hash_multimap <Key, Ty, Tr, Alloc>& left,
const hash_multimap <Key, Ty, Tr, Alloc>& right);The template function returns !(right < left).
template<class Key, class Ty, class Tr, class Alloc>
bool operator>(
const hash_map <Key, Ty, Tr, Alloc>& left,
const hash_map <Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator>(
const hash_multimap <Key, Ty, Tr, Alloc>& left,
const hash_multimap <Key, Ty, Tr, Alloc>& right);The template function returns right < left.
template<class Key, class Ty, class Tr, class Alloc>
bool operator>=(
const hash_map <Key, Ty, Tr, Alloc>& left,
const hash_map <Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
bool operator!=(
const hash_multimap <Key, Ty, Tr, Alloc>& left,
const hash_multimap <Key, Ty, Tr, Alloc>& right);The template function returns !(left < right).
template<class Key, class Ty, class Tr, class Alloc>
void swap(
hash_map <Key, Ty, Tr, Alloc>& left,
hash_map <Key, Ty, Tr, Alloc>& right);
template<class Key, class Ty, class Tr, class Alloc>
void swap(
hash_multimap <Key, Ty, Tr, Alloc>& left,
hash_multimap <Key, Ty, Tr, Alloc>& right);The template function executes
left.swap(right).
See also the
Table of Contents and the
Index.
Copyright © 1998-2002
by P.J. Plauger. All rights reserved.
36 - hash_set
<hash_set>
Include the STL
standard header <hash_set> to define the
container
template classes hash_set and
hash_multiset, and their supporting
templates.
namespace std {
template<class Key, class Tr, class Alloc>
class hash_set;
template<class Key, class Tr, class Alloc>
class hash_multiset;
// TEMPLATE FUNCTIONS
template<class Key, class Tr, class Alloc>
bool operator==(
const hash_set<Key, Tr, Alloc>& left,
const hash_set<Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator==(
const hash_multiset<Key, Tr, Alloc>& left,
const hash_multiset<Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator!=(
const hash_set<Key, Tr, Alloc>& left,
const hash_set<Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator!=(
const hash_multiset<Key, Tr, Alloc>& left,
const hash_multiset<Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator<(
const hash_set<Key, Tr, Alloc>& left,
const hash_set<Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator<(
const hash_multiset<Key, Tr, Alloc>& left,
const hash_multiset<Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator>(
const hash_set<Key, Tr, Alloc>& left,
const hash_set<Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator>(
const hash_multiset<Key, Tr, Alloc>& left,
const hash_multiset<Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator<=(
const hash_set<Key, Tr, Alloc>& left,
const hash_set<Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator<=(
const hash_multiset<Key, Tr, Alloc>& left,
const hash_multiset<Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator>=(
const hash_set<Key, Tr, Alloc>& left,
const hash_set<Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator>=(
const hash_multiset<Key, Tr, Alloc>& left,
const hash_multiset<Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
void swap(
hash_set<Key, Tr, Alloc>& left,
hash_set<Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
void swap(
hash_multiset<Key, Tr, Alloc>& left,
hash_multiset<Key, Tr, Alloc>& right);
};
allocator_type
· begin
· clear
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· count
· difference_type
· empty
· end
· equal_range
· erase
· find
· get_allocator
· insert
· iterator
· key_comp
· key_compare
· key_type
· lower_bound
· max_size
· hash_multiset
· pointer
· rbegin
· reference
· rend
· reverse_iterator
· size
· size_type
· swap
· upper_bound
· value_comp
· value_compare
· value_type
template<class Key,
class Tr = hash_compare<Key, less<Key> >,
class Alloc = allocator<Key> >
class hash_multiset {
public:
typedef Key key_type;
typedef Tr key_compare;
typedef Key value_type;
typedef Tr value_compare;
typedef Alloc allocator_type;
typedef Alloc::pointer pointer;
typedef Alloc::const_pointer const_pointer;
typedef Alloc::reference reference;
typedef Alloc::const_reference const_reference;
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;
hash_multiset();
explicit hash_multiset(const Tr& traits);
hash_multiset(const Tr& traits, const Alloc& al);
hash_multiset(const hash_multiset& right);
template<class InIt>
hash_multiset(InIt first, InIt last);
template<class InIt>
hash_multiset(InIt first, InIt last,
const Tr& traits);
template<class InIt>
hash_multiset(InIt first, InIt last,
const Tr& traits, const Alloc& al);
const_iterator begin() const;
const_iterator end() const;
const_reverse_iterator rbegin() const;
const_reverse_iterator rend() const;
size_type size() const;
size_type max_size() const;
bool empty() const;
Alloc get_allocator() const;
iterator insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
void clear();
void swap(hash_multiset& right);
key_compare key_comp() const;
value_compare value_comp() const;
const_iterator find(const Key& keyval) const;
size_type count(const Key& keyval) const;
const_iterator lower_bound(const Key& keyval) const;
const_iterator upper_bound(const Key& keyval) const;
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;
};The template class describes an object that controls a
varying-length sequence of elements of type
const Key.
The sequence is
ordered by the
hash traits object
Tr, which includes both a two-operand function for imposing a
strict weak ordering
and a one-operand hash function.
Each element serves as both a sort key and a value.
The sequence is represented in a way that permits lookup, insertion,
and removal of an arbitrary element with a number of operations that can be
independent of the number of elements in the sequence (constant time).
In the worst case, the number of operations is
proportional to the number of elements
in the sequence (linear time). Moreover, inserting an element
invalidates no iterators, and removing an element
invalidates only those iterators which point at the removed element.
The object orders the sequence it controls by calling a stored
hash traits object of type Tr.
You access this stored object by calling the member function
key_comp().
Such a traits object must behave the same as an object of class
hash_compare<Key, Pr>.
Specifically, for all values keyval of type Key,
the call Tr(keyval) yields a distribution
of values of type size_t.
Moreover, class Pr imposes a
strict weak ordering
on sort keys of type Key.
For any element X that precedes
Y in the sequence and has the same hash value,
key_comp()(Y, X) is false. (For the default function object
less<Key>,
sort keys never decrease in value.)
Unlike template class hash_set,
an object of template class hash_multiset does not ensure that
key_comp()(X, Y) is true.
(Keys need not be unique.)
The actual order of elements in the controlled sequence depends on the
hash function, the ordering function, and the current size of the hash
table stored in the container object. You cannot determine the current size
of the hash table, so you cannot in general predict the order of elements
in the controlled sequence. You can always be assured, however, that any
subset of elements that have
equivalent ordering
are adjacent in the controlled sequence.
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class Alloc. Such an allocator object must have
the same external interface as an object of template class
allocator.
Note that the stored allocator object is not copied when the container
object is assigned.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
const_iterator begin() const;
The member function returns a bidirectional iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
void clear();
The member function calls
erase(
begin(),
end()).
typedef T1 const_iterator;
The type describes an object that can serve as a constant
bidirectional iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T1.
typedef Alloc::const_pointer const_pointer;
The type describes an object that can serve as a constant pointer
to an element of the controlled sequence.
typedef Alloc::const_reference const_reference;
The type describes an object that can serve as a constant reference
to an element of the controlled sequence.
typedef reverse_iterator<const_iterator>
const_reverse_iterator;The type describes an object that can serve as a constant reverse
bidirectional iterator for the controlled sequence.
size_type count(const Key& keyval) const;
The member function returns the number of elements in the range
[lower_bound(keyval),
upper_bound(keyval)).
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;
The member function returns a bidirectional iterator that points
just beyond the end of the sequence.
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;The member function returns a pair of iterators X
such that X.first ==
lower_bound(keyval)
and X.second ==
upper_bound(keyval).
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
The first member function removes the element of the controlled
sequence pointed to by where.
The second member function removes the elements
in the range [first, last).
Both return an iterator that designates the first element remaining
beyond any elements removed, or
end() if no such element exists.
The third member removes
the elements with sort keys in the range
[lower_bound(keyval),
upper_bound(keyval)).
It returns the number of elements it removes.
The member functions never throw an exception.
const_iterator find(const Key& keyval) const;
The member function returns
lower_bound(keyval).
Alloc get_allocator() const;
The member function returns the stored
allocator object.
hash_multiset();
explicit hash_multiset(const Tr& traits);
hash_multiset(const Tr& traits, const Alloc& al);
hash_multiset(const hash_multiset& right);
template<class InIt>
hash_multiset(InIt first, InIt last);
template<class InIt>
hash_multiset(InIt first, InIt last,
const Tr& traits);
template<class InIt>
hash_multiset(InIt first, InIt last,
const Tr& traits, const Alloc& 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
right.get_allocator().
Otherwise, it is Alloc().
All constructors also store a
hash traits object that can later
be returned by calling
key_comp().
The hash traits object is the argument traits, if present.
For the copy constructor, it is
right.key_comp()).
Otherwise, it is Tr().
The first three constructors specify an
empty initial controlled sequence. The fourth constructor specifies
a copy of the sequence controlled by right.
The last three constructors specify the sequence of element values
[first, last).
iterator insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);The first member function inserts the element val
in the controlled sequence, then returns
the iterator that designates the inserted element.
The second member function returns insert(val),
using where as a starting place within the controlled
sequence to search for the insertion point. (Insertion can
possibly occur somewhat faster, if the
insertion point immediately precedes or follows where.)
The third member function
inserts the sequence of element values,
for each where in the range [first, last),
by calling insert(*where).
If an exception is thrown during the
insertion of a single element, the container is left unaltered
and the exception is rethrown.
If an exception is thrown during the
insertion of multiple elements, the container is left in a stable
but unspecified state and the exception is rethrown.
typedef T0 iterator;
The type describes an object that can serve as a bidirectional
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T0.
key_compare key_comp() const;
The member function returns the stored
hash traits object that
determines the order of elements in the controlled sequence.
In particular, the stored object defines the member function:
bool operator()(const Key& left, const Key& right);
which returns true if left strictly
precedes right in the sort order.
typedef Tr key_compare;
The type describes a traits object that behaves much like an object of class
hash_compare<Key, Pr>.
In particular, it can compare two
sort keys to determine the relative order of two
elements in the controlled sequence.
typedef Key key_type;
The type describes the sort key object which constitutes each
element of the controlled sequence.
const_iterator lower_bound(const Key& keyval) const;
The member function returns an iterator that designates the
earliest element X in the controlled sequence
for which X has
equivalent ordering
to keyval, as well as the same hash value.
(This is generally uninteresting, except that the interval
[lower_bound(keyval), upper_bound(keyval)) does
delimit all elements with equivalent ordering to keyval.)
If no such element exists, the function returns
end().
size_type max_size() const;
The member function returns the length of the longest sequence that
the object can control.
typedef Alloc::pointer pointer;
The type describes an object that can serve as a pointer to an
element of the controlled sequence.
const_reverse_iterator rbegin() const;
The member function returns a reverse bidirectional
iterator that points just
beyond the end of the controlled sequence. Hence, it designates the
beginning of the reverse sequence.
typedef Alloc::reference reference;
The type describes an object that can serve as a reference to an
element of the controlled sequence.
const_reverse_iterator rend() const;
The member function returns a reverse bidirectional
iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, it designates the end of the reverse sequence.
typedef reverse_iterator<iterator> reverse_iterator;
The type describes an object that can serve as a reverse
bidirectional iterator for the controlled sequence.
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.
void swap(hash_multiset& right);
The member function swaps the controlled sequences between
*this and right. If
get_allocator()
== right.get_allocator(), it does so in constant time,
it throws an exception only as a result of copying the stored
traits object of type Tr, 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.
const_iterator upper_bound(const Key& keyval) const;
The member function returns an iterator
just beyond the iterator that designates the
latest element X in the controlled sequence
for which X has
equivalent ordering
to keyval.
If no such element exists, the function returns
end().
value_compare value_comp() const;
The member function returns a function object that
determines the order of elements in the controlled sequence.
typedef Tr value_compare;
The type describes a function object that can compare two
elements as sort keys to determine their relative order
in the controlled sequence.
typedef Key value_type;
The type describes an element of the controlled sequence.
allocator_type
· begin
· clear
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· count
· difference_type
· empty
· end
· equal_range
· erase
· find
· get_allocator
· insert
· iterator
· key_comp
· key_compare
· key_type
· lower_bound
· max_size
· pointer
· rbegin
· reference
· rend
· reverse_iterator
· hash_set
· size
· size_type
· swap
· upper_bound
· value_comp
· value_compare
· value_type
template<class Key,
class Tr = hash_compare<Key, less<Key> >,
class Alloc = allocator<Key> >
class hash_set {
public:
typedef Key key_type;
typedef Tr key_compare;
typedef Key value_type;
typedef Tr value_compare;
typedef Alloc allocator_type;
typedef Alloc::pointer pointer;
typedef Alloc::const_pointer const_pointer;
typedef Alloc::reference reference;
typedef Alloc::const_reference const_reference;
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;
hash_set();
explicit hash_set(const Tr& traits);
hash_set(const Tr& traits, const Alloc& al);
hash_set(const hash_set& right);
template<class InIt>
hash_set(InIt first, InIt last);
template<class InIt>
hash_set(InIt first, InIt last,
const Tr& traits);
template<class InIt>
hash_set(InIt first, InIt last,
const Tr& traits, const Alloc& al);
const_iterator begin() const;
const_iterator end() const;
const_reverse_iterator rbegin() const;
const_reverse_iterator rend() const;
size_type size() const;
size_type max_size() const;
bool empty() const;
Alloc get_allocator() const;
pair<iterator, bool> insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
void clear();
void swap(hash_set& right);
key_compare key_comp() const;
value_compare value_comp() const;
const_iterator find(const Key& keyval) const;
size_type count(const Key& keyval) const;
const_iterator lower_bound(const Key& keyval) const;
const_iterator upper_bound(const Key& keyval) const;
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;
};The template class describes an object that controls a
varying-length sequence of elements of type
const Key.
The sequence is
ordered by the
hash traits object
Tr, which includes both a two-operand function for imposing a
strict weak ordering
and a one-operand hash function.
Each element serves as both a sort key and a value.
The sequence is represented in a way that permits lookup, insertion,
and removal of an arbitrary element with a number of operations that can be
independent of the number of elements in the sequence (constant time).
In the worst case, the number of operations is
proportional to the number of elements
in the sequence (linear time). Moreover, inserting an element
invalidates no iterators, and removing an element
invalidates only those iterators which point at the removed element.
The object orders the sequence it controls by calling a stored
hash traits object of type Tr.
You access this stored object by calling the member function
key_comp().
Such a traits object must behave the same as an object of class
hash_compare<Key, Pr>.
Specifically, for all values keyval of type Key,
the call Tr(keyval) yields a distribution
of values of type size_t.
Moreover, class Pr imposes a
strict weak ordering
on sort keys of type Key.
For any element X that precedes
Y in the sequence and has the same hash value,
key_comp()(Y, X) is false. (For the default function object
less<Key>,
sort keys never decrease in value.)
Unlike template class hash_multiset,
an object of template class hash_set ensures that
key_comp()(X, Y) is true.
(Each key is unique.)
The actual order of elements in the controlled sequence depends on the
hash function, the ordering function, and the current size of the hash
table stored in the container object. You cannot determine the current size
of the hash table, so you cannot in general predict the order of elements
in the controlled sequence.
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class Alloc. Such an allocator object must have
the same external interface as an object of template class
allocator.
Note that the stored allocator object is not copied when the container
object is assigned.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
const_iterator begin() const;
The member function returns a bidirectional iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
void clear();
The member function calls
erase(
begin(),
end()).
typedef T1 const_iterator;
The type describes an object that can serve as a constant
bidirectional iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T1.
typedef Alloc::const_pointer const_pointer;
The type describes an object that can serve as a constant pointer
to an element of the controlled sequence.
typedef Alloc::const_reference const_reference;
The type describes an object that can serve as a constant reference
to an element of the controlled sequence.
typedef reverse_iterator<const_iterator>
const_reverse_iterator;The type describes an object that can serve as a constant reverse
bidirectional iterator for the controlled sequence.
size_type count(const Key& keyval) const;
The member function returns the number of elements in the range
[lower_bound(keyval),
upper_bound(keyval)).
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;
The member function returns a bidirectional iterator that points
just beyond the end of the sequence.
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;The member function returns a pair of iterators X
such that X.first ==
lower_bound(keyval)
and X.second ==
upper_bound(keyval).
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
The first member function removes the element of the controlled
sequence pointed to by where.
The second member function removes the elements
in the range [first, last).
Both return an iterator that designates the first element remaining
beyond any elements removed, or
end() if no such element exists.
The third member removes
the elements with sort keys in the range
[lower_bound(keyval),
upper_bound(keyval)).
It returns the number of elements it removes.
The member functions never throw an exception.
const_iterator find(const Key& keyval) const;
The member function returns
lower_bound(keyval).
Alloc get_allocator() const;
The member function returns the stored
allocator object.
hash_set();
explicit hash_set(const Tr& traits);
hash_set(const Tr& traits, const Alloc& al);
hash_set(const hash_set& right);
template<class InIt>
hash_set(InIt first, InIt last);
template<class InIt>
hash_set(InIt first, InIt last,
const Tr& traits);
template<class InIt>
hash_set(InIt first, InIt last,
const Tr& traits, const Alloc& 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
right.get_allocator().
Otherwise, it is Alloc().
All constructors also store a
hash traits object that can later
be returned by calling
key_comp().
The hash traits object is the argument traits, if present.
For the copy constructor, it is
right.key_comp()).
Otherwise, it is Tr().
The first three constructors specify an
empty initial controlled sequence. The fourth constructor specifies
a copy of the sequence controlled by right.
The last three constructors specify the sequence of element values
[first, last).
pair<iterator, bool> insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);The first member function determines whether an element X
exists in the sequence whose key has
equivalent ordering
to val. If not, it creates such
an element X and initializes it with val.
The function then determines the iterator where that
designates X. If an insertion occurred, the function
returns pair(where, true).
Otherwise, it returns pair(where, false).
The second member function returns insert(val).first,
using where as a starting place within the controlled
sequence to search for the insertion point. (Insertion can
possibly occur somewhat faster, if the
insertion point immediately precedes or follows where.)
The third member function
inserts the sequence of element values,
for each where in the range [first, last),
by calling insert(*where).
If an exception is thrown during the
insertion of a single element, the container is left unaltered
and the exception is rethrown.
If an exception is thrown during the
insertion of multiple elements, the container is left in a stable
but unspecified state and the exception is rethrown.
typedef T0 iterator;
The type describes an object that can serve as a bidirectional
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T0.
key_compare key_comp() const;
The member function returns the stored
hash traits object that
determines the order of elements in the controlled sequence.
In particular, the stored object defines the member function:
bool operator()(const Key& left, const Key& right);
which returns true if left strictly
precedes right in the sort order.
typedef Tr key_compare;
The type describes a traits object that behaves much like an object of class
hash_compare<Key, Pr>.
In particular, it can compare two
sort keys to determine the relative order of two
elements in the controlled sequence.
typedef Key key_type;
The type describes the sort key object which constitutes each
element of the controlled sequence.
const_iterator lower_bound(const Key& keyval) const;
The member function returns an iterator that designates the
earliest element X in the controlled sequence
for which X has
equivalent ordering
to keyval.
If no such element exists, the function returns
end().
size_type max_size() const;
The member function returns the length of the longest sequence that
the object can control.
typedef Alloc::const_pointer pointer;
The type describes an object that can serve as a pointer to an
element of the controlled sequence.
const_reverse_iterator rbegin() const;
The member function returns a reverse bidirectional
iterator that points just
beyond the end of the controlled sequence. Hence, it designates the
beginning of the reverse sequence.
typedef Alloc::const_reference reference;
The type describes an object that can serve as a reference to an
element of the controlled sequence.
const_reverse_iterator rend() const;
The member function returns a reverse bidirectional
iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, it designates the end of the reverse sequence.
typedef reverse_iterator<iterator> reverse_iterator;
The type describes an object that can serve as a reverse
bidirectional iterator for the controlled sequence.
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.
void swap(hash_set& right);
The member function swaps the controlled sequences between
*this and right. If
get_allocator()
== right.get_allocator(), it does so in constant time,
it throws an exception only as a result of copying the stored
traits object of type Tr, 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.
const_iterator upper_bound(const Key& keyval) const;
The member function returns an iterator
just beyond the iterator that designates the
latest element X in the controlled sequence
for which X has
equivalent ordering
to keyval.
If no such element exists, the function returns
end().
value_compare value_comp() const;
The member function returns a function object that
determines the order of elements in the controlled sequence.
typedef Tr value_compare;
The type describes a function object that can compare two
elements as sort keys to determine their relative order
in the controlled sequence.
typedef Key value_type;
The type describes an element of the controlled sequence.
template<class Key, class Tr, class Alloc>
void swap(
hash_multiset <Key, Tr, Alloc>& left,
hash_multiset <Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
void swap(
hash_set <Key, Tr, Alloc>& left,
hash_set <Key, Tr, Alloc>& right);The template function executes
left.swap(right).
template<class Key, class Tr, class Alloc>
bool operator!=(
const hash_set <Key, Tr, Alloc>& left,
const hash_set <Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator!=(
const hash_multiset <Key, Tr, Alloc>& left,
const hash_multiset <Key, Tr, Alloc>& right);The template function returns !(left == right).
template<class Key, class Tr, class Alloc>
bool operator==(
const hash_set <Key, Tr, Alloc>& left,
const hash_set <Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator==(
const hash_multiset <Key, Tr, Alloc>& left,
const hash_multiset <Key, Tr, Alloc>& right);The first template function overloads operator==
to compare two objects of template class
hash_set.
The second template function overloads operator==
to compare two objects of template class
hash_multiset.
Both functions return
left.size() == right.size() &&
equal(left.
begin(), left.
end(), right.begin()).
template<class Key, class Tr, class Alloc>
bool operator<(
const hash_set <Key, Tr, Alloc>& left,
const hash_set <Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator<(
const hash_multiset <Key, Tr, Alloc>& left,
const hash_multiset <Key, Tr, Alloc>& right);The first template function overloads operator<
to compare two objects of template class
hash_set.
The second template function overloads operator<
to compare two objects of template class
hash_multiset.
Both functions return
lexicographical_compare(left.
begin(), left.
end(), right.begin(), right.end(),
left.value_comp()).
template<class Key, class Tr, class Alloc>
bool operator<=(
const hash_set <Key, Tr, Alloc>& left,
const hash_set <Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator<=(
const hash_multiset <Key, Tr, Alloc>& left,
const hash_multiset <Key, Tr, Alloc>& right);The template function returns !(right < left).
template<class Key, class Tr, class Alloc>
bool operator>(
const hash_set <Key, Tr, Alloc>& left,
const hash_set <Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator>(
const hash_multiset <Key, Tr, Alloc>& left,
const hash_multiset <Key, Tr, Alloc>& right);The template function returns right < left.
template<class Key, class Tr, class Alloc>
bool operator>=(
const hash_set <Key, Tr, Alloc>& left,
const hash_set <Key, Tr, Alloc>& right);
template<class Key, class Tr, class Alloc>
bool operator>=(
const hash_multiset <Key, Tr, Alloc>& left,
const hash_multiset <Key, Tr, Alloc>& right);The template function returns !(left < right).
See also the
Table of Contents and the
Index.
Copyright © 1998-2002
by P.J. Plauger. All rights reserved.
37 - iomanip
<iomanip>
Include the iostreams
standard header <iomanip>
to define several manipulators
that each take a single argument. Each of these manipulators returns
an unspecified type, called T1 through T6
here, that overloads both
istream::operator>>
and
ostream::operator<<.
Thus, you can write extractors and inserters such as:
cin >> setbase(8);
cout << setbase(8);
// DECLARATIONS
T1 resetiosflags(ios_base::fmtflags mask);
T2 setiosflags(ios_base::fmtflags mask);
T3 setbase(int base);
T4 setfill(char ch);
T5 setprecision(streamsize prec);
T6 setw(streamsize wide);
// END OF DECLARATIONST1 resetiosflags(ios_base::fmtflags mask);
The manipulator returns an object that, when extracted from or
inserted into the stream str, calls
str.setf(ios_base::
fmtflags(), mask),
then returns str.
T3 setbase(int base);
The manipulator returns an object that, when extracted from or
inserted into the stream str, calls
str.setf(mask,
ios_base::basefield),
then returns str. Here, mask is determined
as follows:
- If
base is 8, then mask is
ios_base::oct - If
base is 10, then mask is
ios_base::dec - If
base is 16, then mask is
ios_base::hex - If
base is any other value, then mask is
ios_base::fmtflags(0)
T4 setfill(char ch);
The manipulator returns an object that, when extracted from or
inserted into the stream str, calls
str.fill(ch),
then returns str.
T2 setiosflags(ios_base::fmtflags mask);
The manipulator returns an object that, when extracted from or
inserted into the stream str, calls
str.setf(mask),
then returns str.
T5 setprecision(streamsize prec);
The manipulator returns an object that, when extracted from or
inserted into the stream str, calls
str.precision(prec),
then returns str.
T6 setw(streamsize wide);
The manipulator returns an object that, when extracted from or
inserted into the stream str, calls
str.width(wide),
then returns str.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
38 - iomanip2
<iomanip.h>
Include the traditional header <iomanip.h>
to effectively include the standard header
<iomanip>.
#include <iomanip>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
39 - ios
<ios>
ios
· fpos
· ios_base
· locale
· mbstate_t
· streamoff
· streampos
· streamsize
boolalpha
· dec
· fixed
· hex
· internal
· left
· noboolalpha
· noshowbase
· noshowpoint
· noshowpos
· noskipws
· nounitbuf
· nouppercase
· oct
· right
· scientific
· showbase
· showpoint
· showpos
· skipws
· unitbuf
· uppercase
Include the iostreams
standard header <ios> to
define several types and functions basic to the operation of
iostreams. (This header is
typically included for you by another of the iostreams headers. You
seldom have occasion to include it directly.)
A large group of functions are
manipulators. A manipulator
declared in <ios> alters the values stored in its
argument object of class
ios_base. Other manipulators
perform actions on streams controlled by objects of a type derived from
this class,
such as one of the classes
istream or
ostream.
For example, noskipws(str)
clears the format flag
ios_base::skipws in the object
str, which might be of one of these types.
You can also call a manipulator by inserting it into an output
stream or extracting it from an input stream, thanks to some special
machinery supplied in the classes derived from
ios_base. For example:
istr >> noskipws;
calls noskipws(istr).
// DECLARATIONS
typedef T1 streamoff;
typedef T2 streamsize;
class ios_base;
class ios;
class fpos;
class locale;
typedef T3 mbstate_t;
typedef fpos streampos;
// MANIPULATORS
ios_base& boolalpha(ios_base& iosbase);
ios_base& noboolalpha(ios_base& iosbase);
ios_base& showbase(ios_base& iosbase);
ios_base& noshowbase(ios_base& iosbase);
ios_base& showpoint(ios_base& iosbase);
ios_base& noshowpoint(ios_base& iosbase);
ios_base& showpos(ios_base& iosbase);
ios_base& noshowpos(ios_base& iosbase);
ios_base& skipws(ios_base& iosbase);
ios_base& noskipws(ios_base& iosbase);
ios_base& unitbuf(ios_base& iosbase);
ios_base& nounitbuf(ios_base& iosbase);
ios_base& uppercase(ios_base& iosbase);
ios_base& nouppercase(ios_base& iosbase);
ios_base& internal(ios_base& iosbase);
ios_base& left(ios_base& iosbase);
ios_base& right(ios_base& iosbase);
ios_base& dec(ios_base& iosbase);
ios_base& hex(ios_base& iosbase);
ios_base& oct(ios_base& iosbase);
ios_base& fixed(ios_base& iosbase);
ios_base& scientific(ios_base& iosbase);
// END OF DECLARATIONS
bad
· ios
· char_type
· clear
· copyfmt
· eof
· exceptions
· init
· fail
· good
· imbue
· init
· int_type
· narrow
· off_type
· operator!
· operator void *
· pos_type
· rdbuf
· rdstate
· setstate
· tie
· traits_type
· widen
class ios : public ios_base {
public:
typedef char char_type;
typedef char_traits traits_type;
typedef char_traits::int_type int_type;
typedef char_traits::pos_type pos_type;
typedef char_traits::off_type off_type;
explicit ios(streambuf *strbuf);
virtual ~ios();
operator void *() const;
bool operator!() const;
iostate rdstate() const;
void clear(iostate state = goodbit);
void setstate(iostate state);
bool good() const;
bool eof() const;
bool fail() const;
bool bad() const;
iostate exceptions() const;
iostate exceptions(iostate newexcept);
ios& copyfmt(const ios& right);
locale imbue(const locale& loc);
char_type widen(char ch);
char narrow(char_type ch, char dflt);
char_type fill() const;
char_type fill(char_type ch);
ostream *tie() const;
ostream *tie(ostream *newtie);
streambuf *rdbuf() const;
streambuf *rdbuf(streambuf *strbuf);
protected:
void init(streambuf *strbuf);
ios();
ios(const facet&); // not defined
void operator=(const facet&) // not defined
};The class describes the storage and member functions common
to both input streams (of class
istream)
and output streams (of class
ostream).
An object of class
ios helps control a stream with elements
of type char, also known as char_type, whose
character traits are determined by the
class char_traits.
An object of class ios stores:
bool bad() const;
The member function returns true if
rdstate() & badbit
is nonzero.
explicit ios(streambuf *strbuf);
ios();
The first constructor initializes its member objects by calling
init(strbuf). The second
(protected) constructor leaves its member objects uninitialized. A later
call to init must initialize the object before it
can be safely destroyed.
typedef char char_type;
The type is a synonym for char.
void clear(iostate state = goodbit);
The member function replaces the stored
stream state information with
state |
(rdbuf() != 0 ? goodbit : badbit).
If state &
exceptions() is nonzero, it
then throws an object of class
failure.
ios& copyfmt(const ios& right);
The member function reports the
callback event
erase_event.
It then copies from right into *this
the fill character,
the tie pointer, and the
formatting information.
Before altering the
exception mask, it reports the
callback event
copyfmt_event.
If, after the copy is complete, state &
exceptions() is nonzero,
the function effectively calls
clear with the argument
rdstate().
It returns *this.
bool eof() const;
The member function returns true if
rdstate() & eofbit
is nonzero.
iostate exceptions() const;
iostate exceptions(iostate newexcept);
The first member function returns the stored
exception mask. The second member
function stores except in the exception mask and returns
its previous stored value.
bool fail() const;
The member function returns true if
rdstate() & (badbit | failbit)
is nonzero.
char_type fill() const;
char_type fill(char_type ch);
The first member function returns the stored
fill character. The second member
function stores ch in the fill character and returns its
previous stored value.
bool good() const;
The member function returns true if
rdstate() == goodbit
(no state flags are set).
locale imbue(const locale& loc);
The member function calls
ios_base::imbue(loc).
If rdbuf is not a
null pointer, it also calls
rdbuf()->pubimbue(loc).
In any case, it returns the value returned by the call to
ios_base::imbue.
void init(streambuf *strbuf);
The member function stores values in all member objects, so that:
typedef int int_type;
The type is a synonym for int.
char narrow(char_type ch, char dflt);
The member function returns
ch.
typedef streamoff off_type;
The type is a synonym for
streamoff.
operator void *() const;
The operator returns a null pointer only if
fail().
bool operator!() const;
The operator returns
fail().
typedef streampos pos_type;
The type is a synonym for
streampos.
streambuf *rdbuf() const;
streambuf *rdbuf(streambuf *strbuf);
The first member function returns the stored
stream buffer pointer.
The second member function stores strbuf in the stored
stream buffer pointer
and returns the previously stored value.
iostate rdstate() const;
The member function returns the stored
stream state information.
void setstate(iostate state);
The member function effectively calls
clear(state |
rdstate()).
ostream *tie() const;
ostream *tie(ostream *newtie);
The first member function returns the stored
tie pointer. The second member function
stores newtie in the tie pointer and returns its previous
stored value.
typedef char_traits traits_type;
The type is a synonym for
char_traits.
char_type widen(char ch);
The member function returns
ch.
ios_base& boolalpha(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
boolalpha), then returns
iosbase.
ios_base& dec(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
dec, ios_base::
basefield), then returns
iosbase.
ios_base& fixed(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
fixed, ios_base::
floatfield), then returns
iosbase.
class fpos {
public:
typedef mbstate_t St;
fpos(streamoff off);
fpos(St state, fpos_t filepos);
St state() const;
void state(St state);
operator streamoff() const;
streamoff operator-(const fpos& right) const;
fpos& operator+=(streamoff off);
fpos& operator-=(streamoff off);
fpos operator+(streamoff off) const;
fpos operator-(streamoff off) const;
bool operator==(const fpos& right) const;
bool operator!=(const fpos& right) const;
};The class describes an object
that can store all the information needed to restore an arbitrary
file-position indicator
within any stream. An object of class fpos effectively
stores at least two member objects:
- a byte offset, of type
streamoff - a conversion state, for use by an object of class
filebuf,
of type St, which is an unofficial synonym for
mbstate_t
It can also store an arbitrary file position, for use by an object of class
filebuf,
of type fpos_t.
For an environment with limited file size, however,
streamoff and fpos_t may sometimes
be used interchangeably. So the number of
member objects stored may vary.
fpos(streamoff off);
fpos(St state, fpos_t filepos);
The first constructor stores the offset
off,
relative to the beginning of file.
If off is -1,
the resulting object represents an invalid stream position.
The second constructor stores the object state
and a file position determined by filepos.
bool operator!=(const fpos& right) const;
The member function returns !(*this == right).
fpos operator+(streamoff off) const;
The member function returns fpos(*this) += off.
fpos& operator+=(streamoff off);
The member function adds off to the stored offset member object,
then returns *this. For positioning within a file, the
result is generally valid only for
binary streams.
streamoff operator-(const fpos& right) const;
fpos operator-(streamoff off) const;
The first member function returns (streamoff)*this - (streamoff)right.
The second member function returns fpos(*this) -= off.
fpos& operator-=(streamoff off);
The member function returns fpos(*this) -= off.
For positioning within a file, the result is generally valid only for
binary streams.
bool operator==(const fpos& right) const;
The member function returns (streamoff)*this == (streamoff)right.
operator streamoff() const;
The member function returns the stored offset member object,
plus any additional offset stored as part of the fpos_t member object.
St state() const;
void state(St state);
The first member function returns the value stored in the
St member object. The second member function
stores state in the St member object.
ios_base& hex(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
hex, ios_base::
basefield), then returns
iosbase.
ios_base& internal(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
internal, ios_base::
adjustfield), then returns
iosbase.
event
· event_callback
· failure
· flags
· fmtflags
· getloc
· imbue
· Init
· ios_base
· iostate
· iword
· openmode
· operator=
· precision
· pword
· register_callback
· seekdir
· setf
· streamoff
· streampos
· sync_with_stdio
· unsetf
· width
· xalloc
class ios_base {
public:
class failure;
typedef T1 fmtflags;
static const fmtflags boolalpha, dec, fixed, hex,
internal, left, oct, right, scientific,
showbase, showpoint, showpos, skipws, unitbuf,
uppercase, adjustfield, basefield, floatfield;
typedef T2 iostate;
static const iostate badbit, eofbit, failbit,
goodbit;
typedef T3 openmode;
static const openmode app, ate, binary, in, out,
trunc;
typedef T4 seekdir;
typedef ::streamoff streamoff;
typedef ::streampos streampos;
static const seekdir beg, cur, end;
enum event {
copyfmt_event, erase_event,
imbue_event};
static const event copyfmt_event, erase_event,
copyfmt_event;
class Init;
ios_base& operator=(const ios_base& right);
fmtflags flags() const;
fmtflags flags(fmtflags newfmtflags);
fmtflags setf(fmtflags newfmtflags);
fmtflags setf(fmtflags newfmtflags, fmtflags mask);
void unsetf(fmtflags mask);
streamsize precision() const;
streamsize precision(streamsize newprecision);
streamsize width() const;
stramsize width(streamsize newwidth);
locale imbue(const locale& loc);
locale getloc() const;
static int xalloc();
long& iword(int idx);
void *& pword(int idx);
typedef void *(event_callback(event ev,
ios_base& iosbase, int idx);
void register_callback(event_callback pfn, int idx);
static bool sync_with_stdio(bool newsync = true);
protected:
ios_base();
};The class describes the storage and member functions common to both
input and output streams. The class
ios describes additional
common features.
An object of class ios_base stores
formatting information,
which consists of:
An object of class ios_base also stores
stream state information,
in an object of type
iostate, and a
callback stack.
enum event {
copyfmt_event, erase_event,
imbue_event};The type is an enumeration that describes an
object that can store the
callback event used as an argument to
a function registered with
register_callback.
The distinct event values are:
copyfmt_event,
to identify a callback that occurs near the end of a call to
copyfmt, just before the
exception mask is copied.erase_event,
to identify a callback that occurs at the beginning of a call to
copyfmt, or at
the beginning of a call to the destructor for *this.imbue_event,
to identify a callback that occurs at the end of a call to
imbue, just before the
function returns.
typedef void *(event_callback(event ev,
ios_base& iosbase, int idx);The type describes a pointer to a function that can
be registered with
register_callback.
Such a function must not throw an exception.
class failure : public exception {
public:
explicit failure(const string& what_arg) {
};The member class serves as the base class
for all exceptions thrown by the member function
clear in template class
ios. The value returned by
what() is
what_arg.data().
fmtflags flags() const;
fmtflags flags(fmtflags newfmtflags);
The first member function returns the stored
format flags. The second member function
stores newfmtflags in the format flags and returns its previous
stored value.
typedef T1 fmtflags;
static const fmtflags boolalpha, dec, fixed, hex,
internal, left, oct, right, scientific,
showbase, showpoint, showpos, skipws, unitbuf,
uppercase, adjustfield, basefield, floatfield;The type is a bitmask type
T1 that describes an object that can store
format flags. The distinct flag values (elements) are:
boolalpha, to insert or
extract objects of type bool as names (such as true
and false) rather than as numeric valuesdec, to insert or extract
integer values in decimal formatfixed, to insert
floating-point values in fixed-point format (with no exponent field)hex, to insert or extract
integer values in hexadecimal formatinternal,
to pad to a field width
as needed by inserting fill
characters at a point internal to a generated numeric fieldleft,
to pad to a field width as needed
by inserting fill characters
at the end of a generated field (left justification)oct, to insert or extract
integer values in octal formatright,
to pad to a field width
as needed by inserting fill characters
at the beginning of a generated field (right justification)scientific, to insert
floating-point values in scientific format (with an exponent field)showbase, to insert a
prefix that reveals the base of a generated integer fieldshowpoint, to insert a
decimal point unconditionally in a generated floating-point fieldshowpos, to insert a plus
sign in a non-negative generated numeric fieldskipws, to skip leading
white space before certain
extractionsunitbuf, to flush output
after each insertionuppercase, to insert
uppercase equivalents of lowercase letters in certain insertions
In addition, several useful values are:
locale getloc() const;
The member function returns the stored
locale object.
locale imbue(const locale& loc);
The member function stores loc in the
locale object, then reports the
callback event
imbue_event.
It returns the previous stored value.
class Init {
};The nested class describes an object whose construction ensures that
the standard iostreams objects are properly
constructed, even
before the execution of a constructor for an arbitrary static object.
ios_base();
The (protected) constructor does nothing. A later call to
ios::init
must initialize the object before it can be safely destroyed.
Thus, the only safe use for class ios_base is as a base
class for template class
ios.
typedef T2 iostate;
static const iostate badbit, eofbit, failbit, goodbit;
The type is a bitmask type
T2 that describes an object that can store
stream state information. The
distinct flag values (elements) are:
badbit, to record a loss of
integrity of the stream buffereofbit, to record
end-of-file while extracting from a streamfailbit, to record a
failure to extract a valid field from a stream
In addition, a useful value is:
long& iword(int idx);
The member function returns a reference to element
idx of the
extensible array with elements of type
long. All elements are effectively present and initially store
the value zero. The returned reference is invalid after the next call to
iword for the object, after the object is altered by a call to
ios::copyfmt, or
after the object is destroyed.
If idx is negative, or if unique storage is unavailable
for the element, the function calls
setstate(badbit)
and returns a reference that might not be unique.
To obtain a unique index, for use across all objects of type
ios_base, call
xalloc.
typedef T3 openmode;
static const openmode app, ate, binary, in, out, trunc;
The type is a bitmask type
T3 that describes an object that can store the
opening mode for several iostreams
objects. The distinct flag values (elements) are:
app, to seek to the end of a
stream before each insertionate, to seek to the end of a
stream when its controlling object is first createdbinary, to read a file as a
binary stream,
rather than as a
text streamin,
to permit extraction from a streamout,
to permit insertion to a streamtrunc, to truncate an
existing file when its controlling object is first created
ios_base& operator=(const ios_base& right);
The operator copies the stored
formatting information,
making a new copy of any
extensible arrays.
It then returns *this. Note that the
callback stack is not copied.
streamsize precision() const;
streamsize precision(streamsize newprecision);
The first member function returns the stored
display precision. The second member
function stores newprecision in the display precision and returns
its previous stored value.
void *& pword(int idx);
The member function returns a reference to element idx of the
extensible array with elements of type
void pointer. All elements are effectively present and initially
store the null pointer. The returned reference is invalid after the next
call to pword for the object,
after the object is altered by a call to
ios::copyfmt, or
after the object is destroyed.
If idx is negative, or if unique storage is unavailable
for the element, the function calls
setstate(badbit)
and returns a reference that might not be unique.
To obtain a unique index, for use across all objects of type
ios_base, call
xalloc.
void register_callback(event_callback pfn, int idx);
The member function pushes the pair {pfn, idx}
onto the stored
callback stack. When a
callback event ev is reported,
the functions are called, in reverse order of registry, by the
expression (*pfn)(ev, *this, idx).
typedef T4 seekdir;
static const seekdir beg, cur, end;
The type is an enumerated type T4 that describes an
object that can store the
seek mode used as an argument to the
member functions of several iostreams classes. The distinct flag values
are:
beg, to seek (alter the
current read or write position) relative to the beginning oc a sequence
(array, stream, or file)cur, to seek relative to the
current position within a sequenceend, to seek relative to the
end of a sequence
void setf(fmtflags newfmtflags);
fmtflags setf(fmtflags newfmtflags, fmtflags mask);
The first member function effectively calls
flags(newfmtflags | flags()) (set
selected bits), then returns the previous
format flags. The second member function
effectively calls
flags(mask & newfmtflags, flags() & ~mask) (replace selected
bits under a mask), then returns the previous format flags.
typedef ::streamoff streamoff;
The type is a synonym for
::streamoff.
typedef ::streampos streampos;
The type is a synonym for
::streampos.
static bool sync_with_stdio(bool newsync = true);
The static member function stores a
stdio sync flag, which is initially true.
When true, this flag ensures that operations on the same file are properly synchronized
between the iostreams functions and those defined
in the Standard C library.
Otherwise, synchronization may or may not be guaranteed, but performance may be
improved.
The function stores newsync in the stdio sync flag and returns its
previous stored value. You can call it reliably only before performing any operations
on the standard streams.
void unsetf(fmtflags mask);
The member function effectively calls
flags(~mask & flags())
(clear selected bits).
streamsize width() const;
streamsize width(streamsize newwidth);
The first member function returns the stored
field width. The second member function
stores newwidth in the field width and returns its previous
stored value.
static int xalloc();
The static member function returns a stored static value, which it
increments on each call. You can use the return value as a unique index
argument when calling the member functions
iword or
pword.
ios_base& left(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
left, ios_base::
adjustfield), then returns
iosbase.
class locale {
};The class serves as a placeholder for the much more elaborate locale
machinery mandated by Standard C++.
typedef T3 mbstate_t;
The type is an unspecified type T3 that serves as a placeholder
for the more elaborate conversion-state machinery, used to convert between
multibyte and wide-character encodings, mandated by Standard C.
ios_base& noboolalpha(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
boolalpha), then returns
iosbase.
ios_base& noshowbase(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
showbase),
then returns iosbase.
ios_base& noshowpoint(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
showpoint), then returns
iosbase.
ios_base& noshowpos(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
showpos"),
then returns iosbase.
ios_base& noskipws(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
skipws),
then returns iosbase.
ios_base& nounitbuf(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
unitbuf),
then returns iosbase.
ios_base& nouppercase(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
uppercase), then returns
iosbase.
ios_base& oct(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
oct, ios_base::
basefield), then returns
iosbase.
ios_base& right(ios_base& iosbase);
The maiipulator effectively calls
iosbase.setf(ios_base::
right, ios_base::
adjustfield), then returns
iosbase.
ios_base& scientific(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
scientific, ios_base::
floatfield), then returns
iosbase.
ios_base& showbase(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
showbase),
then returns iosbase.
ios_base& showpoint(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
showpoint), then returns
iosbase.
ios_base& showpos(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
showpos),
then returns iosbase.
ios_base& skipws(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
skipws),
then returns iosbase.
typedef T1 streamoff;
The type is a signed integer type T1 that describes an
object that can store a byte offset involved in various stream
positioning operations. Its representation has at least 32 value bits.
It is not necessarily large enough to represent an arbitrary
byte position within a stream. The value streamoff(-1)
generally indicates an erroneous offset.
typedef fpos streampos;
The type is a synonym for fpos.
typedef T2 streamsize;
The type is a signed integer type T3 that describes an
object that can store a count of the number of elements involved in
various stream operations. Its representation has at least 16 bits. It
is not necessarily large enough to represent an arbitrary byte
position within a stream.
ios_base& unitbuf(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
unitbuf),
then returns iosbase.
ios_base& uppercase(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
uppercase), then returns
iosbase.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
40 - iosfwd
<iosfwd>
Include the iostreams
standard header <iosfwd>
to declare forward references to several template classes used
throughout iostreams. All such template classes are defined in other
standard headers. You include this header explicitly only when
you need one of the above declarations, but not its definition.
// DECLARATIONS
typedef T1 streamoff;
typedef T2 streamsize;
typedef fpos streampos;
// CLASSES
class char_traits;
class ios;
class streambuf;
class istream;
class ostream;
class stringbuf;
class istringstream;
class ostringstream;
class filebuf;
class ifstream;
class ofstream;
// END OF DECLARATIONS
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
41 - iostrea2
<iostream.h>
Include the traditional header <iostream.h>
to effectively include the standard header
<iostream>.
#include <iostream>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
42 - iostream
<iostream>
Include the iostreams
standard header <iostream>
to declare objects that control reading from and writing to the
standard streams.
This is often the only header you
need include to perform input and output from a C++ program.
All the objects declared in this header share a peculiar
property -- you can assume they are
constructed before any
static objects you define, in a translation unit that includes
<iostreams>. Equally, you can assume that
these objects are not destroyed before the destructors for any
such static objects you define. (The output streams are, however,
flushed during program termination.)
Hence, you can safely read from
or write to the standard streams prior to program startup and
after program termination.
This guarantee is not universal, however. A static
constructor may call a function in another translation unit.
The called function cannot assume that the objects declared in
this header have been constructed, given the uncertain order
in which translation units participate in static construction.
To use these objects in such a context, you must first construct
an object of class
ios_base::Init,
as in:
#include <iostream>
void marker()
{ // called by some constructor
ios_base::Init unused_name;
cout << "called fun" << endl;
} // DECLARATIONS
extern istream cin;
extern ostream cout;
// END OF DECLARATIONSextern istream cin;
The object controls extractions from the
standard input
as a byte stream.
Once the object is constructed, the call
cin.tie() returns
&cout.
extern ostream cout;
The object controls insertions to the
standard output
as a byte stream.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
43 - istream
<istream>
Include the iostreams
standard header <istream>
to define class
istream,
which mediates extractions for the iostreams.
The header also defines a related
manipulator.
(This header is typically included for you by another
of the iostreams headers. You seldom have occasion to include it
directly.)
// DECLARATIONS
class istream;
// EXTRACTORS
istream&
operator>>(istream& istr, char *str);
istream&
operator>>(istream& istr, char& ch);
istream&
operator>>(istream& istr, signed char *str);
istream&
operator>>(istream& istr, signed char& ch);
istream&
operator>>(istream& istr, unsigned char *str);
istream&
operator>>(istream& istr, unsigned char& ch);
// MANIPULATORS
istream& ws(istream& istr);
// END OF DECLARATIONS
istream
· gcount
· get
· getline
· ignore
· operator>>
· peek
· putback
· read
· readsome
· seekg
· sentry
· sync
· tellg
· unget
class istream : public ios {
public:
explicit istream(streambuf *strbuf);
class sentry;
virtual ~istream();
istream& operator>>(
istream& (*pfn)(istream&));
istream& operator>>(
ios_base& (*pfn)(ios_base&));
istream& operator>>(
ios& (*pfn)(ios&));
istream& operator>>(
streambuf *strbuf);
istream& operator>>(bool& val);
istream& operator>>(short& val);
istream& operator>>(unsigned short& val);
istream& operator>>(int& val);
istream& operator>>(unsigned int& val);
istream& operator>>(long& val);
istream& operator>>(unsigned long& val);
istream& operator>>(void *& val);
istream& operator>>(float& val);
istream& operator>>(double& val);
istream& operator>>(long double& val);
streamsize gcount() const;
int_type get();
istream& get(char_type& ch);
istream& get(char_type *str, streamsize count);
istream&
get(char_type *str, streamsize count, char_type delim);
istream& get(streambuf& strbuf);
istream& get(streambuf& strbuf, char_type delim);
istream& getline(char_type *str, streamsize count);
istream& getline(char_type *str, streamsize count,
char_type delim);
istream& ignore(streamsize count = 1,
int_type delim = traits_type::eof());
int_type peek();
istream& read(char_type *str, streamsize count);
streamsize readsome(char_type *str, streamsize count);
istream& putback(char_type ch);
istream& unget();
pos_type tellg();
istream& seekg(pos_type pos);
istream& seekg(off_type off,
ios_base::seek_dir way);
int sync();
};The class describes an object that controls
extraction of elements and encoded objects from a
stream buffer
with elements of type char, also known as
char_type, whose
character traits are determined by the
class char_traits,
also known as
traits_type.
Most of the member functions that overload
operator>>
are formatted input functions.
They follow the pattern:
iostate state = goodbit;
const sentry ok(*this);
if (ok)
{try
{<extract elements and convert
accumulate flags in state
store a successful conversion> }
catch (...)
{try
{setstate(badbit); }
catch (...)
{}
if ((exceptions() & badbit) != 0)
throw; }}
setstate(state);
return (*this);Many other member functions are
unformatted input functions.
They follow the pattern:
iostate state = goodbit;
count = 0; // the value returned by gcount
const sentry ok(*this, true);
if (ok)
{try
{<extract elements and deliver
count extracted elements in count
accumulate flags in state> }
catch (...)
{try
{setstate(badbit); }
catch (...)
{}
if ((exceptions() & badbit) != 0)
throw; }}
setstate(state);Both groups of functions call
setstate(eofbit)
if they encounter end-of-file while extracting elements.
An object of class istream stores:
- a public base object of class
ios - an extraction count
for the last unformatted input operation (called
count
in the code above)
explicit istream(streambuf *strbuf);
The constructor initializes the base class by calling
init(strbuf).
It also stores zero in the
extraction count.
streamsize gcount() const;
The member function returns the
extraction count.
int_type get();
istream& get(char_type& ch);
istream& get(char_type *str, streamsize count);
istream& get(char_type *str, streamsize count,
char_type delim);
istream& get(streambuf& strbuf);
istream& get(streambuf& strbuf, char_type delim);The first of these
unformatted input functions
extracts an element, if possible, as if by returning
rdbuf()->sbumpc().
Otherwise, it returns
traits_type::eof().
If the function extracts no element, it calls
setstate(failbit).
The second function extracts the
int_type element
meta the same way. If meta compares equal to
traits_type::eof(),
the function calls
setstate(failbit).
Otherwise, it stores
traits_type::to_char_type(meta)
in ch. The function returns *this.
The third function returns get(str, count, widen('\n')).
The fourth function extracts up to count - 1 elements
and stores them in the array beginning at str. It always stores
char_type() after
any extracted elements it stores. In order of testing, extraction stops:
- at end of file
- after the function extracts an element that compares equal to
delim, in which case the element is put back
to the controlled sequence - after the function extracts
count - 1 elements
If the function extracts no elements, it calls
setstate(failbit).
In any case, it returns *this.
The fifth function returns get(strbuf, widen('\n')).
The sixth function extracts elements and inserts them in
strbuf. Extraction stops on end-of-file or on an element
that compares equal to delim (which is not extracted).
It also stops, without extracting the element in question,
if an insertion fails or throws an exception (which is caught
but not rethrown). If the function extracts no elements, it calls
setstate(failbit).
In any case, the function returns *this.
istream& getline(char_type *str, streamsize count);
istream& getline(char_type *str, streamsize count,
char_type delim);The first of these
unformatted input functions
returns getline(str, count, widen('\n')).
The second function extracts up to count - 1 elements
and stores them in the array beginning at str. It always stores
char_type() after
any extracted elements it stores. In order of testing, extraction stops:
- at end of file
- after the function extracts an element that compares equal to
delim, in which case the element is neither put back nor
appended to the controlled sequence - after the function extracts
count - 1 elements
If the function extracts no elements or count - 1 elements, it calls
setstate(failbit).
In any case, it returns *this.
istream& ignore(streamsize count = 1,
int_type delim = traits_type::eof());The unformatted input function
extracts up to count elements and discards them.
If count equals
INT_MAX,
however, it is taken as arbitrarily large.
Extraction stops early on end-of-file or
on an element ch such that
traits_type::to_int_type(ch)
compares equal to delim (which is also extracted).
The function returns *this.
istream& operator>>(
istream& (*pfn)(istream&));
istream& operator>>(
ios_base& (*pfn)(ios_base&));
istream& operator>>(
ios& (*pfn)(ios&));
istream& operator>>(
streambuf *strbuf);
istream& operator>>(bool& val);
istream& operator>>(short& val);
istream& operator>>(unsigned short& val);
istream& operator>>(int& val);
istream& operator>>(unsigned int& val);
istream& operator>>(long& val);
istream& operator>>(unsigned long& val);
istream& operator>>(void *& val);
istream& operator>>(float& val);
istream& operator>>(double& val);
istream& operator>>(long double& val);The first member function ensures that an expression of the
form istr >> ws calls
ws(istr), then returns *this.
The second and third functions ensure that other
manipulators,
such as hex behave
similarly. The remaining functions constitute the
formatted input functions.
The function:
istream& operator>>(
streambuf *strbuf);extracts elements, if strbuf is not a null pointer,
and inserts them in strbuf. Extraction stops on end-of-file.
It also stops, without extracting the element in question,
if an insertion fails or throws an exception (which is caught
but not rethrown).
If the function extracts no elements, it calls
setstate(failbit).
In any case, the function returns *this.
The function:
istream& operator>>(bool& val);
extracts a field and converts it to a boolean value.
The function endeavors to match a complete, nonempty
boolean input field.
If successful it converts
the boolean input field to a value of type bool
and stores that value in val.
A boolean input field takes one of two forms.
If flags() &
ios_base::boolalpha
is false, it is the same as an
integer input field, except that the
converted value must be either 0 (for false) or 1 (for true).
Otherwise, the sequence must match either
false (for false), or
true (for true).
The function returns *this.
The functions:
istream& operator>>(short& val);
istream& operator>>(unsigned short& val);
istream& operator>>(int& val);
istream& operator>>(unsigned int& val);
istream& operator>>(long& val);
istream& operator>>(unsigned long& val);
istream& operator>>(void *& val);
each extract a field and convert it to a numeric value.
Each function endeavors to match a complete, nonempty
integer input field.
If successful, it stores the result in val.
Otherwise, the function stores nothing in val and calls
setstate(ios_base::failbit).
If the function encounters end of file, it calls
setstate(ios_base::eofbit).
The integer input field is converted by the same rules used by the
scan functions
for matching and converting a series of char elements from a file.
The equivalent
scan conversion
specification is determined as follows:
- If
flags() &
ios_base::basefield ==
ios_base::oct, the
conversion specification is lo. - If
flags() & ios_base::basefield ==
ios_base::hex, the
conversion specification is lx. - If
flags() & ios_base::basefield == 0, the
conversion specification is li. - Otherwise, the conversion specification is
ld
if val has a signed type, lu if val
has an unsigned type, or p if val has type
void *.
If the converted value cannot
be represented as the type of val, the function calls
setstate(failbit).
In any case, the function returns *this.
The functions:
istream& operator>>(float& val);
istream& operator>>(double& val);
istream& operator>>(long double& val);
each extract a field and convert it to a numeric value.
Each function endeavors to match a complete, nonempty
A period (.) separates the integer digits from the
fraction digits.
The equivalent scan conversion specifier is f
if val has type float, lf if val
has type double, or Lf if val has type
long double.
If the converted value cannot
be represented as the type of val, the function calls
setstate(failbit).
In any case, it returns *this.
int_type peek();
The unformatted input function
extracts an element, if possible, as if by returning
rdbuf()->sgetc().
Otherwise, it returns
traits_type::eof().
istream& putback(char_type ch);
The unformatted input function
puts back ch, if possible, as if by calling
rdbuf()->sputbackc().
If rdbuf()
is a null pointer, or if the call to sputbackc returns
traits_type::eof(),
the function calls
setstate(badbit).
In any case, it returns *this.
istream& read(char_type *str, streamsize count);
The unformatted input function
extracts up to count elements
and stores them in the array beginning at str.
Extraction stops early on end-of-file, in which case the function calls
setstate(failbit).
In any case, it returns *this.
streamsize readsome(char_type *str, streamsize count);
The unformatted input function
extracts up to count elements
and stores them in the array beginning at str.
If good() is
false, the function calls
setstate(failbit).
Otherwise, it assigns the value of
rdbuf()->in_avail()
to N. If N < 0, the function calls
setstate(eofbit).
Otherwise, it replaces the value stored in N with
the smaller of count and N, then calls
read(str, N).
In any case, the function returns
gcount().
istream& seekg(pos_type pos);
istream& seekg(off_type off,
ios_base::seek_dir way);If fail() is false,
the first member function calls
newpos = rdbuf()->
pubseekpos(pos,
in),
for some pos_type temporary object newpos.
If fail() is false, the second function calls
newpos = rdbuf()->
pubseekoff(off, way,
in).
In either case, if (off_type)newpos == (off_type)(-1)
(the positioning operation fails) the function calls
istr.setstate(failbit).
Both functions return *this.
class sentry {
public:
explicit sentry(istream<Elem, Tr>& istr,
bool noskip = false);
operator bool() const;
};The nested class describes an object whose declaration structures the
formatted input functions and the
unformatted input functions.
If istr.good()
is true, the constructor:
- calls
istr.tie->
flush()
if istr.tie() is not a null pointer - effectively calls
ws(istr) if
istr.flags() &
skipws is nonzero
If, after any such preparation,
istr.good() is false, the constructor calls
istr.setstate(failbit).
In any case, the constructor stores the value returned by istr.good()
in status.
A later call to operator bool() delivers this stored value.
int sync();
If rdbuf() is
a null pointer, the function returns -1. Otherwise, it calls
rdbuf()->pubsync().
If that returns -1, the function calls
setstate(badbit)
and returns -1. Otherwise, the function returns zero.
pos_type tellg();
If fail() is false,
the member function returns
rdbuf()->
pubseekoff(0,
cur,
in).
Otherwise, it returns pos_type(-1).
istream& unget();
The unformatted input function
puts back the previous element in the stream, if possible, as if by calling
rdbuf()->sungetc().
If rdbuf()
is a null pointer, or if the call to sungetc returns
traits_type::eof(),
the function calls
setstate(badbit).
In any case, it returns *this.
istream&
operator>>(istream& istr, char *str);
istream&
operator>>(istream& istr, char& ch);
istream&
operator>>(istream& istr, signed char *str);
istream&
operator>>(istream& istr, signed char& ch);
istream&
operator>>(istream& istr, unsigned char *str);
istream&
operator>>(istream istr, unsigned char& ch);All of these functions are
formatted input functions.
The function:
istream&
operator>>(istream& istr, char *str);extracts up to N - 1 elements
and stores them in the array beginning at str.
If istr.width() is greater
than zero, N is istr.width(); otherwise it is
the size of
the largest array of char that can be declared.
The function always stores
char(0) after
any extracted elements it stores. Extraction stops early on end-of-file,
on a character with value char(0) (which is not extracted),
or on any element (which is not extracted) that would be discarded by
ws.
If the function extracts no elements, it calls
istr.setstate(failbit).
In any case, it calls istr.width(0) and
returns istr.
The function:
istream&
operator>>(istream& istr, char& ch);extracts an element, if possible, and stores it in ch.
Otherwise, it calls
is.setstate(failbit).
In any case, it returns istr.
The function:
istream&
operator>>(istream& istr, signed char *str);returns istr >> (char *)str.
The function:
istream&
operator>>(istream& istr, signed char& ch);returns istr >> (char&)ch.
The function:
istream&
operator>>(istream& istr, unsigned char *str);returns istr >> (char *)str.
The function:
istream&
operator>>(istream& istr, unsigned char& ch);returns istr >> (char&)ch.
istream& ws(istream& istr);
The manipulator extracts and discards any elements
ch for which
isspace(ch)
is true.
The function calls
setstate(eofbit)
if it encounters end-of-file while extracting elements.
It returns istr.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
44 - iterator
<iterator>
advance
· back_insert_iterator
· back_inserter
· bidirectional_iterator_tag
· distance
· forward_iterator_tag
· front_insert_iterator
· front_inserter
· input_iterator_tag
· insert_iterator
· inserter
· istream_iterator
· istreambuf_iterator
· iterator
· iterator_traits
· operator!=
· operator==
· operator<
· operator<=
· operator>
· operator>=
· operator+
· operator-
· ostream_iterator
· ostreambuf_iterator
· output_iterator_tag
· random_access_iterator_tag
· reverse_iterator
Include the STL
standard header <iterator>
to define a number of classes, template classes, and template
functions that aid in the declaration and manipulation of iterators.
namespace std {
struct input_iterator_tag;
struct output_iterator_tag;
struct forward_iterator_tag;
struct bidirectional_iterator_tag;
struct random_access_iterator_tag;
// TEMPLATE CLASSES
template<class Category, class Ty, class Diff,
class Pointer, class Reference>
struct iterator;
template<class Iter>
struct iterator_traits;
template<class Ty>
struct iterator_traits<Ty *>;
template<class Ty>
struct iterator_traits<const Ty *>;
template<class RanIt>
class reverse_iterator;
template<class Container>
class back_insert_iterator;
template<class Container>
class front_insert_iterator;
template<class Container>
class insert_iterator;
template<class Ty, class Elem, class Tr, class Diff>
class istream_iterator;
template<class Ty, class Elem, class Tr>
class ostream_iterator;
template<class Elem, class Tr>
class istreambuf_iterator;
template<class Elem, class Tr>
class ostreambuf_iterator;
// TEMPLATE FUNCTIONS
template<class RanIt>
bool operator==(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);
template<class Ty, class Elem, class Tr, class Diff>
bool operator==(
const istream_iterator<Ty, Elem, Tr, Diff>& left,
const istream_iterator<Ty, Elem, Tr, Diff>& right);
template<class Elem, class Tr>
bool operator==(
const istreambuf_iterator<Elem, Tr>& left,
const istreambuf_iterator<Elem, Tr>& right);
template<class RanIt>
bool operator!=(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);
template<class Ty, class Elem, class Tr, class Diff>
bool operator!=(
const istream_iterator<Ty, Elem, Tr, Diff>& left,
const istream_iterator<Ty, Elem, Tr, Diff>& right);
template<class Elem, class Tr>
bool operator!=(
const istreambuf_iterator<Elem, Tr>& left,
const istreambuf_iterator<Elem, Tr>& right);
template<class RanIt>
bool operator<(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);
template<class RanIt>
bool operator>(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);
template<class RanIt>
bool operator<=(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);
template<class RanIt>
bool operator>=(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);
template<class RanIt>
Diff operator-(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);
template<class RanIt>
reverse_iterator<RanIt> operator+(
Diff off,
const reverse_iterator<RanIt>& right);
template<class Container>
back_insert_iterator<Container> back_inserter(Container& cont);
template<class Container>
front_insert_iterator<Container> front_inserter(Container& cont);
template<class Container, class Iter>
insert_iterator<Container> inserter(Container& cont, Iter it);
template<class InIt, class Diff>
void advance(InIt& it, Diff off);
template<class Init>
iterator_traits<InIt>::difference_type
distance(InIt first, InIt last);
};template<class InIt, class Diff>
void advance(InIt& it, Diff off);The template function effectively advances it by
incrementing it off times. If InIt is
a random-access iterator type, the function evaluates the expression
it += off. Otherwise, it performs each increment
by evaluating ++it. If InIt is an
input or forward iterator type, off must not be negative.
template<class Container>
class back_insert_iterator
: public iterator<output_iterator_tag,
void, void, void, void> {
public:
typedef Container container_type;
typedef typename Container::reference reference;
explicit back_insert_iterator(Container& cont);
back_insert_iterator&
operator=(typename Container::const_reference val);
back_insert_iterator& operator*();
back_insert_iterator& operator++();
back_insert_iterator operator++(int);
protected:
Container *container;
};The template class describes an output iterator object.
It inserts elements
into a container of type Container, which it accesses via
the protected pointer object it stores called
container.
The container must define:
- the member type
const_reference, which is the type of
a constant reference to an element of the sequence controlled by the container - the member type
reference, which is the type of
a reference to an element of the sequence controlled by the container - the member type
value_type, which is the type of
an element of the sequence controlled by the container - the member function
push_back(value_type val),
which appends a new element with value val to the end of
the sequence
explicit back_insert_iterator(Container& cont);
The constructor initializes
container
with &cont.
typedef Container container_type;
The type is a synonym for the template parameter Container.
back_insert_iterator& operator*();
The member function returns *this.
back_insert_iterator& operator++();
back_insert_iterator operator++(int);
The member functions both return *this.
back_insert_iterator&
operator=(typename Container::const_reference val);The member function evaluates
container->
push_back(val), then returns *this->
typedef typename Container::reference reference;
The type describes a reference to an element of the sequence
controlled by the associated container.
template<class Container>
back_insert_iterator<Container> back_inserter(Container& cont);The template function returns
back_insert_iterator<Container>(cont).
struct bidirectional_iterator_tag
: public forward_iterator_tag {
};The type is the same as
iterator<Iter>::iterator_category
when Iter describes an object that can serve as a
bidirectional iterator.
template<class Init>
typename iterator_traits<InIt>::difference_type
distance(InIt first, InIt last);The template function sets a count N to zero. It then
effectively advances first
and increments N until first == last.
If InIt is
a random-access iterator type, the function evaluates the expression
N += last - first. Otherwise, it performs each iterator
increment by evaluating ++first.
The function returns N.
struct forward_iterator_tag
: public input_iterator_tag {
};The type is the same as
iterator<Iter>::iterator_category
when Iter describes an object that can serve as a
forward iterator.
template<class Container>
class front_insert_iterator
: public iterator<output_iterator_tag,
void, void, void, void> {
public:
typedef Container container_type;
typedef typename Container::reference reference;
explicit front_insert_iterator(Container& cont);
front_insert_iterator&
operator=(typename Container::const_reference val);
front_insert_iterator& operator*();
front_insert_iterator& operator++();
front_insert_iterator operator++(int);
protected:
Container *container;
};The template class describes an output iterator object.
It inserts elements
into a container of type Container, which it accesses via
the protected pointer object it stores called
container.
The container must define:
- the member type
const_reference, which is the type of
a constant reference to an element of the sequence controlled by the container - the member type
reference, which is the type of
a reference to an element of the sequence controlled by the container - the member type
value_type, which is the type of
an element of the sequence controlled by the container - the member function
push_front(value_type val),
which prepends a new element with value val to the beginning of
the sequence
typedef Container container_type;
The type is a synonym for the template parameter Container.
explicit front_insert_iterator(Container& cont);
The constructor initializes
container
with &cont.
front_insert_iterator& operator*();
The member function returns *this.
front_insert_iterator& operator++();
front_insert_iterator operator++(int);
The member functions both return *this.
front_insert_iterator&
operator=(typename Container::const_reference val);The member function evaluates
container->
push_front(val), then returns *this.
typedef typename Container::reference reference;
The type describes a reference to an element of the sequence
controlled by the associated container.
template<class Container>
front_insert_iterator<Container> front_inserter(Container& cont);The template function returns
front_insert_iterator<Container>(cont).
struct input_iterator_tag {
};The type is the same as
iterator<Iter>::iterator_category
when Iter describes an object that can serve as an
input iterator.
template<class Container>
class insert_iterator
: public iterator<output_iterator_tag,
void, void, void, void> {
public:
typedef Container container_type;
typedef typename Container::reference reference;
insert_iterator(Container& cont,
typename Container::iterator it);
insert_iterator&
operator=(typename Container::const_reference val);
insert_iterator& operator*();
insert_iterator& operator++();
insert_iterator& operator++(int);
protected:
Container *container;
typename Container::iterator iter;
};The template class describes an output iterator object.
It inserts elements
into a container of type Container, which it accesses via
the protected pointer object it stores called
container.
It also stores the protected iterator object, of class
Container::iterator, called
iter.
The container must define:
- the member type
const_reference, which is the type of
a constant reference to an element of the sequence controlled by the container - the member type
iterator, which is the type of
an iterator for the container - the member type
reference, which is the type of
a reference to an element of the sequence controlled by the container - the member type
value_type, which is the type of
an element of the sequence controlled by the container - the member function
insert(iterator it,
value_type val),
which inserts a new element with value val immediately before
the element designated by it in the controlled sequence,
then returns an iterator that designates the inserted element
typedef Container container_type;
The type is a synonym for the template parameter Container.
insert_iterator(Container& cont,
typename Container::iterator it);The constructor initializes
container
with &cont, and
iter
with it.
insert_iterator& operator*();
The member function returns *this.
insert_iterator& operator++();
insert_iterator& operator++(int);
The member functions both return *this.
insert_iterator&
operator=(typename Container::const_reference val);The member function evaluates
iter =
container->
insert(iter, val), then returns *this.
typedef typename Container::reference reference;
The type describes a reference to an element of the sequence
controlled by the associated container.
template<class Container, class Iter>
insert_iterator<Container> inserter(Container& cont, Iter it);The template function returns
insert_iterator<Container>(cont, it).
template<class Ty, class Elem = char,
class Tr = char_traits>
class Diff = ptrdiff_t>
class istream_iterator
: public iterator<input_iterator_tag,
Ty, Diff, const Ty *, const Ty&> {
public:
typedef Elem char_type;
typedef Tr traits_type;
typedef basic_istream<Elem, Tr> istream_type;
istream_iterator();
istream_iterator(istream_type& istr);
const Ty& operator*() const;
const Ty *operator->() const;
istream_iterator<Ty, Elem, Tr, Diff>& operator++();
istream_iterator<Ty, Elem, Tr, Diff> operator++(int);
};The template class describes an input iterator object.
It extracts objects of class Ty
from an input stream, which it accesses via an object it stores,
of type pointer to
basic_istream<Elem, Tr>.
After constructing or incrementing an object of class
istream_iterator with a non-null stored pointer,
the object attempts to extract and store an object of type
Ty from the associated input stream. If the extraction
fails, the object effectively replaces the stored pointer with
a null pointer (thus making an end-of-sequence indicator).
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
istream_iterator();
istream_iterator(istream_type& istr);
The first constructor initializes the input stream pointer
with a null pointer.
The second constructor initializes the input stream pointer
with &istr, then attempts to extract and store
an object of type Ty.
typedef basic_istream<Elem, Tr> istream_type;
The type is a synonym for
basic_istream<Elem, Tr>.
const Ty& operator*() const;
The operator returns the stored object of type Ty.
const Ty *operator->() const;
The operator returns &**this.
istream_iterator<Ty, Elem, Tr, Diff>& operator++();
istream_iterator<Ty, Elem, Tr, Diff> operator++(int);
The first operator attempts to extract and store an object
of type Ty from the associated input stream. The second
operator makes a copy of the object, increments the object, then
returns the copy.
typedef Tr traits_type;
The type is a synonym for the template parameter Tr.
template<class Elem, class Tr = char_traits<Elem> >
class istreambuf_iterator
: public iterator<input_iterator_tag,
Elem, typename Ty::off_type, Elem *, Elem&> {
public:
typedef Elem char_type;
typedef Tr traits_type;
typedef typename Tr::int_type int_type;
typedef basic_streambuf<Elem, Tr> streambuf_type;
typedef basic_istream<Elem, Tr> istream_type;
istreambuf_iterator(streambuf_type *strbuf = 0) throw();
istreambuf_iterator(istream_type& istr) throw();
Elem operator*() const;
istreambuf_iterator& operator++();
istreambuf_iterator operator++(int);
bool equal(const istreambuf_iterator& right) const;
};The template class describes an input iterator object.
It extracts elements of class Elem
from an input stream buffer,
which it accesses via an object it stores,
of type pointer to
basic_streambuf<Elem,
Tr>.
After constructing or incrementing an object of class
istreambuf_iterator with a non-null stored pointer,
the object effectively attempts to extract and store an object of type
Elem from the associated input stream.
(The extraction may be delayed, however, until the object
is actually dereferenced or copied.) If the extraction
fails, the object effectively replaces the stored pointer with
a null pointer (thus making an end-of-sequence indicator).
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
bool equal(const istreambuf_iterator& right) const;
The member function returns true only if the stored stream buffer
pointers for the object and right are both null pointers
or are both non-null pointers.
typedef typename Tr::int_type int_type;
The type is a synonym for
Ty::int_type.
typedef basic_istream<Elem, Tr> istream_type;
The type is a synonym for
basic_istream<Elem,
Tr>.
istreambuf_iterator(streambuf_type *strbuf = 0) throw();
istreambuf_iterator(istream_type& istr) throw();
The first constructor initializes the input stream-buffer pointer
with strbuf.
The second constructor initializes the input stream-buffer pointer with
istr.rdbuf(),
then (eventually) attempts to extract and store
an object of type Elem.
Elem operator*() const;
The operator returns the stored object of type Elem.
istreambuf_iterator& operator++();
istreambuf_iterator operator++(int);
The first operator (eventually) attempts to extract and store an object
of type Elem from the associated input stream. The second
operator makes a copy of the object, increments the object, then
returns the copy.
typedef basic_streambuf<Elem, Tr> streambuf_type;
The type is a synonym for
basic_streambuf<Elem,
Tr>.
typedef Tr traits_type;
The type is a synonym for the template parameter Tr.
template<class Category, class Ty, class Diff = ptrdiff_t
class Pointer = Ty *, class Reference = Ty&>
struct iterator {
typedef Category iterator_category;
typedef Ty value_type;
typedef Diff difference_type;
typedef Pointer pointer;
typedef Reference reference;
};The template class can serve as a convenient base class
for an iterator class that you define.
It defines the member types
iterator_category
(a synonym for the template parameter Category),
value_type
(a synonym for the template parameter Ty),
difference_type
(a synonym for the template parameter Diff),
pointer
(a synonym for the template parameter Pointer), and
reference
(a synonym for the template parameter Reference).
Note that value_type should not be a constant
type even if pointer points at an object of const type
and reference designates an object of const type.
template<class Iter>
struct iterator_traits {
typedef typename Iter::iterator_category iterator_category;
typedef typename Iter::value_type value_type;
typedef typename Iter::difference_type difference_type;
typedef typename Iter::pointer pointer;
typedef typename Iter::reference reference;
};
template<class Ty>
struct iterator_traits<Ty *> {
typedef random_access_iterator_tag iterator_category;
typedef Ty value_type;
typedef ptrdiff_t difference_type;
typedef Ty *pointer;
typedef Ty& reference;
};
template<class Ty>
struct iterator_traits<const Ty *> {
typedef random_access_iterator_tag iterator_category;
typedef Ty value_type;
typedef ptrdiff_t difference_type;
typedef const Ty *pointer;
typedef const Tr& reference;
};The template class determines several critical types associated
with the iterator type Iter.
It defines the member types
iterator_category
(a synonym for Iter::iterator_category),
value_type
(a synonym for Iter::value_type),
difference_type
(a synonym for Iter::difference_type),
pointer
(a synonym for Iter::pointer), and
reference
(a synonym for Iter::reference).
The partial specializations determine the critical types associated
with an object pointer type Ty * or const Ty *. In this
implementation,
you can also use several template functions that do not make use of
partial specialization:
template<class Category, class Ty, class Diff>
C _Iter_cat(const iterator<Category, Ty, Diff>&);
template<class Ty>
random_access_iterator_tag _Iter_cat(const Ty *);
template<class Category, class Ty, class Diff>
Ty *_Val_type(const iterator<Category, Ty, Diff>&);
template<class Ty>
Ty *_Val_type(const Ty *);
template<class Category, class Ty, class Diff>
Diff *_Dist_type(const iterator<Category, Ty, Diff>&);
template<class Ty>
ptrdiff_t *_Dist_type(const Ty *);which determine several of the same types a bit more indirectly.
You use these functions as arguments
on a function call. Their sole purpose is to supply a useful template
class parameter to the called function.
template<class RanIt>
bool operator!=(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);
template<class Ty, class Elem, class Tr, class Diff>
bool operator!=(
const istream_iterator<Ty, Elem, Tr, Diff>& left,
const istream_iterator<Ty, Elem, Tr, Diff>& right);
template<class Elem, class Tr>
bool operator!=(
const istreambuf_iterator<Elem, Tr>& left,
const istreambuf_iterator<Elem, Tr>& right);The template operator returns !(left == right).
template<class RanIt>
bool operator==(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);
template<class Ty, class Elem, class Tr, class Diff>
bool operator==(
const istream_iterator<Ty, Elem, Tr, Diff>& left,
const istream_iterator<Ty, Elem, Tr, Diff>& right);
template<class Elem, class Tr>
bool operator==(
const istreambuf_iterator<Elem, Tr>& left,
const istreambuf_iterator<Elem, Tr>& right);The first template operator returns true only if
left.current ==
right.current. The second template operator returns true only
if both left and right store the same
stream pointer. The third template operator returns
left.equal(right).
template<class RanIt>
bool operator<(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);The template operator returns
right.current <
left.current [sic].
template<class RanIt>
bool operator<=(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);The template operator returns !(right < left).
template<class RanIt>
bool operator>(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);The template operator returns right < left.
template<class RanIt>
bool operator>=(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);The template operator returns !(left < right).
template<class RanIt>
reverse_iterator<RanIt> operator+(Diff off,
const reverse_iterator<RanIt>& right);The template operator returns right + off.
template<class RanIt>
Diff operator-(
const reverse_iterator<RanIt>& left,
const reverse_iterator<RanIt>& right);The template operator returns
right.current -
left.current [sic].
template<class Ty, class Elem = char,
class Tr = char_traits<Elem> >
class ostream_iterator
: public iterator<output_iterator_tag,
void, void, void, void> {
public:
typedef Elem char_type;
typedef Tr traits_type;
typedef basic_ostream<Elem, Tr> ostream_type;
ostream_iterator(ostream_type& ostr);
ostream_iterator(ostream_type& ostr, const Elem *delim);
ostream_iterator<Ty, Elem, Tr>& operator=(const Ty& val);
ostream_iterator<Ty, Elem, Tr>& operator*();
ostream_iterator<Ty, Elem, Tr>& operator++();
ostream_iterator<Ty, Elem, Tr> operator++(int);
};The template class describes an output iterator object.
It inserts objects of class Ty
into an output stream, which it accesses via an object it stores,
of type pointer to
basic_ostream<Elem, Tr>.
It also stores a pointer to a delimiter string, a
null-terminated string
of elements of type Elem, which is appended after
each insertion. (Note that the string itself is not copied
by the constructor.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
ostream_iterator<Ty, Elem, Tr>& operator*();
The operator returns *this.
ostream_iterator<Ty, Elem, Tr>& operator++();
ostream_iterator<Ty, Elem, Tr> operator++(int);
The operators both return *this.
ostream_iterator<Ty, Elem, Tr>& operator=(const Ty& val);
The operator inserts val into the
output stream associated with the object,
then returns *this.
ostream_iterator(ostream_type& ostr);
ostream_iterator(ostream_type& ostr, const Elem *delim);
The first constructor initializes the output stream pointer
with &ostr. The delimiter string pointer designates an
empty string. The second constructor initializes the output stream
pointer with &ostr and the delimiter string pointer
with delim.
typedef basic_ostream<Elem, Tr> ostream_type;
The type is a synonym for
basic_ostream<Elem, Tr>.
typedef Tr traits_type;
The type is a synonym for the template parameter Tr.
template<class Elem, class Tr = char_traits<Elem> >
class ostreambuf_iterator
: public iterator<output_iterator_tag,
void, void, void, void> {
public:
typedef Elem char_type;
typedef Tr traits_type;
typedef basic_streambuf<Elem, Tr> streambuf_type;
typedef basic_ostream<Elem, Tr> ostream_type;
ostreambuf_iterator(streambuf_type *stebuf) throw();
ostreambuf_iterator(ostream_type& ostr) throw();
ostreambuf_iterator& operator=(Elem ch);
ostreambuf_iterator& operator*();
ostreambuf_iterator& operator++();
T1 operator++(int);
bool failed() const throw();
};The template class describes an output iterator object.
It inserts elements of class Elem
into an output stream buffer,
which it accesses via an object it stores,
of type pointer to
basic_streambuf<Elem, Tr>.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
bool failed() const throw();
The member function returns true only if an insertion into the
output stream buffer has earlier failed.
ostreambuf_iterator& operator*();
The operator returns *this.
ostreambuf_iterator& operator++();
T1 operator++(int);
The first operator returns *this. The second operator
returns an object of some type T1 that can be converted to
ostreambuf_iterator<Elem, Tr>.
ostreambuf_iterator& operator=(Elem ch);
The operator inserts ch into the associated stream buffer,
then returns *this.
typedef basic_ostream<Elem, Tr> ostream_type;
The type is a synonym for
basic_ostream<Elem,
Tr>.
ostreambuf_iterator(streambuf_type *strbuf) throw();
ostreambuf_iterator(ostream_type& ostr) throw();
The first constructor initializes the output stream-buffer pointer
with strbuf.
The second constructor initializes the output stream-buffer pointer with
ostr.rdbuf().
(The stored pointer must not be a null pointer.)
typedef basic_streambuf<Elem, Tr> streambuf_type;
The type is a synonym for basic_streambuf<Elem, Tr>.
typedef Tr traits_type;
The type is a synonym for the template parameter Tr.
struct output_iterator_tag {
};The type is the same as
iterator<Iter>::iterator_category
when Iter describes an object that can serve as a
output iterator.
struct random_access_iterator_tag
: public bidirectional_iterator_tag {
};The type is the same as
iterator<Iter>::iterator_category
when Iter describes an object that can serve as a
random-access iterator.
template<class RanIt>
class reverse_iterator : public iterator<
typename iterator_traits<RanIt>::iterator_category,
typename iterator_traits<RanIt>::value_type,
typename iterator_traits<RanIt>::difference_type,
typename iterator_traits<RanIt>::pointer,
typename iterator_traits<RanIt>::reference> {
typedef typename iterator_traits<RanIt>::difference_type
difference_type;
typedef typename iterator_traits<RanIt>::pointer
pointer;
typedef typename iterator_traits<RanIt>::reference
reference;
public:
typedef RanIt iterator_type;
reverse_iterator();
explicit reverse_iterator(RanIt right);
template<class Ty>
reverse_iterator(const reverse_iterator<Ty>& right);
RanIt base() const;
reference operator*() const;
pointer operator->() const;
reverse_iterator& operator++();
reverse_iterator operator++(int);
reverse_iterator& operator--();
reverse_iterator operator--();
reverse_iterator& operator+=(difference_type off);
reverse_iterator operator+(difference_type off) const;
reverse_iterator& operator-=(difference_type off);
reverse_iterator operator-(difference_type off) const;
reference operator[](difference_type off) const;
protected:
RanIt current;
};The template class describes an object that behaves like a
random-access iterator, only in reverse. It stores a random-access iterator
of type RanIt in the protected object
current.
Incrementing the object X of type
reverse_iterator
decrements X.current, and decrementing x
increments X.current.
Moreover, the expression *X evaluates to
*(current - 1),
of type reference. Typically, reference is
type Tr&.
Thus, you can use an object of class
reverse_iterator to access in reverse
order a sequence that is traversed in order by a random-access
iterator.
Several STL containers specialize
reverse_iterator for RanIt a bidirectional iterator.
In these cases, you must not call any of the member functions operator+=,
operator+, operator-=, operator-, or
operator[].
RanIt base() const;
The member function returns
current.
typedef typename iterator_traits<RanIt>::difference_type
difference_type;The type is a synonym for the iterator trait
typename iterator_traits<RanIt>::pointer.
typedef RanIt iterator_type;
The type is a synonym for the template parameter RanIt.
reference operator*() const;
The operator returns
*(current - 1).
reverse_iterator operator+(difference_type off) const;
The operator returns reverse_iterator(*this) += off.
reverse_iterator& operator++();
reverse_iterator operator++(int);
The first (preincrement) operator evaluates
--current.
then returns *this.
The second (postincrement) operator makes a copy of *this,
evaluates --current, then returns the copy.
reverse_iterator& operator+=(difference_type off);
The operator evaluates
current - off.
then returns *this.
reverse_iterator operator-(difference_type off) const;
The operator returns reverse_iterator(*this) -= off.
reverse_iterator& operator--();
reverse_iterator operator--();
The first (predecrement) operator evaluates
++current.
then returns *this.
The second (postdecrement) operator makes a copy of *this,
evaluates ++current, then returns the copy.
reverse_iterator& operator-=(difference_type off);
The operator evaluates
current + off.
then returns *this.
pointer operator->() const;
The operator returns &**this.
reference operator[](difference_type off) const;
The operator returns *(*this + off).
typedef typename iterator_traits<RanIt>::pointer
pointer;The type is a synonym for the iterator trait
typename iterator_traits<RanIt>::pointer.
typedef typename iterator_traits<RanIt>::reference
reference;The type is a synonym for the iterator trait
typename iterator_traits<RanIt>::reference.
reverse_iterator();
explicit reverse_iterator(RanIt right);
template<class Ty>
reverse_iterator(const reverse_iterator<Ty>& right);The first constructor initializes
current
with its default constructor. The second constructor initializes
current with
right.current.
The template constructor initializes current
with right.base().
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
45 - lib_cont
Container
A container is an
STL template class
that manages a sequence of elements.
Such elements can be of any object type that supplies
a copy constructor, a destructor, and an assignment operator
(all with sensible behavior, of course).
The destructor may not throw an exception.
This document describes the properties required of all such
containers, in terms of a generic template class Container.
An actual container template class may have additional template parameters.
It will certainly have additional member functions.
The STL template container classes are:
deque
hash_map
hash_multimap
hash_multiset
hash_set
list
map
multimap
multiset
set
slist
vectorThe four hash containers and slist
are not required by the C++ Standard.
The Standard C++ library template class basic_string also
meets the requirements for a template container class.
namespace std {
template<class Ty>
class Container;
// TEMPLATE FUNCTIONS
template<class Ty>
bool operator==(
const Container<Ty>& left,
const Container<Ty>& right);
template<class Ty>
bool operator!=(
const Container<Ty>& left,
const Container<Ty>& right);
template<class Ty>
bool operator<(
const Container<Ty>& left,
const Container<Ty>& right);
template<class Ty>
bool operator>(
const Container<Ty>& left,
const Container<Ty>& right);
template<class Ty>
bool operator<=(
const Container<Ty>& left,
const Container<Ty>& right);
template<class Ty>
bool operator>=(
const Container<Ty>& left,
const Container<Ty>& right);
template<class Ty>
void swap(
Container<Ty>& left,
Container<Ty>& right);
};
begin
· clear
· const_iterator
· const_reference
· const_reverse_iterator
· difference_type
· empty
· end
· erase
· iterator
· max_size
· rbegin
· reference
· rend
· reverse_iterator
· size
· size_type
· swap
· value_type
template<class Ty>
class Container {
public:
typedef T0 size_type;
typedef T1 difference_type;
typedef T2 reference;
typedef T3 const_reference;
typedef T4 value_type;
typedef T5 iterator;
typedef T6 const_iterator;
typedef T7 reverse_iterator;
typedef T8 const_reverse_iterator;
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;
size_type size() const;
size_type max_size() const;
bool empty() const;
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
void clear();
void swap(Container& right);
};The template class describes an object that controls a
varying-length sequence of elements,
typically of type Ty.
The sequence is stored in different ways, depending on the
actual container.
A container constructor or member function may find occasion
to call the constructor Ty(const Ty&) or the function
Ty::operator=(const Ty&). If such a call throws
an exception, the container object is obliged to maintain its integrity,
and to rethrow any exception it catches. You can safely swap, assign to,
erase, or destroy a container object
after it throws one of these exceptions.
In general, however, you cannot otherwise predict the state of the
sequence controlled by the container object.
A few additional caveats:
- If the expression
~Ty() throws an exception, the
resulting state of the container object is undefined. - If the container stores an allocator object
al,
and al throws an exception
other than as a result of a call to al.allocate,
the resulting state of the container object is undefined. - If the container stores a function object
comp,
to determine how to order the controlled sequence, and comp
throws an exception of any kind, the resulting state of the container
object is undefined.
The container classes defined by STL satisfy several additional
requirements, as described in the following paragraphs.
Container template class
list provides deterministic,
and useful, behavior even in the presence of the exceptions
described above. For example, if an exception is thrown during the
insertion of one or more elements, the container is left unaltered
and the exception is rethrown.
For all the container classes defined by STL,
if an exception is thrown during calls to the following member
functions:
insert // single element inserted at end
push_back
push_front
the container is left unaltered and the exception is rethrown.
For all the container classes defined by STL,
no exception is thrown during calls to the following member
functions:
pop_back
pop_front
The member function erase
throws an exception only if a
copy operation
(assignment or copy construction) throws an exception.
Moreover, no exception is thrown while copying an iterator returned by a
member function.
The member function swap
makes additional promises for all container classes defined by STL:
- The member function throws an exception only if the container stores
an allocator object
al,
and al throws an exception when copied,
or if the container stores a function object comp,
to determine how to order the controlled sequence, and comp
throws an exception when copied. - References, pointers, and iterators that designate elements of
the controlled sequences being swapped remain valid.
An object of a container class defined by STL
allocates and frees storage for the sequence it controls
through a stored object of type Alloc,
which is typically a template parameter. Such an
allocator object must have
the same external interface as an object of class
allocator<Ty>.
In particular, Alloc must be the same type as
Alloc::rebind<value_type>::other
For all container classes defined by STL, the member function:
Alloc get_allocator() const;
returns a copy of the stored allocator object.
Note that the stored allocator object is not copied when the container
object is assigned. All constructors initialize the value stored
in allocator, to Alloc() if the constructor contains
no allocator parameter.
According to the
C++ Standard
a container class defined by STL can assume that:
- All objects of class
Alloc compare equal. - Type
Alloc::const_pointer is the same as
const Ty *. - Type
Alloc::const_reference is the same as
const Ty&. - Type
Alloc::pointer is the same as
Ty *. - Type
Alloc::reference is the same as
Ty&.
In this
implementation, however,
containers do not make such simplifying assumptions.
Thus, they work properly with allocator objects that are
more ambitious:
- All objects of class
Alloc need not compare equal.
(You can maintain multiple pools of storage.) - Type
Alloc::const_pointer need not be the same as
const Ty *.
(A const pointer can be a class.) - Type
Alloc::pointer need not be the same as
Ty *.
(A pointer can be a class.)
const_iterator begin() const;
iterator begin();
The member function returns an iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
void clear();
The member function calls
erase(
begin(),
end()).
typedef T6 const_iterator;
The type describes an object that can serve as a constant
iterator for the controlled sequence.
It is described here as a
synonym for the unspecified type T6.
typedef T3 const_reference;
The type describes an object that can serve as a constant reference
to an element of the controlled sequence. It is described here as a
synonym for the unspecified type T3
(typically Alloc::const_reference).
typedef T8 const_reverse_iterator;
The type describes an object that can serve as a constant reverse
iterator for the controlled sequence. It is described here as a
synonym for the unspecified type T8 (typically
reverse_iterator
<const_iterator>).
typedef T1 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 unspecified type T1
(typically Alloc::difference_type).
bool empty() const;
The member function returns true for an empty controlled sequence.
const_iterator end() const;
iterator end();
The member function returns an iterator that points
just beyond the end of the sequence.
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
The first member function removes the element of the controlled
sequence pointed to by where. The second member function
removes the elements of the controlled sequence
in the range [first, last).
Both return an iterator that designates the first element remaining
beyond any elements removed, or
end() if no such element exists.
The member functions throw an exception only if a copy operation
throws an exception.
typedef T5 iterator;
The type describes an object that can serve as an
iterator for the controlled sequence.
It is described here as a
synonym for the unspecified type T5.
An object of type iterator can be cast
to an object of type
const_iterator.
size_type max_size() const;
The member function returns the length of the longest sequence that
the object can control, in constant time regardless of the length of the
controlled sequence.
const_reverse_iterator rbegin() const;
reverse_iterator rbegin();
The member function returns a reverse iterator that designates the
last element of the controlled sequence. Hence, it designates the
beginning of the reverse sequence.
typedef T2 reference;
The type describes an object that can serve as a reference to an
element of the controlled sequence. It is described here as a
synonym for the unspecified type T2
(typically Alloc::reference).
An object of type reference can be cast
to an object of type
const_reference.
const_reverse_iterator rend() const;
reverse_iterator rend();
The member function returns a reverse iterator that designates the
(fictitious) element before the first element of the controlled
sequence. Hence, it points just beyond the end of the reverse sequence.
typedef T7 reverse_iterator;
The type describes an object that can serve as a reverse iterator
for the controlled sequence. It is described here as a
synonym for the unspecified type T7 (typically
reverse_iterator
<iterator>).
size_type size() const;
The member function returns the length of the controlled sequence,
in constant time regardless of the length of the controlled sequence.
typedef T0 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 unspecified type T0
(typically Alloc::size_type).
void swap(Container& right);
The member function swaps the controlled sequences between
*this and right. If
get_allocator()
== right.get_allocator(), it does so in constant time. Otherwise,
it performs a number of element assignments and constructor calls
proportional to the number of elements in the two controlled sequences.
typedef T4 value_type;
The type is a synonym for the template parameter Ty.
It is described here as a
synonym for the unspecified type T4
(typically Alloc::value_type).
template<class Ty>
bool operator!=(
const Container <Ty>& left,
const Container <Ty>& right);The template function returns !(left == right).
template<class Ty>
bool operator==(
const Container <Ty>& left,
const Container <Ty>& right);The template function overloads operator== to compare
two objects of template class
Container. The function returns
left.size() == right.size() &&
equal(left.
begin(), left.
end(), right.begin()).
template<class Ty>
bool operator<(
const Container <Ty>& left,
const Container <Ty>& right);The template function overloads operator< to compare
two objects of template class
Container. The function returns
lexicographical_compare(left.
begin(), left.
end(), right.begin(), right.end()).
template<class Ty>
bool operator<=(
const Container <Ty>& left,
const Container <Ty>& right);The template function returns !(right < left).
template<class Ty>
bool operator>(
const Container <Ty>& left,
const Container <Ty>& right);The template function returns right < left.
template<class Ty>
bool operator>=(
const Container <Ty>& left,
const Container <Ty>& right);The template function returns !(left < right).
template<class Ty>
void swap(
Container <Ty>& left,
Container <Ty>& right);The template function executes
left.swap(right).
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
46 - lib_cpp
C++ Library Overview
Using C++ Library Headers
· C++ Library Conventions
· Iostreams Conventions
· Program
Startup and Termination
· Exceptions
All C++ library entities are declared or defined in one or more
standard headers.
To make use of a library entity in a program, write an
include directive
that names the relevant standard header.
The full set of 28
C++ library headers
(along with the additional 15
Standard C headers)
constitutes a
hosted implementation
of Embedded C++:
<cassert>,
<cctype>,
<cerrno>,
<cfloat>,
<climits>,
<clocale>,
<cmath>,
<complex>,
<csetjmp>,
<csignal>,
<cstdarg>,
<cstddef>,
<cstdio>,
<cstdlib>,
<cstring>,
<ctime>,
<fstream>,
<iomanip>,
<ios>,
<iosfwd>,
<iostream>,
<istream>,
<new>,
<ostream>,
<sstream>,
<streambuf>,
<string>, and
<strstream>
A freestanding implementation
of the C++ library provides only a subset of these headers:
<cstddef>,
<cstdlib>
(declaring at least the functions
abort,
atexit, and
exit),
<new>, and
<cstdarg>.
The C++ library headers also have a broader subdivision --
iostreams headers.
You include the contents of a standard header by naming it in an
include directive,
as in:
#include <iostream> /* include I/O facilities */
You can include the standard headers in any order, a standard
header more than once, or two or more standard headers that define
the same macro or the same type.
Do not include a standard header within a declaration. Do not
define macros that have the same names as keywords before you include
a standard header.
A C++ library header includes any other C++ library headers
it needs to define needed types. (Always include explicitly any
C++ library headers needed in a translation unit, however, lest
you guess wrong about its actual dependencies.) A Standard C header
never includes another standard header. A standard header declares
or defines only the entities described for it in this document.
Every function in the library is declared in a standard header.
Unlike in Standard C, the standard header never provides a
masking macro,
with the same name as the function, that masks the function
declaration and achieves the same effect.
The C++ Standard requires that nearly all names
in the C++ library headers be defined in the
std namespace,
or in a namespace
nested within the std namespace.
Otherwise, all names are defined in the global namespace.
In this implementation,
however, you can ignore namespaces.
The C++ library obeys much the same
conventions
as the Standard C library, plus a few more outlined here.
An implementation has certain latitude in how it declares types
and functions in the C++ library:
- Names of functions in the Standard C library may have either
extern "C++" or
extern "C" linkage.
Include the appropriate
Standard C header
rather than declare a library entity inline. - A member function name in a library class may have additional
function signatures over those listed in this document. You can
be sure that a function call described here behaves as expected,
but you cannot reliably take the address of a library member function.
(The type may not be what you expect.)
- A library class may have undocumented (non-virtual) base classes.
A class documented as derived from another class may, in fact,
be derived from that class through other undocumented classes.
- A type defined as a synonym for some integer type may be the
same as one of several different integer types.
- A bitmask type can
be implemented as either an integer type or an enumeration.
In either case, you can perform bitwise operations (such as AND
and OR) on values of the same bitmask type. The elements
A and B of a bitmask type are nonzero
values such that A & B is zero. - A library function that has no exception specification can
throw an arbitrary exception, unless its definition clearly
restricts such a possibility.
On the other hand, there are some restrictions you can count on:
- The Standard C library uses no
masking macros. Only specific function
signatures are reserved, not the names of the functions themselves.
- A library function name outside a class will not have
additional, undocumented, function signatures. You can reliably
take its address.
- Base classes and member functions described as virtual are
assuredly virtual, while those described as non-virtual are
assuredly non-virtual.
- Two types defined by the C++ library
are always different unless this document explicitly suggests
otherwise.
- Functions supplied by the library, including the default versions of
replaceable functions,
can throw at most those exceptions listed in any exception
specification.
No destructors supplied by the library throw exceptions.
Functions in the
Standard C library
may propagate an exception, as when
qsort calls a comparison
function that throws an exception, but they do not otherwise throw
exceptions.
The iostreams headers support conversions
between text and encoded forms, and input and output to external
files:
<fstream>,
<iomanip>,
<ios>,
<iosfwd>,
<iostream>,
<istream>,
<ostream>,
<sstream>,
<streambuf>, and
<strstream>.
The simplest use of iostreams requires only that you include
the header <iostream>. You can then extract values from
cin, to read the
standard input.
The rules for doing so are outlined in the description of the class
istream.
You can also insert values to
cout, to write the
standard output.
The rules for doing so are outlined in the description of the class
ostream.
Format control common to both extractors and insertors is managed
by the class ios.
Manipulating this format information in the guise of extracting and
inserting objects is the province of several
manipulators.
You can perform the same iostreams operations on files that you
open by name, using the classes declared in
<fstream>.
To convert between iostreams and objects of class
string,
use the classes declared in <sstream>.
And to do the same with C strings,
use the classes declared in <strstream>.
The remaining headers provide support services, typically of direct
interest to only the most advanced users of the iostreams classes.
A C++ program performs the same operations as does a C program
program startup and at
program termination,
plus a few more outlined here.
Before the target environment calls the function
main, and after it stores
any constant initial values you specify in all objects that have
static duration, the program executes any remaining constructors
for such static objects. The order of execution is not specified
between translation units, but you can nevertheless assume that some
iostreams objects are properly initialized
for use by these static constructors. These control
text streams:
You can also use these objects within the destructors called for
static objects, during
program termination.
As with C, returning
from main or calling
exit
calls all functions registered with
atexit
in reverse order of registry.
In this implementation,
exception handling can be either enabled or disabled.
This document describes all behavior as if exception handling is enabled.
If exception handling is disabled, however:
- Throw specifications in library function declarations
are not actually present.
- Catch clauses in library function definitions likewise are not
actually present. It is not possible for the program to catch an
exception, except in the limited sense outlined below. Hence, the
library has no occasion to rethrow an exception.
- Rather than throw an exception, as in
throw ex, the library
actually calls ex._Raise().
Here, void _Raise()
is a member function of class exception,
the base class for all exceptions thrown by the library. It performs the following
operations, in order:
- If a raise handler
has been registered by an earlier call to the static member function
exception::
_Set_raise_handler(void
(*)(const exception&), then _Raise calls the
raise handler. _Raise then calls the protected virtual member function
void _Doraise(), which typically calls
_Throw(*this) in any class derived
from exception. (This ensures that the most derived version
of the virtual public member function what gets called
by _Throw, as outlined below.)_Raise then calls _Throw(*this).
The replaceable global function
void _Throw(const exception& ex)
never returns to its caller.
If the pointer returned by ex.what() is not a null pointer,
the function writes to the
standard error output stream
a diagnostic message that includes the
null-terminated string
designated by the pointer. In any event, the function then calls
abort.
The net effect of all this machinery is to supply several levels of control,
in lieu of the normal exception-handling machinery:
- You can dynamically specify a raise handler that is called whenever the
library would normally throw any exception
derived from class
exception. - You can override
_Doraise, in a class you derive
from exception, to get control whenever an object of that
class would normally be thrown by the library (assuming that any raise handler
you register returns to its caller). - You can define your own version of
_Throw, to statically handle
termination on all thrown exceptions as you see fit.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
47 - lib_file
Files and Streams
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of the C library:
the Green Hills Software C Library.
For documentation pertaining to it,
please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
48 - lib_over
C Library Overview
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of the C library:
the Green Hills Software C Library.
For documentation pertaining to it,
please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
49 - lib_prin
Formatted Output
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of the C library:
the Green Hills Software C Library.
For documentation pertaining to it,
please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
50 - lib_scan
Formatted Input
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of the C library:
the Green Hills Software C Library.
For documentation pertaining to it,
please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
51 - lib_stl
STL Conventions
Algorithm Conventions
· Iterator Conventions
The Standard
Template Library, or
STL, establishes uniform standards
for the application of
iterators to STL
containers or other sequences
that you define, by STL
algorithms or other functions
that you define. This document summarizes many of the conventions
used widely throughout the Standard Template Library.
The STL facilities make widespread use of
iterators, to
mediate between the various algorithms
and the sequences upon which they act.
For brevity in the remainder of this document,
the name of an iterator type (or its prefix)
indicates the category of iterators required
for that type. In order of increasing power, the categories are
summarized here as:
OutIt --
An output iterator X
can only have a value V stored indirect on it,
after which it must be incremented before the next store,
as in (*X++ = V), (*X = V, ++X), or
(*X = V, X++).InIt --
An input iterator X
can represent a singular value that indicates end-of-sequence.
If an input
iterator does not compare equal to its end-of-sequence value,
it can have a value V accessed indirect on it
any number of times, as in (V = *X). To progress
to the next value, or end-of-sequence, you increment it, as in
++X, X++, or (V = *X++).
Once you increment any copy of an input iterator, none
of the other copies can safely be compared, dereferenced, or
incremented thereafter.FwdIt --
A forward iterator X
can take the place of an output iterator (for writing) or an
input iterator (for reading). You can, however, read
(via V = *X) what you just wrote (via *X = V)
through a forward iterator. And you can make multiple copies
of a forward iterator, each of which can be dereferenced and
incremented independently.BidIt --
A bidirectional iterator X
can take the place of a forward iterator. You can, however,
also decrement a bidirectional iterator, as in
--X, X--, or (V = *X--).RanIt --
A random-access iterator X
can take the place of a bidirectional iterator. You can also
perform much the same integer arithmetic on a random-access iterator
that you can on an object pointer. For N an integer object,
you can write x[N], x + N, x - N,
and N + X.
Note that an object pointer can take the place of a random-access
iterator, or any other for that matter. All iterators can be assigned
or copied. They are assumed to be lightweight objects and hence are
often passed and returned by value, not by reference.
Note also that none of the operations described above can throw
an exception, at least when performed on a valid iterator.
The hierarchy of iterator categories can be
summarize by showing three sequences.
For write-only access to a sequence, you can use any of:
output iterator
-> forward iterator
-> bidirectional iterator
-> random-access iteratorThe right arrow means ``can be replaced by.'' So any algorithm
that calls for an output iterator should work nicely with a forward
iterator, for example, but not the other way around.
For read-only access to a sequence, you can use any of:
input iterator
-> forward iterator
-> bidirectional iterator
-> random-access iteratorAn input iterator is the weakest of all categories, in this
case.
Finally, for read/write access to a sequence, you can use any
of:
forward iterator
-> bidirectional iterator
-> random-access iteratorRemember that an object pointer can always serve as a random-access
iterator. Hence, it can serve as any category of iterator, so long
as it supports the proper read/write access
to the sequence it designates.
An iterator It other than an object pointer must also
define the member types required by the specialization
iterator_traits<It>.
Note that these requirements can be met by deriving It
from the public base class
iterator.
This ``algebra'' of iterators is fundamental to practically
everything else in the
Standard
Template Library. It is important
to understand the promises, and limitations, of each iterator category
to see how iterators are used by containers and algorithms in STL.
The descriptions of the algorithm template functions
employ several shorthand phrases:
- The phrase ``in the range
[A, B)'' means
the sequence of zero or more discrete values beginning with A
up to but not including B. A range is valid only if
B is reachable from A --
you can store A
in an object N (N = A),
increment the object zero or more times (++N),
and have the object compare equal to B
after a finite number of increments (N == B). - The phrase ``each
N in the range
[A, B)'' means that N
begins with the value A and is incremented
zero or more times until it equals the value B.
The case N == B is not in the range. - The phrase ``the lowest value of
N
in the range [A, B) such that X'' means
that the condition X is determined for each N
in the range [A, B) until the condition X is met. - The phrase ``the highest value of
N
in the range [A, B) such that X'' usually means
that X is determined for each N
in the range [A, B).
The function stores in K a
copy of N each time the condition X is met.
If any such store occurs, the function replaces the final
value of N (which equals B)
with the value of K. For a bidirectional or
random-access iterator, however, it can also mean that
N begins with the highest value in the range
and is decremented over the range until the condition X is met. - Expressions such as
X - Y, where X
and Y can be iterators other than random-access
iterators, are intended in the mathematical sense. The
function does not necessarily evaluate operator- if it must
determine such a value. The same is also true for expressions
such as X + N and X - N,
where N is an integer type.
Several algorithms make use of a predicate that performs a
pairwise comparison,
such as with operator==, to yield a bool result.
The predicate function operator==, or any
replacement for it, must not alter either of its operands.
It must yield the same boolresult every time it is evaluated,
and it must yield the same result if a copy of either operand is substituted
for the operand.
Several algorithms make use of a predicate that must impose a
strict weak ordering
on pairs of elements from a sequence.
For the predicate pr(X, Y):
pr(X, X) is false
(X can't be ordered before itself)X and Y have an
equivalent ordering
if !pr(X, Y) && !pr(Y, X)
(X == Y need not be defined)pr(X, Y) &&
pr(Y, Z) implies pr(X, Z)
(ordering is transitive)
Some of these algorithms implicitly use the predicate
X < Y, and some use a predicate pr(X, Y)
passed as a function object. Predicates that
satisfy the ``strict weak ordering'' requirement are
X < Y and X > Y for the
arithmetic types and for string objects.
Note, however, that predicates such as X <= Y and
X >= Y for these same types
do not satisfy this requirement.
A sequence of elements designated by iterators in the range
[first, last) is
``a sequence ordered by
operator<'' if, for each N
in the range [0, last - first) and for each M
in the range (N, last - first) the predicate
!(*(first + M) < *(first + N))
is true. (Note that the elements are sorted in
ascending order.)
The predicate function operator<, or any
replacement for it, must not alter either of its operands.
It must yield the same boolresult every time it is evaluated,
and it must yield the same result if a copy of either operand is substituted
for the operand.
Moreover, it must impose a
strict weak ordering on the operands
it compares.
A sequence of elements designated by iterators in the range
[first, last) is
``a heap ordered by
operator<'' if:
- For each
N
in the range [1, last - first) the predicate
!(*first < *(first + N))
is true. (The first element is the largest.) - It is possible to insert (
push_heap)
a new element or remove (pop_heap) the largest element
in logarithmic time and preserve the heap discipline
in the resulting sequence.
Its internal structure
is otherwise known only to the template functions
make_heap,
pop_heap, and
push_heap.
As with an ordered sequence,
the predicate function operator<, or any
replacement for it, must not alter either of its operands,
and it must impose a
strict weak ordering on the operands
it compares.
It must yield the same boolresult every time it is evaluated,
and it must yield the same result if a copy of either operand is substituted
for the operand.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
52 - limits
<limits.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
53 - list
<list>
Include the STL
standard header <list> to define the
container
template class list and several supporting
templates.
namespace std {
template<class Ty, class Alloc>
class list;
// TEMPLATE FUNCTIONS
template<class Ty, class Alloc>
bool operator==(
const list<Ty, Alloc>& left,
const list<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator!=(
const list<Ty, Alloc>& left,
const list<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator<(
const list<Ty, Alloc>& left,
const list<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator>(
const list<Ty, Alloc>& left,
const list<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator<=(
const list<Ty, Alloc>& left,
const list<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator>=(
const list<Ty, Alloc>& left,
const list<Ty, Alloc>& right);
template<class Ty, class Alloc>
void swap(
list<Ty, Alloc>& left,
list<Ty, Alloc>& right);
};
allocator_type
· assign
· back
· begin
· clear
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· difference_type
· empty
· end
· erase
· front
· get_allocator
· insert
· iterator
· list
· max_size
· merge
· pointer
· pop_back
· pop_front
· push_back
· push_front
· rbegin
· reference
· remove
· remove_if
· rend
· resize
· reverse
· reverse_iterator
· size
· size_type
· sort
· splice
· swap
· unique
· value_type
template<class Ty, class Alloc = allocator<Ty> >
class list {
public:
typedef Alloc allocator_type;
typedef typename Alloc::pointer pointer;
typedef typename Alloc::const_pointer
const_pointer;
typedef typename Alloc::reference reference;
typedef typename Alloc::const_reference const_reference;
typedef typename Alloc::value_type value_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;
list();
explicit list(const Alloc& al);
explicit list(size_type count);
list(size_type count, const Ty& val);
list(size_type count, const Ty& val, const Alloc& al);
list(const list& right);
template<class InIt>
list(InIt first, InIt last);
template<class InIt>
list(InIt first, InIt last, const Alloc& al);
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;
void resize(size_type newsize);
void resize(size_type newsize, Ty val);
size_type size() const;
size_type max_size() const;
bool empty() const;
Alloc get_allocator() const;
reference front();
const_reference front() const;
reference back();
const_reference back() const;
void push_front(const Ty& val);
void pop_front();
void push_back(const Ty& val);
void pop_back();
template<class InIt>
void assign(InIt first, InIt last);
void assign(size_type count, const Ty& val);
iterator insert(iterator where, const Ty& val);
void insert(iterator where, size_type count, const Ty& val);
template<class InIt>
void insert(iterator where, InIt first, InIt last);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
void clear();
void swap(list& right);
void splice(iterator where, list& right);
void splice(iterator where, list& right, iterator first);
void splice(iterator where, list& right, iterator first,
iterator last);
void remove(const Ty& val);
templace<class Pr1>
void remove_if(Pr1 pred);
void unique();
template<class Pr2>
void unique(Pr2 pred);
void merge(list& right);
template<class Pr3>
void merge(list& right, Pr3 pred);
void sort();
template<class Pr3>
void sort(Pr3 pred);
void reverse();
};The template class describes an object that controls a
varying-length sequence of elements of type Ty.
The sequence is stored as a bidirectional linked list of elements,
each containing a member of type Ty.
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class Alloc. Such an allocator object must have
the same external interface as an object of template class
allocator.
Note that the stored allocator object is not copied when the container
object is assigned.
List reallocation
occurs when a member function must insert, erase, or splice elements of
the controlled sequence. In all such cases, only iterators
or references that designate erased or spliced elemets
of the controlled sequence become
invalid.
All additions to the controlled sequence occur as if by calls to
insert, which is the
only member function that calls the constructor
Ty(const Ty&). If such an expression throws
an exception, the container object inserts no new elements and rethrows
the exception. Thus, an object of template class list
is left in a known state when such exceptions occur.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
template<class InIt>
void assign(InIt first, InIt last);
void assign(size_type count, const Ty& val);If InIt is an integer type, the first member
function behaves the same as assign((size_type)first, (Ty)last).
Otherwise, the
first member function replaces the sequence
controlled by *this with the sequence
[first, last), which must not overlap
the initial controlled sequence.
The second member function replaces the sequence
controlled by *this with a repetition of count
elements of value val.
reference back();
const_reference back() const;
The member function returns a reference to the last element of the
controlled sequence, which must be non-empty.
const_iterator begin() const;
iterator begin();
The member function returns a bidirectional iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
void clear();
The member function calls
erase(
begin(),
end()).
typedef T1 const_iterator;
The type describes an object that can serve as a constant
bidirectional iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T1.
typedef typename Alloc::const_pointer
const_pointer;The type describes an object that can serve as a constant pointer
to an element of the controlled sequence.
typedef typename Alloc::const_reference const_reference;
The type describes an object that can serve as a constant reference
to an element of the controlled sequence.
typedef reverse_iterator<const_iterator>
const_reverse_iterator;The type describes an object that can serve as a constant reverse
bidirectional iterator for the controlled sequence.
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 function returns a bidirectional iterator that points
just beyond the end of the sequence.
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
The first member function removes the element of the controlled
sequence pointed to by where. The second member function
removes the elements of the controlled sequence
in the range [first, last).
Both return an iterator that designates the first element remaining
beyond any elements removed, or
end() if no such element exists.
Erasing N elements causes
N destructor calls.
Reallocation occurs,
so iterators and references become
invalid for the erased
elements.
The member functions never throw an exception.
reference front();
const_reference front() const;
The member function returns a reference to the first element of the
controlled sequence, which must be non-empty.
Alloc get_allocator() const;
The member function returns the stored
allocator object.
iterator insert(iterator where, const Ty& val);
void insert(iterator where, size_type count, const Ty& val);
template<class InIt>
void insert(iterator where, InIt first, InIt last);Each of the member functions inserts, before the element pointed to
by where in the controlled sequence, a sequence
specified by the remaining operands.
The first member function inserts
a single element with value val and returns an iterator
that designates the newly inserted element. The second member function
inserts a repetition of count elements of value val.
If InIt is an integer type, the last member
function behaves the same as insert(where, (size_type)first, (Ty)last).
Otherwise, the last member function inserts the sequence
[first, last), which must not overlap
the initial controlled sequence.
Inserting N elements causes N
constructor calls.
Reallocation occurs,
but no iterators or references become
invalid.
If an exception is thrown during the
insertion of one or more elements, the container is left unaltered
and the exception is rethrown.
typedef T0 iterator;
The type describes an object that can serve as a bidirectional
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T0.
list();
explicit list(const Alloc& al);
explicit list(size_type count);
list(size_type count, const Ty& val);
list(size_type count, const Ty& val,
const Alloc& al);
list(const list& right);
template<class InIt>
list(InIt first, InIt last);
template<class InIt>
list(InIt first, InIt last, const Alloc& 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
right.get_allocator().
Otherwise, it is Alloc().
The first two constructors specify an
empty initial controlled sequence. The third constructor specifies
a repetition of count elements of value Ty().
The fourth and fifth constructors specify
a repetition of count elements of value val.
The sixth constructor specifies a copy of the sequence controlled by
right.
If InIt is an integer type, the last two constructors
specify a repetition of (size_type)first elements of value
(Ty)last. Otherwise, the
last two constructors specify the sequence
[first, last).
size_type max_size() const;
The member function returns the length of the longest sequence that
the object can control.
void merge(list& right);
template<class Pr3>
void merge(list& right, Pre3 pred);Both member functions remove all elements from the sequence
controlled by right and insert them in the controlled
sequence. Both sequences must be
ordered by the same predicate,
described below. The resulting sequence is also ordered by that
predicate.
For the iterators Pi and Pj
designating elements at positions I
and J, the first member function imposes the
order !(*Pj < *Pi) whenever I < J.
(The elements are sorted in ascending order.)
The second member function imposes the order
!pred(*Pj, *Pi) whenever I < J.
No pairs of elements in the original controlled sequence
are reversed in the resulting controlled sequence. If a pair
of elements in the resulting controlled sequence has
equivalent ordering
(!(*Pi < *Pj) && !(*Pj < *Pi)),
an element from the original controlled sequence appears before
an element from the sequence controlled by right.
An exception occurs only if pred throws an exception.
In that case, the controlled sequence is left in unspecified order
and the exception is rethrown.
typedef typename Alloc::pointer pointer;
The type describes an object that can serve as a pointer to an
element of the controlled sequence.
void pop_back();
The member function removes the last element of the
controlled sequence, which must be non-empty.
The member function never throws an exception.
void pop_front();
The member function removes the first element of the
controlled sequence, which must be non-empty.
The member function never throws an exception.
void push_back(const Ty& val);
The member function inserts an element with value val
at the end of the controlled sequence.
If an exception is thrown, the container is left unaltered
and the exception is rethrown.
void push_front(const Ty& val);
The member function inserts an element with value val
at the beginning of the controlled sequence.
If an exception is thrown, the container is left unaltered
and the exception is rethrown.
const_reverse_iterator rbegin() const;
reverse_iterator rbegin();
The member function returns a reverse bidirectional
iterator that points just
beyond the end of the controlled sequence. Hence, it designates the
beginning of the reverse sequence.
typedef typename Alloc::reference reference;
The type describes an object that can serve as a reference to an
element of the controlled sequence.
void remove(const Ty& val);
The member function removes from the controlled sequence
all elements, designated by the iterator where, for which
*where == val.
The member function never throws an exception.
templace<class Pr1>
void remove_if(Pr1 pred);The member function removes from the controlled sequence
all elements, designated by the iterator where, for which
pred(*where) is true.
An exception occurs only if pred throws an exception.
In that case, the controlled sequence is left in an unspecified state
and the exception is rethrown.
const_reverse_iterator rend() const;
reverse_iterator rend();
The member function returns a reverse bidirectional
iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, it designates the end of the reverse sequence.
void resize(size_type newsize);
void resize(size_type newsize, Ty val);
The member functions both ensure that
size() henceforth
returns newsize. If it must make the controlled sequence longer,
the first member function
appends elements with value Ty(), while the second member function
appends elements with value val.
To make the controlled sequence shorter, both member functions call
erase(begin() + newsize, end()).
void reverse();
The member function reverses the order in which elements appear
in the controlled sequence.
typedef reverse_iterator<iterator>
reverse_iterator;The type describes an object that can serve as a reverse
bidirectional iterator for the controlled sequence.
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.
void sort();
template<class Pr3>
void sort(Pr3 pred);Both member functions order the elements in the controlled
sequence by a predicate, described below.
For the iterators Pi and Pj
designating elements at positions I
and J, the first member function imposes the
order !(*Pj < *Pi) whenever I < J.
(The elements are sorted in ascending order.)
The member template function imposes the order
!pred(*Pj, *Pi) whenever I < J.
No ordered pairs of elements in the original controlled sequence
are reversed in the resulting controlled sequence.
(The sort is stable.)
An exception occurs only if pred throws an exception.
In that case, the controlled sequence is left in unspecified order
and the exception is rethrown.
void splice(iterator where, list& right);
void splice(iterator where, list& right, iterator first);
void splice(iterator where, list& right, iterator first,
iterator last);The first member function inserts the sequence controlled
by right before the element in the controlled sequence
pointed to by where. It also removes all elements from
right. (&right must not equal this.)
The second member function removes the element pointed to by
first in the sequence controlled by right and
inserts it before the element in the controlled sequence
pointed to by where. (If where == first || where == ++first,
no change occurs.)
The third member function inserts the subrange
designated by [first, last) from the sequence
controlled by right
before the element in the controlled sequence pointed to by where.
It also removes the original subrange from the sequence controlled
by right. (If &right == this,
the range [first, last) must not include the element
pointed to by where.)
If the third member function inserts
N elements, and &right != this, an object of class
iterator is
incremented N times.
For all splice member functions, If
get_allocator()
== str.get_allocator(), no exception occurs.
Otherwise, a copy and a destructor call also
occur for each inserted element.
Only iterators or references that designate spliced elements become
invalid.
void swap(list& right);
The member function swaps the controlled sequences between
*this and where. If
get_allocator()
== where.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.
void unique();
template<class Pr2>
void unique(Pr2 pred);The first member function removes from the controlled sequence
every element that compares equal to its preceding element.
For the iterators Pi and Pj
designating elements at positions I
and J, the second member function removes every
element for which I + 1 == J && pred(*Pi, *Pj).
For a controlled sequence of length N
(> 0), the predicate pred(*Pi, *Pj)
is evaluated N - 1 times.
An exception occurs only if pred throws an exception.
In that case, the controlled sequence is left in an unspecified state
and the exception is rethrown.
typedef typename Alloc::value_type value_type;
The type is a synonym for the template parameter Ty.
template<class Ty, class Alloc>
bool operator!=(
const list <Ty, Alloc>& left,
const list <Ty, Alloc>& right);The template function returns !(left == right).
template<class Ty, class Alloc>
bool operator==(
const list <Ty, Alloc>& left,
const list <Ty, Alloc>& right);The template function overloads operator== to compare
two objects of template class
list. The function returns
left.size() == right.size() &&
equal(left.
begin(), left.
end(), right.begin()).
template<class Ty, class Alloc>
bool operator<(
const list <Ty, Alloc>& left,
const list <Ty, Alloc>& right);The template function overloads operator< to compare
two objects of template class
list. The function returns
lexicographical_compare(left.
begin(), left.
end(), right.begin(), right.end()).
template<class Ty, class Alloc>
bool operator<=(
const list <Ty, Alloc>& left,
const list <Ty, Alloc>& right);The template function returns !(right < left).
template<class Ty, class Alloc>
bool operator>(
const list <Ty, Alloc>& left,
const list <Ty, Alloc>& right);The template function returns right < left.
template<class Ty, class Alloc>
bool operator>=(
const list <Ty, Alloc>& left,
const list <Ty, Alloc>& right);The template function returns !(left < right).
template<class Ty, class Alloc>
void swap(
list <Ty, Alloc>& left,
list <Ty, Alloc>& right);The template function executes
left.swap(right).
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
54 - locale
<locale.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
55 - map
<map>
Include the STL
standard header <map> to define the
container
template classes map and
multimap, and their supporting
templates.
namespace std {
template<class Key, class Ty, class Pr, class Alloc>
class map;
template<class Key, class Ty, class Pr, class Alloc>
class multimap;
// TEMPLATE FUNCTIONS
template<class Key, class Ty, class Pr, class Alloc>
bool operator==(
const map<Key, Ty, Pr, Alloc>& left,
const map<Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator==(
const multimap<Key, Ty, Pr, Alloc>& left,
const multimap<Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator!=(
const map<Key, Ty, Pr, Alloc>& left,
const map<Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator!=(
const multimap<Key, Ty, Pr, Alloc>& left,
const multimap<Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator<(
const map<Key, Ty, Pr, Alloc>& left,
const map<Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator<(
const multimap<Key, Ty, Pr, Alloc>& left,
const multimap<Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator>(
const map<Key, Ty, Pr, Alloc>& left,
const map<Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator>(
const multimap<Key, Ty, Pr, Alloc>& left,
const multimap<Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator<=(
const map<Key, Ty, Pr, Alloc>& left,
const map<Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator<=(
const multimap<Key, Ty, Pr, Alloc>& left,
const multimap<Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator>=(
const map<Key, Ty, Pr, Alloc>& left,
const map<Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator>=(
const multimap<Key, Ty, Pr, Alloc>& left,
const multimap<Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
void swap(
map<Key, Ty, Pr, Alloc>& left,
map<Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
void swap(
multimap<Key, Ty, Pr, Alloc>& left,
multimap<Key, Ty, Pr, Alloc>& right);
};
allocator_type
· begin
· clear
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· count
· difference_type
· empty
· end
· equal_range
· erase
· find
· get_allocator
· insert
· iterator
· key_comp
· key_compare
· key_type
· lower_bound
· map
· mapped_type
· max_size
· operator[]
· pointer
· rbegin
· reference
· rend
· reverse_iterator
· size
· size_type
· swap
· upper_bound
· value_comp
· value_compare
· value_type
template<class Key, class Ty, class Pr = less<Key>,
class Alloc = allocator<pair<const Key, Ty> > >
class map {
public:
typedef Key key_type;
typedef Ty mapped_type;
typedef Pr key_compare;
typedef Alloc allocator_type;
typedef pair<const Key, Ty> value_type;
class value_compare;
typedef Alloc::pointer pointer;
typedef Alloc::const_pointer const_pointer;
typedef Alloc::reference reference;
typedef Alloc::const_reference const_reference;
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;
map();
explicit map(const Pr& pred);
map(const Pr& pred, const Alloc& al);
map(const map& right);
template<class InIt>
map(InIt first, InIt last);
template<class InIt>
map(InIt first, InIt last,
const Pr& pred);
template<class InIt>
map(InIt first, InIt last,
const Pr& pred, const Alloc& al);
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;
size_type size() const;
size_type max_size() const;
bool empty() const;
Alloc get_allocator() const;
mapped_type operator[](const Key& keyval);
pair<iterator, bool> insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
void clear();
void swap(map& right);
key_compare key_comp() const;
value_compare value_comp() const;
iterator find(const Key& keyval);
const_iterator find(const Key& keyval) const;
size_type count(const Key& keyval) const;
iterator lower_bound(const Key& keyval);
const_iterator lower_bound(const Key& keyval) const;
iterator upper_bound(const Key& keyval);
const_iterator upper_bound(const Key& keyval) const;
pair<iterator, iterator> equal_range(const Key& keyval);
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;
};The template class describes an object that controls a
varying-length sequence of elements of type
pair<const Key, Ty>.
The sequence is
ordered by the predicate
Pr.
The first element of each pair is the sort key and the
second is its associated value.
The sequence is represented in a way that permits lookup, insertion,
and removal of an arbitrary element with a number of operations
proportional to the logarithm of the number of elements
in the sequence (logarithmic time). Moreover, inserting an element
invalidates no iterators, and removing an element
invalidates only those iterators which point at the removed element.
The object orders the sequence it controls by calling a
stored function object of type Pr. You access
this stored object by calling the member function
key_comp().
Such a function object must impose a
strict weak ordering
on sort keys of type Key.
For any element X that precedes
Y in the sequence,
key_comp()(Y.first,
X.first) is false. (For the default function object
less<Key>,
sort keys never decrease in value.)
Unlike template class multimap,
an object of template class map ensures that
key_comp()(X.first, Y.first) is true.
(Each key is unique.)
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class Alloc. Such an allocator object must have
the same external interface as an object of template class
allocator.
Note that the stored allocator object is not copied when the container
object is assigned.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
const_iterator begin() const;
iterator begin();
The member function returns a bidirectional iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
void clear();
The member function calls
erase(
begin(),
end()).
typedef T1 const_iterator;
The type describes an object that can serve as a constant
bidirectional iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T1.
typedef Alloc::const_pointer const_pointer;
The type describes an object that can serve as a constant pointer
to an element of the controlled sequence.
typedef Alloc::const_reference const_reference;
The type describes an object that can serve as a constant reference
to an element of the controlled sequence.
typedef reverse_iterator<const_iterator>
const_reverse_iterator;The type describes an object that can serve as a constant reverse
bidirectional iterator for the controlled sequence.
size_type count(const Key& keyval) const;
The member function returns the number of elements
in the range
[lower_bound(keyval),
upper_bound(keyval)).
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 function returns a bidirectional iterator that points
just beyond the end of the sequence.
pair<iterator, iterator> equal_range(const Key& keyval);
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;The member function returns a pair of iterators X
such that X.first ==
lower_bound(keyval)
and X.second ==
upper_bound(keyval).
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
The first member function removes the element of the controlled
sequence pointed to by where.
The second member function removes the elements
in the interval [first, last).
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
the elements with sort keys in the range
[lower_bound(keyval),
upper_bound(keyval)).
It returns the number of elements it removes.
The member functions never throw an exception.
iterator find(const Key& keyval);
const_iterator find(const Key& keyval) const;
The member function returns an iterator that designates
the element in the controlled sequence whose sort key has
equivalent ordering
to keyval. If no such element exists,
the function returns
end().
Alloc get_allocator() const;
The member function returns the stored
allocator object.
pair<iterator, bool> insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);The first member function determines whether an element X
exists in the sequence whose key has
equivalent ordering
to that of val. If not, it creates such
an element X and initializes it with val.
The function then determines the iterator where that
designates X. If an insertion occurred, the function
returns pair(where, true).
Otherwise, it returns pair(where, false).
The second member function returns insert(val).first,
using where as a starting place within the controlled
sequence to search for the insertion point. (Insertion can occur
in amortized constant time, instead of logarithmic time, if the
insertion point immediately precedes or follows where.)
The third member function
inserts the sequence of element values,
for each where in the range [first, last),
by calling insert(*where).
If an exception is thrown during the
insertion of a single element, the container is left unaltered
and the exception is rethrown.
If an exception is thrown during the
insertion of multiple elements, the container is left in a stable
but unspecified state and the exception is rethrown.
typedef T0 iterator;
The type describes an object that can serve as a bidirectional
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T0.
key_compare key_comp() const;
The member function returns the stored function object that
determines the order of elements in the controlled sequence.
The stored object defines the member function:
bool operator()(const Key& left, const Key& right);
which returns true if left strictly
precedes right in the sort order.
typedef Pr key_compare;
The type describes a function object that can compare two
sort keys to determine the relative order of two
elements in the controlled sequence.
typedef Key key_type;
The type describes the sort key object stored in each
element of the controlled sequence.
iterator lower_bound(const Key& keyval);
const_iterator lower_bound(const Key& keyval) const;
The member function returns an iterator that designates the
earliest element X in the controlled sequence for which
key_comp()(X.
first, keyval) is
false.
If no such element exists, the function returns
end().
map();
explicit map(const Pr& pred);
map(const Pr& pred, const Alloc& al);
map(const map& right);
template<class InIt>
map(InIt first, InIt last);
template<class InIt>
map(InIt first, InIt last,
const Pr& pred);
template<class InIt>
map(InIt first, InIt last,
const Pr& pred, const Alloc& 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
right.get_allocator().
Otherwise, it is Alloc().
All constructors also store a function object that can later
be returned by calling
key_comp().
The function object is the argument pred, if present.
For the copy constructor, it is
right.key_comp()).
Otherwise, it is Pr().
The first three constructors specify an
empty initial controlled sequence. The fourth constructor specifies
a copy of the sequence controlled by right.
The last three constructors specify the sequence of element values
[first, last).
typedef Ty mapped_type;
The type is a synonym for the template parameter Ty.
size_type max_size() const;
The member function returns the length of the longest sequence that
the object can control.
Ty& operator[](const Key& keyval);
The member function effectively determines the iterator where
as the return value of
insert(
value_type(keyval, Ty()).
(It inserts an element with the specified key if no such element
exists.) It then returns a reference to
(*where).second.
typedef Alloc::pointer pointer;
The type describes an object that can serve as a pointer to an
element of the controlled sequence.
const_reverse_iterator rbegin() const;
reverse_iterator rbegin();
The member function returns a reverse bidirectional
iterator that points just
beyond the end of the controlled sequence. Hence, it designates the
beginning of the reverse sequence.
typedef Alloc::reference reference;
The type describes an object that can serve as a reference to an
element of the controlled sequence.
const_reverse_iterator rend() const;
reverse_iterator rend();
The member function returns a reverse bidirectional
iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, it designates the end of the reverse sequence.
typedef reverse_iterator<iterator> reverse_iterator;
The type describes an object that can serve as a reverse
bidirectional iterator for the controlled sequence.
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.
void swap(map& right);
The member function swaps the controlled sequences between
*this and right. If
get_allocator()
== right.get_allocator(), it does so in constant time,
it throws an exception only as a result of copying the stored
function object of type Pr, 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.
iterator upper_bound(const Key& keyval);
const_iterator upper_bound(const Key& keyval) const;
The member function returns an iterator that designates the
earliest element X in the controlled sequence for which
key_comp()(keyval,
X.first) is
true.
If no such element exists, the function returns
end().
value_compare value_comp() const;
The member function returns a function object that
determines the order of elements in the controlled sequence.
class value_compare
: public binary_function<value_type, value_type,
bool> {
public:
bool operator()(const value_type& left,
const value_type& right) const
{return (comp(left.first, right.first)); }
protected:
value_compare(key_compare pr)
: comp(pr) {}
key_compare comp;
};The type describes a function object that can compare the
sort keys in two elements to determine their relative order
in the controlled sequence. The function object stores an object
comp
of type key_compare.
The member function operator() uses this
object to compare the sort-key components of two element.
typedef pair<const Key, Ty> value_type;
The type describes an element of the controlled sequence.
allocator_type
· begin
· clear
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· count
· difference_type
· empty
· end
· equal_range
· erase
· find
· get_allocator
· insert
· iterator
· key_comp
· key_compare
· key_type
· lower_bound
· mapped_type
· max_size
· multimap
· rbegin
· reference
· rend
· reverse_iterator
· size
· size_type
· swap
· upper_bound
· value_comp
· value_compare
· value_type
template<class Key, class Ty, class Pr = less<Key>,
class Alloc = allocator<pair<const Key, Ty> > >
class multimap {
public:
typedef Key key_type;
typedef Ty mapped_type;
typedef Pr key_compare;
typedef Alloc allocator_type;
typedef pair<const Key, Ty> value_type;
class value_compare;
typedef Alloc::reference reference;
typedef Alloc::const_reference const_reference;
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;
multimap();
explicit multimap(const Pr& pred);
multimap(const Pr& pred, const Alloc& al);
multimap(const multimap& right);
template<class InIt>
multimap(InIt first, InIt last);
template<class InIt>
multimap(InIt first, InIt last,
const Pr& pred);
template<class InIt>
multimap(InIt first, InIt last,
const Pr& pred, const Alloc& al);
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;
size_type size() const;
size_type max_size() const;
bool empty() const;
Alloc get_allocator() const;
iterator insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
void clear();
void swap(multimap& right);
key_compare key_comp() const;
value_compare value_comp() const;
iterator find(const Key& keyval);
const_iterator find(const Key& keyval) const;
size_type count(const Key& keyval) const;
iterator lower_bound(const Key& keyval);
const_iterator lower_bound(const Key& keyval) const;
iterator upper_bound(const Key& keyval);
const_iterator upper_bound(const Key& keyval) const;
pair<iterator, iterator> equal_range(const Key& keyval);
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;
};The template class describes an object that controls a
varying-length sequence of elements of type
pair<const Key, Ty>.
The sequence is
ordered by the predicate
Pr.
The first element of each pair is the sort key and the
second is its associated value.
The sequence is represented in a way that permits lookup, insertion,
and removal of an arbitrary element with a number of operations
proportional to the logarithm of the number of elements
in the sequence (logarithmic time). Moreover, inserting an element
invalidates no iterators, and removing an element
invalidates only those iterators which point at the removed element.
The object orders the sequence it controls by calling a
stored function object of type Pr. You access
this stored object by calling the member function
key_comp().
Such a function object must impose a
strict weak ordering
on sort keys of type Key.
For any element X that precedes
Y in the sequence,
key_comp()(Y.first,
X.first) is false. (For the default function object
less<Key>,
sort keys never decrease in value.)
Unlike template class map,
an object of template class multimap does not ensure that
key_comp()(X.first, Y.first) is true.
(Keys need not be unique.)
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class Alloc. Such an allocator object must have
the same external interface as an object of template class
allocator.
Note that the stored allocator object is not copied when the container
object is assigned.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
const_iterator begin() const;
iterator begin();
The member function returns a bidirectional iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
void clear();
The member function calls
erase(
begin(),
end()).
typedef T1 const_iterator;
The type describes an object that can serve as a constant
bidirectional iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T1.
typedef Alloc::const_pointer const_pointer;
The type describes an object that can serve as a constant pointer
to an element of the controlled sequence.
typedef Alloc::const_reference const_reference;
The type describes an object that can serve as a constant reference
to an element of the controlled sequence.
typedef reverse_iterator<const_iterator>
const_reverse_iterator;The type describes an object that can serve as a constant reverse
bidirectional iterator for the controlled sequence.
size_type count(const Key& keyval) const;
The member function returns the number of elements
in the range
[lower_bound(keyval),
upper_bound(keyval)).
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 function returns a bidirectional iterator that points
just beyond the end of the sequence.
pair<iterator, iterator> equal_range(const Key& keyval);
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;The member function returns a pair of iterators X
such that X.first ==
lower_bound(keyval)
and X.second ==
upper_bound(keyval).
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
The first member function removes the element of the controlled
sequence pointed to by where.
The second member function removes the elements
in the range [first, last).
Both return an iterator that designates the first element remaining
beyond any elements removed, or
end() if no such element exists.
The third member removes
the elements with sort keys in the range
[lower_bound(keyval),
upper_bound(keyval)).
It returns the number of elements it removes.
The member functions never throw an exception.
iterator find(const Key& keyval);
const_iterator find(const Key& keyval) const;
The member function returns an iterator that designates
the earliest element in the controlled sequence whose sort key has
equivalent ordering
to keyval. If no such element exists,
the function returns
end().
Alloc get_allocator() const;
The member function returns the stored
allocator object.
iterator insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);The first member function inserts the element val
in the controlled sequence, then returns
the iterator that designates the inserted element.
The second member function returns insert(val),
using where as a starting place within the controlled
sequence to search for the insertion point. (Insertion can occur
in amortized constant time, instead of logarithmic time, if the
insertion point immediately precedes or follows where.)
The third member function
inserts the sequence of element values,
for each where in the range [first, last),
by calling insert(*where).
If an exception is thrown during the
insertion of a single element, the container is left unaltered
and the exception is rethrown.
If an exception is thrown during the
insertion of multiple elements, the container is left in a stable
but unspecified state and the exception is rethrown.
typedef T0 iterator;
The type describes an object that can serve as a bidirectional
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T0.
key_compare key_comp() const;
The member function returns the stored function object that
determines the order of elements in the controlled sequence.
The stored object defines the member function:
bool operator()(const Key& left, const Key& right);
which returns true if left strictly
precedes right in the sort order.
typedef Pr key_compare;
The type describes a function object that can compare two
sort keys to determine the relative order of two
elements in the controlled sequence.
typedef Key key_type;
The type describes the sort key object stored in each
element of the controlled sequence.
iterator lower_bound(const Key& keyval);
const_iterator lower_bound(const Key& keyval) const;
The member function returns an iterator that designates the
earliest element X in the controlled sequence for which
key_comp()(X.
first, keyval) is
false.
If no such element exists, the function returns
end().
typedef Ty mapped_type;
The type is a synonym for the template parameter Ty.
size_type max_size() const;
The member function returns the length of the longest sequence that
the object can control.
multimap();
explicit multimap(const Pr& pred);
multimap(const Pr& pred, const Alloc& al);
multimap(const multimap& right);
template<class InIt>
multimap(InIt first, InIt last);
template<class InIt>
multimap(InIt first, InIt last,
const Pr& pred);
template<class InIt>
multimap(InIt first, InIt last,
const Pr& pred, const Alloc& 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
right.get_allocator().
Otherwise, it is Alloc().
All constructors also store a function object that can later
be returned by calling
key_comp().
The function object is the argument pred, if present.
For the copy constructor, it is
right.key_comp()).
Otherwise, it is Pr().
The first three constructors specify an
empty initial controlled sequence. The fourth constructor specifies
a copy of the sequence controlled by right.
The last three constructors specify the sequence of element values
[first, last).
typedef Alloc::pointer pointer;
The type describes an object that can serve as a pointer to an
element of the controlled sequence.
const_reverse_iterator rbegin() const;
reverse_iterator rbegin();
The member function returns a reverse bidirectional
iterator that points just
beyond the end of the controlled sequence. Hence, it designates the
beginning of the reverse sequence.
typedef Alloc::reference reference;
The type describes an object that can serve as a reference to an
element of the controlled sequence.
const_reverse_iterator rend() const;
reverse_iterator rend();
The member function returns a reverse bidirectional
iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, it designates the end of the reverse sequence.
typedef reverse_iterator<iterator> reverse_iterator;
The type describes an object that can serve as a reverse
bidirectional iterator for the controlled sequence.
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.
void swap(multimap& right);
The member function swaps the controlled sequences between
*this and right. If
get_allocator()
== right.get_allocator(), it does so in constant time,
it throws an exception only as a result of copying the stored
function object of type Pr, 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.
iterator upper_bound(const Key& keyval);
const_iterator upper_bound(const Key& keyval) const;
The member function returns an iterator that designates the
earliest element right in the controlled sequence for which
key_comp()(keyval,
right.first) is
true.
If no such element exists, the function returns
end().
value_compare value_comp() const;
The member function returns a function object that
determines the order of elements in the controlled sequence.
class value_compare
: public binary_function<value_type, value_type,
bool> {
public:
bool operator()(const value_type& left,
const value_type& right) const
{return (comp(left.first, right.first)); }
protected:
value_compare(key_compare pr)
: comp(pr) {}
key_compare comp;
};The type describes a function object that can compare the
sort keys in two elements to determine their relative order
in the controlled sequence. The function object stores an object
comp
of type key_compare.
The member function operator() uses this
object to compare the sort-key components of two element.
typedef pair<const Key, Ty> value_type;
The type describes an element of the controlled sequence.
template<class Key, class Ty, class Pr, class Alloc>
bool operator!=(
const map <Key, Ty, Pr, Alloc>& left,
const map <Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator!=(
const multimap <Key, Ty, Pr, Alloc>& left,
const multimap <Key, Ty, Pr, Alloc>& right);The template function returns !(left == right).
template<class Key, class Ty, class Pr, class Alloc>
bool operator==(
const map <Key, Ty, Pr, Alloc>& left,
const map <Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator==(
const multimap <Key, Ty, Pr, Alloc>& left,
const multimap <Key, Ty, Pr, Alloc>& right);The first template function overloads operator==
to compare two objects of template class
map.
The second template function overloads operator==
to compare two objects of template class
multimap.
Both functions return
left.size() == right.size() &&
equal(left.
begin(), left.
end(), right.begin()).
template<class Key, class Ty, class Pr, class Alloc>
bool operator<(
const map <Key, Ty, Pr, Alloc>& left,
const map <Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator<(
const multimap <Key, Ty, Pr, Alloc>& left,
const multimap <Key, Ty, Pr, Alloc>& right);The first template function overloads operator<
to compare two objects of template class
map.
The second template function overloads operator<
to compare two objects of template class
multimap.
Both functions return
lexicographical_compare(left.
begin(), left.
end(), right.begin(), right.end(),
left.value_comp()).
template<class Key, class Ty, class Pr, class Alloc>
bool operator<=(
const map <Key, Ty, Pr, Alloc>& left,
const map <Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator<=(
const multimap <Key, Ty, Pr, Alloc>& left,
const multimap <Key, Ty, Pr, Alloc>& right);The template function returns !(right < left).
template<class Key, class Ty, class Pr, class Alloc>
bool operator>(
const map <Key, Ty, Pr, Alloc>& left,
const map <Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator>(
const multimap <Key, Ty, Pr, Alloc>& left,
const multimap <Key, Ty, Pr, Alloc>& right);The template function returns right < left.
template<class Key, class Ty, class Pr, class Alloc>
bool operator>=(
const map <Key, Ty, Pr, Alloc>& left,
const map <Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
bool operator!=(
const multimap <Key, Ty, Pr, Alloc>& left,
const multimap <Key, Ty, Pr, Alloc>& right);The template function returns !(left < right).
template<class Key, class Ty, class Pr, class Alloc>
void swap(
map <Key, Ty, Pr, Alloc>& left,
map <Key, Ty, Pr, Alloc>& right);
template<class Key, class Ty, class Pr, class Alloc>
void swap(
multimap <Key, Ty, Pr, Alloc>& left,
multimap <Key, Ty, Pr, Alloc>& right);The template function executes
left.swap(right).
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
56 - math
<math.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
57 - memory
<memory>
Include the STL
standard header <memory>
to define a class, an operator, and several templates that help
allocate and free objects.
namespace std {
template<class Ty>
class allocator;
template<>
class allocator<void>;
template<class FwdIt, class Ty>
class raw_storage_iterator;
template<class Ty>
class auto_ptr;
template<class Ty>
class auto_ptr_ref;
// TEMPLATE OPERATORS
template<class Ty>
bool operator==(allocator<Ty>& left,
allocator<Ty>& right);
template<class Ty>
bool operator!=(allocator<Ty>& left,
allocator<Ty>& right);
// TEMPLATE FUNCTIONS
template<class Ty>
pair<Ty *, ptrdiff_t>
get_temporary_buffer(ptrdiff_t count);
template<class Ty>
void return_temporary_buffer(Ty *pbuf);
template<class InIt, class FwdIt>
FwdIt uninitialized_copy(InIt first, InIt last,
FwdIt dest);
template<class FwdIt, class Ty>
void uninitialized_fill(FwdIt first, FwdIt last,
const Ty& val);
template<class FwdIt, class Size, class Ty>
void uninitialized_fill_n(FwdIt first, Size count,
const Ty& val);
};template<class Ty>
class allocator {
typedef size_t size_type;
typedef ptrdiff_t difference_type;
typedef Ty *pointer;
typedef const Ty *const_pointer;
typedef Ty& reference;
typedef const Ty& const_reference;
typedef Ty value_type;
pointer address(reference val) const;
const_pointer address(const_reference val) const;
template<class Other>
struct rebind;
allocator() throw();
template<class Other>
allocator(const allocator<Other>& right) throw();
template<class Other>
allocator& operator=(const allocator<Other>& right);
pointer allocate(size_type count, allocator<void>::const_pointer Other *hint = 0);
void deallocate(pointer ptr, size_type count);
void construct(pointer ptr, const Ty& val);
void destroy(pointer ptr);
size_type max_size() const throw();
};The template class describes an object that manages
storage allocation and freeing for arrays of objects of type Ty.
An object of class allocator is the default
allocator object
specified in the constructors for several
container template classes in the Standard C++ library.
Template class allocator supplies several
type definitions that are rather pedestrian.
They hardly seem worth defining.
But another class with the same members
might choose more interesting alternatives.
Constructing a container with an allocator object of such a class
gives individual control over allocation and freeing
of elements controlled by that container.
For example, an allocator object might allocate storage on a
private heap.
Or it might allocate storage on a
far heap, requiring nonstandard
pointers to access the allocated objects. Or it might specify,
through the type definitions it supplies, that elements be
accessed through special
accessor objects that manage
shared memory, or perform automatic
garbage collection.
Hence, a class that allocates storage using an allocator object
should use these types religiously for declaring pointer and
reference objects (as do the containers in the Standard C++ library).
Thus, an allocator defines the types (among others):
These types specify the form that pointers and references
must take for allocated elements.
(allocator::pointer is not necessarily
the same as Ty * for all allocator objects, even though
it has this obvious definition for class allocator.)
pointer address(reference val) const;
const_pointer address(const_reference val) const;
The member functions return the address of val,
in the form that pointers must take for allocated elements.
pointer allocate(size_type count, allocator<void>::const_pointer *hint = 0);
The member function allocates storage for
an array of count elements of type Ty, by calling
operator new(count).
It returns a pointer to the allocated object.
The hint argument helps some allocators
in improving locality of reference -- a valid choice
is the address of an object earlier allocated by the same allocator
object, and not yet deallocated. To supply no
hint, use a null pointer argument instead.
allocator() throw();
template<class Other>
allocator(const allocator<Other>& right) throw();The constructor does nothing. In general, however, an allocator object
constructed from another allocator object should compare equal to it
(and hence permit intermixing of object allocation and freeing between
the two allocator objects).
typedef const Ty *pointer;
The pointer type describes an object ptr that can
designate, via the expression *ptr, any const object
that an object of template class
allocator can allocate.
typedef const Ty& const_reference;
The reference type describes an object that can
designate any const object that an object of template class
allocator can allocate.
void construct(pointer ptr, const Ty& val);
The member function constructs an object of type Ty
at ptr by evaluating the placement
new expression new ((void *)ptr) Ty(val).
void deallocate(pointer ptr, size_type count);
The member function frees storage for
the array of count objects of type
Ty beginning at ptr, by calling
operator delete(ptr).
The pointer ptr must have been earlier returned by a call to
allocate for an allocator
object that compares equal to *this, allocating an array object
of the same size and type.
deallocate never throws an exception.
void destroy(pointer ptr);
The member function destroys the object
designated by ptr,
by calling the destructor ptr->Ty::~Ty().
typedef ptrdiff_t difference_type;
The signed integer type describes an object that can represent the
difference between the addresses of any two elements in a sequence
that an object of template class allocator can allocate.
size_type max_size() const throw();
The member function returns the length of the longest sequence
of elements of type Ty that an object of class
allocator might be able to allocate.
template<class Other>
allocator& operator=(const allocator<Other>& right);The template assignment operator does nothing.
In general, however, an allocator object
assigned to another allocator object should compare equal to it
(and hence permit intermixing of object allocation and freeing between
the two allocator objects).
typedef Ty *pointer;
The pointer type describes an object ptr that can
designate, via the expression *ptr, any object
that an object of template class
allocator can allocate.
template<class Other>
struct rebind {
typedef allocator<Other> other;
};The member template class defines the type
other.
Its sole purpose is to provide the type name allocator<Other>
given the type name allocator<Ty>.
For example, given an allocator object al of type
A, you can allocate an object of type
Other with the expression:
A::rebind<Other>::other(al).allocate(1, (Other *)0)
Or, you can simply name its pointer type by writing the type:
A::rebind<Other>::other::pointer
typedef Ty& reference;
The reference type describes an object that can
designate any object that an object of template class
allocator can allocate.
typedef size_t size_type;
The unsigned integer type describes an object that can represent
the length of any sequence that an object of template class
allocator can allocate.
typedef Ty value_type;
The type is a synonym for the template parameter Ty.
template<>
class allocator<void> {
typedef void *pointer;
typedef const void *const_pointer;
typedef void value_type;
template<class Other>
struct rebind;
allocator() throw();
template<class Other>
allocator(const allocator<Other>) throw();
template<class Other>
allocator<void>& operator=(const allocator<Other>);
};The class explicitly specializes template class
allocator for type void.
Its constructors and assignment operator behave the same as for the
template class, but it defines only the types
const_pointer,
pointer,
value_type,
and the nested template class
rebind.
template<class Ty>
class auto_ptr {
public:
typedef Ty element_type;
explicit auto_ptr(Ty *ptr = 0) throw();
auto_ptr(auto_ptr<Ty>& right) throw();
template<class Other>
auto_ptr(auto_ptr<Other>& right) throw();
auto_ptr(auto_ptr_ref<Ty> right) throw();
~auto_ptr();
template<class Other>
operator auto_ptr<Other>() throw();
template<class Other>
operator auto_ptr_ref<Other>() throw();
template<class Other>
auto_ptr<Ty>& operator=(auto_ptr<Other>& right) throw();
auto_ptr<Ty>& operator=(auto_ptr<Ty>& right) throw();
auto_ptr<Ty>& operator=(auto_ptr_ref<Ty> right) throw();
Ty& operator*() const throw();
Ty *operator->() const throw();
Ty *get() const throw();
Ty *release() const throw();
void reset(Ty *ptr = 0);
};The class describes an object that stores a pointer to an allocated object
myptr of type Ty *. The stored pointer must either be null or
designate an object allocated by a
new expression.
An object constructed with a non-null pointer owns the pointer.
It transfers ownership if its stored value is assigned to another
object. (It replaces the stored value after a transfer with a null pointer.)
The destructor for auto_ptr<Ty>
deletes the allocated object if it owns it.
Hence, an object of class auto_ptr<Ty>
ensures that an allocated object is automatically deleted when
control leaves a block, even via a thrown excepiton.
You should not construct two auto_ptr<Ty> objects
that own the same object.
You can pass an auto_ptr<Ty> object by value as an
argument to a function call. You can return such an object by value as well.
(Both operations depend on the implicit construction of intermediate objects
of class auto_ptr_ref<Ty>, by various
subtle conversion rules.) You cannot, however, reliably manage a sequence of
auto_ptr<Ty> objects with an STL
container.
explicit auto_ptr(Ty *ptr = 0) throw();
auto_ptr(auto_ptr<Ty>& right) throw();
auto_ptr(auto_ptr_ref<Ty> right) throw();
template<class Other>
auto_ptr(auto_ptr<Other>& right) throw();The first constructor stores ptr in myptr,
the stored pointer to the allocated object.
The second constructor transfers ownership of the
pointer stored in right, by storing
right.release()
in myptr.
The third constructor behaves the same as the second, except
that it stores right.ref.release() in myptr, where ref
is the reference stored in right.
The template constructor behaves the same as the second constructor,
provided that a pointer to Other can be implicitly converted
to a pointer to Ty.
~auto_ptr();
The destructor evaluates the expression delete myptr
to delete the object designated by the stored pointer.
typedef Ty element_type;
The type is a synonym for the template parameter Ty.
Ty *get() const throw();
The member function returns the stored pointer myptr.
template<class Other>
auto_ptr<Ty>& operator=(auto_ptr<Other>& right) throw();
auto_ptr<Ty>& operator=(auto_ptr<>& right) throw();
auto_ptr<Ty>& operator=(auto_ptr_ref<>& right) throw();The assignment evaluates the expression delete myptr,
but only if the stored pointer myptr
changes as a result of the assignment.
It then transfers ownership of the pointer designated by right, by storing
right.release() in myptr.
(The last assignment behaves as if right designates the reference
it stores.) The function returns *this.
Ty& operator*() const throw();
The indirection operator returns
*get().
Hence, the stored pointer must not be null.
Ty *operator->() const throw();
The selection operator returns
get(),
so that the expression ap->member behaves the same as
(ap.get())->member, where ap is an object
of class auto_ptr<Ty>.
Hence, the stored pointer must not be null, and Ty
must be a class, structure, or union type with a member member.
template<class Other>
operator auto_ptr<Other>() throw();The type cast operator returns
auto_ptr<Other>(*this).
template<class Other>
operator auto_ptr_ref<Other>() throw();The type cast operator returns
auto_ptr_ref<Other>(*this).
Ty *release() throw();
The member replaces the stored pointer myptr with a null pointer and
returns the previously stored pointer.
void reset(Ty *ptr = 0);
The member function evaluates the expression delete myptr,
but only if the stored pointer value myptr
changes as a result of function call.
It then replaces the stored pointer with ptr.
template<class Ty>
struct auto_ptr_ref {
};The class describes an object that stores a reference to an object of class
auto_ptr<Ty>. It is used as a helper
class for auto_ptr<Ty>. You should not have an occasion
to construct an auto_ptr_ref<Ty> object directly.
template<class Ty>
pair<Ty *, ptrdiff_t>
get_temporary_buffer(ptrdiff_t count);The template function allocates storage for a sequence of at most
count elements of type Ty, from an unspecified
source (which may well be the standard heap used by
operator new).
It returns a value pr, of type
pair<Ty *, ptrdiff_t>.
If the function allocates storage,
pr.first designates
the allocated storage and
pr.second
is the number of elements in the longest sequence the storage can hold.
Otherwise, pr.first is a null pointer.
In this implementation,
if a translator does not support member template functions, the template:
template<class Ty>
pair<Ty *, ptrdiff_t>
get_temporary_buffer(ptrdiff_t count);is replaced by:
template<class Ty>
pair<Ty *, ptrdiff_t>
get_temporary_buffer(ptrdiff_t count, Ty *);template<class Ty>
bool operator!=(allocator<Ty>& left,
allocator<Ty>& right) throw();The template operator returns false.
template<class Ty>
bool operator==(allocator<Ty>& left,
allocator<Ty>& right) throw();The template operator returns true. (Two allocator objects should
compare equal only if an object allocated through one can be deallocated
through the other. If the value of one object is determined from another
by assignment or by construction, the two object should compare equal.)
template<class FwdIt, class Ty>
class raw_storage_iterator
: public iterator<output_iterator_tag,
void, void, void, void> {
public:
typedef FwdIt iter_type;
typedef Ty element_type;
explicit raw_storage_iterator(FwdIt first);
raw_storage_iterator<FwdIt, Ty>& operator*();
raw_storage_iterator<FwdIt, Ty>&
operator=(const Ty& val);
raw_storage_iterator<FwdIt, Ty>& operator++();
raw_storage_iterator<FwdIt, Ty> operator++(int);
};The class describes an output iterator
that constructs objects of type Ty
in the sequence it generates. An object of class
raw_storage_iterator<FwdIt, Ty>
accesses storage through a forward iterator object,
of class FwdIt, that you specify when you construct
the object. For an object first of class FwdIt,
the expression &*first must designate unconstructed storage for
the next object (of type Ty) in the generated sequence.
typedef Ty element_type;
The type is a synonym for the template parameter Ty.
typedef FwdIt iter_type;
The type is a synonym for the template parameter FwdIt.
raw_storage_iterator<FwdIt, Ty>& operator*();
The indirection operator returns *this (so that
operator=(const
Ty&) can perform the actual store
in an expression such as *ptr = val).
raw_storage_iterator<FwdIt, Ty>& operator=(const Ty& val);
The assignment operator constructs the next object in the
output sequence using the stored iterator value first,
by evaluating the
placement new expression
new ((void *)&*first) Ty(val).
The function returns *this.
raw_storage_iterator<FwdIt, Ty>& operator++();
raw_storage_iterator<FwdIt, Ty> operator++(int);
The first (preincrement) operator increments the stored output iterator
object, then returns *this.
The second (postincrement) operator makes a copy of *this,
increments the stored output iterator object, then returns
the copy.
explicit raw_storage_iterator(FwdIt first);
The constructor stores first as the output iterator
object.
template<class Ty>
void return_temporary_buffer(Ty *pbuf);The template function frees the storage designated by pbuf,
which must be earlier allocated by a call to
get_temporary_buffer.
template<class InIt, class FwdIt>
FwdIt uninitialized_copy(InIt first, InIt last,
FwdIt dest);The template function effectively executes:
while (first != last)
new ((void *)&*dest++)
iterator_traits<InIt>::value_type(*first++);
return first;unless the code throws an exception. In that case, all
constructed objects are destroyed and the exception is rethrown.
template<class FwdIt, class Ty>
void uninitialized_fill(FwdIt first, FwdIt last,
const Ty& val);The template function effectively executes:
while (first != last)
new ((void *)&*first++)
iterator_traits<FwdIt>::value_type(val);unless the code throws an exception. In that case, all
constructed objects are destroyed and the exception is rethrown.
template<class FwdIt, class Size, class Ty>
void uninitialized_fill_n(FwdIt first, Size count,
const Ty& val);The template function effectively executes:
while (0 < count--)
new ((void *)&*first++)
iterator_traits<FwdIt>::value_type(val);unless the code throws an exception. In that case, all
constructed objects are destroyed and the exception is rethrown.
See also the
Table of Contents and the
Index.
Copyright © 1992-2006
by P.J. Plauger. All rights reserved.
58 - new
<new>
Include the standard header <new>
to define several types and functions that control allocation and
freeing of storage under program control.
Some of the functions declared in this header are
replaceable.
The implementation supplies a default version, whose behavior is
described in this document. A program can, however, define a
function with the same signature to replace the default version
at link time. The replacement version must satisfy the requirements
described in this document.
// DECLARATIONS
typedef void (*new_handler)();
class bad_alloc;
class nothrow_t;
extern const nothrow_t nothrow;
// FUNCTIONS
new_handler set_new_handler(new_handler pnew) throw();
// OPERATORS
void operator delete(void *ptr) throw(); // REPLACEABLE
void operator delete(void *, void *) throw();
void operator delete(void *ptr, // REPLACEABLE
const nothrow_t&) throw();
void operator delete[](void *ptr) throw(); // REPLACEABLE
void operator delete[](void *, void *) throw();
void operator delete[](void *ptr, // REPLACEABLE
const nothrow_t&) throw();
void *operator new(size_t count) // REPLACEABLE
throw(bad_alloc);
void *operator new(size_t count, // REPLACEABLE
const nothrow_t&) throw();
void *operator new(size_t count, void *ptr) throw();
void *operator new[](size_t count) // REPLACEABLE
throw(bad_alloc);
void *operator new[](size_t count, // REPLACEABLE
const nothrow_t&) throw();
void *operator new[](size_t count,
void *ptr) throw();
// END OF DECLARATIONSclass bad_alloc : public exception {
};The class describes an exception thrown to indicate that
an allocation request did not succeed. The value returned by
what()
is an implementation-defined
C string.
None of the member functions throw any exceptions.
typedef void (*new_handler)();
The type describes a pointer object that
designates a function suitable for use as a
new handler.
extern const nothrow_t nothrow;
The object is used as a function argument to
match the parameter type
nothrow_t.
class nothrow_t {};The class is used as a function parameter to
operator new to indicate that the function should
return a null pointer to report an allocation failure,
rather than throw an exception.
void operator delete(void *ptr) throw(); // REPLACEABLE
void operator delete(void *, void *) throw();
void operator delete(void *ptr, // REPLACEABLE
const nothrow_t&) throw();The first function is called by a
delete expression
to render the value of ptr invalid.
The program can define a function with this function signature that
replaces
the default version defined by the
Standard C++ library. The required behavior is to accept a value of
ptr that is null or that was returned by an earlier call to
operator new(size_t).
The default behavior for a null value of ptr is
to do nothing. Any other value of ptr must be a value returned
earlier by a call as described above.
The default behavior for such a non-null value of ptr is to
reclaim storage allocated by the earlier call.
It is unspecified under what conditions part or all
of such reclaimed storage is allocated by a subsequent call to
operator new(size_t),
or to any of
calloc(size_t),
malloc(size_t), or
realloc(void*, size_t).
The second function is called by a
placement
delete expression corresponding to a
new expression
of the form
new(size_t).
It does nothing.
The third function is called by a placement
delete expression corresponding to a
new expression of the form
new(size_t, const nothrow_t&).
The program can define a function with this function signature that
replaces
the default version defined by the
Standard C++ library. The required behavior is to accept a value of
ptr that is null or that was returned by an earlier call to
operator new(size_t).
The default behavior is to evaluate delete(ptr).
void operator delete[](void *ptr) throw(); // REPLACEABLE
void operator delete[](void *, void *) throw();
void operator delete[](void *ptr, // REPLACEABLE
const nothrow_t&) throw();The first function is called by a
delete[] expression
to render the value of ptr invalid.
The program can define a function with this function signature that
replaces
the default version defined by the
Standard C++ library.
The required behavior is to accept a value of ptr
that is null or that was returned by an earlier call to
operator new[](size_t).
The default behavior is to evaluate delete(ptr).
The second function is called by a
placement
delete[] expression corresponding to a
new[] expression of the form
new[](size_t).
It does nothing.
The third function is called by a placement
delete expression corresponding to a
new[] expression of the form
new[](size_t, const nothrow_t&).
The program can define a function with this function signature that
replaces
the default version defined by the
Standard C++ library. The required behavior is to accept a value of
ptr that is null or that was returned by an earlier call to
operator new[](size_t).
The default behavior is to call
operator delete(ptr, nothrow).
void *operator new(size_t count) throw(bad_alloc); // REPLACEABLE
void *operator new(size_t count, const nothrow_t&) throw(); // REPLACEABLE
void *operator new(size_t count, void *ptr) throw();
The first function is called by a
new expression
to allocate count bytes of storage
suitably aligned to represent any object of that size.
The program can define a function with this function signature that
replaces
the default version defined by the Standard C++ library.
The required behavior is to return a non-null pointer only
if storage can be allocated as requested. Each such allocation
yields a pointer to storage disjoint from any other allocated storage.
The order and contiguity of storage allocated by successive calls
is unspecified. The initial stored value is unspecified.
The returned pointer designates the start (lowest
byte address) of the allocated storage. If count is zero, the
value returned does not compare equal to any other value returned
by the function.
The default behavior is to execute a loop. Within the loop,
the function first attempts to allocate the requested storage. Whether
the attempt involves a call to
malloc(size_t)
is unspecified. If the attempt is successful, the function returns
a pointer to the allocated storage.
Otherwise, the function calls the designated
new handler. If the
called function returns, the loop repeats. The loop terminates when
an attempt to allocate the requested storage is successful or when
a called function does not return.
The required behavior of a
new handler
is to perform one of the following operations:
- make more storage available for allocation and then return
- call either
abort() or
exit(int) - throw an object of type
bad_alloc
The default behavior of a
new handler is to throw an object of type
bad_alloc. A null pointer designates the default
new handler.
The order and contiguity of storage allocated by successive
calls to operator new(size_t) is unspecified,
as are the initial values stored there.
The second function:
void *operator new(size_t count,
const nothrow_t&) throw();is called by a
placement
new expression
to allocate count bytes of storage
suitably aligned to represent any object of that size.
The program can define a function with this function signature that
replaces
the default version defined by the Standard C++ library.
The default behavior is to return
operator new(count) if that
function succeeds. Otherwise, it returns a null pointer.
The third function:
void *operator new(size_t count, void *ptr) throw();
is called by a
placement new expression,
of the form new (args) T.
Here, args consists of a single object pointer.
The function returns ptr.
void *operator new[](size_t count) throw(bad_alloc); // REPLACEABLE
void *operator new[](size_t count, // REPLACEABLE
const nothrow_t&) throw();
void *operator new[](size_t count, void *ptr) throw();The first function is called by a
new[] expression
to allocate count bytes of storage
suitably aligned to represent any array object of
that size or smaller. The program can define a function
with this function signature that
replaces
the default version defined by the Standard C++ library.
The required behavior is the same as for
operator new(size_t).
The default behavior is to return
operator new(count).
The second function is called by a
placement
new[] expression
to allocate count bytes of storage
suitably aligned to represent any array object of that size.
The program can define a function with this function signature that
replaces
the default version defined by the Standard C++ library.
The default behavior is to return
operator new(count) if that
function succeeds. Otherwise, it returns a null pointer.
The third function is called by a
placement
new[] expression,
of the form new (args) T[N].
Here, args consists of a single object pointer.
The function returns ptr.
new_handler set_new_handler(new_handler pnew) throw();
The function stores pnew in a static
new handler pointer
that it maintains, then returns the value previously
stored in the pointer. The new handler is used by
operator new(size_t).
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
59 - new2
<new.h>
Include the traditional header <new.h>
to effectively include the standard header
<new>.
#include <new>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
60 - numeric
<numeric>
Include the STL
standard header <numeric>
to define several template functions useful for computing numeric values.
The descriptions of these templates employ a number of
conventions
common to all algorithms.
namespace std {
template<class InIt, class Ty>
Ty accumulate(InIt first, InIt last, Ty val);
template<class InIt, class Ty, class Fn2>
Ty accumulate(InIt first, InIt last, Ty val, Fn2 func);
template<class InIt1, class InIt2, class Ty>
Ty inner_product(InIt1 first1, InIt1 last1,
Init2 first2, Ty val);
template<class InIt1, class InIt2, class Ty,
class Fn21, class Fn22>
Ty inner_product(InIt1 first1, InIt1 last1,
Init2 first2, Ty val, Fn21 func1, Fn22 func2);
template<class InIt, class OutIt>
OutIt partial_sum(InIt first, InIt last,
OutIt result);
template<class InIt, class OutIt, class Fn2>
OutIt partial_sum(InIt first, InIt last,
OutIt result, Fn2 func);
template<class InIt, class OutIt>
OutIt adjacent_difference(InIt first, InIt last,
OutIt result);
template<class InIt, class OutIt, class Fn2>
OutIt adjacent_difference(InIt first, InIt last,
OutIt result, Fn2 func);
};template<class InIt, class Ty>
Ty accumulate(InIt first, InIt last, Ty val);
template<class InIt, class Ty, class Fn2>
Ty accumulate(InIt first, InIt last, Ty val, Fn2 func);The first template function repeatedly replaces val
with val + *I, for each value of the InIt
iterator I in the interval [first, last).
It then returns val.
The second template function repeatedly replaces val
with func(val, *I), for each value of the InIt
iterator I in the interval [first, last).
It then returns val.
template<class InIt, class OutIt>
OutIt adjacent_difference(InIt first, InIt last,
OutIt result);
template<class InIt, class OutIt, class Fn2>
OutIt adjacent_difference(InIt first, InIt last,
OutIt result, Fn2 func);The first template function stores successive values beginning
at result, for each value of the InIt
iterator I in the interval [first, last).
The first value val stored (if any)
is *I. Each subsequent value
stored is *I - val, and val is replaced
by *I.
The function returns result incremented
last - first times.
The second template function stores successive values beginning
at result, for each value of the InIt
iterator I in the interval [first, last).
The first value val stored (if any)
is *I. Each subsequent value
stored is func(*I, val), and val is replaced
by *I.
The function returns result incremented
last - first times.
template<class InIt1, class InIt2, class Ty>
Ty inner_product(InIt1 first1, InIt1 last1,
Init2 first2, Ty val);
template<class InIt1, class InIt2, class Ty,
class Fn21, class Fn22>
Ty inner_product(InIt1 first1, InIt1 last1,
Init2 first2, Ty val, Fn21 func1, Fn22 func2);The first template function repeatedly replaces val
with val + (*I1 * *I2), for each value of the InIt1
iterator I1 in the interval [first1, last2).
In each case, the InIt2 iterator I2 equals
first2 + (I1 - first1).
The function returns val.
The second template function repeatedly replaces val
with func1(val, func2(*I1, *I2)),
for each value of the InIt1
iterator I1 in the interval [first1, last2).
In each case, the InIt2 iterator I2 equals
first2 + (I1 - first1).
The function returns val.
template<class InIt, class OutIt>
OutIt partial_sum(InIt first, InIt last,
OutIt result);
template<class InIt, class OutIt, class Fn2>
OutIt partial_sum(InIt first, InIt last,
OutIt result, Fn2 func);The first template function stores successive values beginning
at result, for each value of the InIt
iterator I in the interval [first, last).
The first value val stored (if any)
is *I. Each subsequent value val
stored is val + *I.
The function returns result incremented
last - first times.
The second template function stores successive values beginning
at result, for each value of the InIt
iterator I in the interval [first, last).
The first value val stored (if any)
is *I. Each subsequent value val
stored is func(val, *I).
The function returns result incremented
last - first times.
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
61 - ostream
<ostream>
// DECLARATIONS
class ostream;
// INSERTERS
ostream&
operator<<(ostream& ostr, const char *str);
ostream&
operator<<(ostream& ostr, char ch);
ostream&
operator<<(ostream& ostr, const signed char *str);
ostream&
operator<<(ostream& ostr, signed char ch);
ostream&
operator<<(ostream& ostr, const unsigned char *str);
ostream&
operator<<(ostream& ostr, unsigned char ch);
// MANIPULATORS
ostream& endl(ostream& ostr);
ostream& ends(ostream& ostr);
ostream& flush(ostream& ostr);
// END OF DECLARATIONSInclude the iostreams
standard header <ostream> to define
class ostream,
which mediates insertions for the iostreams.
The header also defines several related
manipulators.
(This header is typically included for you by another
of the iostreams headers. You seldom have occasion to include it
directly.)
ostream
· flush
· operator<<
· put
· seekp
· sentry
· tellp
· write
class ostream : public ios {
public:
explicit ostream(streambuf *strbuf);
class sentry;
virtual ~ostream();
ostream& operator<<(
ostream& (*pfn)(ostream&));
ostream& operator<<(
ios_base;& (*pfn)(ios_base&));
ostream& operator<<(
ios& (*pfn)(ios&));
ostream& operator<<(
streambuf *strbuf);
ostream& operator<<(bool val);
ostream& operator<<(short val);
ostream& operator<<(unsigned short val);
ostream& operator<<(int val);
ostream& operator<<(unsigned int val);
ostream& operator<<(long val);
ostream& operator<<(unsigned long val);
ostream& operator<<(float val);
ostream& operator<<(double val);
ostream& operator<<(long double val);
ostream& operator<<(const void *val);
ostream& put(char_type ch);
ostream& write(char_type *str, streamsize count);
ostream& flush();
pos_type tellp();
ostream& seekp(pos_type pos);
ostream& seekp(off_type off,
ios_base::seek_dir way);
};The class describes an object that controls
insertion of elements and encoded objects into a
stream buffer
with elements of type char, also known as
char_type, whose
character traits are determined by the
class char_traits,
also known as
traits_type.
Most of the member functions that overload
operator<<
are formatted output functions.
They follow the pattern:
iostate state = goodbit;
const sentry ok(*this);
if (ok)
{try
{<convert and insert elements
accumulate flags in state> }
catch (...)
{try
{setstate(badbit); }
catch (...)
{}
if ((exceptions() & badbit) != 0)
throw; }}
width(0); // except for operator<<(Elem)
setstate(state);
return (*this);Two other member functions are
unformatted output functions.
They follow the pattern:
iostate state = goodbit;
const sentry ok(*this);
if (!ok)
state |= badbit;
else
{try
{<obtain and insert elements
accumulate flags in state> }
catch (...)
{try
{setstate(badbit); }
catch (...)
{}
if ((exceptions() & badbit) != 0)
throw; }}
setstate(state);
return (*this);Both groups of functions call
setstate(badbit)
if they encounter a failure while inserting elements.
An object of class ostream stores only
a public base object of class
ios
explicit ostream(streambuf *strbuf);
The constructor initializes the base class by calling
init(strbuf).
ostream& flush();
If rdbuf() is
not a null pointer, the function calls
rdbuf()->pubsync().
If that returns -1, the function calls
setstate(badbit).
It returns *this.
ostream& operator<<(
ostream& (*pfn)(ostream&));
ostream& operator<<(
ios_base& (*pfn)(ios_base&));
ostream& operator<<(
ios& (*pfn)(ios&));
ostream& operator<<(
streambuf *strbuf);
ostream& operator<<(bool val);
ostream& operator<<(short val);
ostream& operator<<(unsigned short val);
ostream& operator<<(int val);
ostream& operator<<(unsigned int val);
ostream& operator<<(long val);
ostream& operator<<(unsigned long val);
ostream& operator<<(float val);
ostream& operator<<(double val);
ostream& operator<<(long double val);
ostream& operator<<(const void *val);The first member function ensures that an expression of the
form ostr << endl calls
endl(ostr), then returns *this.
The second and third functions ensure that other
manipulators,
such as hex behave
similarly. The remaining functions are all
formatted output functions.
The function:
ostream& operator<<(
streambuf *strbuf);extracts elements from strbuf,
if strbuf is not a null pointer, and inserts them.
If strbuf is a null pointer, the function calls
setstate(badbit).
Otherwise, extraction stops on end-of-file,
or if an extraction throws an exception (which is rethrown).
It also stops, without extracting the element in question,
if an insertion fails. If the function inserts no elements, or
if an extraction throws an exception, the function calls
setstate(failbit).
In any case, the function returns *this.
All the remaining functions generate an output field and insert it.
The output output field is generated by the same rules used by the
print functions
for generating a series of char elements to a file.
Where a print function pads a field with either spaces or the digit
0, however, the function instead uses
fill.
The equivalent
print conversion
specification is determined as described for each function below.
Padding occurs only if
the minimum number of elements N required to
specify the output field is less than
width().
Such padding consists of a sequence of N - width() copies of
fill().
Padding then occurs as follows:
- If
flags() &
ios_base::adjustfield ==
ios_base::left,
the flag - is prepended to the conversion specification.
(Padding occurs after the generated text.) - If
flags() & ios_base::adjustfield ==
ios_base::internal,
the flag 0 is prepended. (For a numeric output field,
padding occurs where the print functions pad with 0.) - Otherwise, no additional flag is prepended.
(Padding occurs before the generated sequence.)
The function:
ostream& operator<<(bool val);
converts val to a
boolean output field
and inserts it as an array of char, with
a conversion specifier of s.
A boolean output field takes one of two forms.
If flags() &
ios_base::boolalpha
is false, the generated sequence is either 0 (for false)
or 1 (for true).
Otherwise, the generated sequence is either
false (for false), or
true (for true). The
function then calls width(0) to reset the
field width to zero.
The function returns *this.
The functions:
ostream& operator<<(short val);
ostream& operator<<(unsigned short val);
ostream& operator<<(int val);
ostream& operator<<(unsigned int val);
ostream& operator<<(long val);
ostream& operator<<(unsigned long val);
ostream& operator<<(const void *val);
each convert val to an
integer output field
and inserts it. The equivalent
print conversion
specification is determined as follows:
- If
flags() &
ios_base::basefield ==
ios_base::oct, the
conversion specification is lo and the converted value is
(long)val. - If
flags() & ios_base::basefield ==
ios_base::hex, the
conversion specification is lx and the converted value is
(unsigned long)val. - Otherwise, the conversion specification is
ld
and the converted value is (long)val.
If width()
is nonzero, a field width of this value is prepended. The
function then calls width(0) to reset the
field width to zero.
Finally:
- If
flags() &
ios_base::showpos
is nonzero, the flag + is prepended to the conversion
specification. - If
flags() &
ios_base::showbase
is nonzero, the flag # is prepended to the conversion
specification.
The function returns *this.
The functions:
ostream& operator<<(float val);
ostream& operator<<(double val);
ostream& operator<<(long double val);
each convert val to a
floating-point output field
and insert it.
A period (.) separates the integer digits from the
fraction digits.
The equivalent print conversion specification is determined as follows:
- If
flags() &
ios_base::floatfield ==
ios_base::fixed, the
conversion specification is f. - If
flags() & ios_base::floatfield ==
ios_base::scientific, the
conversion specification is e.
If flags() &
ios_base::uppercase
is nonzero, e is replaced with E. - Otherwise, the conversion specification is
g.
If flags() & ios_base::uppercase
is nonzero, g is replaced with G.
If val has type double, the function prepends l
to the conversion specification. If val has type long double,
it prepends L to the conversion specification.
If flags() & ios_base::fixed is nonzero, or if
precision()
is greater than zero, a precision with the value
precision() is prepended to the conversion specification.
Any padding behaves the same
as for an integer output field.
If width()
is nonzero, a field width of this value is prepended. The
function then calls width(0) to reset the
field width to zero. Finally:
- If
flags() &
ios_base::showpos
is nonzero, the flag + is prepended to the conversion
specification. - If
flags() &
ios_base::showpoint
is nonzero, the flag # is prepended to the conversion
specification.
ostream& put(char_type ch);
The unformatted output function
inserts the element ch. It returns *this.
ostream& seekp(pos_type pos);
ostream& seekp(off_type off,
ios_base::seek_dir way);If fail() is false,
the first member function calls
newpos = rdbuf()->
pubseekpos(pos,
out),
for some pos_type temporary object newpos.
If fail() is false, the second function calls
newpos = rdbuf()->
pubseekoff(off, way,
out).
In either case, if (off_type)newpos == (off_type)(-1)
(the positioning operation fails) the function calls
istr.setstate(failbit).
Both functions return *this.
class sentry {
public:
explicit sentry(ostream& ostr);
operator bool() const;
~sentry();
private:
sentry(const sentry&); // not defined
sentry& operator=(const sentry&); // not defined
bool status;
};The nested class describes an object whose declaration structures the
formatted output functions
and the
unformatted output functions.
If ostr.good() is true, and
ostr.tie() is not
a null pointer, the constructor calls
ostr.tie->flush().
The constructor then stores the value returned by ostr.good()
in status.
A later call to operator bool() delivers this stored value.
If
flags() &
unitbuf is nonzero,
the destructor calls
flush().
pos_type tellp();
If fail() is false,
the member function returns
rdbuf()->
pubseekoff(0,
cur,
in).
Otherwise, it returns pos_type(-1).
ostream& write(const char_type *str, streamsize count);
The unformatted output function
inserts the sequence of count elements
beginning at str.
ostream endl(ostream& ostr);
The manipulator calls
ostr.put(ostr.
widen('\n')),
then calls
ostr.flush().
It returns ostr.
ostream& ends(ostream& ostr);
The manipulator calls
ostr.put(Elem('\0')).
It returns ostr.
ostream& flush(ostream& ostr);
The manipulator calls
ostr.flush().
It returns ostr.
ostream&
operator<<(ostream& ostr, const char *str);
ostream&
operator<<(ostream& ostr, char ch);
ostream&
operator<<(ostream& ostr, const signed char *str);
ostream&
operator<<(ostream& ostr, signed char ch);
ostream&
operator<<(ostream& ostr, const unsigned char *str);
ostream&
operator<<(ostream& ostr, unsigned char ch);All of these functions are
formatted output functions.
The function:
ostream&
operator<<(ostream& ostr, const char *str);determines the length N =
traits_type::length(str)
of the sequence beginning at str, and inserts the sequence. If
N < ostr.width(),
then the function also inserts a repetition of ostr.width() - N
fill characters.
The repetition precedes the sequence if
(ostr.flags() &
adjustfield !=
left.
Otherwise, the repetition follows the sequence.
The function returns ostr.
The function:
ostream&
operator<<(ostream& ostr, char ch);inserts the element ch. If
1 < ostr.width(),
then the function also inserts a repetition of ostr.width() - 1
fill characters.
The repetition precedes the sequence if
(ostr.flags() &
adjustfield !=
left.
Otherwise, the repetition follows the sequence.
It returns ostr.
The function:
ostream&
operator<<(ostream& ostr, const signed char *str);returns ostr << (const char *)str.
The function:
ostream&
operator<<(ostream& ostr, signed char ch);returns ostr << (char)ch.
The function:
ostream&
operator<<(ostream& ostr, const unsigned char *str);returns ostr << (const char *)str.
The function:
ostream&
operator<<(ostream& ostr, unsigned char ch);returns ostr << (char)ch.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
62 - preproc
Preprocessing
The translator processes each source file in a series of phases.
Preprocessing constitutes the earliest phases, which produce a
translation unit.
Preprocessing treats a source file as a sequence of
text lines. You can specify
directives and
macros
that insert, delete, and alter source text.
This document describes briefly just those aspects
of preprocessing most relevant to the use of the Standard C library:
The macro __FILE__
expands to a
string literal
that gives the remembered
filename
of the current source file. You can alter the value of this macro
by writing a
line directive.
The macro __LINE__
expands to a decimal integer constant
that gives the remembered line number within the current source file.
You can alter the value of this macro by writing a
line directive.
A define directive
defines a name as a macro.
Following the directive name define,
you write one of two forms:
- a name not immediately followed by a left parenthesis,
followed by any sequence of preprocessing tokens -- to define a
macro without parameters
- a name immediately followed by a left parenthesis with no
intervening white space, followed by zero or more distinct parameter
names separated by commas, followed by a right parenthesis, followed
by any sequence of preprocessing tokens -- to define a macro with
as many parameters as names that you write inside the parentheses
You can selectively skip groups of lines
within source files by writing an
if directive,
or one of the other conditional directives,
ifdef or ifndef.
You follow the conditional directive by the first group of lines
that you want to selectively skip.
Zero or more elif directives follow this first group of lines,
each followed by a group of lines that you want to selectively skip.
An optional else directive follows all groups of lines controlled
by elif directives, followed by the last group of lines you want
to selectively skip.
The last group of lines ends with an endif directive.
At most one group of lines is retained in the translation unit --
the one immediately preceded by a directive whose
#if expression has a nonzero value.
For the directive:
#ifdef X
this expression is defined (X), and for the directive:
#ifndef X
this expression is !defined (X).
A #if expression is a
conditional expression that the preprocessor evaluates.
You can write only
integer constant expressions, with the following
additional considerations:
- The expression
defined X, or defined (X),
is replaced by 1 if X is defined as a macro, otherwise 0. - You cannot write the
sizeof
or type cast operators. (The translator expands all macro
names, then replaces each remaining name with 0,
before it recognizes keywords.)
- The translator may be able to represent a broader range of integers
than the target environment.
- The translator represents type int the same as long,
and unsigned int the same as unsigned long.
- The translator can translate character constants to a set of
code values different from the set for the target environment.
An include directive
includes the contents of a
standard header
or another source file in a translation unit. The contents of
the specified standard header or source file replace the include
directive. Following the directive name include,
write one of the following:
- a standard header name between angle brackets
- a filename between double quotes
- any other form that expands to one of the two previous forms
after macro replacement
A line directive alters
the source line number and filename used by the predefined macros
__FILE__ and
__FILE__.
Following the directive name line,
write one of the following:
- a decimal integer (giving the new line number of the line following)
- a decimal integer as before, followed by a string literal (giving
the new line number and the new source filename)
- any other form that expands to one of the two previous forms
after macro replacement
Preprocessing translates each source file in a series of distinct
phases.
The first few phases of translation:
terminate each line with a newline character (NL),
convert trigraphs to their single-character equivalents,
and concatenate each line ending in a backslash (\)
with the line following. Later phases process
include directives,
expand macros, and so on to produce a
translation unit.
The translator combines separate translation units,
with contributions as needed from the
Standard C library, at
link time, to form the executable
program.
An undef directive
removes a macro definition. You might want to
remove a macro definition so that you can define it differently with
a define directive or to unmask any other meaning given to
the name. The name whose definition you want to remove
follows the directive name undef.
If the name is not currently defined as a macro,
the undef directive has no effect.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
63 - queue
<queue>
Include the STL
standard header <queue>
to define the template classes priority_queue and
queue, and several supporting templates.
namespace std {
template<class Ty, class Container>
class queue;
template<class Ty, class Container, class Pr>
class priority_queue;
// TEMPLATE FUNCTIONS
template<class Ty, class Container>
bool operator==(const queue<Ty, Container>& left,
const queue<Ty, Container>&);
template<class Ty, class Container>
bool operator!=(const queue<Ty, Container>& left,
const queue<Ty, Container>&);
template<class Ty, class Container>
bool operator<(const queue<Ty, Container>& left,
const queue<Ty, Container>&);
template<class Ty, class Container>
bool operator>(const queue<Ty, Container>& left,
const queue<Ty, Container>&);
template<class Ty, class Container>
bool operator<=(const queue<Ty, Container>& left,
const queue<Ty, Container>&);
template<class Ty, class Container>
bool operator>=(const queue<Ty, Container>& left,
const queue<Ty, Container>&);
};template<class Ty, class Container>
bool operator!=(const queue <Ty, Container>& left,
const queue <Ty, Container>& right);The template function returns !(left == right).
template<class Ty, class Container>
bool operator==(const queue <Ty, Container>& left,
const queue <Ty, Container>& right);The template function overloads operator== to compare
two objects of template class
queue. The function returns
left.c == right.c.
template<class Ty, class Container>
bool operator<(const queue <Ty, Container>& left,
const queue <Ty, Container>& right);The template function overloads operator< to compare
two objects of template class
queue. The function returns
left.c < right.c.
template<class Ty, class Container>
bool operator<=(const queue <Ty, Container>& left,
const queue <Ty, Container>& right);The template function returns !(right < left).
template<class Ty, class Container>
bool operator>(const queue <Ty, Container>& left,
const queue <Ty, Container>& right);The template function returns right < left.
template<class Ty, class Container>
bool operator>=(const queue <Ty, Container>& left,
const queue <Ty, Container>& right);The template function returns !(left < right).
template<class Ty,
class Container = vector<Ty>,
class Pr = less<typename Container::value_type> >
class priority_queue {
public:
typedef Container container_type;
typedef typename Container::value_type value_type;
typedef typename Container::size_type size_type;
priority_queue();
explicit priority_queue(const Pr& pred);
priority_queue(const Pr& pred,
const container_type& cont);
priority_queue(const priority_queue& right);
template<class InIt>
priority_queue(InIt first, InIt last);
template<class InIt>
priority_queue(InIt first, InIt last,
const Pr& pred);
template<class InIt>
priority_queue(InIt first, InIt last,
const Pr& pred, const container_type& cont);
bool empty() const;
size_type size() const;
const value_type& top() const;
void push(const value_type& val);
void pop();
protected:
Container c;
Pr comp;
};The template class describes an object that controls a
varying-length sequence of elements.
The object allocates and frees storage for the sequence it controls
through a protected object named
c,
of class Container.
The type Ty of elements in the controlled sequence must match
value_type.
The sequence is ordered using a protected object named
comp.
After each insertion or removal of the top element (at position zero),
for the iterators P0 and Pi
designating elements at positions 0
and I, comp(*P0, *Pi) is false.
(For the default template parameter
less<typename Container::value_type>
the top element of the sequence compares largest, or highest priority.)
An object of class Container must supply
random-access iterators and
several public members defined the same as for
deque and
vector
(both of which are suitable candidates for class Container).
The required members are:
typedef Ty value_type;
typedef T0 size_type;
typedef T1 iterator;
Container();
template<class InIt>
Container(InIt first, InIt last);
template<class InIt>
void insert(iterator where, InIt first, InIt last);
iterator begin();
iterator end();
bool empty() const;
size_type size() const;
const value_type& front() const;
void push_back(const value_type& val);
void pop_back();Here, T0 and T1 are unspecified types
that meet the stated requirements.
typedef typename Container::container_type container_type;
The type is a synonym for the template parameter Container.
bool empty() const;
The member function returns true for an empty controlled sequence.
void pop();
The member function removes the first element of the
controlled sequence, which must be non-empty, then reorders it.
priority_queue();
explicit priority_queue(const Pr& pred);
priority_queue(const Pr& pred,
const container_type& cont);
priority_queue(const priority_queue& right);
template<class InIt>
priority_queue(InIt first, InIt last);
template<class InIt>
priority_queue(InIt first, InIt last,
const Pr& pred);
template<class InIt>
priority_queue(InIt first, InIt last,
const Pr& pred, const container_type& cont);All constructors with an argument cont
initialize the stored object with
c(cont).
The remaining constructors initialize the stored object with
c, to specify an
empty initial controlled sequence.
The last three constructors then call
c.insert(c.end(), first, last).
All constructors also store a function object in
comp.
The function object comp is the argument pred, if present.
For the copy constructor, it is right.comp.
Otherwise, it is Pr().
A non-empty initial controlled sequence is then ordered by calling
make_heap(c.begin(),
c.end(), comp).
void push(const Ty& val);
The member function inserts an element with value val
at the end of the controlled sequence, then reorders it.
size_type size() const;
The member function returns the length of the controlled sequence.
typedef typename Container::size_type size_type;
The type is a synonym for Container::size_type.
const value_type& top() const;
The member function returns a reference to the first (highest priority)
element of the controlled sequence, which must be non-empty.
typedef typename Container::value_type value_type;
The type is a synonym for Container::value_type.
template<class Ty,
class Container = deque<Ty> >
class queue {
public:
typedef Container container_type;
typedef typename Container::value_type value_type;
typedef typename Container::size_type size_type;
queue();
explicit queue(const container_type& cont);
bool empty() const;
size_type size() const;
value_type& back();
const value_type& back() const;
value_type& front();
const value_type& front() const;
void push(const value_type& val);
void pop();
protected:
Container c;
};The template class describes an object that controls a
varying-length sequence of elements.
The object allocates and frees storage for the sequence it controls
through a protected object named
c,
of class Container.
The type Ty of elements in the controlled sequence must match
value_type.
An object of class Container must supply
several public members defined the same as for
deque and
list
(both of which are suitable candidates for class Container).
The required members are:
typedef Ty value_type;
typedef T0 size_type;
Container();
bool empty() const;
size_type size() const;
value_type& front();
const value_type& front() const;
value_type& back();
const value_type& back() const;
void push_back(const value_type& val);
void pop_front();
bool operator==(const Container& cont) const;
bool operator!=(const Container& cont) const;
bool operator<(const Container& cont) const;
bool operator>(const Container& cont) const;
bool operator<=(const Container& cont) const;
bool operator>=(const Container& cont) const;Here, T0 is an unspecified type
that meets the stated requirements.
value_type& back();
const value_type& back() const;
The member function returns a reference to the last element of the
controlled sequence, which must be non-empty.
typedef Container container_type;
The type is a synonym for the template parameter Container.
bool empty() const;
The member function returns true for an empty controlled sequence.
value_type& front();
const value_type& front() const;
The member function returns a reference to the first element of the
controlled sequence, which must be non-empty.
void pop();
The member function removes the first element of the
controlled sequence, which must be non-empty.
void push(const Ty& val);
The member function inserts an element with value val
at the end of the controlled sequence.
queue();
explicit queue(const container_type& cont);
The first constructor initializes the stored object with
c(), to specify an
empty initial controlled sequence.
The second constructor initializes the stored object with
c(cont), to specify an
initial controlled sequence that is a copy of the sequence controlled
by cont.
size_type size() const;
The member function returns the length of the controlled sequence.
typedef typename Container::size_type size_type;
The type is a synonym for Container::size_type.
typedef typename Container::value_type value_type;
The type is a synonym for Container::value_type.
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
64 - set
<set>
Include the STL
standard header <set> to define the
container
template classes set and
multiset, and their supporting
templates.
namespace std {
template<class Key, class Pr, class Alloc>
class set;
template<class Key, class Pr, class Alloc>
class multiset;
// TEMPLATE FUNCTIONS
template<class Key, class Pr, class Alloc>
bool operator==(
const set<Key, Pr, Alloc>& left,
const set<Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator==(
const multiset<Key, Pr, Alloc>& left,
const multiset<Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator!=(
const set<Key, Pr, Alloc>& left,
const set<Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator!=(
const multiset<Key, Pr, Alloc>& left,
const multiset<Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator<(
const set<Key, Pr, Alloc>& left,
const set<Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator<(
const multiset<Key, Pr, Alloc>& left,
const multiset<Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator>(
const set<Key, Pr, Alloc>& left,
const set<Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator>(
const multiset<Key, Pr, Alloc>& left,
const multiset<Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator<=(
const set<Key, Pr, Alloc>& left,
const set<Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator<=(
const multiset<Key, Pr, Alloc>& left,
const multiset<Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator>=(
const set<Key, Pr, Alloc>& left,
const set<Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator>=(
const multiset<Key, Pr, Alloc>& left,
const multiset<Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
void swap(
set<Key, Pr, Alloc>& left,
set<Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
void swap(
multiset<Key, Pr, Alloc>& left,
multiset<Key, Pr, Alloc>& right);
};
allocator_type
· begin
· clear
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· count
· difference_type
· empty
· end
· equal_range
· erase
· find
· get_allocator
· insert
· iterator
· key_comp
· key_compare
· key_type
· lower_bound
· max_size
· multiset
· pointer
· rbegin
· reference
· rend
· reverse_iterator
· size
· size_type
· swap
· upper_bound
· value_comp
· value_compare
· value_type
template<class Key, class Pr = less<Key>,
class Alloc = allocator<Key> >
class multiset {
public:
typedef Key key_type;
typedef Pr key_compare;
typedef Key value_type;
typedef Pr value_compare;
typedef Allov allocator_type;
typedef Alloc::pointer pointer;
typedef Alloc::const_pointer const_pointer;
typedef Alloc::reference reference;
typedef Alloc::const_reference const_reference;
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;
multiset();
explicit multiset(const Pr& pred);
multiset(const Pr& pred, const Alloc& al);
multiset(const multiset& right);
template<class InIt>
multiset(InIt first, InIt last);
template<class InIt>
multiset(InIt first, InIt last,
const Pr& pred);
template<class InIt>
multiset(InIt first, InIt last,
const Pr& pred, const Alloc& al);
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;
size_type max_size() const;
bool empty() const;
Alloc get_allocator() const;
iterator insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
void clear();
void swap(multiset& right);
key_compare key_comp() const;
value_compare value_comp() const;
iterator find(const Key& keyval);
const_iterator find(const Key& keyval) const;
size_type count(const Key& keyval) const;
iterator lower_bound(const Key& keyval);
const_iterator lower_bound(const Key& keyval) const;
iterator upper_bound(const Key& keyval);
const_iterator upper_bound(const Key& keyval) const;
pair<iterator, iterator> equal_range(const Key& keyval);
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;
};The template class describes an object that controls a
varying-length sequence of elements of type
const Key.
The sequence is
ordered by the predicate
Pr.
Each element serves as both a sort key and a value.
The sequence is represented in a way that permits lookup, insertion,
and removal of an arbitrary element with a number of operations
proportional to the logarithm of the number of elements
in the sequence (logarithmic time). Moreover, inserting an element
invalidates no iterators, and removing an element
invalidates only those iterators which point at the removed element.
The object orders the sequence it controls by calling a
stored function object of type Pr. You access
this stored object by calling the member function
key_comp().
Such a function object must impose a
strict weak ordering
on sort keys of type Key.
For any element X that precedes
Y in the sequence,
key_comp()(Y, X) is false. (For the default function object
less<Key>,
sort keys never decrease in value.)
Unlike template class set,
an object of template class multiset does not ensure that
key_comp()(X, Y) is true.
(Keys need not be unique.)
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class Alloc. Such an allocator object must have
the same external interface as an object of template class
allocator.
Note that the stored allocator object is not copied when the container
object is assigned.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
iterator begin();
const_iterator begin() const;
The member function returns a bidirectional iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
void clear();
The member function calls
erase(
begin(),
end()).
typedef T1 const_iterator;
The type describes an object that can serve as a constant
bidirectional iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T1.
typedef Alloc::const_pointer const_pointer;
The type describes an object that can serve as a constant pointer
to an element of the controlled sequence.
typedef Alloc::const_reference const_reference;
The type describes an object that can serve as a constant reference
to an element of the controlled sequence.
typedef reverse_iterator<const_iterator>
const_reverse_iterator;The type describes an object that can serve as a constant reverse
bidirectional iterator for the controlled sequence.
size_type count(const Key& keyval) const;
The member function returns the number of elements
in the range
[lower_bound(keyval),
upper_bound(keyval)).
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.
iterator end();
const_iterator end() const;
The member function returns a bidirectional iterator that points
just beyond the end of the sequence.
pair<iterator, iterator>
equal_range(const Key& keyval);
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;The member function returns a pair of iterators X
such that X.first ==
lower_bound(keyval)
and X.second ==
upper_bound(keyval).
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
The first member function removes the element of the controlled
sequence pointed to by where.
The second member function removes the elements
in the range [first, last).
Both return an iterator that designates the first element remaining
beyond any elements removed, or
end() if no such element exists.
The third member removes
the elements with sort keys in the range
[lower_bound(keyval),
upper_bound(keyval)).
It returns the number of elements it removes.
The member functions never throw an exception.
iterator find(const Key& keyval);
const_iterator find(const Key& keyval) const;
The member function returns an iterator that designates
the earliest element in the controlled sequence whose sort key has
equivalent ordering
to keyval. If no such element exists,
the function returns
end().
Alloc get_allocator() const;
The member function returns the stored
allocator object.
iterator insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);The first member function inserts the element val
in the controlled sequence, then returns
the iterator that designates the inserted element.
The second member function returns insert(val),
using where as a starting place within the controlled
sequence to search for the insertion point. (Insertion can occur
in amortized constant time, instead of logarithmic time, if the
insertion point immediately precedes or follows where.)
The third member function
inserts the sequence of element values,
for each it in the range [first, last),
by calling insert(*where).
If an exception is thrown during the
insertion of a single element, the container is left unaltered
and the exception is rethrown.
If an exception is thrown during the
insertion of multiple elements, the container is left in a stable
but unspecified state and the exception is rethrown.
typedef T0 iterator;
The type describes an object that can serve as a bidirectional
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T0.
key_compare key_comp() const;
The member function returns the stored function object that
determines the order of elements in the controlled sequence.
The stored object defines the member function:
bool operator(const Key& left, const Key& right);
which returns true if left strictly
precedes right in the sort order.
typedef Pr key_compare;
The type describes a function object that can compare two
sort keys to determine the relative order of two
elements in the controlled sequence.
typedef Key key_type;
The type describes the sort key object which constitutes each
element of the controlled sequence.
iterator lower_bound(const Key& keyval);
const_iterator lower_bound(const Key& keyval) const;
The member function returns an iterator that designates the
earliest element X in the controlled sequence for which
key_comp()(X, keyval) is
false.
If no such element exists, the function returns
end().
multiset();
explicit multiset(const Pr& pred);
multiset(const Pr& pred, const Alloc& al);
multiset(const multiset& right);
template<class InIt>
multiset(InIt first, InIt last);
template<class InIt>
multiset(InIt first, InIt last,
const Pr& pred);
template<class InIt>
multiset(InIt first, InIt last,
const Pr& pred, const Alloc& 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
right.get_allocator().
Otherwise, it is Alloc().
All constructors also store a function object that can later
be returned by calling
key_comp().
The function object is the argument pred, if present.
For the copy constructor, it is
right.key_comp()).
Otherwise, it is Pr().
The first three constructors specify an
empty initial controlled sequence. The fourth constructor specifies
a copy of the sequence controlled by right.
The last three constructors specify the sequence of element values
[first, last).
size_type max_size() const;
The member function returns the length of the longest sequence that
the object can control.
typedef Alloc::pointer pointer;
The type describes an object that can serve as a pointer to an
element of the controlled sequence.
reverse_iterator rbegin();
const_reverse_iterator rbegin() const;
The member function returns a reverse bidirectional
iterator that points just
beyond the end of the controlled sequence. Hence, it designates the
beginning of the reverse sequence.
typedef Alloc::reference reference;
The type describes an object that can serve as a reference to an
element of the controlled sequence.
reverse_iterator rend();
const_reverse_iterator rend() const;
The member function returns a reverse bidirectional
iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, it designates the end of the reverse sequence.
typedef reverse_iterator<iterator> reverse_iterator;
The type describes an object that can serve as a reverse
bidirectional iterator for the controlled sequence.
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.
void swap(multiset& right);
The member function swaps the controlled sequences between
*this and right. If
get_allocator()
== right.get_allocator(), it does so in constant time,
it throws an exception only as a result of copying the stored
function object of type Pr, 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.
iterator upper_bound(const Key& keyval)
const_iterator upper_bound(const Key& keyval) const;
The member function returns an iterator that designates the
earliest element X in the controlled sequence for which
key_comp()(keyval, X) is
true.
If no such element exists, the function returns
end().
value_compare value_comp() const;
The member function returns a function object that
determines the order of elements in the controlled sequence.
typedef Pr value_compare;
The type describes a function object that can compare two
elements as sort keys to determine their relative order
in the controlled sequence.
typedef Key value_type;
The type describes an element of the controlled sequence.
template<class Key, class Pr, class Alloc>
bool operator!=(
const set <Key, Pr, Alloc>& left,
const set <Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator!=(
const multiset <Key, Pr, Alloc>& left,
const multiset <Key, Pr, Alloc>& right);The template function returns !(left == right).
template<class Key, class Pr, class Alloc>
bool operator==(
const set <Key, Pr, Alloc>& left,
const set <Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator==(
const multiset <Key, Pr, Alloc>& left,
const multiset <Key, Pr, Alloc>& right);The first template function overloads operator==
to compare two objects of template class
set.
The second template function overloads operator==
to compare two objects of template class
multiset.
Both functions return
left.size() == right.size() &&
equal(left.
begin(), left.
end(), right.begin()).
template<class Key, class Pr, class Alloc>
bool operator<(
const set <Key, Pr, Alloc>& left,
const set <Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator<(
const multiset <Key, Pr, Alloc>& left,
const multiset <Key, Pr, Alloc>& right);The first template function overloads operator<
to compare two objects of template class
set.
The second template function overloads operator<
to compare two objects of template class
multiset.
Both functions return
lexicographical_compare(left.
begin(), left.
end(), right.begin(), right.end(),
left.value_comp()).
template<class Key, class Pr, class Alloc>
bool operator<=(
const set <Key, Pr, Alloc>& left,
const set <Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator<=(
const multiset <Key, Pr, Alloc>& left,
const multiset <Key, Pr, Alloc>& right);The template function returns !(right < left).
template<class Key, class Pr, class Alloc>
bool operator>(
const set <Key, Pr, Alloc>& left,
const set <Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator>(
const multiset <Key, Pr, Alloc>& left,
const multiset <Key, Pr, Alloc>& right);The template function returns right < left.
template<class Key, class Pr, class Alloc>
bool operator>=(
const set <Key, Pr, Alloc>& left,
const set <Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
bool operator>=(
const multiset <Key, Pr, Alloc>& left,
const multiset <Key, Pr, Alloc>& right);The template function returns !(left < right).
allocator_type
· begin
· clear
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· count
· difference_type
· empty
· end
· equal_range
· erase
· find
· get_allocator
· insert
· iterator
· key_comp
· key_compare
· key_type
· lower_bound
· max_size
· pointer
· rbegin
· reference
· rend
· reverse_iterator
· set
· size
· size_type
· swap
· upper_bound
· value_comp
· value_compare
· value_type
template<class Key, class Pr = less<Key>,
class Alloc = allocator<Key> >
class set {
public:
typedef Key key_type;
typedef Pr key_compare;
typedef Key value_type;
typedef Pr value_compare;
typedef Alloc allocator_type;
typedef Alloc::pointer pointer;
typedef Alloc::const_pointer const_pointer;
typedef Alloc::reference reference;
typedef Alloc::const_reference const_reference;
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;
set();
explicit set(const Pr& pred);
set(const Pr& pred, const Alloc& al);
set(const set& right);
template<class InIt>
set(InIt first, InIt last);
template<class InIt>
set(InIt first, InIt last,
const Pr& pred);
template<class InIt>
set(InIt first, InIt last,
const Pr& pred, const Alloc& al);
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;
size_type max_size() const;
bool empty() const;
Alloc get_allocator() const;
pair<iterator, bool> insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
void clear();
void swap(set& right);
key_compare key_comp() const;
value_compare value_comp() const;
iterator find(const Key& keyval);
const_iterator find(const Key& keyval) const;
size_type count(const Key& keyval) const;
iterator lower_bound(const Key& keyval);
const_iterator lower_bound(const Key& keyval) const;
iterator upper_bound(const Key& keyval);
const_iterator upper_bound(const Key& keyval) const;
pair<iterator, iterator> equal_range(const Key& keyval);
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;
};The template class describes an object that controls a
varying-length sequence of elements of type const Key.
The sequence is
ordered by the predicate
Pr.
Each element serves as both a sort key and a value.
The sequence is represented in a way that permits lookup, insertion,
and removal of an arbitrary element with a number of operations
proportional to the logarithm of the number of elements
in the sequence (logarithmic time). Moreover, inserting an element
invalidates no iterators, and removing an element
invalidates only those iterators which point at the removed element.
The object orders the sequence it controls by calling a
stored function object of type Pr. You access
this stored object by calling the member function
key_comp().
Such a function object must impose a
strict weak ordering
on sort keys of type Key.
For any element X that precedes
Y in the sequence,
key_comp()(Y, X) is false. (For the default function object
less<Key>,
sort keys never decrease in value.)
Unlike template class multiset,
an object of template class set ensures that
key_comp()(X, Y) is true.
(Each key is unique.)
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class Alloc. Such an allocator object must have
the same external interface as an object of template class
allocator.
Note that the stored allocator object is not copied when the container
object is assigned.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
iterator begin();
const_iterator begin() const;
The member function returns a bidirectional iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
void clear();
The member function calls
erase(
begin(),
end()).
typedef T1 const_iterator;
The type describes an object that can serve as a constant
bidirectional iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T1.
typedef Alloc::const_pointer const_pointer;
The type describes an object that can serve as a constant pointer
to an element of the controlled sequence.
typedef Alloc::const_reference const_reference;
The type describes an object that can serve as a constant reference
to an element of the controlled sequence.
typedef reverse_iterator<const_iterator>
const_reverse_iterator;The type describes an object that can serve as a constant reverse
bidirectional iterator for the controlled sequence.
size_type count(const Key& keyval) const;
The member function returns the number of elements
in the range
[lower_bound(keyval),
upper_bound(keyval)).
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.
iterator end();
const_iterator end() const;
The member function returns a bidirectional iterator that points
just beyond the end of the sequence.
pair<iterator, iterator>
equal_range(const Key& keyval);
pair<const_iterator, const_iterator>
equal_range(const Key& keyval) const;The member function returns a pair of iterators X
such that X.first ==
lower_bound(keyval)
and X.second ==
upper_bound(keyval).
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
size_type erase(const Key& keyval);
The first member function removes the element of the controlled
sequence pointed to by where.
The second member function removes the elements
in the range [first, last).
Both return an iterator that designates the first element remaining
beyond any elements removed, or
end() if no such element exists.
The third member removes
the elements with sort keys in the range
[lower_bound(keyval),
upper_bound(keyval)).
It returns the number of elements it removes.
The member functions never throw an exception.
iterator find(const Key& keyval);
const_iterator find(const Key& keyval) const;
The member function returns an iterator that designates
the element in the controlled sequence whose sort key has
equivalent ordering
to keyval. If no such element exists,
the function returns
end().
Alloc get_allocator() const;
The member function returns the stored
allocator object.
pair<iterator, bool> insert(const value_type& val);
iterator insert(iterator where, const value_type& val);
template<class InIt>
void insert(InIt first, InIt last);The first member function determines whether an element X
exists in the sequence whose key has
equivalent ordering
to that of val. If not, it creates such
an element X and initializes it with val.
The function then determines the iterator where that
designates X. If an insertion occurred, the function
returns pair(where, true).
Otherwise, it returns pair(where, false).
The second member function returns insert(val).first,
using where as a starting place within the controlled
sequence to search for the insertion point. (Insertion can occur
in amortized constant time, instead of logarithmic time, if the
insertion point immediately precedes or follows where.)
The third member function
inserts the sequence of element values,
for each where in the range [first, last),
by calling insert(*where).
If an exception is thrown during the
insertion of a single element, the container is left unaltered
and the exception is rethrown.
If an exception is thrown during the
insertion of multiple elements, the container is left in a stable
but unspecified state and the exception is rethrown.
typedef T0 iterator;
The type describes an object that can serve as a bidirectional
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T0.
key_compare key_comp() const;
The member function returns the stored function object that
determines the order of elements in the controlled sequence.
The stored object defines the member function:
bool operator(const Key& left, const Key& right);
which returns true if left strictly
precedes right in the sort order.
typedef Pr key_compare;
The type describes a function object that can compare two
sort keys to determine the relative order of two
elements in the controlled sequence.
typedef Key key_type;
The type describes the sort key object which constitutes each
element of the controlled sequence.
iterator lower_bound(const Key& keyval);
const_iterator lower_bound(const Key& keyval) const;
The member function returns an iterator that designates the
earliest element X in the controlled sequence for which
key_comp()(X, keyval) is
false.
If no such element exists, the function returns
end().
size_type max_size() const;
The member function returns the length of the longest sequence that
the object can control.
typedef Alloc::pointer pointer;
The type describes an object that can serve as a pointer to an
element of the controlled sequence.
reverse_iterator rbegin();
const_reverse_iterator rbegin() const;
The member function returns a reverse bidirectional
iterator that points just
beyond the end of the controlled sequence. Hence, it designates the
beginning of the reverse sequence.
typedef Alloc::const_reference const_reference;
The type describes an object that can serve as a reference to an
element of the controlled sequence.
reverse_iterator rend();
const_reverse_iterator rend() const;
The member function returns a reverse bidirectional
iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, it designates the end of the reverse sequence.
typedef reverse_iterator<iterator> reverse_iterator;
The type describes an object that can serve as a reverse
bidirectional iterator for the controlled sequence.
set();
explicit set(const Pr& pred);
set(const Pr& pred, const Alloc& al);
set(const set& right);
template<class InIt>
set(InIt first, InIt last);
template<class InIt>
set(InIt first, InIt last,
const Pr& pred);
template<class InIt>
set(InIt first, InIt last,
const Pr& pred, const Alloc& 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
right.get_allocator().
Otherwise, it is Alloc().
All constructors also store a function object that can later
be returned by calling
key_comp().
The function object is the argument pred, if present.
For the copy constructor, it is
right.key_comp()).
Otherwise, it is Pr().
The first three constructors specify an
empty initial controlled sequence. The fourth constructor specifies
a copy of the sequence controlled by right.
The last three constructors specify the sequence of element values
[first, last).
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.
void swap(set& right);
The member function swaps the controlled sequences between
*this and right. If
get_allocator()
== right.get_allocator(), it does so in constant time,
it throws an exception only as a result of copying the stored
function object of type Pr, 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.
iterator upper_bound(const Key& keyval)
const_iterator upper_bound(const Key& keyval) const;
The member function returns an iterator that designates the
earliest element X in the controlled sequence for which
key_comp()(keyval, X) is
true.
If no such element exists, the function returns
end().
value_compare value_comp() const;
The member function returns a function object that
determines the order of elements in the controlled sequence.
typedef Pr value_compare;
The type describes a function object that can compare two
elements as sort keys to determine their relative order
in the controlled sequence.
typedef Key value_type;
The type describes an element of the controlled sequence.
template<class Key, class Pr, class Alloc>
void swap(
multiset <Key, Pr, Alloc>& left,
multiset <Key, Pr, Alloc>& right);
template<class Key, class Pr, class Alloc>
void swap(
set <Key, Pr, Alloc>& left,
set <Key, Pr, Alloc>& right);The template function executes
left.swap(right).
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
65 - setjmp
<setjmp.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
66 - signal
<signal.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
67 - slist
<slist>
namespace std {
template<class T, class A>
class slist;
// TEMPLATE FUNCTIONS
template<class T, class A>
bool operator==(
const slist<T, A>& lhs,
const slist<T, A>& rhs);
template<class T, class A>
bool operator!=(
const slist<T, A>& lhs,
const slist<T, A>& rhs);
template<class T, class A>
bool operator<(
const slist<T, A>& lhs,
const slist<T, A>& rhs);
template<class T, class A>
bool operator>(
const slist<T, A>& lhs,
const slist<T, A>& rhs);
template<class T, class A>
bool operator<=(
const slist<T, A>& lhs,
const slist<T, A>& rhs);
template<class T, class A>
bool operator>=(
const slist<T, A>& lhs,
const slist<T, A>& rhs);
template<class T, class A>
void swap(
slist<T, A>& lhs,
slist<T, A>& rhs);
};Include the STL
standard header <slist> to define the
container
template class slist and several supporting
templates.
template<class T, class A>
bool operator!=(
const slist <T, A>& lhs,
const slist <T, A>& rhs);The template function returns !(lhs == rhs).
template<class T, class A>
bool operator==(
const slist <T, A>& lhs,
const slist <T, A>& rhs);The template function overloads operator== to compare
two objects of template class
slist. The function returns
lhs.size() == rhs.size() &&
equal(lhs.
begin(), lhs.
end(), rhs.begin()).
template<class T, class A>
bool operator<(
const slist <T, A>& lhs,
const slist <T, A>& rhs);The template function overloads operator< to compare
two objects of template class
slist. The function returns
lexicographical_compare(lhs.
begin(), lhs.
end(), rhs.begin(), rhs.end()).
template<class T, class A>
bool operator<=(
const slist <T, A>& lhs,
const slist <T, A>& rhs);The template function returns !(rhs < lhs).
template<class T, class A>
bool operator>(
const slist <T, A>& lhs,
const slist <T, A>& rhs);The template function returns rhs < lhs.
template<class T, class A>
bool operator>=(
const slist <T, A>& lhs,
const slist <T, A>& rhs);The template function returns !(lhs < rhs).
allocator_type
· assign
· back
· begin
· clear
· const_iterator
· const_pointer
· const_reference
· difference_type
· empty
· end
· erase
· front
· get_allocator
· insert
· iterator
· slist
· max_size
· merge
· pointer
· pop_back
· pop_front
· previous
· push_back
· push_front
· reference
· remove
· remove_if
· resize
· reverse
· size
· size_type
· sort
· splice
· swap
· unique
· value_type
template<class T, class A = allocator<T> >
class slist {
public:
typedef A allocator_type;
typedef typename A::pointer pointer;
typedef typename A::const_pointer
const_pointer;
typedef typename A::reference reference;
typedef typename A::const_reference const_reference;
typedef typename A::value_type value_type;
typedef T0 iterator;
typedef T1 const_iterator;
typedef T2 size_type;
typedef T3 difference_type;
slist();
explicit slist(const A& al);
explicit slist(size_type n);
slist(size_type n, const T& v);
slist(size_type n, const T& v, const A& al);
slist(const slist& x);
template<class InIt>
slist(InIt first, InIt last);
template<class InIt>
slist(InIt first, InIt last, const A& al);
iterator begin();
const_iterator begin() const;
iterator end();
const_iterator end() const;
iterator previous(const_iterator it);
const_iterator previous(const_iterator it) const;
void resize(size_type n);
void resize(size_type n, T x);
size_type size() const;
size_type max_size() const;
bool empty() const;
A get_allocator() const;
reference front();
const_reference front() const;
reference back();
const_reference back() const;
void push_front(const T& x);
void pop_front();
void push_back(const T& x);
void pop_back();
template<class InIt>
void assign(InIt first, InIt last);
void assign(size_type n, const T& x);
iterator insert(iterator it, const T& x);
void insert(iterator it, size_type n, const T& x);
template<class InIt>
void insert(iterator it, InIt first, InIt last);
iterator erase(iterator it);
iterator erase(iterator first, iterator last);
void clear();
void swap(slist& x);
void splice(iterator it, slist& x);
void splice(iterator it, slist& x, iterator first);
void splice(iterator it, slist& x, iterator first,
iterator last);
void remove(const T& x);
templace<class Pred>
void remove_if(Pred pr);
void unique();
template<class Pred>
void unique(Pred pr);
void merge(slist& x);
template<class Pred>
void merge(slist& x, Pred pr);
void sort();
template<class Pred>
void sort(Pred pr);
void reverse();
};The template class describes an object that controls a
varying-length sequence of elements of type T.
The sequence is stored as a singly linked list of elements,
each containing a member of type T.
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class A. Such an allocator object must have
the same external interface as an object of template class
allocator.
Note that the stored allocator object is not copied when the container
object is assigned.
List reallocation
occurs when a member function must insert, erase or splice elements of
the controlled sequence. In all such cases, only the following iterators
or references become
invalid:
- iterators that designated a position
immediately beyond an inserted element
- iterators that designate an erased element or a position
immediately beyond an erased element
- iterators that designate a spliced element or a position
immediately beyond a spliced element
All additions to the controlled sequence occur as if by calls to
insert, which is the
only member function that calls the constructor
T(const T&). If such an expression throws
an exception, the container object inserts no new elements and rethrows
the exception. Thus, an object of template class slist
is left in a known state when such exceptions occur.
typedef A allocator_type;
The type is a synonym for the template parameter A.
template<class InIt>
void assign(InIt first, InIt last);
void assign(size_type n, const T& x);If InIt is an integer type, the first member
function behaves the same as assign((size_type)first, (T)last).
Otherwise, the
first member function replaces the sequence
controlled by *this with the sequence
[first, last), which must not overlap
the initial controlled sequence.
The second member function replaces the sequence
controlled by *this with a repetition of n
elements of value x.
reference back();
const_reference back() const;
The member function returns a reference to the last element of the
controlled sequence, which must be non-empty.
const_iterator begin() const;
iterator begin();
The member function returns a forward iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
void clear();
The member function calls
erase(
begin(),
end()).
typedef T1 const_iterator;
The type describes an object that can serve as a constant
forward iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T1.
typedef typename A::const_pointer
const_pointer;The type describes an object that can serve as a constant pointer
to an element of the controlled sequence.
typedef typename A::const_reference const_reference;
The type describes an object that can serve as a constant reference
to an element of the controlled sequence.
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 function returns a forward iterator that points
just beyond the end of the sequence.
iterator erase(iterator it);
iterator erase(iterator first, iterator last);
The first member function removes the element of the controlled
sequence pointed to by it. The second member function
removes the elements of the controlled sequence
in the range [first, last).
Both return an iterator that designates the first element remaining
beyond any elements removed, or
end() if no such element exists.
Erasing N elements causes
N destructor calls.
Reallocation occurs,
so iterators and references become
invalid for the erased
elements and iterators become invalid for any remaining element
immediately beyond an erased element.
The member functions never throw an exception.
reference front();
const_reference front() const;
The member function returns a reference to the first element of the
controlled sequence, which must be non-empty.
A get_allocator() const;
The member function returns the stored
allocator object.
iterator insert(iterator it, const T& x);
void insert(iterator it, size_type n, const T& x);
template<class InIt>
void insert(iterator it, InIt first, InIt last);Each of the member functions inserts, before the element pointed to
by it in the controlled sequence, a sequence
specified by the remaining operands.
The first member function inserts
a single element with value x and returns an iterator
that designates the newly inserted element. The second member function
inserts a repetition of n elements of value x.
If InIt is an integer type, the last member
function behaves the same as insert(it, (size_type)first, (T)last).
Otherwise, the last member function inserts the sequence
[first, last), which must not overlap
the initial controlled sequence.
Inserting N elements causes N
constructor calls.
Reallocation occurs,
so iterators become
invalid for any element
that was immediately beyond it.
If an exception is thrown during the
insertion of one or more elements, the container is left unaltered
and the exception is rethrown.
typedef T0 iterator;
The type describes an object that can serve as a forward
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T0.
size_type max_size() const;
The member function returns the length of the longest sequence that
the object can control.
void merge(slist& x);
template<class Pred>
void merge(slist& x, Pred pr);Both member functions remove all elements from the sequence
controlled by x and insert them in the controlled
sequence. Both sequences must be
ordered by the same predicate,
described below. The resulting sequence is also ordered by that
predicate.
For the iterators Pi and Pj
designating elements at positions i
and j, the first member function imposes the
order !(*Pj < *Pi) whenever i < j.
(The elements are sorted in ascending order.)
The second member function imposes the order
!pr(*Pj, *Pi) whenever i < j.
No pairs of elements in the original controlled sequence
are reversed in the resulting controlled sequence. If a pair
of elements in the resulting controlled sequence compares equal
(!(*Pi < *Pj) && !(*Pj < *Pi)),
an element from the original controlled sequence appears before
an element from the sequence controlled by x.
An exception occurs only if pr throws an exception.
In that case, the controlled sequence is left in unspecified order
and the exception is rethrown.
typedef typename A::pointer pointer;
The type describes an object that can serve as a pointer to an
element of the controlled sequence.
void pop_back();
The member function removes the last element of the
controlled sequence, which must be non-empty.
This operation takes time proportional to the number of elements
in the controlled sequence (linear time complexity).
The member function never throws an exception.
void pop_front();
The member function removes the first element of the
controlled sequence, which must be non-empty.
The member function never throws an exception.
iterator previous(const_iterator it);
const_iterator previous(const_iterator it) const;
The member function returns an iterator that designates the element
immediately preceding it, if possible; otherwise it returns
end().
This operation takes time proportional to the number of elements
in the controlled sequence (linear time complexity).
void push_back(const T& x);
The member function inserts an element with value x
at the end of the controlled sequence.
If an exception is thrown, the container is left unaltered
and the exception is rethrown.
void push_front(const T& x);
The member function inserts an element with value x
at the beginning of the controlled sequence.
If an exception is thrown, the container is left unaltered
and the exception is rethrown.
typedef typename A::reference reference;
The type describes an object that can serve as a reference to an
element of the controlled sequence.
void remove(const T& x);
The member function removes from the controlled sequence
all elements, designated by the iterator P, for which
*P == x.
The member function never throws an exception.
templace<class Pred>
void remove_if(Pred pr);The member function removes from the controlled sequence
all elements, designated by the iterator P, for which
pr(*P) is true.
An exception occurs only if pr throws an exception.
In that case, the controlled sequence is left in an unspecified state
and the exception is rethrown.
void resize(size_type n);
void resize(size_type n, T x);
The member functions both ensure that
size() henceforth
returns n. If it must make the controlled sequence longer,
the first member function
appends elements with value T(), while the second member function
appends elements with value x.
To make the controlled sequence shorter, both member functions call
erase(begin() + n, end()).
void reverse();
The member function reverses the order in which elements appear
in the controlled sequence.
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.
slist();
explicit slist(const A& al);
explicit slist(size_type n);
slist(size_type n, const T& v);
slist(size_type n, const T& v,
const A& al);
slist(const slist& x);
template<class InIt>
slist(InIt first, InIt last);
template<class InIt>
slist(InIt first, InIt last, const A& 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 first two constructors specify an
empty initial controlled sequence. The third constructor specifies
a repetition of n elements of value T().
The fourth and fifth constructors specify
a repetition of n elements of value x.
The sixth constructor specifies a copy of the sequence controlled by
x.
If InIt is an integer type, the last two constructors
specify a repetition of (size_type)first elements of value
(T)last. Otherwise, the
last two constructors specify the sequence
[first, last).
void sort();
template<class Pred>
void sort(Pred pr);Both member functions order the elements in the controlled
sequence by a predicate, described below.
For the iterators Pi and Pj
designating elements at positions i
and j, the first member function imposes the
order !(*Pj < *Pi) whenever i < j.
(The elements are sorted in ascending order.)
The member template function imposes the order
!pr(*Pj, *Pi) whenever i < j.
No ordered pairs of elements in the original controlled sequence
are reversed in the resulting controlled sequence.
(The sort is stable.)
An exception occurs only if pr throws an exception.
In that case, the controlled sequence is left in unspecified order
and the exception is rethrown.
void splice(iterator it, slist& x);
void splice(iterator it, slist& x, iterator first);
void splice(iterator it, slist& x, iterator first,
iterator last);The first member function inserts the sequence controlled
by x before the element in the controlled sequence
pointed to by it. It also removes all elements from
x. (&x must not equal this.)
The second member function removes the element pointed to by
first in the sequence controlled by x and
inserts it before the element in the controlled sequence
pointed to by it. (If it == first || it == ++first,
no change occurs.)
The third member function inserts the subrange
designated by [first, last) from the sequence
controlled by x
before the element in the controlled sequence pointed to by it.
It also removes the original subrange from the sequence controlled
by x. (If &x == this,
the range [first, last) must not include the element
pointed to by it.)
If the third member function inserts
N elements, and &x != this, an object of class
iterator is
incremented N times.
For all splice member functions, If
get_allocator()
== str.get_allocator(), no exception occurs.
Otherwise, a copy and a destructor call also
occur for each inserted element.
Iterators or references that designate
spliced elements, or that designate the first element beyond a
sequence of spliced elements, become
invalid.
void swap(slist& x);
The member function swaps the controlled sequences between
*this and x. If
get_allocator()
== x.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.
void unique();
template<class Pred>
void unique(Pred pr);The first member function removes from the controlled sequence
every element that compares equal to its preceding element.
For the iterators Pi and Pj
designating elements at positions i
and j, the second member function removes every
element for which i + 1 == j && pr(*Pi, *Pj).
For a controlled sequence of length N
(> 0), the predicate pr(*Pi, *Pj)
is evaluated N - 1 times.
An exception occurs only if pr throws an exception.
In that case, the controlled sequence is left in an unspecified state
and the exception is rethrown.
typedef typename A::value_type value_type;
The type is a synonym for the template parameter T.
template<class T, class A>
void swap(
slist <T, A>& lhs,
slist <T, A>& rhs);The template function executes
lhs.swap(rhs).
See also the
Table of Contents and the
Index.
Copyright © 1999-2002 by P.J. Plauger.
All rights reserved.
68 - sstream
<sstream>
Include the iostreams
standard header <sstream>
to define several classes that support
iostreams operations on
sequences stored in an allocated array object.
Such sequences are easily converted to and from objects of
class
string.
// DECLARATIONS
class stringbuf;
class istringstream;
class ostringstream;
// END OF DECLARATIONSclass stringbuf : public streambuf {
public:
stringbuf(ios_base::openmode mode =
ios_base::in | ios_base::out);
stringbuf(const string& str,
ios_base::openmode mode =
ios_base::in | ios_base::out);
string str() const;
void str(const string& newstr);
protected:
virtual pos_type seekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode mode =
ios_base::in | ios_base::out);
virtual pos_type seekpos(pos_type sp,
ios_base::openmode mode =
ios_base::in | ios_base::out);
virtual int_type underflow();
virtual int_type pbackfail(int_type meta =
traits_type::eof());
virtual int_type overflow(int_type meta =
traits_type::eof());
};The class
describes a stream buffer that controls
the transmission of elements
to and from a sequence of elements
stored in an array object. The object is allocated, extended, and
freed as necessary to accommodate changes in the sequence.
An object of class
stringbuf
stores a copy of the
ios_base::openmode
argument from its constructor as its
stringbuf mode mode:
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
stringbuf(ios_base::openmode mode =
ios_base::in | ios_base::out);
stringbuf(const string& str,
ios_base::openmode mode =
ios_base::in | ios_base::out);The first constructor stores a null pointer in all the pointers
controlling the
input buffer and the
output buffer. It
also stores mode as the
stringbuf mode.
The second constructor allocates a copy of the sequence controlled
by the string object str.
If mode & ios_base::in is nonzero,
it sets the input buffer to begin reading
at the start of the sequence.
If mode & ios_base::out is nonzero,
it sets the output buffer to begin
writing at the start of the sequence.
It also stores mode as the
stringbuf mode.
typedef char char_type;
The type is a synonym for char.
typedef traits_type::int_type int_type;
The type is a synonym for
traits_type::int_type.
typedef traits_type::off_type off_type;
The type is a synonym for
traits_type::off_type.
virtual int_type overflow(int_type meta =
traits_type::eof());If meta does not compare equal to
traits_type::eof(),
the protected virtual member function endeavors to insert the element
traits_type::to_char_type(meta)
into the
output buffer.
It can do so in various ways:
- If a write position
is available, it can store the element into the write position
and increment the next pointer for the output buffer.
- It can make a write position available by allocating
new or additional storage for the output buffer. (Extending the
output buffer this way also extends any associated
input buffer.)
If the function cannot succeed, it returns traits_type::eof().
Otherwise, it returns
traits_type::not_eof(meta).
virtual int_type pbackfail(int_type meta =
traits_type::eof());The protected virtual member function endeavors to put back an element
into the
input buffer,
then make it the current element (pointed to
by the next pointer).
If meta compares equal to
traits_type::eof(),
the element to push back is effectively the one already in the stream
before the current element. Otherwise, that element is replaced by
byte =
traits_type::to_char_type(meta).
The function can put back an element in various ways:
- If a putback position
is available, and the element stored there compares equal to
byte,
it can simply decrement the next pointer for the input buffer. - If a putback position is available,
and if the stringbuf mode permits
the sequence to be altered (
mode &
ios_base::out is nonzero),
it can store byte into the putback position and decrement the
next pointer for the input buffer.
If the function cannot succeed, it returns
traits_type::eof(). Otherwise, it returns
traits_type::not_eof(meta).
typedef traits_type::pos_type pos_type;
The type is a synonym for
traits_type::pos_type.
virtual pos_type seekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode mode =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
stringbuf,
a stream position consists
purely of a stream offset. Offset zero designates the first element
of the controlled sequence.
The new position is determined as follows:
- If
way ==
ios_base::beg,
the new position is the beginning of the stream plus off. - If
way ==
ios_base::cur,
the new position is the current stream position plus off. - If
way ==
ios_base::end,
the new position is the end of the stream plus off.
If
mode & ios_base::in is nonzero,
the function alters the next position to read in the
input buffer.
If mode & ios_base::out is nonzero,
the function alters the next position to write in the
output buffer.
For a stream to be affected, its buffer must exist.
For a positioning operation to succeed, the resulting
stream position must lie within the controlled sequence.
If the function affects both stream positions, way
must be ios_base::beg or ios_base::end
and both streams are positioned at the same element.
Otherwise (or if neither position is affected) the positioning
operation fails.
If the function succeeds in altering either or both of the stream positions,
it returns the resultant stream position.
Otherwise, it fails and returns an invalid stream position.
virtual pos_type seekpos(pos_type sp,
ios_base::openmode mode =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
stringbuf,
a stream position consists
purely of a stream offset. Offset zero designates the first element
of the controlled sequence. The new position is determined
by sp.
If
mode & ios_base::in is nonzero,
the function alters the next position to read in the
input buffer.
If mode & ios_base::out is nonzero,
the function alters the next position to write in the
output buffer.
For a stream to be affected, its buffer must exist.
For a positioning operation to succeed, the resulting
stream position must lie within the controlled sequence.
Otherwise (or if neither position is affected) the positioning
operation fails.
If the function succeeds in altering either or both of the stream positions,
it returns the resultant stream position.
Otherwise, it fails and returns an invalid stream position.
string str() const;
void str(const string& newstr);
The first member function returns an object of class
string,
whose controlled sequence is a copy of the sequence controlled
by *this. The sequence copied depends on the stored
stringbuf mode mode:
- If
mode &
ios_base::out is nonzero
and an output buffer exists,
the sequence is the entire output buffer
(epptr() -
pbase()
elements beginning with pbase()). - Otherwise, if
mode &
ios_base::in is nonzero
and an input buffer exists,
the sequence is the entire input buffer
(egptr() -
eback()
elements beginning with eback()). - Otherwise, the copied sequence is empty.
The second member function deallocates any sequence currently
controlled by *this. It then
allocates a copy of the sequence controlled
by newstr. If mode & ios_base::in is nonzero,
it sets the input buffer to begin reading
at the beginning of the sequence.
If mode & ios_base::out is nonzero,
it sets the output buffer to begin
writing at the beginning of the sequence.
typedef char_traits traits_type;
The type is a synonym for
char_traits.
virtual int_type underflow();
The protected virtual member function endeavors to extract the current
element byte from the
input buffer,
then advance the current stream position, and return the element as
traits_type::to_int_type(byte).
It can do so in only one way:
If a read position
is available, it takes byte as the element stored
in the read position and advances the next pointer for the input buffer.
If the function cannot succeed, it returns
traits_type::eof(). Otherwise,
it returns the current element in the input stream,
converted as described above.
class istringstream : public istream {
public:
explicit istringstream(ios_base::openmode mode =
ios_base::in);
explicit istringstream(const string& str,
ios_base::openmode mode = ios_base::in);
stringbuf *rdbuf() const;
string str();
void str(const string& newstr);
};The class describes an object that controls
extraction of elements and encoded objects from a
stream buffer of class
stringbuf.
The object stores an object of class
stringbuf.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
explicit istringstream(ios_base::openmode mode =
ios_base::in);
explicit istringstream(const string& str,
ios_base::openmode mode = ios_base::in);The first constructor initializes the base class by calling
istream(sb),
where sb is the stored object of class
stringbuf.
It also initializes sb by calling
stringbuf(mode | ios_base::in).
The second constructor initializes the base class by calling
istream(sb).
It also initializes sb by calling
stringbuf(str,
mode | ios_base::in).
stringbuf *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
stringbuf.
string str() const;
void str(const string& newstr);
The first member function returns
rdbuf()->
str().
The second member function calls rdbuf()-> str(newstr).
class ostringstream : public ostream {
public:
typedef Alloc allocator_type;
explicit ostringstream(ios_base::openmode mode =
ios_base::out);
explicit ostringstream(const string& str,
ios_base::openmode mode = ios_base::out);
stringbuf *rdbuf() const;
string str();
void str(const string& newstr);
};The class describes an object that controls
insertion of elements and encoded objects into a
stream buffer of class
stringbuf.
The object stores an object of class
stringbuf.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
explicit ostringstream(ios_base::openmode mode =
ios_base::out);
explicit ostringstream(const string& str,
ios_base::openmode mode = ios_base::out);The first constructor initializes the base class by calling
ostream(sb),
where sb is the stored object of class
stringbuf.
It also initializes sb by calling
stringbuf(mode | ios_base::out).
The second constructor initializes the base class by calling
ostream(sb).
It also initializes sb by calling
stringbuf(str,
mode | ios_base::out).
stringbuf *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
stringbuf.
string str() const;
void str(const string& newstr);
The first member function returns
rdbuf()->
str().
The second member function calls rdbuf()-> str(newstr).
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
69 - stack
<stack>
Include the STL
standard header <stack>
to define the template class stack and two supporting
templates.
namespace std {
template<class Ty, class Container>
class stack;
// TEMPLATE FUNCTIONS
template<class Ty, class Container>
bool operator==(const stack<Ty, Container>& left,
const stack<Ty, Container>&);
template<class Ty, class Container>
bool operator!=(const stack<Ty, Container>& left,
const stack<Ty, Container>&);
template<class Ty, class Container>
bool operator<(const stack<Ty, Container>& left,
const stack<Ty, Container>&);
template<class Ty, class Container>
bool operator>(const stack<Ty, Container>& left,
const stack<Ty, Container>&);
template<class Ty, class Container>
bool operator<=(const stack<Ty, Container>& left,
const stack<Ty, Container>&);
template<class Ty, class Container>
bool operator>=(const stack<Ty, Container>& left,
const stack<Ty, Container>&);
};template<class Ty, class Container>
bool operator!=(const stack <Ty, Container>& left,
const stack <Ty, Container>& right);The template function returns !(left == right).
template<class Ty, class Container>
bool operator==(const stack <Ty, Container>& left,
const stack <Ty, Container>& right);The template function overloads operator== to compare
two objects of template class
stack. The function returns
left.c == right.c.
template<class Ty, class Container>
bool operator<(const stack <Ty, Container>& left,
const stack <Ty, Container>& right);The template function overloads operator< to compare
two objects of template class
stack. The function returns
left.c < right.c.
template<class Ty, class Container>
bool operator<=(const stack <Ty, Container>& left,
const stack <Ty, Container>& right);The template function returns !(right < left).
template<class Ty, class Container>
bool operator>(const stack <Ty, Container>& left,
const stack <Ty, Container>& right);The template function returns right < left.
template<class Ty, class Container>
bool operator>=(const stack <Ty, Container>& left,
const stack <Ty, Container>& right);The template function returns !(left < right).
template<class Ty,
class Container = deque<Ty> >
class stack {
public:
typedef Container container_type;
typedef typename Container::value_type value_type;
typedef typename Container::size_type size_type;
stack();
explicit stack(const container_type& cont);
bool empty() const;
size_type size() const;
value_type& top();
const value_type& top() const;
void push(const value_type& val);
void pop();
protected:
Container c;
};The template class describes an object that controls a
varying-length sequence of elements.
The object allocates and frees storage for the sequence it controls
through a protected object named
c,
of class Container.
The type Ty of elements in the controlled sequence must match
value_type.
An object of class Container must supply
several public members defined the same as for
deque,
list, and
vector
(all of which are suitable candidates for class Container).
The required members are:
typedef Ty value_type;
typedef T0 size_type;
Container();
bool empty() const;
size_type size() const;
value_type& back();
const value_type& back() const;
void push_back(const value_type& val);
void pop_back();
bool operator==(const Container& cont) const;
bool operator!=(const Container& cont) const;
bool operator<(const Container& cont) const;
bool operator>(const Container& cont) const;
bool operator<=(const Container& cont) const;
bool operator>=(const Container& cont) const;Here, T0 is an unspecified type
that meets the stated requirements.
typedef Container container_type;
The type is a synonym for the template parameter Container.
bool empty() const;
The member function returns true for an empty controlled sequence.
void pop();
The member function removes the last element of the
controlled sequence, which must be non-empty.
void push(const Ty& val);
The member function inserts an element with value val
at the end of the controlled sequence.
size_type size() const;
The member function returns the length of the controlled sequence.
typedef typename Container::size_type size_type;
The type is a synonym for Container::size_type.
stack();
explicit stack(const container_type& cont);
The first constructor initializes the stored object with
c(), to specify an
empty initial controlled sequence.
The second constructor initializes the stored object with
c(cont), to specify an
initial controlled sequence that is a copy of the sequence controlled
by cont.
value_type& top();
const value_type& top() const;
The member function returns a reference to the last element of the
controlled sequence, which must be non-empty.
typedef typename Container::value_type value_type;
The type is a synonym for Container::value_type.
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
70 - stdarg
<stdarg.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
71 - stddef
<stddef.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
72 - stdexcep
<stdexcept>
Include the standard header <stdexcept>
to define several classes used for reporting exceptions.
The classes form a derivation hierarchy, as indicated by the indenting
above, all derived from class
exception.
// DECLARATIONS
class logic_error;
class domain_error;
class invalid_argument;
class length_error;
class out_of_range;
class runtime_error;
class range_error;
class overflow_error;
class underflow_error;
// END OF DECLARATIONSclass domain_error : public logic_error {
public:
domain_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report a
domain error. The value returned by
what() is a copy of
message.data().
class invalid_argument : public logic_error {
public:
invalid_argument(const string& message);
};The class serves as the base class for all exceptions thrown
to report an invalid argument. The value returned by
what() is a copy of
message.data().
class length_error : public logic_error {
public:
length_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report an attempt to generate an object too long to be specified.
The value returned by
what() is a copy of
message.data().
class logic_error : public exception {
public:
logic_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report errors presumably detectable before the program executes,
such as violations of logical preconditions. The value returned by
what() is a copy of
message.data().
class out_of_range : public logic_error {
public:
out_of_range(const string& message);
};The class serves as the base class for all exceptions thrown
to report an argument that is out of its valid range. The value returned by
what() is a copy of
message.data().
class overflow_error : public runtime_error {
public:
overflow_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report an arithmetic overflow. The value returned by
what() is a copy of
message.data().
class range_error : public runtime_error {
public:
range_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report a
range error. The value returned by
what() is a copy of
message.data().
class runtime_error : public exception {
public:
runtime_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report errors presumably detectable only when the program executes.
The value returned by
what() is a copy of
message.data().
class underflow_error : public runtime_error {
public:
underflow_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report an arithmetic underflow. The value returned by
what() is a copy of
message.data().
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
73 - stdio
<stdio.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
74 - stdlib
<stdlib.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
75 - stl
<stl.h>
Include the special header <stl.h>
to effectively include all the standard headers that constitute the
Standard
Template Library (STL) and hoist their names outside the
std namespace.
The header also defines macro names that redefine
the STL container template classes
to match their more traditional definitions.
#include <algorithm>
#include <deque>
#include <functional>
#include <iterator>
#include <list>
#include <map>
#include <memory>
#include <numeric>
#include <queue>
#include <set>
#include <stack>
#include <utility>
#include <vector>
using namespace std;
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
76 - streambu
<streambuf>
Include the iostreams
standard header <streambuf> to define
class streambuf,
which is basic to the operation of the iostreams classes.
(This header is typically included for you by another
of the iostreams headers. You seldom have occasion to include it
directly.)
// DECLARATIONS
class streambuf;
// END OF DECLARATIONS
streambuf
· char_type
· eback
· egptr
· epptr
· gbump
· getloc
· gptr
· imbue
· in_avail
· int_type
· off_type
· overflow
· pbackfail
· pbase
· pbump
· pos_type
· pptr
· pubimbue
· pubseekoff
· pubseekpos
· pubsetbuf
· pubsync
· sbumpc
· seekoff
· seekpos
· setbuf
· setg
· setp
· sgetc
· sgetn
· showmanyc
· snextc
· sputbackc
· sputc
· sputn
· stossc
· sungetc
· sync
· traits_type
· uflow
· underflow
· xsgetn
· xsputn
class streambuf {
public:
typedef char char_type;
typedef char_traits traits_type;
typedef traits_type::int_type int_type;
typedef traits_type::pos_type pos_type;
typedef traits_type::off_type off_type;
virtual ~streambuf();
locale pubimbue(const locale& loc);
locale getloc() const;
streambuf *pubsetbuf(char_type *buffer,
streamsize count);
pos_type pubseekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
pos_type pubseekpos(pos_type sp,
ios_base::openmode which =
ios_base::in | ios_base::out);
int pubsync();
streamsize in_avail();
int_type snextc();
int_type sbumpc();
int_type sgetc();
void stossc(); [optional]
streamsize sgetn(char_type *ptr, streamsize count);
int_type sputbackc(char_type ch);
int_type sungetc();
int_type sputc(char_type ch);
streamsize sputn(const char_type *ptr, streamsize count);
protected:
streambuf();
char_type *eback() const;
char_type *gptr() const;
char_type *egptr() const;
void gbump(int count);
void setg(char_type *gbeg,
char_type *gnext, char_type *gend);
char_type *pbase() const;
char_type *pptr() const;
char_type *epptr() const;
void pbump(int count);
void setp(char_type *pbeg, char_type *pend);
virtual void imbue(const locale &loc);
virtual streambuf *setbuf(char_type *buffer,
streamsize count);
virtual pos_type seekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual pos_type seekpos(pos_type sp,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual int sync();
virtual streamsize showmanyc();
virtual streamsize xsgetn(char_type *ptr,
streamsize count);
virtual int_type underflow();
virtual int_type uflow();
virtual int_type pbackfail(int_type meta =
traits_type::eof());
virtual streamsize xsputn(const char_type *ptr,
streamsize count);
virtual int_type overflow(int_type meta =
traits_type::eof());
};The class describes an abstract base class for deriving a
stream buffer, which controls
the transmission of elements to and from a specific
representation of a stream. An object of class
streambuf helps control
a stream with elements of type char, also known as
char_type, whose
character traits
are determined by the class
char_traits,
also known as
traits_type.
Every stream buffer conceptually controls
two independent streams, in fact, one for extractions (input) and one for
insertions (output). A specific representation may, however, make
either or both of these streams inaccessible. It typically maintains
some relationship between the two streams.
What you insert into the output stream of a
stringbuf
object, for example, is what you later extract from its input stream.
And when you position one stream of a
filebuf
object, you position the other stream in tandem.
The public interface to template class
streambuf
supplies the operations common to all stream buffers, however
specialized. The protected interface supplies the operations
needed for a specific representation of a stream
to do its work. The protected virtual member functions let you
tailor the behavior of a derived stream buffer for a specific
representation of a stream. Each of the derived stream buffers
in this library describes how it specializes the
behavior of its protected virtual member functions. Documented
here is the default behavior for the base class,
which is often to do nothing.
The remaining protected member
functions control copying to and from any storage supplied to
buffer transmissions to and from streams.
An input buffer,
for example, is characterized by:
eback(),
a pointer to the beginning of the buffergptr(),
a pointer to the next element to readegptr(),
a pointer just past the end of the buffer
Similarly, an output buffer
is characterized by:
pbase(),
a pointer to the beginning of the bufferpptr(),
a pointer to the next element to writeepptr(),
a pointer just past the end of the buffer
For any buffer, the protocol is:
- If the next pointer is null, no buffer exists. Otherwise,
all three pointers point into the same sequence. (They can
be safely compared for order.)
- For an output buffer, if the next pointer compares less
than the end pointer, you can store an element at the
write position
designated by the next pointer.
- For an input buffer, if the next pointer compares less
than the end pointer, you can read an element at the
read position
designated by the next pointer.
- For an input buffer, if the beginning pointer compares less
than the next pointer, you can put back an element at the
putback position
designated by the decremented next pointer.
Any protected virtual member functions you write for a
class derived from streambuf
must cooperate in maintaining this protocol.
An object of class streambuf
stores the six pointers described above.
streambuf();
The protected constructor stores a null pointer in all the pointers
controlling the
input buffer and the
output buffer.
typedef char char_type;
The type is a synonym for char.
char_type *eback() const;
The member function returns a pointer to the beginning of the
input buffer.
char_type *egptr() const;
The member function returns a pointer just past the end of the
input buffer.
char_type *epptr() const;
The member function returns a pointer just past the end of the
output buffer.
void gbump(int count);
The member function adds count to the next pointer for the
input buffer.
locale getloc() const;
The member function returns the stored locale object.
char_type *gptr() const;
The member function returns a pointer to the next element of the
input buffer.
virtual void imbue(const locale &loc);
The default behavior is to do nothing.
streamsize in_avail();
If a read position is available,
the member function returns
egptr() -
gptr().
Otherwise, it returns
showmanyc().
typedef traits_type::int_type int_type;
The type is a synonym for
traits_type::int_type.
typedef traits_type::off_type off_type;
The type is a synonym for
traits_type::off_type.
virtual int_type overflow(int_type meta =
traits_type::eof());If meta does not compare equal to
traits_type::eof(),
the protected virtual member function endeavors to insert the element
traits_type:: to_char_type(meta)
into the output stream. It can do so in various ways:
- If a write position is available,
it can store the element into the write position and increment the
next pointer for the
output buffer.
- It can make a write position available by allocating
new or additional storage for the output buffer.
- It can make a write position available by writing out, to some
external destination, some or all of the elements
between the beginning and next pointers for the output buffer.
If the function cannot succeed, it returns
traits_type::eof() or throws an exception.
Otherwise, it returns
traits_type::not_eof(meta).
The default behavior is to return traits_type::eof().
virtual int_type pbackfail(int_type meta =
traits_type::eof());The protected virtual member function endeavors to put back an element
into the input stream, then make it the current element (pointed to
by the next pointer).
If meta compares equal to
traits_type::eof(),
the element to push back is effectively the one already in the stream
before the current element. Otherwise, that element is replaced by
traits_type::
to_char_type(meta).
The function can put back an element in various ways:
- If a putback position is available,
it can store the element into the putback position and decrement the
next pointer for the
input buffer.
- It can make a putback position available by allocating
new or additional storage for the input buffer.
- For a stream buffer with common input and output streams,
it can make a putback position available by writing out, to some
external destination, some or all of the elements
between the beginning and next pointers for the output buffer.
If the function cannot succeed, it returns
traits_type::eof() or throws an exception. Otherwise,
it returns some other value.
The default behavior is to return traits_type::eof().
char_type *pbase() const;
The member function returns a pointer to the beginning of the
output buffer.
void pbump(int count);
The member function adds count to the next pointer for the
output buffer.
typedef traits_type::pos_type pos_type;
The type is a synonym for
traits_type::pos_type.
char_type *pptr() const;
The member function returns a pointer to the next element of the
output buffer.
locale pubimbue(const locale& loc);
The member function stores loc in the
locale object, calls
imbue(),
then returns the previous value stored in the locale object.
pos_type pubseekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);The member function returns
seekoff(off, way,
which).
pos_type pubseekpos(pos_type sp,
ios_base::openmode which =
ios_base::in | ios_base::out);The member function returns
seekpos(sp, which).
streambuf *pubsetbuf(char_type *buffer, streamsize count);
The member function returns
setbuf(buffer, count).
int pubsync();
The member function returns
sync().
int_type sbumpc();
If a read position is available,
the member function returns
traits_type::to_int_type(
*gptr())
and increments the next pointer for the
input buffer.
Otherwise, it returns
uflow().
virtual pos_type seekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. The new position is determined
as follows:
- If
way ==
ios_base::beg,
the new position is the beginning of the stream plus off. - If
way ==
ios_base::cur,
the new position is the current stream position plus off. - If
way ==
ios_base::end,
the new position is the end of the stream plus off.
Typically, if
which & ios_base::in is nonzero,
the input stream is affected, and if which & ios_base::out
is nonzero, the output stream is affected. Actual use of this parameter
varies among derived stream buffers, however.
If the function succeeds in altering the stream position(s),
it returns the resultant stream position (or one of them).
Otherwise, it returns an invalid stream position.
The default behavior is to return an invalid stream position.
virtual pos_type seekpos(pos_type sp,
ios_base::openmode which =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams.
The new position is sp.
Typically, if
which & ios_base::in is nonzero,
the input stream is affected, and if which & ios_base::out
is nonzero, the output stream is affected. Actual use of this parameter
varies among derived stream buffers, however.
If the function succeeds in altering the stream position(s),
it returns the resultant stream position (or one of them).
Otherwise, it returns an invalid stream position.
The default behavior is to return an invalid stream position.
virtual streambuf *setbuf(char_type *buffer,
streamsize count);The protected virtual member function performs an operation
particular to each derived stream buffer. (See, for example,
filebuf.)
The default behavior is to return this.
void setg(char_type *gbeg, char_type *gnext,
char_type *gend);The member function stores gbeg in the beginning pointer,
gnext in the next pointer,
and gend in the end pointer for the
input buffer.
void setp(char_type *pbeg, char_type *pend);
The member function stores pbeg in the beginning pointer,
pbeg in the next pointer,
and pend in the end pointer for the
output buffer.
int_type sgetc();
If a read position is available,
the member function returns
traits_type::to_int_type(
*gptr())
Otherwise, it returns
underflow().
streamsize sgetn(char_type *ptr, streamsize count);
The member function returns
xsgetn(ptr, count).
virtual streamsize showmanyc();
The protected virtual member function returns a count of the
number of characters that can be extracted from the input
stream with no fear that the program will suffer an indefinite
wait. The default behavior is to return zero.
int_type snextc();
The member function calls
sbumpc() and,
if that function returns
traits_type::eof(),
returns traits_type::eof().
Otherwise, it returns
sgetc().
int_type sputbackc(char_type ch);
If a putback position is available
and ch compares equal to the character stored in that position,
the member function decrements the next pointer for the
input buffer and returns
traits_type::to_int_type(ch).
Otherwise, it returns
pbackfail(ch).
int_type sputc(char_type ch);
If a write position is available,
the member function stores ch in the write position,
increments the next pointer for the
output buffer, and returns
traits_type::to_int_type(ch).
Otherwise, it returns
overflow(ch).
streamsize sputn(const char_type *ptr, streamsize count);
The member function returns
xsputn(ptr, count).
void stossc(); [optional]
The member function calls
sbumpc().
Note that an implementation is not required to supply this member function.
int_type sungetc();
If a putback position is available,
the member function decrements the next pointer for the
input buffer and returns
traits_type::to_int_type(
*gptr()).
Otherwise it returns
pbackfail().
virtual int sync();
The protected virtual member function endeavors to synchronize
the controlled streams with any associated external streams.
Typically, this involves writing out any elements between the beginning
and next pointers for the
output buffer.
It does not involve putting back any elements between the next
and end pointers for the
input buffer.
If the function cannot succeed, it returns -1.
The default behavior is to return zero.
typedef char_traits traits_type;
The type is a synonym for
char_traits.
virtual int_type uflow();
The protected virtual member function endeavors to extract the current
element ch from the input stream,
then advance the current stream position, and return the element as
traits_type::to_int_type(ch).
It can do so in various ways:
- If a read position is available,
it takes
ch as the element stored in the read position
and advances the next pointer for the
input buffer. - It can read an element directly, from some external source,
and deliver it as the value
ch. - For a stream buffer with common input and output streams,
it can make a read position available by writing out, to some
external destination, some or all of the elements
between the beginning and next pointers for the output buffer.
Or it can allocate new or additional storage for the
input buffer. The function
then reads in, from some external source, one or more elements.
If the function cannot succeed, it returns
traits_type::eof(),
or throws an exception. Otherwise,
it returns the current element ch in the input stream,
converted as described above, and advances the next pointer
for the input buffer. The default behavior is to call
underflow()
and, if that function returns traits_type::eof(),
to return traits_type::eof(). Otherwise, the function
returns the current element ch in the input stream,
converted as described above, and advances the next pointer
for the input buffer.
virtual int_type underflow();
The protected virtual member function endeavors to extract the current
element ch from the input stream,
without advancing the current stream position, and return it as
traits_type::to_int_type(ch).
It can do so in various ways:
- If a read position is available,
ch is the element stored in the read position. - It can make a read position available by allocating
new or additional storage for the
input buffer, then reading in,
from some external source, one or more elements.
If the function cannot succeed, it returns
traits_type::eof(),
or throws an exception. Otherwise,
it returns the current element in the input stream,
converted as described above.
The default behavior is to return traits_type::eof().
virtual streamsize xsgetn(char_type *ptr, streamsize count);
The protected virtual member function extracts up to count
elements from the input stream, as if by repeated calls to
sbumpc,
and stores them in the array beginning at ptr.
It returns the number of elements actually extracted.
virtual streamsize xsputn(const char_type *ptr,
streamsize count);The protected virtual member function inserts up to count
elements into the output stream, as if by repeated calls to
sputc,
from the array beginning at ptr.
It returns the number of elements actually inserted.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
77 - string
<string.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
78 - string2
<string>
string
· char_allocator
· char_traits
· getline
· operator+
· operator!=
· operator==
· operator<
· operator<<
· operator<=
· operator>
· operator>=
· operator>>
· swap
Include the standard header <string>
to define the
class
string and various
supporting classes and functions.
// DECLARATIONS
class char_allocator;
class char_traits;
class string;
// FUNCTIONS
string operator+(
const string& left,
const string& right);
string operator+(
const string& left,
const char *right);
string operator+(
const string& left,
char right);
string operator+(
const char *left,
const string& right);
string operator+(
char left,
const string& right);
bool operator==(
const string& left,
const string& right);
bool operator==(
const string& left,
const char *right);
bool operator==(
const char *left,
const string& right);
bool operator!=(
const string& left,
const string& right);
bool operator!=(
const string& left,
const char *right);
bool operator!=(
const char *left,
const string& right);
bool operator<(
const string& left,
const string& right);
bool operator<(
const string& left,
const char *right);
bool operator<(
const char *left,
const string& right);
bool operator>(
const string& left,
const string& right);
bool operator>(
const string& left,
const char *right);
bool operator>(
const char *left,
const string& right);
bool operator<=(
const string& left,
const string& right);
bool operator<=(
const string& left,
const char *right);
bool operator<=(
const char *left,
const string& right);
bool operator>=(
const string& left,
const string& right);
bool operator>=(
const string& left,
const char *right);
bool operator>=(
const char *left,
const string& right);
void swap(
string& left,
string& right);
ostream& operator<<(
ostream& ostr,
const string& str);
istream& operator>>(
istream& istr,
string& str);
istream& getline(
istream& istr,
string& str);
istream& getline(
istream& istr,
string& str,
char delim);
// END OF DECLARATIONS
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
class string {
public:
typedef char_traits traits_type;
typedef char_allocator allocator_type;
typedef T0 iterator;
typedef T1 const_iterator;
typedef T2 size_type;
typedef T3 difference_type;
class const_reverse_iterator;
class reverse_iterator;
typedef allocator_type::pointer
pointer;
typedef allocator_type::const_pointer
const_pointer;
typedef allocator_type::reference
reference;
typedef allocator_type::const_reference
const_reference;
typedef allocator_type::value_type
value_type;
static const size_type npos = -1;
string();
explicit string(const allocator_type& al);
string(const string& right);
string(const string& right, size_type roff,
size_type count = npos);
string(const string& right, size_type roff,
size_type count, const allocator_type& al);
string(const value_type *ptr, size_type count);
string(const value_type *ptr, size_type count,
const allocator_type& al);
string(const value_type *ptr);
string(const value_type *ptr,
const allocator_type& al);
string(size_type count, value_type ch);
string(size_type count, value_type ch,
const allocator_type& al);
string(const_iterator first,
const_iterator last);
string(const_iterator first,
const_iterator last,
const allocator_type& al);
string& operator=(const string& right);
string& operator=(const value_type *ptr);
string& operator=(value_type ch);
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 off) const;
reference at(size_type off);
const_reference operator[](size_type off) const;
reference operator[](size_type off);
void push_back(value_type ch);
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 newsize, value_type ch = value_type());
size_type capacity() const;
void reserve(size_type count = 0);
bool empty() const;
string& operator+=(const string& right);
string& operator+=(const value_type *ptr);
string& operator+=(value_type ch); string& append(const string& right);
string& append(const string& right,
size_type roff, size_type count);
string& append(const value_type *ptr,
size_type count);
string& append(const value_type *ptr);
string& append(size_type count, value_type ch);
string& append(const_iterator first,
const_iterator last);
string& assign(const string& right);
string& assign(const string& right,
size_type roff, size_type count);
string& assign(const value_type *ptr,
size_type count);
string& assign(const value_type *ptr);
string& assign(size_type count, value_type ch);
string& assign(const_iterator first,
const_iterator last);
string& insert(size_type off,
const string& right);
string& insert(size_type off,
const string& right, size_type roff,
size_type count);
string& insert(size_type off,
const value_type *ptr, size_type count);
string& insert(size_type off,
const value_type *ptr);
string& insert(size_type off,
size_type count, value_type ch);
iterator insert(iterator where,
value_type ch = value_type());
void insert(iterator where, size_type count, value_type ch);
void insert(iterator where,
const_iterator first, const_iterator last);
string& erase(size_type off = 0,
size_type count = npos);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
void clear();
string& replace(size_type off, size_type n0,
const string& right);
string& replace(size_type off, size_type n0,
const string& right, size_type roff,
size_type count);
string& replace(size_type off, size_type n0,
const value_type *ptr, size_type count);
string& replace(size_type off, size_type n0,
const value_type *ptr);
string& replace(size_type off, size_type n0,
size_type count, value_type ch);
string& replace(iterator first, iterator last,
const string& right);
string& replace(iterator first, iterator last,
const value_type *ptr, size_type count);
string& replace(iterator first, iterator last,
const value_type *ptr);
string& replace(iterator first, iterator last,
size_type count, value_type ch);
string& replace(iterator first, iterator last,
const_iterator first2, const_iterator last2);
size_type copy(value_type *ptr, size_type count,
size_type off = 0) const;
void swap(string& right); size_type find(const string& right,
size_type off = 0) const;
size_type find(const value_type *ptr, size_type off,
size_type count) const;
size_type find(const value_type *ptr,
size_type off = 0) const;
size_type find(value_type ch, size_type off = 0) const;
size_type rfind(const string& right,
size_type off = npos) const;
size_type rfind(const value_type *ptr, size_type off,
size_type count = npos) const;
size_type rfind(const value_type *ptr,
size_type off = npos) const;
size_type rfind(value_type ch,
size_type off = npos) const;
size_type find_first_of(const string& right,
size_type off = 0) const;
size_type find_first_of(const value_type *ptr,
size_type off, size_type count) const;
size_type find_first_of(const value_type *ptr,
size_type off = 0) const;
size_type find_first_of(value_type ch,
size_type off = 0) const;
size_type find_last_of(const string& right,
size_type off = npos) const;
size_type find_last_of(const value_type *ptr,
size_type off, size_type count = npos) const;
size_type find_last_of(const value_type *ptr,
size_type off = npos) const;
size_type find_last_of(value_type ch,
size_type off = npos) const;
size_type find_first_not_of(const string& right,
size_type off = 0) const;
size_type find_first_not_of(const value_type *ptr,
size_type off, size_type count) const;
size_type find_first_not_of(const value_type *ptr,
size_type off = 0) const;
size_type find_first_not_of(value_type ch,
size_type off = 0) const;
size_type find_last_not_of(const string& right,
size_type off = npos) const;
size_type find_last_not_of(const value_type *ptr,
size_type off, size_type count) const;
size_type find_last_not_of(const value_type *ptr,
size_type off = npos) const;
size_type find_last_not_of(value_type ch,
size_type off = npos) const;
string substr(size_type off = 0,
size_type count = npos) const;
int compare(const string& right) const;
int compare(size_type off, size_type n0,
const string& right) const;
int compare(size_type off, size_type n0,
const string& right, size_type roff,
size_type count) const;
int compare(const value_type *ptr) const;
int compare(size_type off, size_type n0,
const value_type *ptr) const;
int compare(size_type off, size_type n0,
const value_type *ptr, size_type off) const;
allocator_type get_allocator() const;
};The class describes an object that controls a
varying-length sequence of elements of type char,
also known as
value_type.
Various important properties of the elements
in a string
are described by the class
char_traits,
also known as
traits_type.
The object allocates and frees storage for the sequence it controls
through a stored allocator object of class
char_allocator, also known as
allocator_type.
Note that the stored allocator object is not copied when the container
object is assigned.
The sequences controlled by an object of class
string are usually called
strings. These objects should not be
confused, however, with the null-terminated
C strings used throughout the
Standard C++ library.
Many member functions require an
operand sequence of elements.
You can specify such an operand sequence several
ways:
ch -- one element
with value chcount, ch -- a repetition of count elements each
with value chptr -- a null-terminated sequence
(such as a C string) beginning at
ptr (which must not be a null pointer),
where the terminating element is the value
value_type() and is not part of
the operand sequenceptr, count -- a sequence of count elements
beginning at ptr (which must not be a null pointer)right -- the sequence specified by the
string object rightright, roff, count -- the substring of the
string object right with up to count
elements (or through the end of the string, whichever comes first)
beginning at position rofffirst, last -- a sequence of elements delimited
by the iterators first and last, in the
range [first, last), which may overlap
the sequence controlled by the string object whose member function
is being called
If a position argument
(such as roff above) is beyond the end of the string on a
call to a string member function, the function
reports an
out-of-range error by
throwing an object of class
out_of_range.
If a function is asked to generate a sequence longer than
max_size() elements,
the function reports a
length error by
throwing an object of class
length_error.
References, pointers, and iterators that designate elements of the
controlled sequence can become invalid after any call to a function
that alters the controlled sequence, or after the first call to the
non-const member functions
at,
begin,
end,
operator[],
rbegin, or
rend.
(The idea is to permit multiple strings to share the same representation
until one string becomes a candidate for change, at which point that string
makes a private copy of the representation, using a discipline called
copy on write.)
typedef char_allocator allocator_type;
The type is a synonym for
char_allocator.
string& append(const value_type *ptr);
string& append(const value_type *ptr,
size_type count);
string& append(const string& right,
size_type roff, size_type count);
string& append(const string& right);
string& append(size_type count, value_type ch);
string& append(const_iterator first,
const_iterator last);The
member functions each append the
operand sequence to the end of the
sequence controlled by *this,
then return *this.
string& assign(const value_type *ptr);
string& assign(const value_type *ptr,
size_type count);
string& assign(const string& right,
size_type roff, size_type count);
string& assign(const string& right);
string& assign(size_type count, value_type ch);
string& assign(const_iterator first,
const_iterator last);The
member functions each replace
the sequence controlled by *this with the
operand sequence, then return *this.
const_reference at(size_type off) const;
reference at(size_type off);
The member functions each return a reference to the element of the
controlled sequence at position off,
or report an out-of-range error.
string(const value_type *ptr);
string(const value_type *ptr,
const allocator_type& al);
string(const value_type *ptr, size_type count);
string(const value_type *ptr, size_type count,
const allocator_type& al);
string(const string& right);
string(const string& right, size_type roff,
size_type count = npos);
string(const string& right, size_type roff,
size_type count, const allocator_type& al);
string(size_type count, value_type ch);
string(size_type count, value_type ch,
const allocator_type& al);
string();
explicit string(const allocator_type& al);
string(const_iterator first, const_iterator last);
string(const_iterator first, const_iterator last,
const allocator_type& al);All constructors store an
allocator object and
initialize the controlled sequence. The allocator object is the argument
al, if present. For the copy constructor, it is
right.get_allocator().
Otherwise, it is Alloc().
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.
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 string& right) const;
int compare(size_type off, size_type n0,
const string& right) const;
int compare(size_type off, size_type n0,
const string& right, size_type roff, size_type count) const;
int compare(const value_type *ptr) const;
int compare(size_type off, size_type n0,
const value_type *ptr) const;
int compare(size_type off, size_type n0,
const value_type *ptr, size_type off) const;The member functions each compare up to n0 elements of the
controlled sequence beginning with position off, or the
entire controlled sequence if these arguments are not supplied,
to the operand sequence.
Each function returns:
- a negative value if the first differing element in the controlled
sequence compares less than the corresponding element in the operand
sequence (as determined by
traits_type::compare), or if the
two have a common prefix but the operand sequence is longer - zero if the two compare equal element by element and are the same
length
- a positive value otherwise
typedef 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 allocator_type::const_pointer
const_pointer;The type is a synonym for allocator_type::const_pointer.
typedef allocator_type::const_reference
const_reference;The type is a synonym for allocator_type::const_reference.
class const_reverse_iterator;
The type describes an object that can serve as a constant reverse
iterator for the controlled sequence. You can, for example, access each of
the elements in the controlled sequence in reverse order by writing:
string::const_reverse_iterator rit;
for (rit = rbegin(); rit != rend(); ++rit)
process *ritsize_type copy(value_type *ptr, size_type count,
size_type off = 0) const;The member function copies up to count elements from the
controlled sequence, beginning at position off, to the
array of value_type beginning at ptr. 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 where);
string& erase(size_type off = 0,
size_type count = 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 where.
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 count elements of
the controlled sequence beginning at position off, then
returns *this.
size_type find(value_type ch, size_type off = 0) const;
size_type find(const value_type *ptr,
size_type off = 0) const;
size_type find(const value_type *ptr, size_type off,
size_type count) const;
size_type find(const string& right,
size_type off = 0) const;The member functions each find the first (lowest beginning position)
subsequence in the controlled sequence, beginning on or after position
off, 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 ch,
size_type off = 0) const;
size_type find_first_not_of(const value_type *ptr,
size_type off = 0) const;
size_type find_first_not_of(const value_type *ptr,
size_type off, size_type count) const;
size_type find_first_not_of(const string& right,
size_type off = 0) const;The member functions each find the first (lowest position) element of the
controlled sequence, at or after position off, 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 ch,
size_type off = 0) const;
size_type find_first_of(const value_type *ptr,
size_type off = 0) const;
size_type find_first_of(const value_type *ptr,
size_type off, size_type count) const;
size_type find_first_of(const string& right,
size_type off = 0) const;The member functions each find the first (lowest position) element of the
controlled sequence, at or after position off, 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 ch,
size_type off = npos) const;
size_type find_last_not_of(const value_type *ptr,
size_type off = npos) const;
size_type find_last_not_of(const value_type *ptr,
size_type off, size_type count) const;
size_type find_last_not_of(const string& right,
size_type off = npos) const;The member functions each find the last (highest position) element of the
controlled sequence, at or before position off, 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 ch,
size_type off = npos) const;
size_type find_last_of(const value_type *ptr,
size_type off = npos) const;
size_type find_last_of(const value_type *ptr,
size_type off, size_type count = npos) const;
size_type find_last_of(const string& right,
size_type off = npos) const;The member functions each find the last (highest position) element of the
controlled sequence, at or before position off, 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.
string& insert(size_type off, const value_type *ptr);
string& insert(size_type off, const value_type *ptr,
size_type count);
string& insert(size_type off,
const string& right);
string& insert(size_type off,
const string& right, size_type roff, size_type count);
string& insert(size_type off,
size_type count, value_type ch);
iterator insert(iterator where,
value_type ch = value_type());
void insert(iterator where,
const_iterator first, const_iterator last);
void insert(iterator where, size_type count, value_type ch);The member functions each insert, before position off or
before the element pointed to by where in the controlled
sequence, the
operand sequence specified by the
remaining operands. A function that returns a value returns
*this.
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.
string& operator+=(value_type ch);
string& operator+=(const value_type *ptr);
string& operator+=(const string& right);
The operators each append the
operand sequence to the end of the
sequence controlled by *this, then return *this.
string& operator=(value_type ch);
string& operator=(const value_type *ptr);
string& operator=(const string& right);
The operators each replace the sequence controlled by *this
with the
operand sequence,
then return *this.
const_reference operator[](size_type off) const;
reference operator[](size_type off);
The member functions each return a reference to the element of the
controlled sequence at position off. If that position is
invalid, the behavior is undefined. Note, however, that
cstr[cstr.size()] == 0 for the first member function.
typedef allocator_type::pointer
pointer;The type is a synonym for allocator_type::pointer.
void push_back(value_type ch);
The member function effectively calls
insert(
end(), ch).
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 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.
string& replace(size_type off, size_type n0,
const value_type *ptr);
string& replace(size_type off, size_type n0,
const value_type *ptr, size_type count);
string& replace(size_type off, size_type n0,
const string& right);
string& replace(size_type off, size_type n0,
const string& right, size_type roff, size_type count);
string& replace(size_type off, size_type n0,
size_type count, value_type ch);
string& replace(iterator first, iterator last,
const value_type *ptr);
string& replace(iterator first, iterator last,
const value_type *ptr, size_type count);
string& replace(iterator first, iterator last,
const string& right);
string& replace(iterator first, iterator last,
size_type count, value_type ch);
string& replace(iterator first, iterator last,
const_iterator first2, const_iterator last2);The member functions each replace up to n0 elements of the
controlled sequence beginning with position off, 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.
void reserve(size_type count = 0);
The member function ensures that
capacity()
henceforth returns at least count.
void resize(size_type newsize, value_type ch = value_type());
The member function ensures that
size() henceforth
returns newsize. If it must make the controlled sequence longer,
it appends elements with value ch.
To make the controlled sequence shorter, the member function effectively calls
erase(begin() + newsize, end()).
class reverse_iterator;
The type describes an object that can serve as a reverse
iterator for the controlled sequence. You can, for example, access each of
the elements in the controlled sequence in reverse order by writing:
string::reverse_iterator rit;
for (rit = rbegin(); rit != rend(); ++rit)
process *ritsize_type rfind(value_type ch, size_type off = npos) const;
size_type rfind(const value_type *ptr,
size_type off = npos) const;
size_type rfind(const value_type *ptr,
size_type off, size_type count = npos) const;
size_type rfind(const string& right,
size_type off = npos) const;The member functions each find the last
(highest beginning position) subsequence in
the controlled sequence, beginning on or before position off,
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.
string substr(size_type off = 0,
size_type count = npos) const;The member function returns an object whose controlled sequence is a
copy of up to count elements of the controlled sequence
beginning at position off.
void swap(string& right);
The member function swaps the controlled sequences between
*this and str. If
get_allocator()
== right.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 char_traits traits_type;
The type is a synonym for
char_traits.
typedef allocator_type::value_type
value_type;The type is a synonym for allocator_type::value_type.
class char_allocator {
public:
char_allocator();
pointer allocate(size_type count, const void *hint);
void deallocate(pointer ptr, size_type count);
size_type max_size() const;
bool operator==(char_allocator& left,
char_allocator& right) const;
};The class describes an object that manages
storage allocation and freeing for arrays of objects of type char.
An object of class char_allocator is the
allocator object
used by class
string.
It is used here primarily to minimize differences with full Standard C++.
pointer allocate(size_type count, const void *hint);
The member function allocates storage for
an array of count elements of type char, by calling
operator new(count).
It returns a pointer to the allocated object.
The hint argument is unused here. To supply no
hint, use a null pointer argument instead.
char_allocator();
The constructor does nothing.
void deallocate(pointer ptr, size_type count);
The member function frees storage for
the array of count objects of type
char beginning at ptr, by calling
operator delete(ptr).
The pointer ptr must have been earlier returned by a call to
allocate for an allocator
object that compares equal to *this, allocating an array object
of the same size and type.
size_type max_size() const;
The member function returns the length of the longest sequence
of elements of type char that an object of class
char_allocator might be able to allocate.
bool operator==(char_allocator& left,
char_allocator& right) const;The operator returns true. (Two allocator objects should
compare equal only if an object allocated through one can be deallocated
through the other. If the value of one object is determined from another
by assignment or by construction, the two object should compare equal.)
class char_traits {
public:
typedef char char_type;
typedef int int_type;
typedef streampos pos_type;
typedef streamoff off_type;
typedef mbstate_t state_type;
static void assign(char_type& left, const char_type& right);
static char_type *assign(char_type *first, size_t count,
char_type ch);
static bool eq(const char_type& left,
const char_type& right);
static bool lt(const char_type& left,
const char_type& right);
static int compare(const char_type *first1,
const char_type *first2, size_t count);
static size_t length(const char_type *first);
static char_type *copy(char_type *first1,
const char_type *first2, size_t count);
static char_type *move(char_type *first1,
const char_type *first2, size_t count);
static const char_type *find(const char_type *first,
size_t count, const char_type& ch);
static char_type to_char_type(const int_type& meta);
static int_type to_int_type(const char_type& ch);
static bool eq_int_type(const int_type& left,
const int_type& right);
static int_type eof();
static int_type not_eof(const int_type& meta);
};The class describes various
character traits
for type char.
The class
string
as well as several iostreams classes, including
ios, use this information
to manipulate elements of type char.
None of the member functions of class char_traits may
throw exceptions.
static void assign(char_type& left, const char_type& right);
static char_type *assign(char_type *first, size_t count,
char_type ch);The first static member function assigns right
to left. The second static member function assigns ch
to each element X[N] for N
in the range [0, count).
typedef char char_type;
The type is a synonym for char.
static int compare(const char_type *first1,
const char_type *first2, size_t count);The static member function compares the sequence of length count
beginning at first1to the sequence of the same length beginning
at first2. The function returns:
- a negative value if the first differing element in
first1
(as determined by
eq) compares less
than the corresponding element in first2 (as determined by
lt) - zero if the two compare equal element by element
- a positive value otherwise
static char_type *copy(char_type *first1, const char_type *first2,
size_t count);The static member function copies the sequence of count
elements beginning at first2 to the array beginning at first1,
then returns first1. The source and destination
must not overlap.
static int_type eof();
The static member function returns a value that represents
end-of-file (EOF).
static bool eq(const char_type& left, const char_type& right);
The static member function returns true if left compares
equal to right.
static bool eq_int_type(const int_type& left,
const int_type& right);The static member function returns true if
left compares equal to right.
static const char_type *find(const char_type *first,
size_t count, const char_type& ch);The static member function determines the lowest N
in the range [0, count) for which
eq(first[N], ch)
is true. If successful, it returns first + N. Otherwise,
it returns a null pointer.
typedef int int_type;
The type is a synonym for int.
static size_t length(const char_type *first);
The static member function returns the number of elements
N in the sequence beginning at first
up to but not including the element first[N] which
compares equal to char_type().
static bool lt(const char_type& left, const char_type& right);
The static member function returns true if left compares
less than right.
static char_type *move(char_type *first1, const char_type *first2,
size_t count);The static member function copies the sequence of count
elements beginning at first2 to the array beginning at first1,
then returns first1. The source and destination may overlap.
static int_type not_eof(const int_type& meta);
If
!eq_int_type(
eof(), meta),
the static member function returns meta.
Otherwise, it returns a value other than
eof().
typedef streamoff off_type;
The type is a synonym for
streamoff.
typedef streampos pos_type;
The type is a synonym for
streampos.
typedef mbstate_t state_type;
The type is a synonym for
mbstate_t.
static char_type to_char_type(const int_type& meta);
The static member function returns meta represented as
type Elem. A value of meta that cannot be so
represented yields an unspecified result.
static int_type to_int_type(const char_type& ch);
The static member function returns ch represented as
type int_type. It must be possible to convert any value ch of type
Elem to int_type (by evaluating
meta = to_int_type(ch))
then back to Elem (by evaluating
ch = to_char_type(meta))
and obtain a value that compares equal to ch.
istream& getline(istream& istr,
string& str);
istream& getline(istream& istr,
string& str, char delim);The first function returns getline(istr, str, istr.widen('\n')).
The second function replaces the sequence controlled by
str with a sequence of elements extracted from the stream
istr. In order of testing, extraction stops:
- at end of file
- after the function extracts an element that compares equal to
delim, in which case the element is neither put back nor
appended to the controlled sequence - after the function extracts
str.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 istr.
string operator+(
const string& left,
const string& right);
string operator+(
const string& left,
const char *right);
string operator+(
const string& left,
char right);
string operator+(
const char *left,
const string& right);
string operator+(
char left,
const string& right);The functions each overload operator+ to
concatenate two objects of class
string.
All effectively return
string(left).append(right).
bool operator!=(
const string& left,
const string& right);
bool operator!=(
const string& left,
const char *right);
bool operator!=(
const char *left,
const string& right);The functions each overload operator!= to compare
two objects of class
string. All effectively
return string(left).compare(right)
!= 0.
bool operator==(
const string& left,
const string& right);
bool operator==(
const string& left,
const char *right);
bool operator==(
const char *left,
const string& right);The functions each overload operator== to compare
two objects of class
string. All effectively
return string(left).compare(right)
== 0.
bool operator<(
const string& left,
const string& right);
bool operator<(
const string& left,
const char *right);
bool operator<(
const char *left,
const string& right);The functions each overload operator< to
compare two objects of class
string. All effectively
return string(left).compare(right)
< 0.
ostream& operator<<(
ostream& ostr,
const string& str);The function is a
formatted output functions
that overloads operator<< to
determine the length len =
str.size()
of the sequence controlled by str, and insert the sequence. If
len < ostr.width(),
then the function also inserts a repetition of ostr.width() - len
fill characters.
The repetition precedes the sequence if
(ostr.flags() &
adjustfield !=
left.
Otherwise, the repetition follows the sequence.
The function returns ostr.
bool operator<=(
const string& left,
const string& right);
bool operator<=(
const string& left,
const char *right);
bool operator<=(
const char *left,
const string& right);The functions each overload operator<= to
compare two objects of class
string. All effectively
return string(left).compare(right)
<= 0.
bool operator>(
const string& left,
const string& right);
bool operator>(
const string& left,
const char *right);
bool operator>(
const char *left,
const string& right);The functions each overload operator> to
compare two objects of class
string. All effectively
return string(left).compare(right)
> 0.
bool operator>=(
const string& left,
const string& right);
bool operator>=(
const string& left,
const char *right);
bool operator>=(
const char *left,
const string& right);The functions each overload operator>= to
compare two objects of class
string. All effectively
return string(left).compare(right)
>= 0.
istream& operator>>(
istream& istr,
string& str);The template function overloads operator>> to
replace the sequence controlled by str with a sequence of
elements extracted from the stream istr. Extraction stops:
- at end of file
- after the function extracts
istr.width()
elements, if that value is nonzero - after the function extracts
istr.max_size()
elements - after the function extracts an element
ch for which
isspace(ch)
is true, in which case the character is put back
If the function extracts no elements, it calls
setstate(ios_base::failbit).
In any case, it calls istr.width(0) and
returns *this.
template<class Tr, class Alloc>
void swap(
string& left,
string& right);The template function executes
left.swap(right).
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
79 - strstrea
<strstream>
Include the iostreams
standard header <strstream>
to define several classes that support
iostreams operations on
sequences stored in an allocated array of char object.
Such sequences are easily converted to and from
C strings.
// DECLARATIONS
class strstreambuf;
class istrstream;
class ostrstream;
// END OF DECLARATIONSclass strstreambuf : public streambuf {
public:
explicit strstreambuf(streamsize count = 0);
strstreambuf(void (*allocfunc)(size_t),
void (*freefunc)(void *));
strstreambuf(char *getptr, streamsize count,
char *putptr = 0);
strstreambuf(signed char *getptr, streamsize count,
signed char *putptr = 0);
strstreambuf(unsigned char *getptr, streamsize count,
unsigned char *putptr = 0);
strstreambuf(const char *getptr, streamsize count);
strstreambuf(const signed char *getptr, streamsize count);
strstreambuf(const unsigned char *getptr, streamsize count);
void freeze(bool freezeit = true);
char *str();
streamsize pcount();
protected:
virtual streampos seekoff(streamoff off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual streampos seekpos(streampos sp,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual int underflow();
virtual int pbackfail(int meta = EOF);
virtual int overflow(int meta = EOF);
};The class describes a
stream buffer that controls
the transmission of elements to and from a sequence of elements
stored in a char array object. Depending on how it
is constructed, the object can be allocated, extended, and
freed as necessary to accommodate changes in the sequence.
An object of class strstreambuf
stores several bits of mode information as its
strstreambuf mode.
These bits indicate whether the controlled sequence:
- has been allocated,
and hence needs to be freed eventually
- is modifiable
- is extendable by reallocating storage
- has been frozen
and hence needs to be unfrozen before the object is destroyed,
or freed (if allocated) by an agency other than the object
A controlled sequence that is frozen cannot be modified or extended,
regardless of the state of these separate mode bits.
The object also stores pointers to two functions that control
strstreambuf allocation.
If these are null pointers, the object devises its own method
of allocating and freeing storage for the controlled sequence.
void freeze(bool freezeit = true);
If freezeit is true, the function alters the stored
strstreambuf mode to make the
controlled sequence frozen. Otherwise, it makes the controlled
sequence not frozen.
streamsize pcount();
The member function returns a count of the number of elements
written to the controlled sequence. Specifically, if
pptr() is a
null pointer, the function returns zero. Otherwise, it returns
pptr() -
pbase().
virtual int overflow(int meta = EOF);
If meta != EOF,
the protected virtual member function endeavors to insert the element
(char)meta
into the
output buffer.
It can do so in various ways:
- If a write position
is available, it can store the element into the write position
and increment the next pointer for the output buffer.
- If the stored
strstreambuf mode says the
controlled sequence is modifiable, extendable, and not frozen,
the function can make a write position available by allocating
new for the output buffer. (Extending the
output buffer this way also extends any associated
input buffer.)
If the function cannot succeed, it returns
EOF. Otherwise, if meta == EOF it returns some
value other than EOF. Otherwise, it returns meta.
virtual int pbackfail(int meta = EOF);
The protected virtual member function endeavors to put back an element
into the
input buffer,
then make it the current element (pointed to
by the next pointer).
If meta == EOF,
the element to push back is effectively the one already in the stream
before the current element. Otherwise, that element is replaced by
ch = (char)meta.
The function can put back an element in various ways:
- If a putback position
is available, and the element stored there compares equal to
ch,
it can simply decrement the next pointer for the input buffer. - If a putback position is available,
and if the strstreambuf mode
says the controlled sequence is modifiable, the function
can store
ch into the putback position and decrement the
next pointer for the input buffer.
If the function cannot succeed, it returns
EOF. Otherwise, if meta == EOF it returns some
value other than EOF. Otherwise, it returns meta.
virtual streampos seekoff(streamoff off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
strstreambuf, a stream position consists
purely of a stream offset. Offset zero designates the first element
of the controlled sequence.
The new position is determined as follows:
- If
way ==
ios_base::beg,
the new position is the beginning of the stream plus off. - If
way ==
ios_base::cur,
the new position is the current stream position plus off. - If
way ==
ios_base::end,
the new position is the end of the stream plus off.
If
which & ios_base::in is nonzero and
the input buffer exist,
the function alters the next position to read in the
input buffer.
If which & ios_base::out is also nonzero,
way != ios_base::cur,
and the output buffer exists,
the function also sets the next position to write to
match the next position to read.
Otherwise, if which & ios_base::out is nonzero
and the output buffer exists,
the function alters the next position to write in the
output buffer.
Otherwise, the positioning operation fails.
For a positioning operation to succeed, the resulting
stream position must lie within the controlled sequence.
If the function succeeds in altering either or both stream positions,
it returns the resultant stream position.
Otherwise, it fails and returns an invalid stream position.
virtual streampos seekpos(streampos sp,
ios_base::openmode which =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
strstreambuf, a stream position consists
purely of a stream offset. Offset zero designates the first element
of the controlled sequence. The new position is determined
by sp.
If
which & ios_base::in is nonzero
and the input buffer exists,
the function alters the next position to read in the
input buffer.
(If which & ios_base::out is nonzero
and the output buffer exists,
the function also sets the next position to write to
match the next position to read.)
Otherwise, if which & ios_base::out is nonzero
and the output buffer exists,
the function alters the next position to write in the
output buffer.
Otherwise, the positioning operation fails.
For a positioning operation to succeed, the resulting
stream position must lie within the controlled sequence.
If the function succeeds in altering either or both stream positions,
it returns the resultant stream position.
Otherwise, it fails and returns an invalid stream position.
char *str();
The member function calls
freeze(), then
returns a pointer to the beginning of the controlled sequence.
(Note that no terminating null element exists, unless you insert
one explicitly.)
explicit strstreambuf(streamsize count = 0);
strstreambuf(void (*allocfunc)(size_t),
void (*freefunc)(void *));
strstreambuf(char *getptr, streamsize count,
char *putptr = 0);
strstreambuf(signed char *getptr, streamsize count,
signed char *putptr = 0);
strstreambuf(unsigned char *getptr, streamsize count,
unsigned char *putptr = 0);
strstreambuf(const char *getptr, streamsize count);
strstreambuf(const signed char *getptr, streamsize count);
strstreambuf(const unsigned char *getptr, streamsize count);The first constructor stores a null pointer in all the pointers
controlling the
input buffer, the
output buffer, and
strstreambuf allocation.
It sets the stored
strstreambuf mode to make the
controlled sequence modifiable and extendable.
And it accepts count as a suggested initial allocation size.
The second constructor behaves much as the first, except that
it stores allocfunc as the pointer to the function to
call to allocate storage, and freefunc as the pointer
to the function to call to free that storage.
The three constructors:
strstreambuf(char *getptr, streamsize count,
char *putptr = 0);
strstreambuf(signed char *getptr, streamsize count,
signed char *putptr = 0);
strstreambuf(unsigned char *getptr, streamsize count,
unsigned char *putptr = 0);also behave much as the first, except that getptr
designates the array object used to hold the controlled
sequence. (Hence, it must not be a null pointer.) The number
of elements N in the array is determined as
follows:
- If
(count > 0), then N is count. - If
(count == 0), then N is
strlen((const char *)getptr). - If
(count < 0), then N is
INT_MAX.
If putptr is a null pointer, the function establishes
just an input buffer, by executing:
setg(getptr, getptr, getptr + N);
Otherwise, it establishes both input and output buffers, by
executing:
setg(getptr, getptr, putptr);
setp(putptr, getptr + N);
In this case, putptr must be in the interval
[getptr, getptr + N].
Finally, the three constructors:
strstreambuf(const char *getptr, streamsize count);
strstreambuf(const signed char *getptr, streamsize count);
strstreambuf(const unsigned char *getptr, streamsize count);
all behave the same as:
streambuf((char *)getptr, count);
except that the stored mode makes the controlled sequence neither
modifiable not extendable.
virtual int underflow();
The protected virtual member function endeavors to extract the current
element ch from the
input buffer,
then advance the current stream position, and return the element as
(int)(unsigned char)ch.
It can do so in only one way:
If a read position
is available, it takes ch as the element stored
in the read position and advances the next pointer for the input buffer.
If the function cannot succeed, it returns
EOF. Otherwise,
it returns the current element in the input stream,
converted as described above.
class istrstream : public istream {
public:
explicit istrstream(const char *ptr);
explicit istrstream(char *ptr);
istrstream(const char *ptr, streamsize count);
istrstream(char *ptr, streamsize count);
strstreambuf *rdbuf() const;
char *str();
};The class describes an object that controls
extraction of elements and encoded objects from a
stream buffer of class
strstreambuf.
The object stores an ojbect of class
strstreambuf.
explicit istrstream(const char *ptr);
explicit istrstream(char *ptr);
istrstream(const char *ptr, streamsize count);
istrstream(char *ptr, streamsize count);
All the constructors initialize the base class by calling
istream(sb),
where sb is the stored object of class
strstreambuf.
The first two constructors also initialize sb by calling
strstreambuf((const
char *)ptr, 0). The remaining two constructors instead call
strstreambuf((const char *)ptr, count).
strstreambuf *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
strstreambuf.
char *str();
The member function returns
rdbuf()->
str().
class ostrstream : public ostream {
public:
ostrstream();
ostrstream(char *ptr, streamsize count,
ios_base::openmode mode = ios_base::out);
strstreambuf *rdbuf() const;
void freeze(bool freezeit = true);
char *str();
streamsize pcount() const;
};The class describes an object that controls
insertion of elements and encoded objects into a
stream buffer of class
strstreambuf.
The object stores an ojbect of class
strstreambuf.
void freeze(bool freezeit = true)
The member function calls
rdbuf()->
freeze(freezeit).
ostrstream();
ostrstream(char *ptr, streamsize count,
ios_base::openmode mode = ios_base::out);Both constructors initialize the base class by calling
ostream(sb),
where sb is the stored object of class
strstreambuf.
The first constructor also initializes sb by calling
strstreambuf().
The second constructor initializes the base class one of two ways:
- If
mode &
ios_base::app == 0, then
ptr must designate the first element of an array of count
elements, and the constructor calls
strstreambuf(ptr, count, ptr). - Otherwise,
ptr must designate the first element of an
array of count elements that contains a
C string
whose first element is designated
by ptr, and the constructor calls
strstreambuf(ptr, count, ptr +
strlen(ptr).
streamsize pcount() const;
The member function returns
rdbuf()->
pcount().
strstreambuf *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
strstreambuf.
char *str();
The member function returns
rdbuf()->
str().
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
80 - time
<time.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
81 - utility
<utility>
Include the STL
standard header <utility>
to define several templates of general use
throughout the Standard Template Library.
Four template operators --
operator!=,
operator<=,
operator>, and
operator>= -- define a
total ordering
on pairs of operands of the same type, given definitions of
operator== and operator<.
If an implementation
supports namespaces,
these template operators are defined in the
rel_ops namespace,
nested within the std namespace.
If you wish to make use of these template operators,
write the declaration:
using namespace std::rel_ops;
which promotes the template operators into the current namespace.
namespace std {
template<class T, class Ty2>
struct pair;
// TEMPLATE FUNCTIONS
template<class Ty1, class Ty2>
pair<Ty, Ty2> make_pair(Ty1 val1, Ty2 val2);
template<class Ty1, class Ty2>
bool operator==(const pair<Ty, Ty2>& left,
const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
bool operator!=(const pair<Ty, Ty2>& left,
const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
bool operator<(const pair<Ty, Ty2>& left,
const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
bool operator>(const pair<Ty1, Ty2>& left,
const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
bool operator<=(const pair<Ty1, Ty2>& left,
const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
bool operator>=(const pair<Ty1, Ty2>& left,
const pair<Ty1, Ty2>& right);
namespace rel_ops {
template<class Ty>
bool operator!=(const Ty& left, const Ty& right);
template<class Ty>
bool operator<=(const Ty& left, const Ty& right);
template<class Ty>
bool operator>(const Ty& left, const Ty& right);
template<class Ty>
bool operator>=(const Ty& left, const Ty& right);
};
};template<class Ty1, class Ty2>
pair<Ty1, Ty2> make_pair(Ty1 val1, Ty2 val2);The template function returns
pair<Ty1, Ty2>(val1, val2).
template<class Ty>
bool operator!=(const Ty& left, const Ty& right);
template<class Ty1, class Ty2>
bool operator!=(const pair<Ty1, Ty2>& left,
const pair<Ty1, Ty2>& right);The template function returns !(left == right).
template<class Ty1, class Ty2>
bool operator==(const pair<Ty1, Ty2>& left,
const pair<Ty1, Ty2>& right);The template function returns
left.first == right.first &&
left.second == right.second.
template<class Ty1, class Ty2>
bool operator<(const pair<Ty1, Ty2>& left,
const pair<Ty1, Ty2>& right);The template function returns
left.first < right.first ||
!(right.first < left.first &&
left.second < right.second).
template<class Ty>
bool operator<=(const Ty& left, const Ty& right);
template<class Ty1, class Ty2>
bool operator<=(const pair<Ty1, Ty2>& left,
const pair<Ty1, Ty2>& right);The template function returns !(right < left).
template<class Ty>
bool operator>(const Ty& left, const Ty& right);
template<class Ty1, class Ty2>
bool operator>(const pair<Ty1, Ty2>& left,
const pair<Ty1, Ty2>& right);The template function returns right < left.
template<class Ty>
bool operator>=(const Ty& left, const Ty& right);
template<class Ty1, class Ty2>
bool operator>=(const pair<Ty1, Ty2>& left,
const pair<Ty1, Ty2>& right);The template function returns !(left < right).
template<class Ty1, class Ty2>
struct pair {
typedef Ty1 first_type;
typedef Ty2 second_type
Ty1 first;
Ty2 second;
pair();
pair(const Ty1& val1, const Ty2& val2);
template<class Other1, class Other2>
pair(const pair<Other1, Other2>& right);
};The template class stores a pair of objects,
first,
of type Ty1, and
second,
of type Ty2. The type definition
first_type,
is the same as the template parameter Ty1, while
second_type,
is the same as the template parameter Ty2.
The first (default) constructor initializes
first to Ty1() and second
to Ty2(). The second constructor initializes
first to val1 and second
to val2. The third (template) constructor initializes
first to right.first and second
to right.second. Ty1 and Ty2 each
need supply only a default constructor, single-argument constructor,
and a destructor.
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
82 - vector
<vector>
Include the STL
standard header <vector> to define the
container
template class vector and several supporting
templates.
namespace std {
template<class Ty, class Alloc>
class vector;
template<class Alloc>
class vector<bool>;
// TEMPLATE FUNCTIONS
template<class Ty, class Alloc>
bool operator==(
const vector<Ty, Alloc>& left,
const vector<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator!=(
const vector<Ty, Alloc>& left,
const vector<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator<(
const vector<Ty, Alloc>& left,
const vector<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator>(
const vector<Ty, Alloc>& left,
const vector<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator<=(
const vector<Ty, Alloc>& left,
const vector<Ty, Alloc>& right);
template<class Ty, class Alloc>
bool operator>=(
const vector<Ty, Alloc>& left,
const vector<Ty, Alloc>& right);
template<class Ty, class Alloc>
void swap(
vector<Ty, Alloc>& left,
vector<Ty, Alloc>& right);
};template<class Ty, class Alloc>
bool operator!=(
const vector <Ty, Alloc>& left,
const vector <Ty, Alloc>& right);The template function returns !(left == right).
template<class Ty, class Alloc>
bool operator==(
const vector <Ty, Alloc>& left,
const vector <Ty, Alloc>& right);The template function overloads operator== to compare
two objects of template class
vector. The function returns
left.size() == right.size() &&
equal(left.
begin(), left.
end(), right.begin()).
template<class Ty, class Alloc>
bool operator<(
const vector <Ty, Alloc>& left,
const vector <Ty, Alloc>& right);The template function overloads operator< to compare
two objects of template class
vector. The function returns
lexicographical_compare(left.
begin(), left.
end(), right.begin(), right.end()).
template<class Ty, class Alloc>
bool operator<=(
const vector <Ty, Alloc>& left,
const vector <Ty, Alloc>& right);The template function returns !(right < left).
template<class Ty, class Alloc>
bool operator>(
const vector <Ty, Alloc>& left,
const vector <Ty, Alloc>& right);The template function returns right < left.
template<class Ty, class Alloc>
bool operator>=(
const vector <Ty, Alloc>& left,
const vector <Ty, Alloc>& right);The template function returns !(left < right).
template<class Ty, class Alloc>
void swap(
vector <Ty, Alloc>& left,
vector <Ty, Alloc>& right);The template function executes
left.swap(right).
allocator_type
· assign
· at
· back
· begin
· capacity
· clear
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· difference_type
· empty
· end
· erase
· front
· get_allocator
· insert
· iterator
· max_size
· operator[]
· pointer
· pop_back
· push_back
· rbegin
· reference
· rend
· reserve
· resize
· reverse_iterator
· size
· size_type
· swap
· value_type
· vector
template<class Ty, class Alloc = allocator<Ty> >
class vector {
public:
typedef Alloc allocator_type;
typedef typename Alloc::pointer pointer;
typedef typename Alloc::const_pointer
const_pointer;
typedef typename Alloc::reference reference;
typedef typename Alloc::const_reference
const_reference;
typedef typename Alloc::value_type value_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;
vector();
explicit vector(const Alloc& al);
explicit vector(size_type count);
vector(size_type count, const Ty& val);
vector(size_type count, const Ty& val,
const Alloc& al);
vector(const vector& right);
template<class InIt>
vector(InIt first, InIt last);
template<class InIt>
vector(InIt first, InIt last,
const Alloc& al);
void reserve(size_type count);
size_type capacity() const;
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;
void resize(size_type newsize);
void resize(size_type newsize, Ty val);
size_type size() const;
size_type max_size() const;
bool empty() const;
Alloc get_allocator() const;
reference at(size_type off);
const_reference at(size_type off) const;
reference operator[](size_type off);
const_reference operator[](size_type off);
reference front();
const_reference front() const;
reference back();
const_reference back() const;
void push_back(const Ty& val);
void pop_back();
template<class InIt>
void assign(InIt first, InIt last);
void assign(size_type count, const Ty& val);
iterator insert(iterator where, const Ty& val);
void insert(iterator where, size_type count, const Ty& val);
template<class InIt>
void insert(iterator where, InIt first, InIt last);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
void clear();
void swap(vector& right);
};The template class describes an object that controls a
varying-length sequence of elements of type Ty.
The sequence is stored as an array of Ty.
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class Alloc. Such an allocator object must have
the same external interface as an object of template class
allocator.
Note that the stored allocator object is not copied when the container
object is assigned.
Vector reallocation
occurs when a member function must grow the controlled sequence
beyond its current storage capacity.
Other insertions and erasures may alter various storage addresses
within the sequence. In all such cases,
iterators or references that point at
altered portions of the controlled sequence become
invalid.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
template<class InIt>
void assign(InIt first, InIt last);
void assign(size_type count, const Ty& val);If InIt is an integer type, the first member
function behaves the same as assign((size_type)first, (Ty)last).
Otherwise, the
first member function replaces the sequence
controlled by *this with the sequence
[first, last), which must not overlap
the initial controlled sequence.
The second member function replaces the sequence
controlled by *this with a repetition of count
elements of value val.
const_reference at(size_type off) const;
reference at(size_type off);
The member function returns a reference to the element of the
controlled sequence at position off. If that position is
invalid, the function throws an object of class
out_of_range.
reference back();
const_reference back() const;
The member function returns a reference to the last element of the
controlled sequence, which must be non-empty.
const_iterator begin() const;
iterator begin();
The member function returns a random-access iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
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()).
typedef 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 Alloc::const_pointer
const_pointer;The type describes an object that can serve as a constant pointer
to an element of the controlled sequence.
typedef typename Alloc::const_reference
const_reference;The type describes an object that can serve as a constant reference
to an element of the controlled sequence.
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.
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 function returns a random-access iterator that points
just beyond the end of the sequence.
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
The first member function removes the element of the controlled
sequence pointed to by where. The second member function
removes the elements of the controlled sequence
in the range [first, last).
Both return an iterator that designates the first element remaining
beyond any elements removed, or
end() if no such element exists.
Erasing N elements causes N destructor calls
and an assignment for each of the elements between the insertion
point and the end of the sequence. No
reallocation occurs,
so iterators and references become
invalid only from the first element
erased through the end of the sequence.
The member functions throw an exception only if a copy operation
throws an exception.
reference front();
const_reference front() const;
The member function returns a reference to the first element of the
controlled sequence, which must be non-empty.
Alloc get_allocator() const;
The member function returns the stored
allocator object.
iterator insert(iterator where, const Ty& val);
void insert(iterator where, size_type count, const Ty& val);
template<class InIt>
void insert(iterator where, InIt first, InIt last);Each of the member functions inserts, before the element pointed to
by where in the controlled sequence, a sequence
specified by the remaining operands. The first member function inserts
a single element with value val and returns an iterator
that designates the newly inserted element. The second member function
inserts a repetition of count elements of value val.
If InIt is an integer type, the last member
function behaves the same as insert(where, (size_type)first, (Ty)last).
Otherwise, the
last member function inserts the sequence
[first, last), which must not overlap
the initial controlled sequence.
When inserting a single element, the number of
element copies is linear in the number of elements between the insertion
point and the end of the sequence. When inserting a single element
at the end of the sequence, the amortized number of element copies
is constant. When inserting N elements,
the number of element copies
is linear in N plus the number of elements
between the insertion point and the end of the sequence
-- except when the template member
is specialized for InIt an input iterator, which
behaves like N single insertions.
If
reallocation occurs, the capacity
increases by a fixed factor (at least),
and all iterators and references become
invalid.
If no reallocation occurs, iterators become invalid
only from the point of insertion through the end of the sequence.
If an exception is thrown during the
insertion of one or more elements, and the exception is not thrown while
copying an element, the container is left unaltered
and the exception is rethrown.
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 max_size() const;
The member function returns the length of the longest sequence that
the object can control.
const_reference operator[](size_type off) const;
reference operator[](size_type off);
The member function returns a reference to the element of the
controlled sequence at position off. If that position is
invalid, the behavior is undefined.
typedef typename Alloc::pointer pointer;
The type describes an object that can serve as a pointer to an
element of the controlled sequence.
void pop_back();
The member function removes the last element of the
controlled sequence, which must be non-empty.
The member function never throws an exception.
void push_back(const Ty& val);
The member function inserts an element with value val
at the end of the controlled sequence.
If an exception is thrown, the container is left unaltered
and the exception is rethrown.
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 Alloc::reference reference;
The type describes an object that can serve as a reference to an
element of the controlled sequence.
const_reverse_iterator rend() const;
reverse_iterator rend();
The member function returns a reverse iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, it designates the end of the reverse sequence.
void reserve(size_type count);
If count is greater than
max_size(),
the member function reports a
length error by
throwing an object of class length_error.
Otherwise, it ensures that
capacity()
henceforth returns at least count.
void resize(size_type newsize);
void resize(size_type newsize, Ty val);
The member functions both ensure that
size() henceforth
returns newsize. If it must make the controlled sequence longer,
the first member function appends elements with value Ty(),
while the second member function appends elements with value val.
To make the controlled sequence shorter, both member functions call
erase(begin() + newsize, 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 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.
void swap(vector& right);
The member function swaps the controlled sequences between
*this and right. If
get_allocator()
== right.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 typename Alloc::value_type value_type;
The type is a synonym for the template parameter Ty.
vector();
explicit vector(const Alloc& al);
explicit vector(size_type count);
vector(size_type count, const Ty& val);
vector(size_type count, const Ty& val, const Alloc& al);
vector(const vector& right);
template<class InIt>
vector(InIt first, InIt last);
template<class InIt>
vector(InIt first, InIt last, const Alloc& 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
right.get_allocator().
Otherwise, it is Alloc().
The first two constructors specify an
empty initial controlled sequence. The third constructor specifies
a repetition of count elements of value Ty().
The fourth and fifth constructors specify
a repetition of count elements of value val.
The sixth constructor specifies a copy of the sequence controlled by
right.
If InIt is an integer type, the last two constructors
specify a repetition of (size_type)first elements of value
(Ty)last. Otherwise, the
last two constructors specify the sequence
[first, last).
template<class Alloc>
class vector<bool, Alloc> {
public:
class reference;
typedef bool const_reference;
typedef T0 iterator;
typedef T1 const_iterator;
typedef T4 pointer;
typedef T5 const_pointer;
void flip();
static void swap(reference left, reference right);
// rest same as template class vector
};The class is a partial specialization of template class
vector for elements of type
bool. It alters the definition of four member
types (to optimize the packing and unpacking of elements)
and adds two member functions. Its behavior is otherwise
the same as for template class vector.
typedef 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 unspecified type T1.
typedef T5 const_pointer;
The type describes an object that can serve as a pointer
to a constant element of the controlled sequence. It is described here as a
synonym for the unspecified type T5.
typedef bool const_reference;
The type describes an object that can serve as a constant reference
to an element of the controlled sequence, in this case bool.
void flip();
The member function inverts the values of all the members of the
controlled sequence.
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 unspecified type T0.
typedef T4 pointer;
The type describes an object that can serve as a pointer
to an element of the controlled sequence. It is described here as a
synonym for the unspecified type T4.
class reference {
public:
reference& operator=(const reference& right);
reference& operator=(bool val);
void flip();
bool operator~() const;
operator bool() const;
};The type describes an object that can serve as a reference to an
element of the controlled sequence. Specifically, for two objects
ref and ref2 of class reference:
bool(ref) yields the value of the element
designated by ref~ref yields the inverted value of the element
designated by refref.flip() inverts the value designated by refref2 = bool(ref) and ref2 = ref
both assign the value of the element
designated by ref to the element designated by ref2
It is unspecified how member functions of class
vector<bool> construct objects of
class reference that designate elements of a controlled
sequence. The default constructor for class reference
generates an object that refers to no such element.
void swap(reference left, reference right);
The static member function swaps the members of the
controlled sequences designated by left and right.
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.