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 basic_string<Elem, Tr, Alloc>& str,
typename basic_string<Elem, Tr, Alloc>::size_type
pos = 0,
typename basic_string<Elem, Tr, Alloc>::size_type
count = basic_string<Elem, Tr, Alloc>::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>
basic_string<Elem, Tr, Alloc> 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 basic_string<Elem, Tr, Alloc>& str,
typename basic_string<Elem, Tr, Alloc>::size_type
pos = 0,
typename basic_string<Elem, Tr, Alloc>::size_type
count = basic_string<Elem, Tr, Alloc>::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>
basic_string<Elem, Tr, Alloc> to_string() const;The member function constructs str, an object of class
basic_string<Elem, Tr, Alloc>.
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
basic_string<Elem,
Tr, allocator<Elem> >& 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 define the macros traditionally defined in the Standard C library header
<ctype.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 <ctype.h>
#endif
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.
(Amendment 1 adds the type
mbstate_t,
which describes an object that can store a conversion state.
It also relaxes the above rules for
generalized multibyte characters, which describe the encoding
rules for a broad range of
wide streams.)
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:
btowc,
mblen,
mbrlen,
mbrtowc,
mbsrtowcs,
mbstowcs,
mbtowc,
wcrtomb,
wcsrtombs,
wcstombs,
wctob, and
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 - ciso646
<ciso646>
Include the standard header <ciso646>
to effectively include the standard header
<iso646.h>.
#include <iso646.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
10 - 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.
11 - clocale
<clocale>
Include the standard header <clocale>
to define the macros traditionally defined in the Standard C library header
<locale.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 <locale.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
12 - cmath
<cmath>
Include the standard header <cmath>
to define the macros traditionally defined in the Standard C library header
<math.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 <math.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
13 - complex
<complex>
abs
· arg
· complex
· complex<double>
· complex<float>
· complex<long double>
· conj
· cos
· cosh
· exp
· 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 template class complex and a host of
supporting template functions.
Unless otherwise specified,
functions that can return multiple values return an imaginary
part in the half-open interval (-pi, pi].
namespace std {
#define __STD_COMPLEX
// TEMPLATE CLASSES
template<class Ty>
class complex;
template<>
class complex<float>;
template<>
class complex<double>;
template<>
class complex<long double>;
// TEMPLATE FUNCTIONS
template<class Ty>
complex<Ty> operator+(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator+(const complex<Ty>& left,
const Ty& right);
template<class Ty>
complex<Ty> operator+(const Ty& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator-(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator-(const complex<Ty>& left,
const Ty& right);
template<class Ty>
complex<Ty> operator-(const Ty& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator*(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator*(const complex<Ty>& left,
const Ty& right);
template<class Ty>
complex<Ty> operator*(const Ty& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator/(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator/(const complex<Ty>& left,
const Ty& right);
template<class Ty>
complex<Ty> operator/(const Ty& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator+(const complex<Ty>& left);
template<class Ty>
complex<Ty> operator-(const complex<Ty>& left);
template<class Ty>
bool operator==(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
bool operator==(const complex<Ty>& left,
const Ty& right);
template<class Ty>
bool operator==(const Ty& left,
const complex<Ty>& right);
template<class Ty>
bool operator!=(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
bool operator!=(const complex<Ty>& left,
const Ty& right);
template<class Ty>
bool operator!=(const Ty& left,
const complex<Ty>& right);
template<class Ty, class Elem, class Tr>
basic_istream<Elem, Tr>&
operator>>(basic_istream<Elem, Tr>& istr,
complex<Ty>& right);
template<class Ty, class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
const complex<Ty>& right);
template<class Ty>
Ty real(const complex<Ty>& left);
template<class Ty>
Ty imag(const complex<Ty>& left);
template<class Ty>
Ty abs(const complex<Ty>& left);
template<class Ty>
Ty arg(const complex<Ty>& left);
template<class Ty>
Ty norm(const complex<Ty>& left);
template<class Ty>
complex<Ty> conj(const complex<Ty>& left);
template<class Ty>
complex<Ty> polar(const Ty& rho, const Ty& theta = 0);
template<class Ty>
complex<Ty> cos(const complex<Ty>& left);
template<class Ty>
complex<Ty> cosh(const complex<Ty>& left);
template<class Ty>
complex<Ty> exp(const complex<Ty>& left);
template<class Ty>
complex<Ty> log(const complex<Ty>& left);
template<class Ty>
complex<Ty> log10(const complex<Ty>& left);
template<class Ty>
complex<Ty> pow(const complex<Ty>& left, int right);
template<class Ty>
complex<Ty> pow(const complex<Ty>& left, const Ty& right);
template<class Ty>
complex<Ty> pow(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> pow(const Ty& left, const complex<Ty>& right);
template<class Ty>
complex<Ty> sin(const complex<Ty>& left);
template<class Ty>
complex<Ty> sinh(const complex<Ty>& left);
template<class Ty>
complex<Ty> sqrt(const complex<Ty>& left);
};template<class Ty>
Ty abs(const complex<Ty>& left);The function returns the magnitude of left.
template<class Ty>
Ty arg(const complex<Ty>& 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);
template<class Other>
complex(const complex<Other>& right);
template<class Other>
complex& operator=(const complex<Other>& right);
template<class Other>
complex& operator+=(const complex<Other>& right);
template<class Other>
complex& operator-=(const complex<Other>& right);
template<class Other>
complex& operator*=(const complex<Other>& right);
template<class Other>
complex& operator/=(const complex<Other>& 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 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.
An object of class Ty:
- has a public default constructor, destructor,
copy constructor, and assignment operator -- with
conventional behavior
- can be assigned integer or floating-point values, or
type cast to such values -- with
conventional behavior
- defines the arithmetic operators and math functions, as needed,
that are defined for the floating-point
types -- with conventional behavior
In particular, no subtle differences may exist between copy construction
and default construction followed by assignment. And none of the operations
on objects of class Ty may throw exceptions.
Explicit specializations of template class complex
exist for the three floating-point types. In this
implementation, a value of any other
type Ty is type cast to double for actual calculations,
with the double result assigned back to the stored object
of type Ty.
complex(const Ty& realval = 0, const Ty& imagval = 0);
template<class Other>
complex(const complex<Other>& 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().
In this
implementation, if a
translator does not support member template functions, the template:
template<class Other>
complex(const complex<Other>& right);is replaced by:
complex(const complex& right);
which is the copy constructor.
Ty imag() const;
The member function returns the stored imaginary part.
template<class Other>
complex& operator*=(const complex<Other>& 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.
In this
implementation, if a
translator does not support member template functions, the template:
template<class Other>
complex& operator*=(const complex<Other>& right);is replaced by:
complex& operator*=(const complex& right);
template<class Other>
complex& operator+=(const complex<Other>& 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.
In this
implementation, if a
translator does not support member template functions, the template:
template<class Other>
complex& operator+=(const complex<Other>& right);is replaced by:
complex& operator+=(const complex& right);
template<class Other>
complex& operator-=(const complex<Other>& 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.
In this
implementation, if a
translator does not support member template functions, the template:
template<class Other>
complex& operator-=(const complex<Other>& right);is replaced by:
complex& operator-=(const complex& right);
template<class Other>
complex& operator/=(const complex<Other>& 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.
In this
implementation, if a
translator does not support member template functions, the template:
template<class Other>
complex& operator/=(const complex<Other>& right);is replaced by:
complex& operator/=(const complex& right);
template<class Other>
complex& operator=(const complex<Other>& 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.
In this
implementation, if a
translator does not support member template functions, the template:
template<class Other>
complex& operator=(const complex<Other>& right);is replaced by:
complex& operator=(const complex& right);
which is the default assignment operator.
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.
template<>
class complex<double> {
public:
complex(double realval = 0, double imagval = 0);
complex(const complex<float>& right);
explicit complex(const complex<long double>& right);
// rest same as template class complex
};The explicitly specialized template 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
explicit specialization differs only in the constructors it defines.
The first constructor initializes the stored real part to
realval and the stored imaginary part to imagval.
The remaining two constructors initialize the stored real part to
right.real() and the stored imaginary part to
right.imag().
template<>
class complex<float> {
public:
complex(float realval = 0, float imagval = 0);
explicit complex(const complex<double>& right);
explicit complex(const complex<long double>& right);
// rest same as template class complex
};The explicitly specialized template 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
explicit specialization differs only in the constructors it defines.
The first constructor initializes the stored real part to
realval and the stored imaginary part to imagval.
The remaining two constructors initialize the stored real part to
right.real() and the stored imaginary part to
right.imag().
template<>
class complex<long double> {
public:
complex(long double realval = 0, long double imagval = 0);
complex(const complex<float>& right);
complex(const complex<double>& right);
// rest same as template class complex
};The explicitly specialized template class
describes an object that stores two objects
of type long double, one that represents the real part
of a complex number and one that represents the imaginary part. The
explicit specialization differs only in the constructors it defines.
The first constructor initializes the stored real part to
realval and the stored imaginary part to imagval.
The remaining two constructors initialize the stored real part to
right.real() and the stored imaginary part to
right.imag().
template<class Ty>
complex<Ty> conj(const complex<Ty>& left);The function returns the conjugate of left.
template<class Ty>
complex<Ty> cos(const complex<Ty>& left);The function returns the cosine of left.
template<class Ty>
complex<Ty> cosh(const complex<Ty>& left);The function returns the hyperbolic cosine of left.
template<class Ty>
complex<Ty> exp(const complex<Ty>& left);The function returns the exponential of left.
template<class Ty>
Ty imag(const complex<Ty>& left);The function returns the imaginary part of left.
template<class Ty>
complex<Ty> log(const complex<Ty>& left);The function returns the logarithm of left.
The branch cuts are along the negative real axis.
template<class Ty>
complex<Ty> log10(const complex<Ty>& left);The function returns the base 10
logarithm of left.
The branch cuts are along the negative real axis.
template<class Ty>
Ty norm(const complex<Ty>& left);The function returns the squared magnitude of left.
template<class Ty>
bool operator!=(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
bool operator!=(const complex<Ty>& left,
const Ty& right);
template<class Ty>
bool operator!=(const Ty& left,
const complex<Ty>& right);The operators each return true only if
real(left) != real(right) ||
imag(left) != imag(right).
template<class Ty>
complex<Ty> operator*(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator*(const complex<Ty>& left,
const Ty& right);
template<class Ty>
complex<Ty> operator*(const Ty& left,
const complex<Ty>& right);The operators each convert both operands to the return type,
then return the complex product
of the converted left and right.
template<class Ty>
complex<Ty> operator+(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator+(const complex<Ty>& left,
const Ty& right);
template<class Ty>
complex<Ty> operator+(const Ty& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator+(const complex<Ty>& 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.
template<class Ty>
complex<Ty> operator-(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator-(const complex<Ty>& left,
const Ty& right);
template<class Ty>
complex<Ty> operator-(const Ty& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator-(const complex<Ty>& 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).
template<class Ty>
complex<Ty> operator/(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> operator/(const complex<Ty>& left,
const Ty& right);
template<class Ty>
complex<Ty> operator/(const Ty& left,
const complex<Ty>& right);The operators each convert both operands to the return type,
then return the complex quotient
of the converted left and right.
template<class Ty, class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
const complex<Ty>& right);The template function inserts the complex value right
in the output stream os, effectively by executing:
basic_ostringstream<Elem, Tr> osstr;
osstr.flags(ostr.flags());
osstr.imbue(ostr.imbue());
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.
template<class Ty>
bool operator==(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
bool operator==(const complex<Ty>& left,
const Ty& right);
template<class Ty>
bool operator==(const Ty& left,
const complex<Ty>& right);The operators each return true only if
real(left) == real(right) &&
imag(left) == imag(right).
template<class Ty, class Elem, class Tr>
basic_istream<Elem, Tr>&
operator>>(basic_istream<Elem, Tr>& istr,
complex<Ty>& 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 Elem,
and re and im are objects of type Ty.
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.
template<class Ty>
complex<Ty> polar(const Ty& rho,
const Ty& theta = 0);The function returns the complex value whose magnitude
is rho and whose phase angle is theta.
template<class Ty>
complex<Ty> pow(const complex<Ty>& left, int right);
template<class Ty>
complex<Ty> pow(const complex<Ty>& left,
const Ty& right);
template<class Ty>
complex<Ty> pow(const complex<Ty>& left,
const complex<Ty>& right);
template<class Ty>
complex<Ty> pow(const Ty& left,
const complex<Ty>& 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.
template<class Ty>
Ty real(const complex<Ty>& left);The function returns the real part of left.
template<class Ty>
complex<Ty> sin(const complex<Ty>& left);The function returns the sine of left.
template<class Ty>
complex<Ty> sinh(const complex<Ty>& left);The function returns the hyperbolic sine of left.
template<class Ty>
complex<Ty> sqrt(const complex<Ty>& 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.
template<class Ty>
complex<Ty> tan(const complex<Ty>& left);The function returns the tangent of left.
template<class Ty>
complex<Ty> tanh(const complex<Ty>& 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.
14 - 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.
15 - 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.
16 - csetjmp
<csetjmp>
Include the standard header <csetjmp>
to define the macros traditionally defined in the Standard C library header
<setjmp.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 <setjmp.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
17 - csignal
<csignal>
Include the standard header <csignal>
to define the macros traditionally defined in the Standard C library header
<signal.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 <signal.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
18 - cstdarg
<cstdarg>
Include the standard header <cstdarg>
to define the macros traditionally defined in the Standard C library header
<stdarg.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 <stdarg.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
19 - cstddef
<cstddef>
Include the standard header <cstddef>
to define the macros traditionally defined in the Standard C library header
<stddef.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 <stddef.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
20 - cstdio
<cstdio>
Include the standard header <cstdio>
to define the macros traditionally defined in the Standard C library header
<stdio.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 <stdio.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
21 - cstdlib
<cstdlib>
Include the standard header <cstdlib>
to define the macros traditionally defined in the Standard C library header
<stdlib.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 <stdlib.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
22 - cstring
<cstring>
Include the standard header <cstring>
to define the macros traditionally defined in the Standard C library header
<string.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 <string.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
23 - ctime
<ctime>
Include the standard header <ctime>
to define the macros traditionally defined in the Standard C library header
<time.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 <time.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
24 - 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.
25 - 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.
26 - 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.
27 - 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.
28 - 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.
29 - exceptio
<exception>
Include the standard header <exception>
to define several types and functions related to the handling
of exceptions.
namespace std {
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();
};class 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.
30 - 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.
31 - 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.
32 - fstream
<fstream>
Include the iostreams
standard header <fstream>
to define several classes that support
iostreams operations on
sequences stored in external
files.
namespace std {
template<class Elem, class Tr = char_traits<Elem> >
class basic_filebuf;
typedef basic_filebuf<char> filebuf;
typedef basic_filebuf<wchar_t> wfilebuf;
template<class Elem, class Tr = char_traits<Elem> >
class basic_ifstream;
typedef basic_ifstream<char> ifstream;
typedef basic_ifstream<wchar_t> wifstream;
template<class Elem, class Tr = char_traits<Elem> >
class basic_ofstream;
typedef basic_ofstream<char> ofstream;
typedef basic_ofstream<wchar_t> wofstream;
template<class Elem, class Tr = char_traits<Elem> >
class basic_fstream;
typedef basic_fstream<char> fstream;
typedef basic_fstream<wchar_t> wfstream;
};template <class Elem, class Tr = char_traits<Elem> >
class basic_filebuf : public basic_streambuf<Elem, Tr> {
public:
typedef typename basic_streambuf<Elem, Tr>::char_type
char_type;
typedef typename basic_streambuf<Elem, Tr>::traits_type
traits_type;
typedef typename basic_streambuf<Elem, Tr>::int_type
int_type;
typedef typename basic_streambuf<Elem, Tr>::pos_type
pos_type;
typedef typename basic_streambuf<Elem, Tr>::off_type
off_type;
basic_filebuf();
bool is_open() const;
basic_filebuf *open(const char *filename,
ios_base::openmode mode);
basic_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 basic_streambuf<Elem, Tr>
*setbuf(Elem *buffer, streamsize count);
};The template class
describes a stream buffer that controls
the transmission of elements
of type Elem, whose
character traits are determined by the
class Tr,
to and from a sequence of elements stored in an external
file.
An object of class
basic_filebuf<Elem, Tr> stores a
file pointer, which designates the
FILE object
that controls the stream
associated with an
open file.
It also stores pointers to two
file conversion facets
for use by the protected member functions
overflow and
underflow.
basic_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 Elem char_type;
The type is a synonym for the template parameter Elem.
basic_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.
For a wide stream,
if any insertions have occured since the stream was opened, or since the last
call to streampos, the function calls
overflow().
It also inserts any sequence needed to restore the
initial conversion state,
by using the
file conversion facet
fac to call
fac.unshift
as needed. Each element byte of type char thus
produced is written to the associated stream designated by the
file pointer fp as if by successive calls of the form
fputc(byte, fp).
If the call to fac.unshift or any write fails,
the function does not succeed.
typedef typename 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 typename traits_type::off_type off_type;
The type is a synonym for
traits_type::off_type.
basic_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 not a null pointer, the function
determines the
file conversion facet:
use_facet<
codecvt<Elem, char,
traits_type::
state_type>
>(getloc()),
for use by
underflow
and
overflow.
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 convert any pending output in the output buffer, followed
by
ch, by using the
file conversion facet
fac to call
fac.out
as needed. Each element ch of type char thus
produced is written 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 typename 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
basic_filebuf<Elem, Tr>, a stream position can be represented
by an object of type
fpos_t, which stores an
offset and any state information needed to parse a
wide stream.
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,
binary streams, and
wide 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
basic_filebuf<Elem, Tr>, a stream position can be represented
by an object of type
fpos_t, which stores an
offset and any state information needed to parse a
wide stream.
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,
binary streams, and
wide streams.
For a wide stream,
if any insertions have occured since the stream was opened, or since the last
call to streampos, the function calls
overflow().
It also inserts any sequence needed to restore the
initial conversion state,
by using the
file conversion facet
fac to call
fac.unshift
as needed. Each element byte of type char thus
produced is written to the associated stream designated by the
file pointer fp as if by successive calls of the form
fputc(byte, fp).
If the call to fac.unshift or any write fails,
the function does not succeed.
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 basic_streambuf<Elem, Tr>
*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 Tr traits_type;
The type is a synonym for the template parameter Tr.
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),
and convert them to an element ch of type Elem
by using the
file conversion facet
fac to call
fac.in
as needed.
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.
template <class Elem, class Tr = char_traits<Elem> >
class basic_fstream : public basic_iostream<Elem, Tr> {
public:
basic_fstream();
explicit basic_fstream(const char *filename,
ios_base::openmode mode =
ios_base::in | ios_base::out);
basic_filebuf<Elem, Tr> *rdbuf() const;
bool is_open() const;
void open(const char *filename,
ios_base::openmode mode =
ios_base::in | ios_base::out);
void close();
};The template class describes an object that controls
insertion and extraction of elements and encoded objects using a
stream buffer of class
basic_filebuf<Elem, Tr>,
with elements of type Elem, whose
character traits are determined
by the class Tr. The object stores an object of class
basic_filebuf<Elem, Tr>.
basic_fstream();
explicit basic_fstream(const char *filename,
ios_base::openmode mode =
ios_base::in | ios_base::out);The first constructor initializes the base class by calling
basic_iostream(sb),
where sb is the stored object of class
basic_filebuf<Elem, Tr>.
It also initializes sb by calling
basic_filebuf<Elem,
Tr>().
The second constructor initializes the base class by calling
basic_iostream(sb).
It also initializes sb by calling
basic_filebuf<Elem,
Tr>(),
then sb.open(filename, mode).
If the latter function returns a null pointer, the constructor calls
setstate(failbit).
voidclose();
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 | ios_base::out);The member function calls
rdbuf()->
open(filename, mode).
If that function returns a null pointer, the function calls
setstate(failbit).
basic_filebuf<Elem, Tr> *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
basic_filebuf<Elem, Tr>.
template <class Elem, class Tr = char_traits<Elem> >
class basic_ifstream : public basic_istream<Elem, Tr> {
public:
basic_filebuf<Elem, Tr> *rdbuf() const;
basic_ifstream();
explicit basic_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 template class describes an object that controls
extraction of elements and encoded objects from a
stream buffer of class
basic_filebuf<Elem, Tr>,
with elements of type Elem, whose
character traits are determined
by the class Tr. The object stores an object of class
basic_filebuf<Elem, Tr>.
basic_ifstream();
explicit basic_ifstream(const char *filename,
ios_base::openmode mode = ios_base::in);The first constructor initializes the base class by calling
basic_istream(sb),
where sb is the stored object of class
basic_filebuf<Elem, Tr>.
It also initializes sb by calling
basic_filebuf<Elem,
Tr>().
The second constructor initializes the base class by calling
basic_istream(sb).
It also initializes sb by calling
basic_filebuf<Elem, Tr>(),
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).
basic_filebuf<Elem, Tr> *rdbuf() const
The member function returns the address of the stored stream buffer.
template <class Elem, class Tr = char_traits<Elem> >
class basic_ofstream : public basic_ostream<Elem, Tr> {
public:
basic_filebuf<Elem, Tr> *rdbuf() const;
basic_ofstream();
explicit basic_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 template class describes an object that controls
insertion of elements and encoded objects into a
stream buffer of class
basic_filebuf<Elem, Tr>,
with elements of type Ele, whose
character traits are determined
by the class Tr. The object stores an object of class
basic_filebuf<Elem, Tr>.
basic_ofstream();
explicit basic_ofstream(const char *filename,
ios_base::openmode which = ios_base::out);The first constructor initializes the base class by calling
basic_ostream(sb),
where sb is the stored object of class
basic_filebuf<Elem, Tr>.
It also initializes sb by calling
basic_filebuf<Elem, Tr>().
The second constructor initializes the base class by calling
basic_ostream(sb).
It also initializes sb by calling
basic_filebuf<Elem, Tr>(),
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).
basic_filebuf<Elem, Tr> *rdbuf() const
The member function returns the address of the stored
stream buffer.
typedef basic_filebuf<char, char_traits<char> > filebuf;
The type is a synonym for template class
basic_filebuf, specialized
for elements of type char with default
character traits.
typedef basic_fstream<char, char_traits<char> > fstream;
The type is a synonym for template class
basic_fstream, specialized
for elements of type char with default
character traits.
typedef basic_ifstream<char, char_traits<char> > ifstream;
The type is a synonym for template class
basic_ifstream, specialized
for elements of type char with default
character traits.
typedef basic_ofstream<char, char_traits<char> >
ofstream;The type is a synonym for template class
basic_ofstream, specialized
for elements of type char with default
character traits.
typedef basic_fstream<wchar_t, char_traits<wchar_t> >
wfstream;The type is a synonym for template class
basic_fstream, specialized
for elements of type wchar_t with default
character traits.
typedef basic_ifstream<wchar_t, char_traits<wchar_t> >
wifstream;The type is a synonym for template class
basic_ifstream, specialized
for elements of type wchar_t with default
character traits.
typedef basic_ofstream<wchar_t, char_traits<wchar_t> >
wofstream;The type is a synonym for template class
basic_ofstream, specialized
for elements of type wchar_t with default
character traits.
typedef basic_filebuf<wchar_t, char_traits<wchar_t> >
wfilebuf;The type is a synonym for template class
basic_filebuf, specialized
for elements of type wchar_t with default
character traits.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
33 - fstream2
<fstream.h>
Include the traditional header <fstream.h>
to effectively include the standard header
<fstream> and hoist its
names outside the
std namespace.
In this
implementation, all
names are hoisted, to provide a more traditional library environment.
#include <fstream>
using namespace std;
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
34 - 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.
35 - 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.
36 - 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.
37 - 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.
38 - 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
basic_istream<Elem,
Tr>::operator>>
and
basic_ostream<Elem,
Tr>::operator<<.
Thus, you can write extractors and inserters such as:
cin >> setbase(8);
cout << setbase(8);
namespace std {
T1 resetiosflags(ios_base::fmtflags mask);
T2 setiosflags(ios_base::fmtflags mask);
T3 setbase(int base);
template<class Elem>
T4 setfill(Elem ch);
T5 setprecision(streamsize prec);
T6 setw(streamsize wide);
};T1 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)
template<class Elem>
T4 setfill(Elem ch);The template manipulator returns an object that, when extracted from or
inserted into the stream str, calls
str.fill(ch),
then returns str. The type Elem must be the
same as the element type for the stream 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.
39 - iomanip2
<iomanip.h>
Include the traditional header <iomanip.h>
to effectively include the standard header
<iomanip> and hoist its
names outside the
std namespace.
In this
implementation, all
names are hoisted, to provide a more traditional library environment.
#include <iomanip>
using namespace std;
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
40 - ios
<ios>
basic_ios
· fpos
· ios
· ios_base
· streamoff
· streampos
· streamsize
· wios
· wstreampos
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 a specialization of one of the template classes
basic_istream or
basic_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).
namespace std {
typedef T1 streamoff;
typedef T2 streamsize;
class ios_base;
// TEMPLATE CLASSES
template <class Elem, class Tr = char_traits<Elem> >
class basic_ios;
typedef basic_ios<char, char_traits<char> > ios;
typedef basic_ios<wchar_t, char_traits<wchar_t> >
wios;
template <class Statetype>
class fpos;
typedef fpos<mbstate_t> streampos;
typedef fpos<mbstate_t> wstreampos;
// 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);
};
bad
· basic_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
template <class Elem, class Tr = char_traits<Elem> >
class basic_ios : public ios_base {
public:
typedef Elem char_type;
typedef Tr traits_type;
typedef typename Tr::int_type int_type;
typedef typename Tr::pos_type pos_type;
typedef typename Tr::off_type off_type;
explicit basic_ios(basic_streambuf<Elem, Tr> *strbuf);
virtual ~basic_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);
basic_ios& copyfmt(const basic_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);
basic_ostream<Elem, Tr> *tie() const;
basic_ostream<Elem, Tr> *tie(basic_ostream<Elem, Tr> *newtie);
basic_streambuf<Elem, Tr> *rdbuf() const;
basic_streambuf<Elem, Tr>
*rdbuf(basic_streambuf<Elem, Tr> *strbuf);
Elem widen(char ch);
char narrow(Elem ch, char dflt);
protected:
void init(basic_streambuf<Elem, Tr> *strbuf);
basic_ios();
basic_ios(const facet&); // not defined
void operator=(const facet&) // not defined
};The template class describes the storage and member functions common
to both input streams (of template class
basic_istream)
and output streams (of template class
basic_ostream)
that depend on the template parameters. (The class
ios_base describes what is common
and not dependent on template parameters. An object of class
basic_ios<Elem, Tr> helps control a stream with elements
of type Elem, whose
character traits are determined by the
class Tr.
An object of class basic_ios<Elem, Tr> stores:
bool bad() const;
The member function returns true if
rdstate() & badbit
is nonzero.
explicit basic_ios(basic_streambuf<Elem, Tr> *strbuf);
basic_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 Elem char_type;
The type is a synonym for the template parameter Elem.
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.
basic_ios& copyfmt(const basic_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. Note that storing a new exception mask
can throw an exception just like the call
clear(
rdstate()).
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(basic_streambuf<Elem, Tr> *strbuf);
The member function stores values in all member objects, so that:
typedef typename Ty::int_type int_type;
The type is a synonym for
Ty::int_type.
char narrow(char_type ch, char dflt);
The member function returns
use_facet<
ctype<Elem> >(
getloc()).
narrow(ch, dflt).
typedef typename Ty::off_type off_type;
The type is a synonym for
Ty::off_type.
operator void *() const;
The operator returns a null pointer only if
fail().
bool operator!() const;
The operator returns
fail().
typedef typename Ty::pos_type pos_type;
The type is a synonym for
Ty::pos_type.
basic_streambuf<Elem, Tr> *rdbuf() const;
basic_streambuf<Elem, Tr> *rdbuf(basic_streambuf<Elem, Tr> *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()).
basic_ostream<Elem, Tr> *tie() const;
basic_ostream<Elem, Tr> *tie(basic_ostream<Elem, Tr> *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 Tr traits_type;
The type is a synonym for the template parameter Tr.
char_type widen(char ch);
The member function returns
use_facet<
ctype<Elem> >(
getloc()).
widen(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.
template <class St>
class fpos {
public:
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 template 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<St> effectively
stores at least two member objects:
- a byte offset, of type
streamoff - a conversion state, for use by an object of class
basic_filebuf,
of type St, typically
mbstate_t
It can also store an arbitrary file position, for use by an object of class
basic_filebuf,
of type fpos_t.
For an environment with limited file size, however,
streamoff and fpos_t may sometimes
be used interchangeably. And for an environment with no
streams that have a
state-dependent encoding,
mbstate_t may actually be unused. 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 and in the
initial conversion state
(if that matters).
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 that do not have a
state-dependent encoding.
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 that do not have a
state-dependent encoding.
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.
typedef basic_ios<char, char_traits<char> > ios;
The type is a synonym for template class
basic_ios, specialized for
elements of type char with default
character traits.
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 std::streamoff streamoff;
typedef std::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 that does not depend on the template
parameters. (The template class
basic_ios describes what is
common and is dependent on template parameters.
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
basic_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
basic_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
basic_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
basic_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
basic_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 std::streamoff streamoff;
The type is a synonym for std::streamoff.
typedef std::streampos streampos;
The type is a synonym for std::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.
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<mbstate_t> streampos;
The type is a synonym for fpos<
mbstate_t>.
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.
typedef basic_ios<wchar_t, char_traits<wchar_t> > wios;
The type is a synonym for template class
basic_ios, specialized for
elements of type wchar_t with default
character traits.
typedef fpos<mbstate_t> wstreampos;
The type is a synonym for fpos<
mbstate_t>.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
41 - 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.
namespace std {
typedef T1 streamoff;
typedef T2 streamsize;
typedef fpos streampos;
// TEMPLATE CLASSES
template<class Elem>
class char_traits;
class char_traits<char>;
class char_traits<wchar_t>;
template<class Elem, class Tr = char_traits<Elem> >
class basic_ios;
template<class Elem, class Tr = char_traits<Elem> >
class istreambuf_iterator;
template<class Elem, class Tr = char_traits<Elem> >
class ostreambuf_iterator;
template<class Elem, class Tr = char_traits<Elem> >
class basic_streambuf;
template<class Elem, class Tr = char_traits<Elem> >
class basic_istream;
template<class Elem, class Tr = char_traits<Elem> >
class basic_ostream;
template<class Elem, class Tr = char_traits<Elem> >
class basic_iostream;
template<class Elem, class Tr = char_traits<Elem> >
class basic_stringbuf;
template<class Elem, class Tr = char_traits<Elem> >
class basic_istringstream;
template<class Elem, class Tr = char_traits<Elem> >
class basic_ostringstream;
template<class Elem, class Tr = char_traits<Elem> >
class basic_stringstream;
template<class Elem, class Tr = char_traits<Elem> >
class basic_filebuf;
template<class Elem, class Tr = char_traits<Elem> >
class basic_ifstream;
template<class Elem, class Tr = char_traits<Elem> >
class basic_ofstream;
template<class Elem, class Tr = char_traits<Elem> >
class basic_fstream;
// char TYPE DEFINITIONS
typedef basic_ios<char, char_traits<char> > ios;
typedef basic_streambuf<char, char_traits<char> >
streambuf;
typedef basic_istream<char, char_traits<char> >
istream;
typedef basic_ostream<char, char_traits<char> >
ostream;
typedef basic_iostream<char, char_traits<char> >
iostream;
typedef basic_stringbuf<char, char_traits<char> >
stringbuf;
typedef basic_istringstream<char, char_traits<char> >
istringstream;
typedef basic_ostringstream<char, char_traits<char> >
ostringstream;
typedef basic_stringstream<char, char_traits<char> >
stringstream;
typedef basic_filebuf<char, char_traits<char> >
filebuf;
typedef basic_ifstream<char, char_traits<char> >
ifstream;
typedef basic_ofstream<char, char_traits<char> >
ofstream;
typedef basic_fstream<char, char_traits<char> >
fstream;
// wchar_t TYPE DEFINITIONS
typedef basic_ios<wchar_t, char_traits<wchar_t> > wios;
typedef basic_streambuf<wchar_t, char_traits<wchar_t> >
wstreambuf;
typedef basic_istream<wchar_t, char_traits<wchar_t> >
wistream;
typedef basic_ostream<wchar_t, char_traits<wchar_t> >
wostream;
typedef basic_iostream<wchar_t, char_traits<wchar_t> >
wiostream;
typedef basic_stringbuf<wchar_t, char_traits<wchar_t> >
wstringbuf;
typedef basic_istringstream<wchar_t,
char_traits<wchar_t> > wistringstream;
typedef basic_ostringstream<wchar_t,
char_traits<wchar_t> > wostringstream;
typedef basic_stringstream<wchar_t,
char_traits<wchar_t> > wstringstream;
typedef basic_filebuf<wchar_t, char_traits<wchar_t> >
wfilebuf;
typedef basic_ifstream<wchar_t, char_traits<wchar_t> >
wifstream;
typedef basic_ofstream<wchar_t, char_traits<wchar_t> >
wofstream;
typedef basic_fstream<wchar_t, char_traits<wchar_t> >
wfstream;
};
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
42 - iostrea2
<iostream.h>
Include the traditional header <iostream.h>
to effectively include the standard header
<iostream> and hoist its
names outside the
std namespace.
In this
implementation, all
names are hoisted, to provide a more traditional library environment.
#include <iostream>
using namespace std;
In this
implementation,
<iostream.h> does
not declare the
wide oriented
stream objects
wcin,
wcout,
wcerr, and
wclog.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
43 - 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.
The objects fall into two groups:
Once you perform
certain operations
on a stream, such as the
standard input,
you cannot perform operations of a different orientation on
the same stream. Hence, a program cannot operate interchangeably on both
cin and
wcin, for example.
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;
}namespace std {
extern istream cin;
extern ostream cout;
extern ostream cerr;
extern ostream clog;
extern wistream wcin;
extern wostream wcout;
extern wostream wcerr;
extern wostream wclog;
};extern ostream cerr;
The object controls unbuffered insertions to the
standard error output
as a byte stream.
Once the object is constructed, the expression
cerr.flags() &
unitbuf is nonzero.
extern 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 clog;
The object controls buffered insertions to the
standard error output
as a byte stream.
extern ostream cout;
The object controls insertions to the
standard output
as a byte stream.
extern wostream wcerr;
The object controls unbuffered insertions to the
standard error output
as a wide stream.
Once the object is constructed, the expression
wcerr.flags() &
unitbuf is nonzero.
extern wistream wcin;
The object controls extractions from the
standard input
as a wide stream.
Once the object is constructed, the call
wcin.tie() returns
&wcout.
extern wostream wclog;
The object controls buffered insertions to the
standard error output
as a wide stream.
extern wostream wcout;
The object controls insertions to the
standard output
as a wide stream.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
44 - iso646
<iso646.h>[Added with
Amendment 1]
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.
45 - istream
<istream>
Include the iostreams
standard header <istream>
to define template class
basic_istream,
which mediates extractions for the iostreams, and the template class.
basic_iostream,
which mediates both insertions and extractions.
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.)
namespace std {
template<class Elem, class Tr = char_traits<Elem> >
class basic_istream;
typedef basic_istream<char, char_traits<char> >
istream;
typedef basic_istream<wchar_t, char_traits<wchar_t> >
wistream;
template<class Elem, class Tr = char_traits<Elem> >
class basic_iostream;
typedef basic_iostream<char, char_traits<char> >
iostream;
typedef basic_iostream<wchar_t, char_traits<wchar_t> >
wiostream;
// EXTRACTORS
template<class Elem, class Tr>
basic_istream<Elem, Tr>&
operator>>(basic_istream<Elem, Tr>& istr, Elem *str);
template<class Elem, class Tr>
basic_istream<Elem, Tr>&
operator>>(basic_istream<Elem, Tr>& istr, Elem& ch);
template<class Tr>
basic_istream<char, Tr>&
operator>>(basic_istream<char, Tr>& istr,
signed char *str);
template<class Tr>
basic_istream<char, Tr>&
operator>>(basic_istream<char, Tr>& istr,
signed char& ch);
template<class Tr>
basic_istream<char, Tr>&
operator>>(basic_istream<char, Tr>& istr,
unsigned char *str);
template<class Tr>
basic_istream<char, Tr>&
operator>>(basic_istream<char, Tr>& istr,
unsigned char& ch);
// MANIPULATORS
template class<Elem, Tr>
basic_istream<Elem, Tr>& ws(basic_istream<Elem, Tr>& istr);
};template <class Elem, class Tr = char_traits<Elem> >
class basic_iostream : public basic_istream<Elem, Tr>,
public basic_ostream<Elem, Tr> {
public:
explicit basic_iostream(basic_streambuf<Elem, Tr>& *strbuf);
virtual ~basic_iostream();
};The template class describes an object that controls
insertions, through its base object
basic_ostream<Elem, Tr>,
and extractions, through its base object
basic_istream<Elem, Tr>.
The two objects share a common virtual base object
basic_ios<Elem, Tr>.
They also manage a common
stream buffer,
with elements of type Elem, whose
character traits are determined
by the class Tr. The constructor initializes its base objects
via basic_istream(strbuf) and basic_ostream(strbuf).
basic_istream
· gcount
· get
· getline
· ignore
· operator>>
· peek
· putback
· read
· readsome
· seekg
· sentry
· sync
· tellg
· unget
template <class Elem, class Tr = char_traits<Elem> >
class basic_istream
: virtual public basic_ios<Elem, Tr> {
public:
typedef typename basic_ios<Elem, Tr>::char_type char_type;
typedef typename basic_ios<Elem, Tr>::traits_type traits_type;
typedef typename basic_ios<Elem, Tr>::int_type int_type;
typedef typename basic_ios<Elem, Tr>::pos_type pos_type;
typedef typename basic_ios<Elem, Tr>::off_type off_type;
explicit basic_istream(basic_streambuf<Elem, Tr> *strbuf);
class sentry;
virtual ~basic_istream();
basic_istream& operator>>(
basic_istream& (*pfn)(basic_istream&));
basic_istream& operator>>(
ios_base& (*pfn)(ios_base&));
basic_istream& operator>>(
basic_ios<Elem, Tr>& (*pfn)(basic_ios<Elem, Tr>&));
basic_istream& operator>>(
basic_streambuf<Elem, Tr> *strbuf);
basic_istream& operator>>(bool& val);
basic_istream& operator>>(short& val);
basic_istream& operator>>(unsigned short& val);
basic_istream& operator>>(int& val);
basic_istream& operator>>(unsigned int& val);
basic_istream& operator>>(long& val);
basic_istream& operator>>(unsigned long& val);
basic_istream& operator>>(void *& val);
basic_istream& operator>>(float& val);
basic_istream& operator>>(double& val);
basic_istream& operator>>(long double& val);
streamsize gcount() const;
int_type get();
basic_istream& get(char_type& ch);
basic_istream& get(char_type *str, streamsize count);
basic_istream&
get(char_type *str, streamsize count, char_type delim);
basic_istream&
get(basic_streambuf<char_type, Tr>& strbuf);
basic_istream&
get(basic_streambuf<Elem, Tr>& strbuf, char_type delim);
basic_istream& getline(char_type *str, streamsize count);
basic_istream& getline(char_type *str, streamsize count,
char_type delim);
basic_istream& ignore(streamsize count = 1,
int_type delim = traits_type::eof());
int_type peek();
basic_istream& read(char_type *str, streamsize count);
streamsize readsome(char_type *str, streamsize count);
basic_istream& putback(char_type ch);
basic_istream& unget();
pos_type tellg();
basic_istream& seekg(pos_type pos);
basic_istream& seekg(off_type off,
ios_base::seek_dir way);
int sync();
};The template class describes an object that controls
extraction of elements and encoded objects from a
stream buffer
with elements of type Elem, also known as
char_type, whose
character traits are determined by the
class Tr, 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 basic_istream<Elem, Tr> stores:
- a virtual public base object of class
basic_ios<Elem, Tr> - an extraction count
for the last unformatted input operation (called
count
in the code above)
explicit basic_istream(basic_streambuf<Elem, Tr> *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();
basic_istream& get(char_type& ch);
basic_istream& get(char_type *str, streamsize count);
basic_istream& get(char_type *str, streamsize count,
char_type delim);
basic_istream& get(basic_streambuf<Elem, Tr>& strbuf);
basic_istream& get(basic_streambuf<Elem, Tr>& 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.
basic_istream& getline(char_type *str, streamsize count);
basic_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.
basic_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
numeric_limits<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.
basic_istream& operator>>(
basic_istream& (*pfn)(basic_istream&));
basic_istream& operator>>(
ios_base& (*pfn)(ios_base&));
basic_istream& operator>>(
basic_ios<Elem, Tr>& (*pfn)(basic_ios<Elem, Tr>&));
basic_istream& operator>>(
basic_streambuf<Elem, Tr> *strbuf);
basic_istream& operator>>(bool& val);
basic_istream& operator>>(short& val);
basic_istream& operator>>(unsigned short& val);
basic_istream& operator>>(int& val);
basic_istream& operator>>(unsigned int& val);
basic_istream& operator>>(long& val);
basic_istream& operator>>(unsigned long& val);
basic_istream& operator>>(void *& val);
basic_istream& operator>>(float& val);
basic_istream& operator>>(double& val);
basic_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:
basic_istream& operator>>(
basic_streambuf<Elem, Tr> *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:
basic_istream& operator>>(bool& val);
extracts a field and converts it to a boolean value by calling
use_facet<num_get<Elem,
InIt>(getloc()).
get(InIt(
rdbuf()), Init(0), *this,
getloc(), val). Here, InIt is defined as
istreambuf_iterator<Elem,
Tr>.
The function returns *this.
The functions:
basic_istream& operator>>(short& val);
basic_istream& operator>>(unsigned short& val);
basic_istream& operator>>(int& val);
basic_istream& operator>>(unsigned int& val);
basic_istream& operator>>(long& val);
basic_istream& operator>>(unsigned long& val);
basic_istream& operator>>(void *& val);
each extract a field and convert it to a numeric value by calling
use_facet<num_get<Elem,
InIt>(getloc()).
get(InIt(
rdbuf()), Init(0), *this,
getloc(), val). Here, InIt is defined as
istreambuf_iterator<Elem,
Tr>, and val has type long,
unsigned long, or void * as needed.
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:
basic_istream& operator>>(float& val);
basic_istream& operator>>(double& val);
basic_istream& operator>>(long double& val);
each extract a field and convert it to a numeric value by calling
use_facet<num_get<Elem,
InIt>(getloc()).
get(InIt(
rdbuf()), Init(0), *this,
getloc(), val). Here, InIt is defined as
istreambuf_iterator<Elem,
Tr>, and val has type double or
long double as needed.
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().
basic_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.
basic_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().
basic_istream& seekg(pos_type pos);
basic_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(basic_istream& 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).
basic_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.
typedef basic_iostream<char, char_traits<char> > iostream;
The type is a synonym for template class
basic_iostream, specialized
for elements of type char with default
character traits.
typedef basic_istream<char, char_traits<char> > istream;
The type is a synonym for template class
basic_istream, specialized
for elements of type char with default
character traits.
template<class Elem, class Tr>
basic_istream<Elem, Tr>&
operator>>(basic_istream<Elem, Tr>& istr, Elem *str);
template<class Elem, class Tr>
basic_istream<Elem, Tr>&
operator>>(basic_istream<Elem, Tr>& istr, Elem& ch);
template<class Tr>
basic_istream<char, Tr>&
operator>>(basic_istream<char, Tr>& istr,
signed char *str);
template<class Tr>
basic_istream<char, Tr>&
operator>>(basic_istream<char, Tr>& istr,
signed char& ch);
template<class Tr>
basic_istream<char, Tr>&
operator>>(basic_istream<char, Tr>& istr,
unsigned char *str);
template<class Tr>
basic_istream<char, Tr>&
operator>>(basic_istream<char, Tr>& istr,
unsigned char& ch);The template function:
template<class Elem, class Tr>
basic_istream<Elem, Tr>&
operator>>(basic_istream<Elem, Tr>& istr, Elem *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 Elem that can be declared.
The function always stores
Elem() after
any extracted elements it stores. Extraction stops early on end-of-file,
on a character with value Elem(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 template function:
template<class Elem, class Tr>
basic_istream<Elem, Tr>&
operator>>(basic_istream<Elem, Tr>& 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 template function:
template<class Tr>
basic_istream<char, Tr>&
operator>>(basic_istream<char, Tr>& istr,
signed char *str);returns istr >> (char *)str.
The template function:
template<class Tr>
basic_istream<char, Tr>&
operator>>(basic_istream<char, Tr>& istr,
signed char& ch);returns istr >> (char&)ch.
The template function:
template<class Tr>
basic_istream<char, Tr>&
operator>>(basic_istream<char, Tr>& istr,
unsigned char *str);returns istr >> (char *)str.
The template function:
template<class Tr>
basic_istream<char, Tr>&
operator>>(basic_istream<char, Tr>& istr,
unsigned char& ch);returns istr >> (char&)ch.
typedef basic_iostream<wchar_t, char_traits<wchar_t> >
wiostream;The type is a synonym for template class
basic_iostream, specialized
for elements of type wchar_t with default
character traits.
typedef basic_istream<wchar_t, char_traits<wchar_t> >
wistream;The type is a synonym for template class
basic_istream, specialized
for elements of type wchar_t with default
character traits.
template class<Elem, Tr>
basic_istream<Elem, Tr>& ws(basic_istream<Elem, Tr>& istr);The manipulator extracts and discards any elements
ch for which
use_facet<
ctype<Elem> >(
getloc()).
is(
ctype<Elem>::space, 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.
46 - 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.
47 - 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.
48 - lib_cpp
C++ Library Overview
Using C++ Library Headers
· C++ Library Conventions
· Iostreams Conventions
· Program
Startup and Termination
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 Standard C++ library consists of 51 required headers.
This implementation also includes
three additional headers, <hash_map>,
<hash_set>,
and <slist>, not required by the C++ Standard,
for a total of 54 headers.
These 54
C++ library headers
(along with the additional 18
Standard C headers)
constitute a
hosted implementation
of the C++ library:
<algorithm>,
<bitset>,
<cassert>,
<cctype>,
<cerrno>,
<cfloat>,
<ciso646>,
<climits>,
<clocale>,
<cmath>,
<complex>,
<csetjmp>,
<csignal>,
<cstdarg>,
<cstddef>,
<cstdio>,
<cstdlib>,
<cstring>,
<ctime>,
<cwchar>,
<cwctype>,
<deque>,
<exception>,
<fstream>,
<functional>,
<hash_map>,
<hash_set>,
<iomanip>,
<ios>,
<iosfwd>,
<iostream>,
<istream>,
<iterator>,
<limits>,
<list>,
<locale>,
<map>,
<memory>,
<new>,
<numeric>,
<ostream>,
<queue>,
<set>,
<slist>,
<sstream>,
<stack>,
<stdexcept>,
<streambuf>,
<string>,
<strstream>,
<typeinfo>,
<utility>,
<valarray>, and
<vector>.
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),
<exception>,
<limits>,
<new>,
<typeinfo>, and
<cstdarg>.
The C++ library headers have two broader subdivisions,
iostreams headers and
STL 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.
All names other than operator delete and
operator new in the C++ library headers are defined in the
std namespace,
or in a namespace nested within the std namespace.
You refer to the name
cin, for example,
as std::cin. Note, however, that macro names are not subject to
namespace qualification, so you always write
__STD_COMPLEX
without a namespace qualifier.
In some translation environments, including a C++ library header
may hoist external names declared in the std namespace
into the global namespace as well, with individual using
declarations for each of the names. Otherwise, the header does
not introduce any library names into the current namespace.
The C++ Standard requires that the
C Standard headers declare
all external names in namespace std, then hoist them into
the global namespace with individual using declarations
for each of the names.
But in some translation environments the C Standard headers
include no namespace declarations,
declaring all names directly in the global namespace.
Thus, the most portable way to deal with namespaces is to follow
two rules:
- To assuredly declare in namespace
std
an external name that is traditionally declared
in <stdlib.h>, for example,
include the header <cstdlib>. Know that
the name might also be declared in the global namespace. - To assuredly declare in the global namespace
an external name declared in
<stdlib.h>,
include the header <stdlib.h> directly. Know that
the name might also be declared in namespace std.
Thus, if you want to call
std::abort()
to cause abnormal termination,
you should include <cstdlib>.
And if you want to call abort(),
you should include
<stdlib.h>.
Alternatively, you can write the declaration:
using namespace std;
which assuredly hoists all library names into the current namespace.
If you write this declaration immediately after all include
directives, you hoist the names into the global namespace.
You can subsequently ignore namespace
considerations in the remainder of the translation unit.
You also avoid most dialect differences across different
translation environments.
Unless specifically indicated otherwise, you may not define names in
the std namespace, or in a namespace nested within the
std namespace.
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
basic_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
basic_ostream.
Format control common to both extractors and insertors is managed
by the class basic_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
basic_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.
An exception thrown from such a registered function calls
terminate().
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
49 - 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.
50 - 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.
51 - 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.
52 - 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.
53 - 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.
54 - 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.
55 - limits2
<limits>
Include the standard header <limits>
to define the template class numeric_limits.
Explicit specializations of this class describe many arithmetic properties
of the scalar types (other than pointers).
namespace std {
enum float_denorm_style;
enum float_round_style;
template<class Ty>
class numeric_limits;
};enum float_denorm_style {
denorm_indeterminate = -1,
denorm_absent = 0,
denorm_present = 1
};The enumeration describes the various methods that an implementation
can choose for representing a denormalized floating-point value --
one too small to represent as a normalized value:
enum float_round_style {
round_indeterminate = -1,
round_toward_zero = 0,
round_to_nearest = 1,
round_toward_infinity = 2,
round_toward_neg_infinity = 3
};The enumeration describes the various methods that an implementation
can choose for rounding a floating-point value to an integer value:
template<class Ty>
class numeric_limits {
public:
static const float_denorm_style has_denorm
= denorm_absent;
static const bool has_denorm_loss = false;
static const bool has_infinity = false;
static const bool has_quiet_NaN = false;
static const bool has_signaling_NaN = false;
static const bool is_bounded = false;
static const bool is_exact = false;
static const bool is_iec559 = false;
static const bool is_integer = false;
static const bool is_modulo = false;
static const bool is_signed = false;
static const bool is_specialized = false;
static const bool tinyness_before = false;
static const bool traps = false;
static const float_round_style round_style =
round_toward_zero;
static const int digits = 0;
static const int digits10 = 0;
static const int max_exponent = 0;
static const int max_exponent10 = 0;
static const int min_exponent = 0;
static const int min_exponent10 = 0;
static const int radix = 0;
static Ty denorm_min() throw();
static Ty epsilon() throw();
static Ty infinity() throw();
static Ty max() throw();
static Ty min() throw();
static Ty quiet_NaN() throw();
static Ty round_error() throw();
static Ty signaling_NaN() throw();
};The template class describes many arithmetic properties of its
parameter type Ty. The header defines explicit specializations
for the types wchar_t, bool, char, signed char,
unsigned char, short, unsigned short, int, unsigned int, long,
unsigned long, float, double, and long double. For all these
explicit specializations, the member is_specialized is true,
and all relevant members have meaningful values.
The program can supply additional explicit specializations.
For an arbitrary specialization, no members have meaningful
values. A member object that does not have a meaningful value
stores zero (or false) and a member function that does not return
a meaningful value returns Ty(0).
static Ty denorm_min() throw();
The function returns the minimum value for the type
(which is the same as
min() if
has_denorm is
not equal to
denorm_present).
static const int digits = 0;
The member stores the number of
radix digits
that the type can represent without change
(which is the number of bits other than any sign bit
for a predefined integer type, or the number of mantissa
digits for a predefined floating-point type).
static const int digits10 = 0;
The member stores the number of decimal digits
that the type can represent without change.
static Ty epsilon() throw();
The function returns the difference between 1 and the smallest
value greater than 1 that is representable for the type
(which is the value
FLT_EPSILON
for type float).
static const float_denorm_style has_denorm =
denorm_absent;The member stores
denorm_present
for a floating-point type that has
denormalized values (effectively a variable number of exponent bits).
static const bool has_denorm_loss = false;
The member stores true for a type that determines
whether a value has lost accuracy because it is delivered
as a denormalized result (too small to represent as
a normalized value) or because it is inexact (not the
same as a result not subject to limitations of exponent
range and precision), an option with
IEC 559 floating-point representations
that can affect some results.
static const bool has_infinity = false;
The member stores true for a type that has
a representation for positive infinity.
True if is_iec559 is true.
static const bool has_quiet_NaN = false;
The member stores true for a type that has
a representation for a quiet NaN,
an encoding that is ``Not a Number'' which does not
signal its presence in an expression.
True if is_iec559 is true.
static const bool has_signaling_NaN = false;
The member stores true for a type that has
a representation for a signaling NaN,
an encoding that is ``Not a Number'' which
signals its presence in an expression
by reporting an exception.
True if is_iec559 is true.
static Ty infinity() throw();
The function returns the representation of positive infinity
for the type. The return value is meaningful only if
has_infinity is true.
static const bool is_bounded = false;
The member stores true for a type that has
a bounded set of representable values (which is the case
for all predefined types).
static const bool is_exact = false;
The member stores true for a type that has
exact representations for all its values (which is the case
for all predefined integer types). A fixed-point or rational
representation is also considered exact, but not a floating-point
representation.
static const bool is_iec559 = false;
The member stores true for a type that has
a representation conforming to
IEC 559, an international
standard for representing floating-point values (also known as
IEEE 754 in the USA).
static const bool is_integer = false;
The member stores true for a type that has
an integer representation (which is the case for all
predefined integer types).
static const bool is_modulo = false;
The member stores true for a type that has a
modulo representation,
where all results are reduced modulo some value (which is the
case for all predefined unsigned integer types).
static const bool is_signed = false;
The member stores true for a type that has
a signed representation (which is the case for all predefined
floating-point and signed integer types).
static const bool is_specialized = false;
The member stores true for a type that has
an explicit specialization defined for template class
numeric_limits
(which is the case for all scalar types other than pointers).
static Ty max() throw();
The function returns the maximum finite value for the type
(which is
INT_MAX
for type int and
FLT_MAX
for type float). The return value is meaningful if
is_bounded is true.
static const int max_exponent = 0;
The member stores the maximum positive integer such that
the type can represent as a finite value
radix raised to that power
(which is the value
FLT_MAX_EXP
for type float).
Meaningful only for floating-point types.
static const int max_exponent10 = 0;
The member stores the maximum positive integer such that
the type can represent as a finite value
10 raised to that power (which is the value
FLT_MAX_10_EXP
for type float).
Meaningful only for floating-point types.
static Ty min() throw();
The function returns the minimum normalized value for the type
(which is
INT_MIN
for type int and
FLT_MIN
for type float). The return value is meaningful if
is_bounded is true or
is_bounded is false and
is_signed is false.
static const int min_exponent = 0;
The member stores the minimum negative integer such that
the type can represent as a normalized value
radix raised to that power
(which is the value
FLT_MIN_EXP
for type float).
Meaningful only for floating-point types.
static const int min_exponent10 = 0;
The member stores the minimum negative integer such that
the type can represent as a normalized value
10 raised to that power
(which is the value
FLT_MIN_10_EXP
for type float).
Meaningful only for floating-point types.
static Ty quiet_NaN() throw();
The function returns a representation of a
quiet NaN
for the type. The return value is meaningful only if
has_quiet_NaN is true.
static const int radix = 0;
The member stores the base of the representation
for the type (which is 2 for the predefined integer types,
and the base to which the exponent is raised, or
FLT_RADIX,
for the predefined floating-point types).
static Ty round_error() throw();
The function returns the maximum rounding error for the type.
static const float_round_style round_style =
round_toward_zero;The member stores a value that
describes the vaious methods that an implementation
can choose for rounding a floating-point value to an integer value.
static Ty signaling_NaN() throw();
The function returns a representation of a
signaling NaN
for the type. The return value is meaningful only if
has_signaling_NaN is true.
static const bool tinyness_before = false;
The member stores true for a type that determines
whether a value is ``tiny'' (too small to represent as
a normalized value) before rounding, an option with
IEC 559 floating-point representations
that can affect some results.
static const bool traps = false;
The member stores true for a type that generates some kind of
signal to report certain
arithmetic exceptions.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
56 - 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.
57 - 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.
58 - locale2
<locale>
codecvt
· codecvt_base
· codecvt_byname
· collate
· collate_byname
· ctype
· ctype<char>
· ctype_base
· ctype_byname
· has_facet
· locale
· messages
· messages_base
· messages_byname
· money_base
· money_get
· money_put
· moneypunct
· moneypunct_byname
· num_get
· num_put
· numpunct
· numpunct_byname
· time_base
· time_get
· time_get_byname
· time_put
· time_put_byname
· use_facet
isalnum
· isalpha
· iscntrl
· isdigit
· isgraph
· islower
· isprint
· ispunct
· isspace
· isupper
· isxdigit
· tolower
· toupper
Include the standard header <locale>
to define a host of template classes and functions that encapsulate
and manipulate locales.
namespace std {
class locale;
class ctype_base;
template<class Elem>
class ctype;
template<>
class ctype<char>;
template<class Elem>
class ctype_byname;
class codecvt_base;
template<class Elem, class Byte, class Statype>
class codecvt;
template<class Elem, class Byte, class Statype>
class codecvt_byname;
template<class Elem, class InIt>
class num_get;
template<class Elem, class OutIt>
class num_put;
template<class Elem>
class numpunct;
template<class Elem>
class numpunct_byname;
template<class Elem>
class collate;
template<class Elem>
class collate_byname;
class time_base;
template<class Elem, class InIt>
class time_get;
template<class Elem, class InIt>
class time_get_byname;
template<class Elem, class OutIt>
class time_put;
template<class Elem, class OutIt>
class time_put_byname;
class money_base;
template<class Elem, bool Intl, class InIt>
class money_get;
template<class Elem, bool Intl, class OutIt>
class money_put;
template<class Elem, bool Intl>
class moneypunct;
template<class Elem, bool Intl>
class moneypunct_byname;
class messages_base;
template<class Elem>
class messages;
template<class Elem>
class messages_byname;
// TEMPLATE FUNCTIONS
template<class Facet>
bool has_facet(const locale& loc);
template<class Facet>
const Facet& use_facet(const locale& loc);
template<class Elem>
bool isspace(Elem ch, const locale& loc) const;
template<class Elem>
bool isprint(Elem ch, const locale& loc) const;
template<class Elem>
bool iscntrl(Elem ch, const locale& loc) const;
template<class Elem>
bool isupper(Elem ch, const locale& loc) const;
template<class Elem>
bool islower(Elem ch, const locale& loc) const;
template<class Elem>
bool isalpha(Elem ch, const locale& loc) const;
template<class Elem>
bool isdigit(Elem ch, const locale& loc) const;
template<class Elem>
bool ispunct(Elem ch, const locale& loc) const;
template<class Elem>
bool isxdigit(Elem ch, const locale& loc) const;
template<class Elem>
bool isalnum(Elem ch, const locale& loc) const;
template<class Elem>
bool isgraph(Elem ch, const locale& loc) const;
template<class Elem>
Elem toupper(Elem ch, const locale& loc) const;
template<class Elem>
Elem tolower(Elem ch, const locale& loc) const;
};template<class Elem, class Byte, class Statype>
class codecvt
: public locale::facet, codecvt_base {
public:
typedef Elem intern_type;
typedef Byte extern_type;
typedef Statype state_type;
explicit codecvt(size_t refs = 0);
result in(Statype& state,
const Byte *first1, const Byte *last1,
const Byte *next1,
Elem *first2, Elem *last2, Elem *next2);
result out(Statype& state,
const Elem *first1, const Elem *last1,
const Elem *next1,
Byte *first2, Byte *last2, Byte *next2);
result unshift(Statype& state,
Byte *first2, Byte *last2, Byte *next2);
bool always_noconv() const throw();
int max_length() const throw();
int length(const Statype& state,
const Byte *first1, const Byte *last1,
size_t _N2) const throw();
int encoding() const throw();
static locale::id id;
protected:
~codecvt();
virtual result do_in(Statype& state,
const Byte *first1, const Byte *last1,
const Byte *next1,
Elem *first2, Elem *last2, Elem *next2);
virtual result do_out(Statype& state,
const Elem *first1, const Elem *last1,
const Elem *next1,
Byte *first2, Byte *last2, Byte *next2);
virtual result do_unshift(Statype& state,
Byte *first2, Byte *last2, Byte *next2);
virtual bool do_always_noconv() const throw();
virtual int do_max_length() const throw();
virtual int do_encoding() const throw();
virtual int do_length(const Statype& state,
const Byte *first1, const Byte *last1,
size_t len2) const throw();
};The template class describes an object that can serve as a
locale facet, to control conversions between
a sequence of values of type Elem
and a sequence of values of type Byte.
The class Statype
characterizes the transformation -- and an object of class
Statype stores any necessary state information during
a conversion.
As with any locale facet, the static object
id has an initial
stored value of zero. The first attempt to access its stored value
stores a unique positive value in id.
The template versions of
do_in and
do_out always return
codecvt_base::noconv.
The Standard C++ library defines an explicit specialization, however,
that is more useful:
template<>
codecvt<wchar_t, char, mbstate_t>which converts between wchar_t and char sequences.
bool always_noconv() const throw();
The member function returns
do_always_noconv().
explicit codecvt(size_t refs = 0);
The constructor initializes its
locale::facet base object with
locale::facet(refs).
virtual bool do_always_noconv() const throw();
The protected virtual member function returns true only if every call to
do_in or
do_out returns
noconv.
The template version always returns true.
virtual int do_encoding() const throw();
The protected virtual member function returns:
- -1, if the encoding of sequences of type
extern_type
is state dependent - 0, if the encoding involves sequences of varying lengths
N, if the encoding involves only sequences of length
N
virtual result do_in(Statype state&,
const Byte *first1, const Byte *last1, const Byte *next1,
Elem *first2, Elem *last2, Elem *next2);The protected virtual member function endeavors to convert the
source sequence at [first1, last1)
to a destination sequence that it
stores within [first2, last2). It always stores in
next1 a pointer to the first unconverted element in
the source sequence, and it always stores in next2 a
pointer to the first unaltered element in the destination sequence.
state must represent the
initial conversion state
at the beginning of a new source sequence. The function alters its stored
value, as needed, to reflect the current state of a
successful conversion. Its stored value is otherwise unspecified.
The function returns:
codecvt_base::error
if the source sequence is ill formedcodecvt_base::noconv
if the function performs no conversioncodecvt_base::ok
if the conversion succeedscodecvt_base::partial
if the source is insufficient, or if the destination is not large enough,
for the conversion to succeed
The template version always returns noconv.
virtual int do_length(const Statype state&,
const Byte *first1, const Byte *last1,
size_t len2) const throw();The protected virtual member function effectively calls
do_in(mystate, first1,
last1, next1, buf, buf + len2, next2)
for mystate a copy of state,
some buffer buf, and pointers
next1 and next2. It
then returns next2 - buf.
(Thus, it counts the maximum number of conversions,
not greater than len2, defined by the
source sequence at [first1, last1).)
The template version always returns the lesser of
last1 - first1 and len2.
virtual int do_max_length() const throw();
The protected virtual member function returns
the largest permissible value that can be returned by
do_length(first1,
last1, 1), for arbitrary valid values of first1
and last1. (Thus, it is roughly analogous to the macro
MB_CUR_MAX, at least
when Byte is type char.)
The template version always returns 1.
virtual result do_out(Statype state&,
const Elem *first1, const Elem *last1,
const Elem *next1,
Byte *first2, Byte *last2, Byte *next2);The protected virtual member function endeavors to convert the
source sequence at [first1, last1)
to a destination sequence that it
stores within [first2, last2). It always stores in
next1 a pointer to the first unconverted element in
the source sequence, and it always stores in next2 a
pointer to the first unaltered element in the destination sequence.
state must represent the
initial conversion state
at the beginning of a new source sequence. The function alters its stored
value, as needed, to reflect the current state of a
successful conversion. Its stored value is otherwise unspecified.
The function returns:
codecvt_base::error
if the source sequence is ill formedcodecvt_base::noconv
if the function performs no conversioncodecvt_base::ok
if the conversion succeedscodecvt_base::partial
if the source is insufficient, or if the destination is not large enough,
for the conversion to succeed
The template version always returns noconv.
virtual result do_unshift(Statype state&,
Byte *first2, Byte *last2, Byte *next2);The protected virtual member function endeavors to convert the
source element Elem(0)
to a destination sequence that it
stores within [first2, last2), except for the terminating
element Byte(0). It always stores in next2 a
pointer to the first unaltered element in the destination sequence.
state must represent the
initial conversion state
at the beginning of a new source sequence. The function alters its stored
value, as needed, to reflect the current state of a
successful conversion. Typically, converting the source element
Elem(0) leaves the current state in the initial conversion state.
The function returns:
codecvt_base::error
if state represents an invalid statecodecvt_base::noconv
if the function performs no conversioncodecvt_base::ok
if the conversion succeedscodecvt_base::partial
if the destination is not large enough for the conversion to succeed
The template version always returns noconv.
typedef Byte extern_type;
The type is a synonym for the template parameter Byte.
result in(Statype state&,
const Byte *first1, const Byte *last1, const Byte *next1,
Elem *first2, Elem *last2, Elem *next2);The member function returns
do_in(state, first1, last1,
next1, first2, last2, next2).
typedef Elem intern_type;
The type is a synonym for the template parameter Elem.
int length(const Statype state&,
const Byte *first1, const Byte *last1,
size_t len2) const throw();The member function returns
do_length(first1,
last1, len2).
int encoding() const throw();
The member function returns
do_encoding().
int max_length() const throw();
The member function returns
do_max_length().
result out(Statype state&,
const Elem *first1, const Elem *last1,
const Elem *next1,
Byte *first2, Byte *last2, Byte *next2);The member function returns
do_out(state, first1, last1,
next1, first2, last2, next2).
typedef Statype state_type;
The type is a synonym for the template parameter Statype.
result unshift(Statype state&,
Byte *first2, Byte *last2, Byte *next2);The member function returns
do_unshift(state,
first2, last2, next2).
class codecvt_base {
public:
enum result {ok, partial, error, noconv};
};The class describes an enumeration common to all specializations of
template class codecvt. The enumeration
result
describes the possible return values from
do_in or
do_out:
error
if the source sequence is ill formednoconv
if the function performs no conversionok
if the conversion succeedspartial
if the destination is not large enough for the conversion to succeed
template<class Elem, class Byte, class Statype>
class codecvt_byname
: public codecvt<Elem, Byte, Statype> {
public:
explicit codecvt_byname(const char *locname,
size_t refs = 0);
protected:
~codecvt_byname();
};The template class describes an object that can serve as a
locale facet of type
codecvt<Elem, Byte, Statype>.
Its behavior is determined by the
named locale locname.
The constructor initializes its base object with
codecvt<Elem,
Byte, Statype>(refs).
template<class Elem>
class collate : public locale::facet {
public:
typedef Elem char_type;
typedef basic_string<Elem> string_type;
explicit collate(size_t refs = 0);
int compare(const Elem *first1, const Elem *last1,
const Elem *first2, const Elem *last2) const;
string_type transform(const Elem *first,
const Elem *last) const;
long hash(const Elem *first, const Elem *last) const;
static locale::id id;
protected:
~collate();
virtual int
do_compare(const Elem *first1, const Elem *last1,
const Elem *first2, const Elem *last2) const;
virtual string_type do_transform(const Elem *first,
const Elem *last) const;
virtual long do_hash(const Elem *first,
const Elem *last) const;
};The template class describes an object that can serve as a
locale facet, to control comparisons
of sequences of type Elem.
As with any locale facet, the static object
id has an initial
stored value of zero. The first attempt to access its stored value
stores a unique positive value in id.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
explicit collate(size_t refs = 0);
The constructor initializes its base object with
locale::facet(refs).
int compare(const Elem *first1, const Elem *last1,
const Elem *first2, const Elem *last2) const;The member function returns
do_compare(first1, last1,
first2, last2).
virtual int do_compare(const Elem *first1, const Elem *last1,
const Elem *first2, const Elem *last2) const;The protected virtual member function compares the sequence at
[first1, last1) with the sequence at
[first2, last2). It compares values
by applying operator<
between pairs of corresponding elements of type Elem.
The first sequence compares less if it has the smaller element in
the earliest unequal pair in the sequences, or if no unequal
pairs exist but the first sequence is shorter.
If the first sequence compares less than the second sequence,
the function returns -1. If the second sequence compares less, the function
returns +1. Otherwise, the function returns zero.
virtual long do_hash(const Elem *first,
const Elem *last) const;The protected virtual member function returns an integer derived
from the values of the elements in the sequence
[first, last). Such a hash value can be useful,
for example, in distributing sequences pseudo randomly
across an array of lists.
virtual string_type do_transform(const Elem *first,
const Elem *last) const;The protected virtual member function returns an object of class
string_type whose controlled
sequence is a copy of the sequence [first, last).
If a class derived from collate<Elem> overrides
do_compare, it should
also override do_transform to match. Put simply, two
transformed strings should yield the same result, when passed to
collate::compare, that you would get from passing the
untransformed strings to compare in the derived class.
long hash(const Elem *first, const Elem *last) const;
The member function returns
do_hash(first, last).
typedef basic_string<Elem> string_type;
The type describes a specialization of template class
basic_string
whose objects can store copies of the source sequence.
string_type transform(const Elem *first,
const Elem *last) const;The member function returns
do_transform(first,
last).
template<class Elem>
class collate_byname : public collate<Elem> {
public:
explicit collate_byname(const char *locname,
size_t refs = 0);
protected:
~collate_byname();
};The template class describes an object that can serve as a
locale facet of type
collate<Elem>.
Its behavior is determined by the
named locale locname.
The constructor initializes its base object with
collate<Elem>(refs).
char_type
· ctype
· do_is
· do_narrow
· do_scan_is
· do_scan_not
· do_tolower
· do_toupper
· do_widen
· is
· narrow
· scan_is
· scan_not
· tolower
· toupper
· widen
template<class Elem>
class ctype
: public locale::facet, public ctype_base {
public:
typedef Elem char_type;
explicit ctype(size_t refs = 0);
bool is(mask maskval, Elem ch) const;
const Elem *is(const Elem *first, const Elem *last,
mask *dest) const;
const Elem *scan_is(mask maskval, const Elem *first,
const Elem *last) const;
const Elem *scan_not(mask maskval, const Elem *first,
const Elem *last) const;
Elem toupper(Elem ch) const;
const Elem *toupper(Elem *first, Elem *last) const;
Elem tolower(Elem ch) const;
const Elem *tolower(Elem *first, Elem *last) const;
Elem widen(char byte) const;
const char *widen(char *first, char *last,
Elem *dest) const;
char narrow(Elem ch, char dflt) const;
const Elem *narrow(const Elem *first, const Elem *last,
char dflt, char *dest) const;
static locale::id id;
protected:
~ctype();
virtual bool do_is(mask maskval, Elem ch) const;
virtual const Elem *do_is(const Elem *first, const Elem *last,
mask *dest) const;
virtual const Elem *do_scan_is(mask maskval, const Elem *first,
const Elem *last) const;
virtual const Elem *do_scan_not(mask maskval, const Elem *first,
const Elem *last) const;
virtual Elem do_toupper(Elem ch) const;
virtual const Elem *do_toupper(Elem *first, Elem *last) const;
virtual Elem do_tolower(Elem ch) const;
virtual const Elem *do_tolower(Elem *first, Elem *last) const;
virtual Elem do_widen(char byte) const;
virtual const char *do_widen(char *first, char *last,
Elem *dest) const;
virtual char do_narrow(Elem ch, char dflt) const;
virtual const Elem *do_narrow(const Elem *first,
const Elem *last, char dflt, char *dest) const;
};The template class describes an object that can serve as a
locale facet, to characterize
various properties of a ``character'' (element) of type Elem.
Such a facet also converts between sequences of Elem
elements and sequences of char.
As with any locale facet, the static object
id has an initial
stored value of zero. The first attempt to access its stored value
stores a unique positive value in id.
The Standard C++ library defines two explicit specializations
of this template class:
ctype<char>,
an explicit specialization whose differences are described separatelyctype<wchar_t>, which treats elements as
wide characters
In this
implementation,
other specializations of template class ctype<Elem>:
- convert a value
ch of type Elem to
a value of type char with the expression (char)ch - convert a value
byte of type char to
a value of type Elem with the expression
Elem(byte)
All other operations are performed on char values the same
as for the explicit specialization ctype<char>.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
explicit ctype(size_t refs = 0);
The constructor initializes its
locale::facet base object with
locale::facet(refs).
virtual bool do_is(mask maskval, Elem ch) const;
virtual const Elem *do_is(const Elem *first, const Elem *last,
mask *dest) const;The first protected member template function returns true if
MASK(ch) & maskval is nonzero,
where MASK(ch) designates the mapping between an element
value ch and its classification mask, of type
mask.
The name MASK is purely symbolic here; it is not
defined by the template class. For an object of class
ctype<char>,
the mapping is tab[(unsigned char)(char)ch],
where tab is the stored pointer to the
ctype mask table.
The second protected member template function stores in
dest[I] the value
MASK(first[I]) & maskval, where
I ranges over the interval [0, last - first).
virtual char do_narrow(Elem ch, char dflt) const;
virtual const Elem *do_narrow(const Elem *first, const Elem *last,
char dflt, char *dest) const;The first protected member template function returns
(char)ch, or dflt if that expression
is undefined.
The second protected member template function stores in
dest[I] the value do_narrow(first[I], dflt), for
I in the interval [0, last - first).
virtual const Elem *do_scan_is(mask maskval, const Elem *first,
const Elem *last) const;The protected member function returns the smallest pointer
ptr in the range [first, last) for which
do_is(maskval, *ptr) is true.
If no such value exists, the function returns last.
virtual const Elem *do_scan_not(mask maskval, const Elem *first,
const Elem *last) const;The protected member function returns the smallest pointer
ptr in the range [first, last) for which
do_is(maskval, *ptr) is false.
If no such value exists, the function returns last.
virtual Elem do_tolower(Elem ch) const;
virtual const Elem *do_tolower(Elem *first, Elem *last) const;
The first protected member template function returns
the lowercase character corresponding to ch,
if such a character exists. Otherwise, it returns ch.
The second protected member template function replaces each
element first[I], for I in the interval
[0, last - first), with do_tolower(first[I]).
virtual Elem do_toupper(Elem ch) const;
virtual const Elem *do_toupper(Elem *first, Elem *last) const;
The first protected member template function returns
the uppercase character corresponding to ch,
if such a character exists. Otherwise, it returns ch.
The second protected member template function replaces each
element first[I], for I in the interval
[0, last - first), with do_toupper(first[I]).
virtual Elem do_widen(char byte) const;
virtual const char *do_widen(char *first, char *last,
Elem *dest) const;The first protected member template function returns
Elem(byte).
The second protected member template function stores in
dest[I] the value do_widen(first[I]), for
I in the interval [0, last - first).
bool is(mask maskval, Elem ch) const;
const Elem *is(const Elem *first, const Elem *last,
mask *dest) const;The first member function returns
do_is(maskval, ch).
The second member function returns do_is(first, last, dest).
char narrow(Elem ch, char dflt) const;
const Elem *narrow(const Elem *first, const Elem *last,
char dflt, char *dest) const;The first member function returns
do_narrow(ch, dflt).
The second member function returns do_narrow(first, last,
dflt, dest).
const Elem *scan_is(mask maskval, const Elem *first,
const Elem *last) const;The member function returns
do_scan_is(maskval,
first, last).
const Elem *scan_not(mask maskval, const Elem *first,
const Elem *last) const;The member function returns
do_scan_not(maskval,
first, last).
Elem tolower(Elem ch) const;
const Elem *tolower(Elem *first, Elem *last) const;
The first member function returns
do_tolower(ch).
The second member function returns
do_tolower(first,
last).
Elem toupper(Elem ch) const;
const Elem *toupper(Elem *first, Elem *last) const;
The first member function returns
do_toupper(ch).
The second member function returns
do_toupper(first,
last).
Elem widen(char byte) const;
const char *widen(char *first, char *last, Elem *dest) const;
The first member function returns
do_widen(byte).
The second member function returns
do_widen(first,
last, dest).
template<>
class ctype<char>
: public locale::facet, public ctype_base {
public:
typedef char char_type;
explicit ctype(const mask *tab = 0, bool del = false,
size_t refs = 0);
bool is(mask maskval, char ch) const;
const char *is(const char *first, const char *last,
mask *dest) const;
const char *scan_is(mask maskval,
const char *first, const char *last) const;
const char *scan_not(mask maskval,
const char *first, const char *last) const;
char toupper(char ch) const;
const char *toupper(char *first, char *last) const;
char tolower(char ch) const;
const char *tolower(char *first, char *last) const;
char widen(char byte) const;
const char *widen(char *first, char *last,
char *dest) const;
char narrow(char ch, char dflt) const;
const char *narrow(const char *first,
const char *last, char dflt, char *dest) const;
static locale::id id;
protected:
~ctype();
virtual char do_toupper(char ch) const;
virtual const char *do_toupper(char *first,
char *last) const;
virtual char do_tolower(char ch) const;
virtual const char *do_tolower(char *first,
char *last) const;
virtual char do_widen(char ch) const;
virtual const char *do_widen(char *first, char *last,
char *dest) const;
virtual char do_narrow(char ch, char dflt) const;
virtual const char *do_narrow(const char *first,
const char *last, char dflt, char *dest) const;
const mask *table() const throw();
static const mask *classic_table() const throw();
static const size_t table_size;
};The class is an explicit specialization of template class
ctype for type char.
Hence, it describes an object that can serve as a
locale facet, to characterize
various properties of a ``character'' (element) of type char.
The explicit specialization differs from the template class in several
ways:
- An object of class
ctype<char> stores a
pointer to the first element of a
ctype mask table, an array of
UCHAR_MAX + 1
elements of type
ctype_base::mask.
It also stores a boolean object that indicates whether the array
should be deleted (using operator delete[])
when the ctype<Elem> object
is destroyed. - Its sole public constructor lets you specify
tab, the
ctype mask table, and del,
the boolean object that is true if the array
should be deleted when the ctype<char> object
is destroyed -- as well as the usual reference-count parameter
refs. - The protected member function
table()
returns the stored ctype mask table. - The static member object
table_size
specifies the minimum number of elements in a ctype mask table. - The protected static member function
classic_table()
returns the ctype mask table appropriate to the
"C" locale. - There are no protected virtual member functions
do_is,
do_scan_is, or
do_scan_not.
The corresponding public member functions perform the
equivalent operations themselves. - The member functions
do_narrow and
do_widen simply
copy elements unaltered.
class ctype_base {
public:
enum mask {
space = 1 << 0, // EXAMPLE VALUES ONLY
print = 1 << 1,
cntrl = 1 << 2,
upper = 1 << 3,
lower = 1 << 4,
digit = 1 << 5,
punct = 1 << 6,
xdigit = 1 << 7,
alpha = 1 << 8,
alnum = 0x9 << 5,
graph = 0xB << 5};The class serves as a base class for facets of template class
ctype.
It defines just the enumeration
mask.
Each of the enumeration constants characterizes
a different way to classify characters, as defined by the functions
with similar names declared in the header
<ctype.h>.
The constants are:
You can charaterize a combination of classifications by
ORing these constants. In particular, it is always true that
alnum == (alpha | digit) and
graph == (alnum | punct).
template<class Elem>
class ctype_byname : public ctype<Elem> {
public:
explicit ctype_byname(const char *locname,
size_t refs = 0);
protected:
~ctype_byname();
};The template class describes an object that can serve as a
locale facet of type
ctype<Elem>.
Its behavior is determined by the
named locale locname.
The constructor initializes its base object with
ctype<Elem>(refs)
(or the equivalent for base class
ctype<char>).
template<class Facet>
bool has_facet(const locale& loc);The template function returns true if a
locale facet of class Facet
is listed within the
locale object loc.
template<class Elem>
bool isalnum(Elem ch, const locale& loc) const;The template function returns
use_facet<
ctype<Elem> >(loc).
is(ctype<Elem>::
alnum, ch).
template<class Elem>
bool isalpha(Elem ch, const locale& loc) const;The template function returns
use_facet<
ctype<Elem> >(loc).
is(ctype<Elem>::
alpha, ch).
template<class Elem>
bool iscntrl(Elem ch, const locale& loc) const;The template function returns
use_facet<
ctype<Elem> >(loc).
is(ctype<Elem>::
cntrl, ch).
template<class Elem>
bool isdigit(Elem ch, const locale& loc) const;The template function returns
use_facet<
ctype<Elem> >(loc).
is(ctype<Elem>::
digit, ch).
template<class Elem>
bool isgraph(Elem ch, const locale& loc) const;The template function returns
use_facet<
ctype<Elem> >(loc).
is(ctype<Elem>::
graph, ch).
template<class Elem>
bool islower(Elem ch, const locale& loc) const;The template function returns
use_facet<
ctype<Elem> >(loc).
is(ctype<Elem>::
lower, ch).
template<class Elem>
bool isprint(Elem ch, const locale& loc) const;The template function returns
use_facet<
ctype<Elem> >(loc).
is(ctype<Elem>::
print, ch).
template<class Elem>
bool ispunct(Elem ch, const locale& loc) const;The template function returns
use_facet<
ctype<Elem> >(loc).
is(ctype<Elem>::
punct, ch).
template<class Elem>
bool isspace(Elem ch, const locale& loc) const;The template function returns
use_facet<
ctype<Elem> >(loc).
is(ctype<Elem>::
space, ch).
template<class Elem>
bool isupper(Elem ch, const locale& loc) const;The template function returns
use_facet<
ctype<Elem> >(loc).
is(ctype<Elem>::
upper, ch).
template<class Elem>
bool isxdigit(Elem ch, const locale& loc) const;The template function returns
use_facet<
ctype<Elem> >(loc).
is(ctype<Elem>::
xdigit, ch).
category
· classic
· combine
· facet
· global
· id
· locale
· name
· operator!=
· operator()
· operator==
class locale {
public:
class facet;
class id;
typedef int category;
static const category none, collate, ctype, monetary,
numeric, time, messages, all;
locale();
explicit locale(const char *locname);
locale(const locale& loc, const locale& other,
category cat);
locale(const locale& loc, const char *locname, category cat);
template<class Facet>
locale(const locale& loc, Facet *fac);
template<class Facet>
locale combine(const locale& loc) const;
template<class Elem, class Tr, class Alloc>
bool operator()(const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right) const;
string name() const;
bool operator==(const locale& right) const;
bool operator!=(const locale& right) const;
static locale global(const locale& right);
static const locale& classic();
};The class describes a
locale object that encapsulates a
locale. It represents
culture-specific information as a list of
facets. A facet is a
pointer to an object of a class
derived from class facet
that has a public object of the form:
static locale::id id;
You can define an open-ended set of these facets. You can also
construct a locale object that designates an arbitrary number of
facets.
Predefined groups of these facets represent the
locale categories
traditionally managed in the Standard C library by the function
setlocale.
Category collate
(LC_COLLATE)
includes the facets:
collate<char>
collate<wchar_t>
Category ctype
(LC_CTYPE)
includes the facets:
ctype<char>
ctype<wchar_t>
codecvt<char, char, mbstate_t>
codecvt<wchar_t, char, mbstate_t>
Category monetary
(LC_MONETARY)
includes the facets:
moneypunct<char, false>
moneypunct<wchar_t, false>
moneypunct<char, true>
moneypunct<wchar_t, true>
money_get<char, istreambuf_iterator<char> >
money_get<wchar_t, istreambuf_iterator<wchar_t> >
money_put<char, ostreambuf_iterator<char> >
money_put<wchar_t, ostreambuf_iterator<wchar_t> >
Category numeric
(LC_NUMERIC)
includes the facets:
num_get<char, istreambuf_iterator<char> >
num_get<wchar_t, istreambuf_iterator<wchar_t> >
num_put<char, ostreambuf_iterator<char> >
num_put<wchar_t, ostreambuf_iterator<wchar_t> >
numpunct<char>
numpunct<wchar_t>
Category time
(LC_TIME)
includes the facets:
time_get<char, istreambuf_iterator<char> >
time_get<wchar_t, istreambuf_iterator<wchar_t> >
time_put<char, ostreambuf_iterator<char> >
time_put<wchar_t, ostreambuf_iterator<wchar_t> >
Category messages
(LC_MESSAGES) includes the facets:
messages<char>
messages<wchar_t>
(The last category is required by Posix, but not the C Standard.)
Some of these predefined facets are used by the
iostreams classes,
to control the conversion of numeric values to and from
text sequences.
An object of class locale also stores a
locale name as an object of class
string. Using an
invalid locale name to construct a
locale facet or a locale object
throws an object of class
runtime_error.
The stored locale name is "*" if the locale object
cannot be certain that a C-style locale corresponds exactly
to that represented by the object. Otherwise, you can establish
a matching locale within the Standard C library,
for the locale object loc, by calling
setlocale(
LC_ALL,
loc.name.
c_str()).
In this
implementation,
you can also call the static member function:
static locale empty();
to construct a locale object that has no facets. It is also a
transparent locale --
if the template functions
has_facet and
use_facet cannot find
the requested facet in a transparent locale, they consult first the
global locale and then,
if that is transparent, the
classic locale. Thus, you can write:
cout.imbue(locale::empty());
Subsequent insertions to
cout are
mediated by the current state of the global locale.
You can even write:
locale loc(locale::empty(), locale::classic(),
locale::numeric);
cout.imbue(loc);Numeric formatting rules for subsequent insertions to
cout remain the same as in the
C locale,
even as the global locale supplies changing rules for inserting
dates and monetary amounts.
typedef int category;
static const category none, collate, ctype, monetary,
numeric, time, messages, all;The type is a synonym for int so that it can represent
any of the C locale categories.
It can represent a group of distinct elements of a
bitmask type
(which is anonymous) local to class locale.
The elements are:
In addition, two useful values are:
none, corresponding to none of
the C categoriesall,
corresponding to the C union of all categories
LC_ALL
You can represent an arbitrary group of categories by ORing
these constants, as in monetary | time.
static const locale& classic();
The static member function returns a locale object that represents the
classic locale,
which behaves the same as the
C locale within the
Standard C library.
template<class Facet>
locale combine(const locale& loc) const;The member function returns a locale object that
replaces in (or adds to) *this the facet Facet
listed in loc.
class facet {
protected:
explicit facet(size_t refs = 0);
virtual ~facet();
private:
facet(const facet&) // not defined
void operator=(const facet&) // not defined
};The member class serves as the base class for all
locale facets. Note that you
can neither copy nor assign an object of class facet.
You can construct and destroy objects derived from class
locale::facet, but not objects of the base class proper.
Typically, you construct an object myfac derived
from facet when you construct a locale, as in:
locale loc(locale::classic(), new myfac);
In such cases, the constructor for the base class facet
should have a zero refs argument. When the object
is no longer needed, it is deleted. Thus, you supply a nonzero
refs argument only in those rare cases where you
take responsibility for the lifetime of the object.
static locale global(const locale& loc);
The static member function stores a copy of loc as the
global locale. It also calls
setlocale(
LC_ALL,
loc.name.
c_str()),
to establishing a matching locale within the Standard C library.
The function then returns the previous global locale. At
program startup,
the global locale is the same as the
classic locale.
class id {
protected:
id();
private:
id(const id&) // not defined
void operator=(const id&) // not defined
};The member class describes the static
member object required by each unique
locale facet. Note that you
can neither copy nor assign an object of class id.
locale();
explicit locale(const char *locname);
locale(const locale& loc, const locale& other,
category cat);
locale(const locale& loc, const char *locname, category cat);
template<class Facet>
locale(const locale& loc, Facet *fac);The first constructor initializes the object to match the
global locale. The second constructor
initializes all the
locale categories to have behavior
consistent with the locale name
locname. The remaining constructors copy loc,
with the exceptions noted:
locale(const locale& loc, const locale& other,
category cat);replaces from other those facets
corresponding to a category C
for which C & cat is nonzero.
locale(const locale& loc, const char *locname, category cat);
replaces from locale(locname, all) those facets
corresponding to a category C
for which C & cat is nonzero.
template<class Facet>
locale(const locale& loc, Facet *fac);replaces in (or adds to) loc
the facet fac,
if fac is not a null pointer.
If a locale name locname is a null pointer or otherwise
invalid, the function throws
runtime_error.
string name() const;
The member function returns the stored
locale name.
bool operator!=(const locale& right) const;
The member function returns !(*this == right).
template<class Elem, class Tr, class Alloc>
bool operator()(const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);The member function effectively executes:
const collate<Elem>& fac = use_fac<collate<Elem> >(*this);
return (fac.compare(left.begin(), left.end(),
right.begin(), right.end()) < 0);Thus, you can use a locale object as a
function object.
bool operator==(const locale& right) const;
The member function returns true only if *this and right
are copies of the same locale or have the same name (other than
"*").
template<class Elem>
class messages
: public locale::facet, public messages_base {
public:
typedef Elem char_type;
typedef basic_string<Elem> string_type;
explicit messages(size_t refs = 0);
catalog open(const string& catname,
const locale& loc) const;
string_type get(catalog catval, int set, int message,
const string_type& dflt) const;
void close(catalog catval) const;
static locale::id id;
protected:
~messages();
virtual catalog do_open(const string& catname,
const locale& loc) const;
virtual string_type do_get(catalog catval, int set,
int message, const string_type& dflt) const;
virtual void do_close(catalog catval) const;
};The template class describes an object that can serve as a
locale facet, to characterize
various properties of a
message catalog
that can supply messages represented as sequences of elements
of type Elem.
As with any locale facet, the static object
id has an initial
stored value of zero. The first attempt to access its stored value
stores a unique positive value in id.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
void close(catalog catval) const;
The member function calls
do_close(catval);.
virtual void do_close(catalog catval) const;
The protected member function closes the
message catalog catval,
which must have been opened by an earlier call to
do_open.
virtual string_type do_get(catalog catval, int set, int message,
const string_type& dflt) const;The protected member function endeavors to obtain a
message sequence from the
message catalog
catval. It may make use of set,
message, and dflt in doing so.
It returns a copy of dflt on failure. Otherwise,
it returns a copy of the specified message sequence.
virtual catalog do_open(const string& catname,
const locale& loc) const;The protected member function endeavors to open a
message catalog
whose name is catname. It may make use of the locale
loc in doing so. It returns a value that compares
less than zero on failure. Otherwise, the returned value can
be used as the first argument on a later call to
get.
It should in any case be used as the argument on a later call to
close.
string_type get(catalog catval, int set, int message,
const string_type& dflt) const;The member function returns
do_get(catval, set, message, dflt);.
explicit messages(size_t refs = 0);
The constructor initializes its base object
with locale::facet(refs).
catalog open(const string& catname,
const locale& loc) const;The member function returns
do_open(catname, loc);.
typedef basic_string<Elem> string_type;
The type describes a specialization of template class
basic_string
whose objects can store copies of the message sequences.
class messages_base {
typedef int catalog;
};The class describes a type common to all specializations of
template class messages. The type
catalog
is a synonym for type int that
describes the possible return values from
messages::do_open.
template<class Elem>
class messages_byname : public messages<Elem> {
public:
explicit messages_byname(const char *locname,
size_t refs = 0);
protected:
~messages_byname();
};The template class describes an object that can serve as a
locale facet of type
messages<Elem>.
Its behavior is determined by the
named locale locname.
The constructor initializes its base object with
messages<Elem>(refs).
class money_base {
enum part {none, sign, space, symbol, value};
struct pattern {
char field[4];
};
};The class describes an enumeration and a structure
common to all specializations of
template class moneypunct.
The enumeration
part
describes the possible values in elements of the array
field in the structure
pattern.
The values of part are:
none
to match zero or more spaces or generate nothingsign
to match or generate a positive or negative signspace
to match zero or more spaces or generate a spacesymbol
to match or generate a currency symbolvalue
to match or generate a monetary value
template<class Elem,
class InIt = istreambuf_iterator<Elem> >
class money_get : public locale::facet {
public:
typedef Elem char_type;
typedef InIt iter_type;
typedef basic_string<Elem> string_type;
explicit money_get(size_t refs = 0);
iter_type get(iter_type first, iter_type last,
bool intl, ios_base& iosbase, ios_base::iostate& state,
long double& val) const;
iter_type get(iter_type first, iter_type last,
bool intl, ios_base& iosbase, ios_base::iostate& state,
string_type& val) const;
static locale::id id;
protected:
~money_get();
virtual iter_type do_get(iter_type first,
iter_type last, bool intl, ios_base& iosbase,
ios_base::iostate& state, string_type& val) const;
virtual iter_type do_get(iter_type first,
iter_type last, bool intl, ios_base& iosbase,
ios_base::iostate& state, long double& val) const;
};The template class describes an object that can serve as a
locale facet, to control conversions
of sequences of type Elem to monetary values.
As with any locale facet, the static object
id has an initial
stored value of zero. The first attempt to access its stored value
stores a unique positive value in id.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
virtual iter_type do_get(iter_type first, iter_type last,
bool intl, ios_base& iosbase, ios_base::iostate& state,
string_type& val) const;
virtual iter_type do_get(iter_type first, iter_type last,
bool intl, ios_base& iosbase, ios_base::iostate& state,
long double& val) const;The first virtual protected member function endeavors to match
sequential elements beginning at first in the sequence
[first, last) until it has recognized a complete, nonempty
monetary input field.
If successful, it converts this field to a sequence of one or
more decimal digits, optionally preceded by a minus sign
(-), to represent the amount and stores the result in the
string_type object val.
It returns an iterator
designating the first element beyond the monetary input field.
Otherwise, the function stores
an empty sequence in val and sets
ios_base::failbit in state.
It returns an iterator designating the first element beyond
any prefix of a valid monetary input field. In either case, if the
return value equals last, the function sets
ios_base::eofbit in state.
The second virtual protected member function behaves the same
as the first, except that if successful it converts
the optionally-signed digit sequence to a value of type long double
and stores that value in val.
The format of a monetary input field is determined by the
locale facet fac
returned by the (effective) call
use_facet
<moneypunct<Elem, intl> >(iosbase.
getloc()).
Specifically:
fac.neg_format()
determines the order in which components of the field occur.fac.curr_symbol()
determines the sequence of elements that constitutes a currency symbol.fac.positive_sign()
determines the sequence of elements that constitutes a positive sign.fac.negative_sign()
determines the sequence of elements that constitutes a negative sign.fac.grouping()
determines how digits are grouped to the left of any decimal point.fac.thousands_sep()
determines the element that separates groups of digits to
the left of any decimal point.fac.decimal_point()
determines the element that separates the integer digits from the
fraction digits.fac.frac_digits()
determines the number of significant fraction digits to the right of
any decimal point.
If the sign string (fac.negative_sign
or fac.positive_sign) has more than one element, only
the first element is matched where the element equal to
money_base::sign
appears in the format pattern (fac.neg_format).
Any remaining
elements are matched at the end of the monetary input field.
If neither string has a first element
that matches the next element in the monetary input field,
the sign string is taken as empty and the sign is positive.
If iosbase.flags() &
showbase is nonzero,
the string fac.curr_symbol must match where the
element equal to
money_base::symbol
appears in the format pattern.
Otherwise, if money_base::symbol occurs at the end of
the format pattern, and if no elements of the sign string remain
to be matched, the currency symbol is not matched.
Otherwise, the currency symbol is optionally matched.
If no instances of fac.thousands_sep() occur in
the value portion of the monetary input field
(where the element equal to
money_base::value
appears in the format pattern), no grouping constraint is imposed. Otherwise,
any grouping constraints imposed by fac.grouping()
is enforced. Note that the resulting
digit sequence represents an integer whose
low-order fac.frac_digits() decimal digits are considered
to the right of the decimal point.
Arbitrary
white space is matched
where the element equal to
money_base::space
appears in the format pattern, if it appears other than at the end
of the format pattern.
Otherwise, no internal white space is matched.
An element ch is considered white space if
use_facet
<ctype<Elem> >(iosbase.
getloc()).
is(ctype_base::
space, ch) is true.
iter_type get(iter_type first, iter_type last,
bool intl, ios_base& iosbase, ios_base::iostate& state,
long double& val) const;
iter_type get(iter_type first, iter_type last,
bool intl, ios_base& iosbase, ios_base::iostate& state,
string_type& val) const;Both member functions return
do_get(first, last, intl,
iosbase, state, val).
typedef InIt iter_type;
The type is a synonym for the template parameter InIt.
explicit money_get(size_t refs = 0);
The constructor initializes its base object with
locale::facet(refs).
typedef basic_string<Elem> string_type;
The type describes a specialization of template class
basic_string
whose objects can store sequences of elements from the source sequence.
template<class Elem,
class OutIt = ostreambuf_iterator<Elem> >
class money_put : public locale::facet {
public:
typedef Elem char_type;
typedef OutIt iter_type;
typedef basic_string<Elem> string_type;
explicit money_put(size_t refs = 0);
iter_type put(iter_type next, bool intl, ios_base& iosbase,
Elem fill, long double& val) const;
iter_type put(iter_type next, bool intl, ios_base& iosbase,
Elem fill, string_type& val) const;
static locale::id id;
protected:
~money_put();
virtual iter_type do_put(iter_type next, bool intl,
ios_base& iosbase, Elem fill, string_type& val) const;
virtual iter_type do_put(iter_type next, bool intl,
ios_base& iosbase, Elem fill, long double& val) const;
};The template class describes an object that can serve as a
locale facet, to control conversions
of monetary values to sequences of type Elem.
As with any locale facet, the static object
id has an initial
stored value of zero. The first attempt to access its stored value
stores a unique positive value in id.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
virtual iter_type do_put(iter_type next, bool intl,
ios_base& iosbase, Elem fill, string_type& val) const;
virtual iter_type do_put(iter_type next, bool intl,
ios_base& iosbase, Elem fill, long double& val) const;The first virtual protected member function generates
sequential elements beginning at next to produce a
monetary output field from the
string_type
object val.
The sequence controlled by val must begin with
one or more decimal digits, optionally preceded by a minus sign
(-), which represents the amount.
The function returns an iterator designating the first element beyond
the generated monetary output field.
The second virtual protected member function behaves the same
as the first, except that it effectively first converts val
to a sequence of decimal digits, optionally preceded by a minus sign,
then converts that sequence as above.
The format of a monetary output field is determined by the
locale facet fac
returned by the (effective) call
use_facet
<moneypunct<Elem, intl> >(iosbase.
getloc()).
Specifically:
fac.pos_format()
determines the order in which components of the field are generated
for a non-negative value.fac.neg_format()
determines the order in which components of the field are generated
for a negative value.fac.curr_symbol()
determines the sequence of elements to generate for a currency symbol.fac.positive_sign()
determines the sequence of elements to generate for a positive sign.fac.negative_sign()
determines the sequence of elements to generate for a negative sign.fac.grouping()
determines how digits are grouped to the left of any decimal point.fac.thousands_sep()
determines the element that separates groups of digits to
the left of any decimal point.fac.decimal_point()
determines the element that separates the integer digits from any
fraction digits.fac.frac_digits()
determines the number of significant fraction digits to the right of
any decimal point.
If the sign string (fac.negative_sign
or fac.positive_sign) has more than one element, only
the first element is generated where the element equal to
money_base::sign
appears in the format pattern (fac.neg_format or
fac.pos_format). Any remaining
elements are generated at the end of the monetary output field.
If iosbase.flags() &
showbase is nonzero,
the string fac.curr_symbol is generated where the
element equal to
money_base::symbol
appears in the format pattern.
Otherwise, no currency symbol is generated.
If no grouping constraints are imposed by fac.grouping()
(its first element has the value
CHAR_MAX)
then no instances of fac.thousands_sep() are generated
in the value portion of the monetary output field
(where the element equal to
money_base::value
appears in the format pattern).
If fac.frac_digits() is zero,
then no instance of fac.decimal_point() is generated
after the decimal digits. Otherwise, the resulting monetary output
field places the low-order fac.frac_digits()
decimal digits to the right of the decimal point.
Padding occurs as for any numeric output field,
except that if iosbase.flags() &
iosbase.internal is nonzero, any internal
padding is generated where the element equal to
money_base::space
appears in the format pattern, if it does appear.
Otherwise, internal padding occurs before the generated sequence.
The padding character is fill.
The function calls iosbase.width(0) to reset the
field width to zero.
iter_type put(iter_type next, bool intl, ios_base& iosbase,
Elem fill, long double& val) const;
iter_type put(iter_type next, bool intl, ios_base& iosbase,
Elem fill, string_type& val) const;Both member functions return
do_put(next, intl,
iosbase, fill, val).
typedef InIt iter_type;
The type is a synonym for the template parameter OutIt.
explicit money_put(size_t refs = 0);
The constructor initializes its base object with
locale::facet(refs).
typedef basic_string<Elem> string_type;
The type describes a specialization of template class
basic_string
whose objects can store sequences of elements from the source sequence.
char_type
· curr_symbol
· decimal_point
· do_curr_symbol
· do_decimal_point
· do_frac_digits
· do_grouping
· do_neg_format
· do_negative_sign
· do_pos_format
· do_positive_sign
· do_thousands_sep
· frac_digits
· grouping
· moneypunct
· neg_format
· negative_sign
· pos_format
· positive_sign
· string_type
· thousands_sep
template<class Elem, bool Intl>
class moneypunct
: public locale::facet, public money_base {
public:
typedef Elem char_type;
typedef basic_string<Elem> string_type;
explicit moneypunct(size_t refs = 0);
Elem decimal_point() const;
Elem thousands_sep() const;
string grouping() const;
string_type curr_symbol() const;
string_type positive_sign() const;
string_type negative_sign() const;
int frac_digits() const;
pattern pos_format( oonst;
pattern neg_format() const;
static const bool intl = Intl;
static locale::id id;
protected:
~moneypunct();
virtual Elem do_decimal_point() const;
virtual Elem do_thousands_sep() const;
virtual string do_grouping() const;
virtual string_type do_curr_symbol() const;
virtual string_type do_positive_sign() const;
virtual string_type do_negative_sign() const;
virtual int do_frac_digits() const;
virtual pattern do_pos_format() const;
virtual pattern do_neg_format() const;
};The template class describes an object that can serve as a
locale facet, to desceibe the sequences
of type Elem used to represent a
monetary input field or a
monetary output field.
If the template parameter Intl is true, international
conventions are observed.
As with any locale facet, the static object
id has an initial
stored value of zero. The first attempt to access its stored value
stores a unique positive value in id.
The const static object
intl stores the value
of the template parameter Intl.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
string_type curr_symbol() const;
The member function returns
do_curr_symbol().
Elem decimal_point() const;
The member function returns
do_decimal_point().
string_type do_curr_symbol() const;
The protected virtual member function returns
a locale-specific sequence of elements to use as a currency symbol.
Elem do_decimal_point() const;
The protected virtual member function returns
a locale-specific element to use as a decimal-point.
int do_frac_digits() const;
The protected virtual member function returns
a locale-specific count of the number of digits to display to the
right of any decimal point.
string do_grouping() const;
The protected virtual member function returns a locale-specific
rule for determining how digits
are grouped to the left of any decimal point.
The encoding is the same as for
lconv::grouping.
pattern do_neg_format() const;
The protected virtual member function returns
a locale-specific rule for determining how to generate a
monetary output field for
a neeative amount. Each of the four elements of
pattern::field
can have the values:
none
to match zero or more spaces or generate nothingsign
to match or generate a positive or negative signspace
to match zero or more spaces or generate a spacesymbol
to match or generate a currency symbolvalue
to match or generate a monetary value
Components of a monetary output field are generated
(and components of a
monetary input field are matched)
in the order in which these elements appear in pattern::field.
Each of the values sign, symbol,
value, and either none or space
must appear exactly once. The value none must not appear
first. The value space must not appear first or last.
If Intl is true, the order is symbol,
sign, none, then value.
The template version of moneypunct<Elem, Intl>
returns {money_base::symbol, money_base::sign, money_base::value,
money_base::none}.
string_type do_negative_sign() const;
The protected virtual member function returns
a locale-specific sequence of elements to use as a negative sign.
pattern do_pos_format() const;
The protected virtual member function returns
a locale-specific rule for determining how to generate a
monetary output field for
a positive amount. (It also determines how to match the components of a
monetary input field.)
The encoding is the same as for
do_neg_format.
The template version of moneypunct<Elem, Intl>
returns {money_base::symbol, money_base::sign, money_base::value,
money_base::none}.
string_type do_positive_sign() const;
The protected virtual member function returns
a locale-specific sequence of elements to use as a positive sign.
Elem do_thousands_sep() const;
The protected virtual member function returns
a locale-specific element to use as a group separator to the left of
any decimal point.
int frac_digits() const;
The member function returns
do_frac_digits().
string grouping() const;
The member function returns
do_grouping().
explicit moneypunct(size_t refs = 0);
The constructor initializes its base object with
locale::facet(refs).
pattern neg_format() const;
The member function returns
do_neg_format().
string_type negative_sign() const;
The member function returns
do_negative_sign().
pattern pos_format() const;
The member function returns
do_pos_format().
string_type positive_sign() const;
The member function returns
do_positive_sign().
typedef basic_string<Elem> string_type;
The type describes a specialization of template class
basic_string
whose objects can store copies of the punctuation sequences.
Elem thousands_sep() const;
The member function returns
do_thousands_sep().
template<class Elem, bool Intl>
class moneypunct_byname
: public moneypunct<Elem, Intl> {
public:
explicit moneypunct_byname(const char *locname,
size_t refs = 0);
protected:
~moneypunct_byname();
};The template class describes an object that can serve as a
locale facet of type
moneypunct<Elem, Intl>.
Its behavior is determined by the
named locale locname.
The constructor initializes its base object with
moneypunct<Elem,
Intl>(refs).
template<class Elem, class InIt = istreambuf_iterator<Elem> >
class num_get : public locale::facet {
public:
typedef Elem char_type;
typedef InIt iter_type;
explicit num_get(size_t refs = 0);
iter_type get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
long& val) const;
iter_type get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
unsigned long& val) const;
iter_type get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
double& val) const;
iter_type get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
long double& val) const;
iter_type get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
void *& val) const;
iter_type get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
bool& val) const;
static locale::id id;
protected:
~num_get();
virtual iter_type
do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
long& val) const;
virtual iter_type
do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
unsigned long& val) const;
virtual iter_type
do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
double& val) const;
virtual iter_type
do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
long double& val) const;
virtual iter_type
do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
void *& val) const;
virtual iter_type
do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
bool& val) const;
};The template class describes an object that can serve as a
locale facet, to control conversions
of sequences of type Elem to numeric values.
As with any locale facet, the static object
id has an initial
stored value of zero. The first attempt to access its stored value
stores a unique positive value in id.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
virtual iter_type do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
long& val) const;
virtual iter_type do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
unsigned long& val) const;
virtual iter_type do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
double& val) const;
virtual iter_type do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
long double& val) const;
virtual iter_type do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
void *& val) const;
virtual iter_type do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
bool& val) const;The first virtual protected member function endeavors to match
sequential elements beginning at first in the sequence
[first, last) until it has recognized a complete, nonempty
integer input field.
If successful, it converts this field to its equivalent value as
type long, and stores the result in val.
It returns an iterator
designating the first element beyond the numeric input field.
Otherwise, the function stores nothing in val and sets
ios_base::failbit in state.
It returns an iterator designating the first element beyond
any prefix of a valid integer input field. In either case, if the
return value equals last, the function sets
ios_base::eofbit in state.
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.
(Each such char element is assumed to map to an equivalent element
of type Elem by a simple, one-to-one, mapping.) The equivalent
scan conversion
specification is determined as follows:
- If
iosbase.flags() &
ios_base::basefield ==
ios_base::oct, the
conversion specification is lo. - If
iosbase.flags() & ios_base::basefield ==
ios_base::hex, the
conversion specification is lx. - If
iosbase.flags() & ios_base::basefield == 0, the
conversion specification is li. - Otherwise, the conversion specification is
ld.
The format of an integer input field is further determined by the
locale facet fac
returned by the call
use_facet
<numpunct<Elem>(iosbase.
getloc()).
Specifically:
fac.grouping()
determines how digits are grouped to the left of any decimal pointfac.thousands_sep()
determines the sequence that separates groups of digits to
the left of any decimal point
If no instances of fac.thousands_sep() occur in
the numeric input field, no grouping constraint is imposed. Otherwise,
any grouping constraints imposed by fac.grouping()
is enforced and separators are removed before the scan conversion
occurs.
The second virtual protected member function:
virtual iter_type do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
unsigned long& val) const;behaves the same
as the first, except that it replaces a conversion specification
of ld with lu. If successful it converts
the numeric input field to a value of type unsigned long
and stores that value in val.
The third virtual protected member function:
virtual iter_type do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
double& val) const;behaves the same
as the first, except that it endeavors to match a complete, nonempty
floating-point input field.
fac.decimal_point()
determines the sequence that separates the integer digits from the
fraction digits.
The equivalent scan conversion specifier is lf.
The fourth virtual protected member function:
virtual iter_type do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
long double& val) const;behaves the same the third, except that the equivalent
scan conversion specifier is Lf.
The fifth virtual protected member function:
virtual iter_type do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
void *& val) const;behaves the same the first, except that the equivalent
scan conversion specifier is p.
The sixth virtual protected member function:
virtual iter_type do_get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
bool& val) const;behaves the same
as the first, except that it 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 iosbase.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
fac.falsename()
(for false), or
fac.truename()
(for true).
iter_type get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
long& val) const;
iter_type get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
unsigned long& val) const;
iter_type get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
double& val) const;
iter_type get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
long double& val) const;
iter_type get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
void *& val) const;
iter_type get(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state,
bool& val) const;All member functions return
do_get(first, last,
iosbase, state, val).
typedef InIt iter_type;
The type is a synonym for the template parameter InIt.
explicit num_get(size_t refs = 0);
The constructor initializes its base object with
locale::facet(refs).
template<class Elem, class OutIt = ostreambuf_iterator<Elem> >
class num_put : public locale::facet {
public:
typedef Elem char_type;
typedef OutIt iter_type;
explicit num_put(size_t refs = 0);
iter_type put(iter_type next, ios_base& iosbase,
Elem fill, long val) const;
iter_type put(iter_type next, ios_base& iosbase,
Elem fill, unsigned long val) const;
iter_type put(iter_type next, ios_base& iosbase,
Elem fill, double val) const;
iter_type put(iter_type next, ios_base& iosbase,
Elem fill, long double val) const;
iter_type put(iter_type next, ios_base& iosbase,
Elem fill, const void *val) const;
iter_type put(iter_type next, ios_base& iosbase,
Elem fill, bool val) const;
static locale::id id;
protected:
~num_put();
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, long val) const;
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, unsigned long val) const;
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, double val) const;
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, long double val) const;
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, const void *val) const;
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, bool val) const;
};The template class describes an object that can serve as a
locale facet, to control conversions
of numeric values to sequences of type Elem.
As with any locale facet, the static object
id has an initial
stored value of zero. The first attempt to access its stored value
stores a unique positive value in id.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, long val) const;
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, unsigned long val) const;
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, double val) const;
virtual iter_type do_put(iter_type nextp ios_base& iosbase,
Elem fill, long double val) const;
virtual iter_type do_put(iter_type nextp ios_base& iosbase,
Elem fill, const void *val) const;
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, bool val) const;The first virtual protected member function generates
sequential elements beginning at next to produce an
integer output field
from the value of val.
The function returns an iterator designating the next place to
insert an element beyond the generated integer output field.
The integer output field is generated by the same rules used by the
print functions
for generating a series of char elements to a file.
(Each such char element is assumed to map to an equivalent element
of type Elem by a simple, one-to-one, mapping.) Where a
print function pads a field with either spaces or the digit 0,
however, do_put instead uses fill.
The equivalent
print conversion
specification is determined as follows:
- If
iosbase.flags() &
ios_base::basefield ==
ios_base::oct, the
conversion specification is lo. - If
iosbase.flags() & ios_base::basefield ==
ios_base::hex, the
conversion specification is lx. - Otherwise, the conversion specification is
ld.
If iosbase.width()
is nonzero, a field width of this value is prepended. The
function then calls iosbase.width(0) to reset the
field width to zero.
Padding occurs only if
the minimum number of elements N required to
specify the output field is less than
iosbase.width().
Such padding consists of a sequence of N - width() copies of
fill. Padding then occurs as follows:
- If
iosbase.flags() &
ios_base::adjustfield ==
ios_base::left,
the flag - is prepended. (Padding occurs
after the generated text.) - If
iosbase.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.)
Finally:
- If
iosbase.flags() &
ios_base::showpos
is nonzero, the flag + is prepended to the conversion
specification. - If
iosbase.flags() &
ios_base::showbase
is nonzero, the flag # is prepended to the conversion
specification.
The format of an integer output field is further determined by the
locale facet fac
returned by the call
use_facet
<numpunct<Elem>(iosbase.
getloc()).
Specifically:
fac.grouping()
determines how digits are grouped to the left of any decimal pointfac.thousands_sep()
determines the sequence that separates groups of digits to
the left of any decimal point
If no grouping constraints are imposed by fac.grouping()
(its first element has the value
CHAR_MAX)
then no instances of fac.thousands_sep() are generated
in the output field. Otherwise, separators are inserted after the
print conversion occurs.
The second virtual protected member function:
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, unsigned long val) const;behaves the same
as the first, except that it replaces a conversion specification
of ld with lu.
The third virtual protected member function:
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, double val) const;behaves the same as the first, except that it produces a
floating-point output field
from the value of val.
fac.decimal_point()
determines the sequence that separates the integer digits from the
fraction digits.
The equivalent print conversion specification is determined as follows:
- If
(iosbase.flags() &
ios_base::floatfield) ==
ios_base::fixed, the
conversion specification is lf. - If
(iosbase.flags() & ios_base::floatfield) ==
ios_base::scientific, the
conversion specification is le.
If iosbase.flags() &
ios_base::uppercase
is nonzero, e is replaced with E. - Otherwise, the conversion specification is
lg.
If iosbase.flags() & ios_base::uppercase
is nonzero, g is replaced with G.
If (iosbase.flags() &
ios_base::floatfield) ==
ios_base::fixed, or if
iosbase.precision()
is greater than zero, a precision with the value
iosbase.precision() is prepended to the conversion specification.
Any padding behaves the same
as for an integer output field. The padding character is
fill. Finally:
- If
iosbase.flags() &
ios_base::showpos
is nonzero, the flag + is prepended to the conversion
specification. - If
iosbase.flags() &
ios_base::showpoint
is nonzero, the flag # is prepended to the conversion
specification.
The fourth virtual protected member function:
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, long double val) const;behaves the same the third, except that the qualifier
l in the conversion specification is replaced with
L.
The fifth virtual protected member function:
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, const void *val) const;behaves the same the first, except that the conversion specification
is p, plus any qualifier needed to specify padding.
The sixth virtual protected member function:
virtual iter_type do_put(iter_type next, ios_base& iosbase,
Elem fill, bool val) const;behaves the same
as the first, except that it generates a
boolean output field
from val.
A boolean output field takes one of two forms.
If iosbase.flags() &
ios_base::boolalpha
is false, the member function returns
do_put(next, iosbase, fill, (long)val), which typically produces a
generated sequence of either 0 (for false)
or 1 (for true).
Otherwise, the generated sequence is either
fac.falsename()
(for false), or
fac.truename()
(for true).
iter_type put(iter_type next, ios_base& iosbase,
Elem fill, long val) const;
iter_type put(iter_type next, ios_base& iosbase,
Elem fill, unsigned long val) const;
iter_type put(iter_type iter_type next, ios_base& iosbase,
Elem fill, double val) const;
iter_type put(iter_type next, ios_base& iosbase,
Elem fill, long double val) const;
iter_type put(iter_type next, ios_base& iosbase,
Elem fill, const void *val) const;
iter_type put(iter_type next, ios_base& iosbase,
Elem fill, bool val) const;All member functions return
do_put(next,
iosbase, fill, val).
typedef InIt iter_type;
The type is a synonym for the template parameter OutIt.
explicit num_put(size_t refs = 0);
The constructor initializes its base object with
locale::facet(refs).
char_type
· decimal_point
· do_decimal_point
· do_falsename
· do_grouping
· do_truename
· do_thousands_sep
· falsename
· grouping
· numpunct
· string_type
· thousands_sep
· truename
template<class Elem, class numpunct : public locale::facet {
public:
typedef Elem char_type;
typedef basic_string<Elem> string_type;
explicit numpunct(size_t refs = 0);
Elem decimal_point() const;
Elem thousands_sep() const;
string grouping() const;
string_type truename() const;
string_type falsename() const;
static locale::id id;
protected:
~numpunct();
virtual Elem do_decimal_point() const;
virtual Elem do_thousands_sep() const;
virtual string do_grouping() const;
virtual string_type do_truename() const;
virtual string_type do_falsename() const;
};The template class describes an object that can serve as a
locale facet, to desceibe the sequences
of type Elem used to represent the input fields matched by
num_get
or the output fields generated by
num_get.
As with any locale facet, the static object
id has an initial
stored value of zero. The first attempt to access its stored value
stores a unique positive value in id.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
Elem decimal_point() const;
The member function returns
do_decimal_point().
Elem do_decimal_point() const;
The protected virtual member function returns
a locale-specific element to use as a decimal-point.
string_type do_falsename() const;
The protected virtual member function returns
a locale-specific sequence to use as a text representation of
the value false.
string do_grouping() const;
The protected virtual member function returns a locale-specific
rule for determining how digits
are grouped to the left of any decimal point.
The encoding is the same as for
lconv::grouping.
Elem do_thousands_sep() const;
The protected virtual member function returns
a locale-specific element to use as a group separator to the left of
any decimal point.
string_type do_truename() const;
The protected virtual member function returns
a locale-specific sequence to use as a text representation of
the value true.
string_type falsename() const;
The member function returns
do_falsename().
string grouping() const;
The member function returns
do_grouping().
explicit numpunct(size_t refs = 0);
The constructor initializes its base object with
locale::facet(refs).
typedef basic_string<Elem> string_type;
The type describes a specialization of template class
basic_string
whose objects can store copies of the punctuation sequences.
Elem thousands_sep() const;
The mmmber function returns
do_thousands_sep().
string_type falsename() const;
The member function returns
do_truename().
template<class Elem>
class numpunct_byname : public numpunct<Elem> {
public:
explicit numpunct_byname(const char *locname,
size_t refs = 0);
protected:
~numpunct_byname();
};The template class describes an object that can serve as a
locale facet of type
numpunct<Elem>.
Its behavior is determined by the
named locale locname.
The constructor initializes its base object with
numpunct<Elem>(refs).
class time_base {
public:
enum dateorder {no_order, dmy, mdy, ymd, ydm};
};The class serves as a base class for facets of template class
time_get.
It defines just the enumerated type
dateorder
and several constants of this type. Each of the constants characterizes
a different way to order the components of a date.
The constants are:
no_order
specifies no particular order.dmy
specifies the order day, month, then year, as in
2 December 1979.mdy
specifies the order month, day, then year, as in
December 2, 1979.ymd
specifies the order year, month, then day, as in
1979/12/2.ydm
specifies the order year, day, then month, as in
1979: 2 Dec.
template<class Elem, class InIt = istreambuf_iterator<Elem> >
class time_get : public locale::facet, time_base {
public:
typedef Elem char_type;
typedef InIt iter_type;
explicit time_get(size_t refs = 0);
dateorder date_order() const;
iter_type get_time(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;
iter_type get_date(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;
iter_type get_weekday(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;
iter_type get_month(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;
iter_type get_year(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;
static locale::id id;
protected:
~time_get();
virtual dateorder do_date_order() const;
virtual iter_type
do_get_time(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;
virtual iter_type
do_get_date(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;
virtual iter_type
do_get_weekday(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;
virtual iter_type
do_get_month(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;
virtual iter_type
do_get_year(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;
};The template class describes an object that can serve as a
locale facet, to control conversions
of sequences of type Elem to time values.
As with any locale facet, the static object
id has an initial
stored value of zero. The first attempt to access its stored value
stores a unique positive value in id.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
dateorder date_order() const;
The member function returns
date_order().
virtual dateorder do_date_order() const;
The virtual protected member function returns a value of type
time_base::dateorder,
which describes the order in which date components are matched by
do_get_date.
virtual iter_type
do_get_date(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;The virtual protected member function endeavors to match
sequential elements beginning at first in the sequence
[first, last) until it has recognized a complete, nonempty
date input field.
If successful, it converts this field to its equivalent value as
the components
tm::tm_mon,
tm::tm_day, and tm::tm_year,
and stores the results in pt->tm_mon,
pt->tm_day and pt->tm_year, respectively.
It returns an iterator
designating the first element beyond the date input field.
Otherwise, the function sets
ios_base::failbit in state.
It returns an iterator designating the first element beyond
any prefix of a valid date input field. In either case, if the
return value equals last, the function sets
ios_base::eofbit in state.
In this implementation,
the date input field is assumed to have three fields:
- a month, which is either a sequence of decimal digits whose
corresponding numeric value must be in the range [1, 12],
giving the month plus one, or the sequence matched by
get_month, giving
the month - a day, which is a sequence of decimal digits whose
corresponding numeric value must be in the range [1, 31],
giving the day of the month
- a year, which is the sequence matched by
get_year, giving
the year
The fields are separated by optional spaces,
followed by an optional colon, comma, or slash,
followed by optional spaces. The order of the fields is as specified by
time_get::date_order(),
except that the value no_order is taken as mdy and any
sequence matched by get_month is always taken as a month.
virtual iter_type
do_get_month(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;The virtual protected member function endeavors to match
sequential elements beginning at first in the sequence
[first, last) until it has recognized a complete, nonempty
month input field.
If successful, it converts this field to its equivalent value as
the component
tm::tm_mon,
and stores the result in pt->tm_mon.
It returns an iterator
designating the first element beyond the month input field.
Otherwise, the function sets
ios_base::failbit in state.
It returns an iterator designating the first element beyond
any prefix of a valid month input field. In either case, if the
return value equals last, the function sets
ios_base::eofbit in state.
The month input field is a sequence that matches the longest
of a set of locale-specific sequences, such as: Jan,
January, Feb, February, etc.
The converted value is the number of months since January.
virtual iter_type
do_get_time(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;The virtual protected member function endeavors to match
sequential elements beginning at first in the sequence
[first, last) until it has recognized a complete, nonempty
time input field.
If successful, it converts this field to its equivalent value as
the components
tm::tm_hour,
tm::tm_min, and tm::tm_sec,
and stores the results in pt->tm_hour,
pt->tm_min and pt->tm_sec, respectively.
It returns an iterator
designating the first element beyond the time input field.
Otherwise, the function sets
ios_base::failbit in state.
It returns an iterator designating the first element beyond
any prefix of a valid time input field. In either case, if the
return value equals last, the function sets
ios_base::eofbit in state.
In this implementation,
the time input field has the form HH:MM:SS, where:
HH is a sequence of decimal digits whose
corresponding numeric value must be in the range [0, 24), giving
the hour of the day.MM is a sequence of decimal digits whose
corresponding numeric value must be in the range [0, 60), giving
the minutes past the hour.SS is a sequence of decimal digits whose
corresponding numeric value must be in the range [0, 60), giving
the seconds past the minute.- The literal colons must match corresponding elements
in the input sequence.
virtual iter_type
do_get_weekday(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;The virtual protected member function endeavors to match
sequential elements beginning at first in the sequence
[first, last) until it has recognized a complete, nonempty
weekday input field.
If successful, it converts this field to its equivalent value as
the component
tm::tm_wday,
and stores the result in pt->tm_wday.
It returns an iterator
designating the first element beyond the weekday input field.
Otherwise, the function sets
ios_base::failbit in state.
It returns an iterator designating the first element beyond
any prefix of a valid weekday input field. In either case, if the
return value equals last, the function sets
ios_base::eofbit in state.
The weekday input field is a sequence that matches the longest
of a set of locale-specific sequences, such as: Sun,
Sunday, Mon, Monday, etc.
The converted value is the number of days since Sunday.
virtual iter_type
do_get_year(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;The virtual protected member function endeavors to match
sequential elements beginning at first in the sequence
[first, last) until it has recognized a complete, nonempty
year input field.
If successful, it converts this field to its equivalent value as
the component
tm::tm_year,
and stores the result in pt->tm_year.
It returns an iterator
designating the first element beyond the year input field.
Otherwise, the function sets
ios_base::failbit in state.
It returns an iterator designating the first element beyond
any prefix of a valid year input field. In either case, if the
return value equals last, the function sets
ios_base::eofbit in state.
The year input field is a sequence of decimal digits whose
corresponding numeric value must be in the range [1900, 2036).
The stored value is this value minus 1900.
In this implementation,
values in the range [69, 136) represent the range of years [1969, 2036).
Values in the range [0, 69) are also permissible, but may represent
either the range of years [1900, 1969) or [2000, 2069),
depending on the specific translation environment.
iter_type get_date(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;The member function returns
do_get_date(first, last,
iosbase, state, pt).
iter_type get_month(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;The member function returns
do_get_month(first, last,
iosbase, state, pt).
iter_type get_time(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;The member function returns
do_get_time(first, last,
iosbase, state, pt).
iter_type get_weekday(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;The member function returns
do_get_weekday(first, last,
iosbase, state, pt).
iter_type get_year(iter_type first, iter_type last,
ios_base& iosbase, ios_base::iostate& state, tm *pt) const;The member function returns
do_get_year(first, last,
iosbase, state, pt).
typedef InIt iter_type;
The type is a synonym for the template parameter InIt.
explicit time_get(size_t refs = 0);
The constructor initializes its base object with
locale::facet(refs).
template<class Elem, class InIt>
class time_get_byname : public time_get<Elem, InIt> {
public:
explicit time_get_byname(const char *locname,
size_t refs = 0);
protected:
~time_get_byname();
};The template class describes an object that can serve as a
locale facet of type
time_get<Elem, InIt>.
Its behavior is determined by the
named locale locname.
The constructor initializes its base object with
time_get<Elem,
InIt>(refs).
template<class Elem, class OutIt = ostreambuf_iterator<Elem> >
class time_put : public locale::facet {
public:
typedef Elem char_type;
typedef OutIt iter_type;
explicit time_put(size_t refs = 0);
iter_type put(iter_type next, ios_base& iosbase,
char_type fill, const tm *pt, char fmt, char mod = 0) const;
iter_type put(iter_type next, ios_base& iosbase,
char_type fill, const tm *pt, const Elem *first, const Elem *last) const;
static locale::id id;
protected:
~time_put();
virtual iter_type do_put(iter_type next, ios_base& iosbase,
char_type fill, const tm *pt, char fmt, char mod = 0) const;
};The template class describes an object that can serve as a
locale facet, to control conversions
of time values to sequences of type Elem.
As with any locale facet, the static object
id has an initial
stored value of zero. The first attempt to access its stored value
stores a unique positive value in id.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
virtual iter_type do_put(iter_type next, ios_base& iosbase,
char_type fill, const tm *pt, char fmt, char mod = 0) const;The virtual protected member function generates
sequential elements beginning at next from
time values stored in the object *pt, of type
tm.
The function returns an iterator designating the next place to
insert an element beyond the generated output.
The output is generated by the same rules used by
strftime,
with a last argument of pt,
for generating a series of char elements into an array.
(Each such char element is assumed to map to an equivalent element
of type Elem by a simple, one-to-one, mapping.)
If mod equals zero, the effective format is
"%F", where F is replaced by fmt.
Otherwise, the effective format is
"%MF", where M is replaced by mod.
The parameter fill is not used.
iter_type put(iter_type next, ios_base& iosbase,
char_type fill, const tm *pt, char fmt, char mod = 0) const;
iter_type put(iter_type next, ios_base& iosbase,
char_type fill, const tm *pt, const Elem *first, const Elem *last) const;The first member function returns
do_put(next,
iosbase, fill, pt, fmt, mod). The second member function
copies to *next++ any element in the interval
[first, last) other than a percent (%).
For a percent followed by a character C in the interval
[first, last), the function instead evaluates
next = do_put(next, iosbase, fill, pt, C, 0)
and skips past C.
If, however, C is a qualifier character from the set
EOQ#, followed by a character C2 in the interval
[first, last), the function instead evaluates
next = do_put(next, iosbase, fill, pt, C2, C)
and skips past C2.
typedef InIt iter_type;
The type is a synonym for the template parameter OutIt.
explicit time_put(size_t refs = 0);
The constructor initializes its base object with
locale::facet(refs).
template<class Elem, class OutIt>
class time_put_byname : public time_put<Elem, OutIt> {
public:
explicit time_put_byname(const char *locname,
size_t refs = 0);
protected:
~time_put_byname();
};The template class describes an object that can serve as a
locale facet of type
time_put<Elem, OutIt>.
Its behavior is determined by the
named locale locname.
The constructor initializes its base object with
time_put<Elem,
OutIt>(refs).
template<class Elem>
Elem tolower(Elem ch, const locale& loc) const;The template function returns
use_facet<
ctype<Elem> >(loc).
tolower(ch).
template<class Elem>
Elem toupper(Elem ch, const locale& loc) const;The template function returns
use_facet<
ctype<Elem> >(loc).
toupper(ch).
template<class Facet>
const Facet& use_facet(const locale& loc);The template function returns a reference to the
locale facet of class Facet
listed within the
locale object loc.
If no such object is listed, the function throws an object of class
bad_cast.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
59 - 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.
60 - 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.
61 - 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.
62 - 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.
namespace std {
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 -- NOT IN NAMESPACE std
void operator delete(void *ptr) throw(); // REPLACEABLE
void operator delete(void *, void *) throw();
void operator delete(void *ptr, // REPLACEABLE
const std::nothrow_t&) throw();
void operator delete[](void *ptr) throw(); // REPLACEABLE
void operator delete[](void *, void *) throw();
void operator delete[](void *ptr, // REPLACEABLE
const std::nothrow_t&) throw();
void *operator new(std::size_t count) // REPLACEABLE
throw(std::bad_alloc);
void *operator new(std::size_t count, // REPLACEABLE
const std::nothrow_t&) throw();
void *operator new(std::size_t count, void *ptr) throw();
void *operator new[](std::size_t count) // REPLACEABLE
throw(std::bad_alloc);
void *operator new[](std::size_t count, // REPLACEABLE
const std::nothrow_t&) throw();
void *operator new[](std::size_t count, void *ptr) throw();class 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 std::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(std::size_t).
It does nothing.
The third function is called by a placement
delete expression corresponding to a
new expression of the form
new(std::size_t, const std::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 std::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[](std::size_t).
It does nothing.
The third function is called by a placement
delete expression corresponding to a
new[] expression of the form
new[](std::size_t, const std::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, std::nothrow).
void *operator new(std::size_t count) throw(bad_alloc); // REPLACEABLE
void *operator new(std::size_t count, // REPLACEABLE
const std::nothrow_t&) throw();
void *operator new(std::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(std::size_t count,
const std::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(std::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[](std::size_t count) // REPLACEABLE
throw(std::bad_alloc);
void *operator new[](std::size_t count, // REPLACEABLE
const std::nothrow_t&) throw();
void *operator new[](std::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.
63 - new2
<new.h>
Include the traditional header <new.h>
to effectively include the standard header
<new> and hoist its
names outside the
std namespace.
In this
implementation, all
names are hoisted, to provide a more traditional library environment.
#include <new>
using namespace std;
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
64 - 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.
65 - ostream
<ostream>
namespace std {
template<class Elem, class Tr = char_traits<Elem> >
class basic_ostream;
typedef basic_ostream<char, char_traits<char> >
ostream;
typedef basic_ostream<wchar_t, char_traits<wchar_t> >
wostream;
// INSERTERS
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
const Elem *str);
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
Elem ch);
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
const char *str);
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
char ch);
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
const char *str);
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
char ch);
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
const signed char *str);
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
signed char ch);
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
const unsigned char *str);
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
unsigned char ch);
// MANIPULATORS
template class<Elem, Tr>
basic_ostream<Elem, Tr>&
endl(basic_ostream<Elem, Tr>& ostr);
template class<Elem, Tr>
basic_ostream<Elem, Tr>&
ends(basic_ostream<Elem, Tr>& ostr);
template class<Elem, Tr>
basic_ostream<Elem, Tr>&
flush(basic_ostream<Elem, Tr>& ostr);
};Include the iostreams
standard header <ostream> to define
template
class basic_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.)
basic_ostream
· flush
· operator<<
· put
· seekp
· sentry
· tellp
· write
template <class Elem, class Tr = char_traits<Elem> >
class basic_ostream
: virtual public basic_ios<Elem, Tr> {
public:
typedef typename basic_ios<Elem, Tr>::char_type char_type;
typedef typename basic_ios<Elem, Tr>::traits_type traits_type;
typedef typename basic_ios<Elem, Tr>::int_type int_type;
typedef typename basic_ios<Elem, Tr>::pos_type pos_type;
typedef typename basic_ios<Elem, Tr>::off_type off_type;
explicit basic_ostream(basic_streambuf<Elem, Tr> *strbuf);
class sentry;
virtual ~basic_ostream();
basic_ostream& operator<<(
basic_ostream& (*pfn)(basic_ostream&));
basic_ostream& operator<<(
ios_base;& (*pfn)(ios_base&));
basic_ostream& operator<<(
basic_ios<Elem, Tr>& (*pfn)(basic_ios<Elem, Tr>&));
basic_ostream& operator<<(
basic_streambuf<Elem, Tr> *strbuf);
basic_ostream& operator<<(bool val);
basic_ostream& operator<<(short val);
basic_ostream& operator<<(unsigned short val);
basic_ostream& operator<<(int val);
basic_ostream& operator<<(unsigned int val);
basic_ostream& operator<<(long val);
basic_ostream& operator<<(unsigned long val);
basic_ostream& operator<<(float val);
basic_ostream& operator<<(double val);
basic_ostream& operator<<(long double val);
basic_ostream& operator<<(const void *val);
basic_ostream& put(char_type ch);
basic_ostream& write(char_type *str, streamsize count);
basic_ostream& flush();
pos_type tellp();
basic_ostream& seekp(pos_type pos);
basic_ostream& seekp(off_type off,
ios_base::seek_dir way);
};The template class describes an object that controls
insertion of elements and encoded objects into a
stream buffer
with elements of type Elem, also known as
char_type, whose
character traits are determined by the
class Tr, 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 basic_ostream<Elem, Tr> stores only
a virtual public base object of class
basic_ios<Elem, Tr>
explicit basic_ostream(basic_streambuf<Elem, Tr> *strbuf);
The constructor initializes the base class by calling
init(strbuf).
basic_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.
basic_ostream& operator<<(
basic_ostream& (*pfn)(basic_ostream&));
basic_ostream& operator<<(
ios_base& (*pfn)(ios_base&));
basic_ostream& operator<<(
basic_ios<Elem, Tr>& (*pfn)(basic_ios<Elem, Tr>&));
basic_ostream& operator<<(
basic_streambuf<Elem, Tr> *strbuf);
basic_ostream& operator<<(bool val);
basic_ostream& operator<<(short val);
basic_ostream& operator<<(unsigned short val);
basic_ostream& operator<<(int val);
basic_ostream& operator<<(unsigned int val);
basic_ostream& operator<<(long val);
basic_ostream& operator<<(unsigned long val);
basic_ostream& operator<<(float val);
basic_ostream& operator<<(double val);
basic_ostream& operator<<(long double val);
basic_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:
basic_ostream& operator<<(
basic_streambuf<Elem, Tr> *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.
The function:
basic_ostream& operator<<(bool val);
converts val to a boolean field and inserts it by calling
use_facet<num_put<Elem,
OutIt>(getloc()).
put(OutIt(
rdbuf()), *this,
getloc(), val). Here, OutIt is defined as
ostreambuf_iterator<Elem,
Tr>.
The function returns *this.
The functions:
basic_ostream& operator<<(short val);
basic_ostream& operator<<(unsigned short val);
basic_ostream& operator<<(int val);
basic_ostream& operator<<(unsigned int val);
basic_ostream& operator<<(long val);
basic_ostream& operator<<(unsigned long val);
basic_ostream& operator<<(const void *val);
each convert val to a numeric field and insert it by calling
use_facet<num_put<Elem,
OutIt>(getloc()).
put(OutIt(
rdbuf()), *this,
getloc(), val). Here, OutIt is defined as
ostreambuf_iterator<Elem,
Tr>.
The function returns *this.
The functions:
basic_ostream& operator<<(float val);
basic_ostream& operator<<(double val);
basic_ostream& operator<<(long double val);
each convert val to a numeric field and insert it by calling
use_facet<num_put<Elem,
OutIt>(getloc()).
put(OutIt(
rdbuf()), *this,
getloc(), val). Here, OutIt is defined as
ostreambuf_iterator<Elem,
Tr>. The function returns *this.
basic_ostream& put(char_type ch);
The unformatted output function
inserts the element ch. It returns *this.
basic_ostream& seekp(pos_type pos);
basic_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(basic_ostream<Elem, Tr>& 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
uncaught_exception()
returns false and
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).
basic_ostream& write(const char_type *str, streamsize count);
The unformatted output function
inserts the sequence of count elements
beginning at str.
template class<Elem, Tr>
basic_ostream<Elem, Tr>& endl(basic_ostream<Elem, Tr>& ostr);The manipulator calls
ostr.put(ostr.
widen('\n')),
then calls
ostr.flush().
It returns ostr.
template class<Elem, Tr>
basic_ostream<Elem, Tr>& ends(basic_ostream<Elem, Tr>& ostr);The manipulator calls
ostr.put(Elem('\0')).
It returns ostr.
template class<Elem, Tr>
basic_ostream<Elem, Tr>& flush(basic_ostream<Elem, Tr>& ostr);The manipulator calls
ostr.flush().
It returns ostr.
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
const Elem *str);
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
Elem ch);
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
const char *str);
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
char ch);
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
const char *str);
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
char ch);
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
const signed char *str);
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
signed char ch);
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
const unsigned char *str);
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
unsigned char ch);The template function:
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
const Elem *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 template function:
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
Elem 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 template function:
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
const char *str);behaves the same as:
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
const Elem *str);except that each element ch of the sequence beginning
at str is converted to an object of type Elem by calling
ostr.put(ostr.
widen(ch)).
The template function:
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
char ch);behaves the same as:
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
Elem ch);except that ch is converted to an object
of type Elem by calling
ostr.put(ostr.
widen(ch)).
The template function:
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
const char *str);behaves the same as:
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
const Elem *str);(It does not have to widen the elements before inserting them.)
The template function:
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
char ch);behaves the same as:
template<class Elem, class Tr>
basic_ostream<Elem, Tr>&
operator<<(basic_ostream<Elem, Tr>& ostr,
Elem ch);(It does not have to widen ch before inserting it.)
The template function:
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
const signed char *str);returns ostr << (const char *)str.
The template function:
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
signed char ch);returns ostr << (char)ch.
The template function:
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
const unsigned char *str);returns ostr << (const char *)str.
The template function:
template<class Tr>
basic_ostream<char, Tr>&
operator<<(basic_ostream<char, Tr>& ostr,
unsigned char ch);returns ostr << (char)ch.
typedef basic_ostream<char, char_traits<char> > ostream;
The type is a synonym for template class
basic_ostream, specialized
for elements of type char with default
character traits.
typedef basic_ostream<wchar_t, char_traits<wchar_t> >
wostream;The type is a synonym for template class
basic_ostream, specialized
for elements of type wchar_t with default
character traits.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
66 - 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.
67 - 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.
68 - 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.
69 - 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.
70 - 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.
71 - 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.
72 - sstream
<sstream>
Include the iostreams
standard header <sstream>
to define several template classes that support
iostreams operations on
sequences stored in an allocated array object.
Such sequences are easily converted to and from objects of
template class
basic_string.
namespace std {
template<class Elem,
class Tr = char_traits<Elem>,
class Alloc = allocator<Elem> >
class basic_stringbuf;
typedef basic_stringbuf<char> stringbuf;
typedef basic_stringbuf<wchar_t> wstringbuf;
template<class Elem,
class Tr = char_traits<Elem>,
class Alloc = allocator<Elem> >
class basic_istringstream;
typedef basic_istringstream<char> istringstream;
typedef basic_istringstream<wchar_t> wistringstream;
template<class Elem,
class Tr = char_traits<Elem>,
class Alloc = allocator<Elem> >
class basic_ostringstream;
typedef basic_ostringstream<char> ostringstream;
typedef basic_ostringstream<wchar_t> wostringstream;
template<class Elem,
class Tr = char_traits<Elem>,
class Alloc = allocator<Elem> >
class basic_stringstream;
typedef basic_stringstream<char> stringstream;
typedef basic_stringstream<wchar_t> wstringstream;
};template <class Elem,
class Tr = char_traits<Elem>,
class Alloc = allocator<Elem> >
class basic_stringbuf
: public basic_streambuf<Elem, Tr> {
public:
typedef typename basic_streambuf<Elem, Tr>::char_type
char_type;
typedef typename basic_streambuf<Elem, Tr>::traits_type
traits_type;
typedef typename basic_streambuf<Elem, Tr>::int_type
int_type;
typedef typename basic_streambuf<Elem, Tr>::pos_type
pos_type;
typedef typename basic_streambuf<Elem, Tr>::off_type
off_type;
typedef Alloc allocator_type;
basic_stringbuf(ios_base::openmode mode =
ios_base::in | ios_base::out);
basic_stringbuf(const basic_string<Elem, Tr, Alloc>& str,
ios_base::openmode mode =
ios_base::in | ios_base::out);
basic_string<Elem, Tr, Alloc> str() const;
void str(const basic_string<Elem, Tr, Alloc>& 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 template class
describes a stream buffer that controls
the transmission of elements
of type Elem, whose
character traits are determined by the
class Tr,
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
basic_stringbuf<Elem, Tr, Alloc>
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.
basic_stringbuf(ios_base::openmode mode =
ios_base::in | ios_base::out);
basic_stringbuf(const basic_string<Elem, Tr, Alloc>& 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 Elem char_type;
The type is a synonym for the template parameter Elem.
typedef typename traits_type::int_type int_type;
The type is a synonym for
traits_type::int_type.
typedef typename 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 typename 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
basic_stringbuf<Elem, Tr, Alloc>,
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
basic_stringbuf<Elem, Tr, Alloc>,
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.
basic_string<Elem, Tr, Alloc> str() const;
void str(const basic_string<Elem, Tr, Alloc>& newstr);
The first member function returns an object of class
basic_string<Elem, Tr, Alloc>,
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 Tr traits_type;
The type is a synonym for the template parameter Tr.
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.
template <class Elem,
class Tr = char_traits<Elem>,
class Alloc = allocator<Elem> >
class basic_istringstream
: public basic_istream<Elem, Tr> {
public:
typedef Alloc allocator_type;
explicit basic_istringstream(
ios_base::openmode mode = ios_base::in);
explicit basic_istringstream(
const basic_string<Elem, Tr, Alloc>& str,
ios_base::openmode mode = ios_base::in);
basic_stringbuf<Elem, Tr, Alloc> *rdbuf() const;
basic_string<Elem, Tr, Alloc> str();
void str(const basic_string<Elem, Tr, Alloc>& newstr);
};The template class describes an object that controls
extraction of elements and encoded objects from a
stream buffer of class
basic_stringbuf<Elem, Tr, Alloc>,
with elements of type Elem, whose
character traits are determined
by the class Tr, and whose elements are allocated by
an allocator of class Alloc. The object stores an object of class
basic_stringbuf<Elem, Tr, Alloc>.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
explicit basic_istringstream(
ios_base::openmode mode = ios_base::in);
explicit basic_istringstream(
const basic_string<Elem, Tr, Alloc>& str,
ios_base::openmode mode = ios_base::in);The first constructor initializes the base class by calling
basic_istream(sb),
where sb is the stored object of class
basic_stringbuf<Elem, Tr, Alloc>.
It also initializes sb by calling
basic_stringbuf<Elem,
Tr, Alloc>(mode | ios_base::in).
The second constructor initializes the base class by calling
basic_istream(sb).
It also initializes sb by calling
basic_stringbuf<Elem,
Tr, Alloc>(str, mode | ios_base::in).
basic_stringbuf<Elem, Tr, Alloc> *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
basic_stringbuf<Elem,
Tr, Alloc>.
basic_string<Elem, Tr, Alloc> str() const;
void str(const basic_string<Elem, Tr, Alloc>& newstr);
The first member function returns
rdbuf()->
str().
The second member function calls rdbuf()-> str(newstr).
template <class Elem,
class Tr = char_traits<Elem>,
class Alloc = allocator<Elem> >
class basic_ostringstream
: public basic_ostream<Elem, Tr> {
public:
explicit basic_ostringstream(
ios_base::openmode mode = ios_base::out);
explicit basic_ostringstream(
const basic_string<Elem, Tr, Alloc>& str,
ios_base::openmode mode = ios_base::out);
basic_stringbuf<Elem, Tr, Alloc> *rdbuf() const;
basic_string<Elem, Tr, Alloc> str();
void str(const basic_string<Elem, Tr, Alloc>& newstr);
};The template class describes an object that controls
insertion of elements and encoded objects into a
stream buffer of class
basic_stringbuf<Elem, Tr, Alloc>,
with elements of type Elem, whose
character traits are determined
by the class Tr, and whose elements are allocated by
an allocator of class Alloc. The object stores an object of class
basic_stringbuf<Elem, Tr, Alloc>.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
explicit basic_ostringstream(
ios_base::openmode mode = ios_base::out);
explicit basic_ostringstream(
const basic_string<Elem, Tr, Alloc>& str,
ios_base::openmode mode = ios_base::out);The first constructor initializes the base class by calling
basic_ostream(sb),
where sb is the stored object of class
basic_stringbuf<Elem, Tr, Alloc>.
It also initializes sb by calling
basic_stringbuf<Elem,
Tr, Alloc>(mode | ios_base::out).
The second constructor initializes the base class by calling
basic_ostream(sb).
It also initializes sb by calling
basic_stringbuf<Elem,
Tr, Alloc>(str, mode | ios_base::out).
basic_stringbuf<Elem, Tr, Alloc> *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
basic_stringbuf<Elem,
Tr, Alloc>.
basic_string<Elem, Tr, Alloc> str() const;
void str(const basic_string<Elem, Tr, Alloc>& newstr);
The first member function returns
rdbuf()->
str().
The second member function calls rdbuf()-> str(newstr).
template <class Elem,
class Tr = char_traits<Elem>,
class Alloc = allocator<Elem> >
class basic_stringstream
: public basic_iostream<Elem, Tr> {
public:
typedef Alloc allocator_type;
explicit basic_stringstream(
ios_base::openmode mode =
ios_base::in | ios_base::out);
explicit basic_stringstream(
const basic_string<Elem, Tr, Alloc>& str,
ios_base::openmode mode =
ios_base::in | ios_base::out);
basic_stringbuf<Elem, Tr, Alloc> *rdbuf() const;
basic_string<Elem, Tr, Alloc> str();
void str(const basic_string<Elem, Tr, Alloc>& newstr);
};The template class describes an object that controls
insertion and extraction of elements and encoded objects using a
stream buffer of class
basic_stringbuf<Elem, Tr, Alloc>,
with elements of type Elem, whose
character traits are determined
by the class Tr, and whose elements are allocated by
an allocator of class Alloc. The object stores an object of class
basic_stringbuf<Elem, Tr, Alloc>.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
explicit basic_stringstream(
ios_base::openmode mode =
ios_base::in | ios_base::out);
explicit basic_stringstream(
const basic_string<Elem, Tr, Alloc>& str,
ios_base::openmode mode =
ios_base::in | ios_base::out);The first constructor initializes the base class by calling
basic_iostream(sb),
where sb is the stored object of class
basic_stringbuf<Elem, Tr, Alloc>.
It also initializes sb by calling
basic_stringbuf<Elem,
Tr, Alloc>(mode).
The second constructor initializes the base class by calling
basic_iostream(sb).
It also initializes sb by calling
basic_stringbuf<Elem,
Tr, Alloc>(str, mode).
basic_stringbuf<Elem, Tr, Alloc> *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
basic_stringbuf<Elem,
Tr, Alloc>.
basic_string<Elem, Tr, Alloc> str() const;
void str(const basic_string<Elem, Tr, Alloc>& newstr);
The first member function returns
rdbuf()->
str().
The second member function calls rdbuf()-> str(newstr).
typedef basic_istringstream<char> istringstream;
The type is a synonym for template class
basic_istringstream, specialized
for elements of type char.
typedef basic_ostringstream<char> ostringstream;
The type is a synonym for template class
basic_ostringstream, specialized
for elements of type char.
typedef basic_stringbuf<char> stringbuf;
The type is a synonym for template class
basic_stringbuf, specialized
for elements of type char.
typedef basic_stringstream<char> stringstream;
The type is a synonym for template class
basic_stringstream, specialized
for elements of type char.
typedef basic_istringstream<wchar_t> wistringstream;
The type is a synonym for template class
basic_istringstream, specialized
for elements of type wchar_t.
typedef basic_ostringstream<wchar_t> wostringstream;
The type is a synonym for template class
basic_ostringstream, specialized
for elements of type wchar_t.
typedef basic_stringbuf<wchar_t> wstringbuf;
The type is a synonym for template class
basic_stringbuf, specialized
for elements of type wchar_t.
typedef basic_stringstream<wchar_t> wstringstream;
The type is a synonym for template class
basic_stringstream, specialized
for elements of type wchar_t.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
73 - 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.
74 - 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.
75 - 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.
76 - 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.
namespace std {
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;
};class 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.
77 - 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.
78 - 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.
79 - 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.
80 - streambu
<streambuf>
Include the iostreams
standard header <streambuf> to define
template
class basic_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.)
namespace std {
template<class Elem, class Tr = char_traits<Elem> >
class basic_streambuf;
typedef basic_streambuf<char, char_traits<char> >
streambuf;
typedef basic_streambuf<wchar_t,
char_traits<wchar_t> > wstreambuf;
};
basic_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
template <class Elem, class Tr = char_traits<Elem> >
class basic_streambuf {
public:
typedef Elem char_type;
typedef Tr traits_type;
typedef typename traits_type::int_type int_type;
typedef typename traits_type::pos_type pos_type;
typedef typename traits_type::off_type off_type;
virtual ~streambuf();
locale pubimbue(const locale& loc);
locale getloc() const;
basic_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:
basic_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 basic_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 template 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
basic_streambuf helps control
a stream with elements of type Tr, 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
basic_stringbuf<Elem, Tr>
object, for example, is what you later extract from its input stream.
And when you position one stream of a
basic_filebuf<Elem, Tr>
object, you position the other stream in tandem.
The public interface to template class
basic_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 basic_streambuf<Elem, Tr>
must cooperate in maintaining this protocol.
An object of class basic_streambuf<Elem, Tr>
stores the six pointers described above. It also stores a
locale object
in an object of type
locale
for potential use by a derived stream buffer.
basic_streambuf();
The protected constructor stores a null pointer in all the pointers
controlling the
input buffer and the
output buffer.
It also stores
locale::classic()
in the locale object.
typedef Elem char_type;
The type is a synonym for the template parameter Elem.
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 typename traits_type::int_type int_type;
The type is a synonym for
traits_type::int_type.
typedef typename 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 typename 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).
basic_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 basic_streambuf *setbuf(char_type *buffer,
streamsize count);The protected virtual member function performs an operation
particular to each derived stream buffer. (See, for example,
basic_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 Tr traits_type;
The type is a synonym for the template parameter Tr.
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.
typedef basic_streambuf<char, char_traits<char> >
streambuf;The type is a synonym for template class
basic_streambuf, specialized
for elements of type char with default
character traits.
typedef basic_streambuf<wchar_t, char_traits<wchar_t> >
wstreambuf;The type is a synonym for template class
basic_streambuf, specialized
for elements of type wchar_t with default
character traits.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
81 - 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.
82 - string2
<string>
basic_string
· char_traits
· char_traits<char>
· char_traits<wchar_t>
· getline
· operator+
· operator!=
· operator==
· operator<
· operator<<
· operator<=
· operator>
· operator>=
· operator>>
· string
· swap
· wstring
Include the standard header <string>
to define the
container
template class
basic_string and various
supporting templates.
namespace std {
template<class Elem>
class char_traits;
template<>
class char_traits<char>;
template<>
class char_traits<wchar_t>;
template<class Elem,
class Tr = char_traits<Elem>,
class Alloc = allocator<Elem> >
class basic_string;
typedef basic_string<char> string;
typedef basic_string<wchar_t> wstring;
// TEMPLATE FUNCTIONS
template<class Elem, class Tr, class Alloc>
basic_string<Elem, Tr, Alloc> operator+(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
basic_string<Elem, Tr, Alloc> operator+(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
basic_string<Elem, Tr, Alloc> operator+(
const basic_string<Elem, Tr, Alloc>& left,
Elem right);
template<class Elem, class Tr, class Alloc>
basic_string<Elem, Tr, Alloc> operator+(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
basic_string<Elem, Tr, Alloc> operator+(
Elem left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator==(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator==(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
bool operator==(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator!=(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator!=(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
bool operator!=(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator<(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator<(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
bool operator<(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator>(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator>(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
bool operator>(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator<=(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator<=(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
bool operator<=(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator>=(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator>=(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
bool operator>=(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
void swap(
basic_string<Elem, Tr, Alloc>& left,
basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
basic_ostream<Elem>& operator<<(
basic_ostream<Elem>& ostr,
const basic_string<Elem, Tr, Alloc>& str);
template<class Elem, class Tr, class Alloc>
basic_istream<Elem>& operator>>(
basic_istream<Elem>& istr,
basic_string<Elem, Tr, Alloc>& str);
template<class Elem, class Tr, class Alloc>
basic_istream<Elem, Tr>& getline(
basic_istream<Elem, Tr>& istr,
basic_string<Elem, Tr, Alloc>& str);
template<class Elem, class Tr, class Alloc>
basic_istream<Elem, Tr>& getline(
basic_istream<Elem, Tr>& istr,
basic_string<Elem, Tr, Alloc>& str,
Elem delim);
};
basic_string
· allocator_type
· append
· assign
· at
· begin
· c_str
· capacity
· clear
· compare
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· copy
· data
· difference_type
· empty
· end
· erase
· find
· find_first_not_of
· find_first_of
· find_last_not_of
· find_last_of
· get_allocator
· insert
· iterator
· length
· max_size
· npos
· operator+=
· operator=
· operator[]
· pointer
· push_back
· rbegin
· reference
· rend
· replace
· reserve
· resize
· reverse_iterator
· rfind
· size
· size_type
· substr
· swap
· traits_type
· value_type
template<class Elem,
class Tr = char_traits<Elem>,
class Alloc = allocator<Elem> >
class basic_string {
public:
typedef Tr traits_type;
typedef Alloc allocator_type;
typedef T0 iterator;
typedef T1 const_iterator;
typedef T2 size_type;
typedef T3 difference_type;
typedef reverse_iterator<const_iterator>
const_reverse_iterator;
typedef reverse_iterator<iterator>
reverse_iterator;
typedef typename allocator_type::pointer
pointer;
typedef typename allocator_type::const_pointer
const_pointer;
typedef typename allocator_type::reference
reference;
typedef typename allocator_type::const_reference
const_reference;
typedef typename allocator_type::value_type
value_type;
static const size_type npos = -1;
basic_string();
explicit basic_string(const allocator_type& al);
basic_string(const basic_string& right);
basic_string(const basic_string& right, size_type roff,
size_type count = npos);
basic_string(const basic_string& right, size_type roff,
size_type count, const allocator_type& al);
basic_string(const value_type *ptr, size_type count);
basic_string(const value_type *ptr, size_type count,
const allocator_type& al);
basic_string(const value_type *ptr);
basic_string(const value_type *ptr,
const allocator_type& al);
basic_string(size_type count, value_type ch);
basic_string(size_type count, value_type ch,
const allocator_type& al);
template <class InIt>
basic_string(InIt first, InIt last);
template <class InIt>
basic_string(InIt first, InIt last,
const allocator_type& al);
basic_string& operator=(const basic_string& right);
basic_string& operator=(const value_type *ptr);
basic_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;
basic_string& operator+=(const basic_string& right);
basic_string& operator+=(const value_type *ptr);
basic_string& operator+=(value_type ch); basic_string& append(const basic_string& right);
basic_string& append(const basic_string& right,
size_type roff, size_type count);
basic_string& append(const value_type *ptr,
size_type count);
basic_string& append(const value_type *ptr);
basic_string& append(size_type count, value_type ch);
template<class InIt>
basic_string& append(InIt first, InIt last);
basic_string& assign(const basic_string& right);
basic_string& assign(const basic_string& right,
size_type roff, size_type count);
basic_string& assign(const value_type *ptr,
size_type count);
basic_string& assign(const value_type *ptr);
basic_string& assign(size_type count, value_type ch);
template<class InIt>
basic_string& assign(InIt first, InIt last);
basic_string& insert(size_type off,
const basic_string& right);
basic_string& insert(size_type off,
const basic_string& right, size_type roff,
size_type count);
basic_string& insert(size_type off,
const value_type *ptr, size_type count);
basic_string& insert(size_type off,
const value_type *ptr);
basic_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);
template<class InIt>
void insert(iterator where,
InIt first, InIt last);
basic_string& erase(size_type off = 0,
size_type count = npos);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
void clear();
basic_string& replace(size_type off, size_type n0,
const basic_string& right);
basic_string& replace(size_type off, size_type n0,
const basic_string& right, size_type roff,
size_type count);
basic_string& replace(size_type off, size_type n0,
const value_type *ptr, size_type count);
basic_string& replace(size_type off, size_type n0,
const value_type *ptr);
basic_string& replace(size_type off, size_type n0,
size_type count, value_type ch);
basic_string& replace(iterator first, iterator last,
const basic_string& right);
basic_string& replace(iterator first, iterator last,
const value_type *ptr, size_type count);
basic_string& replace(iterator first, iterator last,
const value_type *ptr);
basic_string& replace(iterator first, iterator last,
size_type count, value_type ch);
template<class InIt>
basic_string&
replace(iterator first, iterator last,
InIt first2, InIt last2);
size_type copy(value_type *ptr, size_type count,
size_type off = 0) const;
void swap(basic_string& right); size_type find(const basic_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 basic_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 basic_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 basic_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 basic_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 basic_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;
basic_string substr(size_type off = 0,
size_type count = npos) const;
int compare(const basic_string& right) const;
int compare(size_type off, size_type n0,
const basic_string& right) const;
int compare(size_type off, size_type n0,
const basic_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 template class describes an object that controls a
varying-length sequence of elements of type Elem,
also known as
value_type.
Such an element type must not require explicit construction or
destruction, and it must be suitable for use as the Elem
parameter to
basic_istream or
basic_ostream.
(A ``plain old data structure,'' or
POD, from C generally meets
this criterion.)
The Standard C++ library provides two specializations of this template
class, with the type definitions
string,
for elements of type char, and
wstring, for elements of type
wchar_t.
Various important properties of the elements
in a basic_string
specialization are described by the class Tr, also known as
traits_type.
A class that specifies these
character traits must
have the same external interface as an object of template class
char_traits.
The object allocates and frees storage for the sequence it controls
through a stored allocator object
of class Alloc, also known as
allocator_type.
Such an allocator object must have
the same external interface as an object of template class
allocator.
(Class
char_traits has
no provision for alternate addressing schemes, such as might be required
to implement a
far heap.)
Note that the stored allocator object is not copied when the container
object is assigned.
The sequences controlled by an object of template class
basic_string are usually called
strings. These objects should not be
confused, however, with the null-terminated
C strings used throughout the
Standard C++ library.
Many member functions require an
operand sequence of elements.
You can specify such an operand sequence several
ways:
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,
for Elem of type char) 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
basic_string object rightright, roff, count -- the substring of the
basic_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 basic_string member function, the function
reports an
out-of-range error by
throwing an object of class
out_of_range.
If a function is asked to generate a sequence longer than
max_size() elements,
the function reports a
length error by
throwing an object of class
length_error.
References, pointers, and iterators that designate elements of the
controlled sequence can become invalid after any call to a function
that alters the controlled sequence, or after the first call to the
non-const member functions
at,
begin,
end,
operator[],
rbegin, or
rend.
(The idea is to permit multiple strings to share the same representation
until one string becomes a candidate for change, at which point that string
makes a private copy of the representation, using a discipline called
copy on write.)
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
basic_string& append(const value_type *ptr);
basic_string& append(const value_type *ptr,
size_type count);
basic_string& append(const basic_string& right,
size_type roff, size_type count);
basic_string& append(const basic_string& right);
basic_string& append(size_type count, value_type ch);
template<class InIt>
basic_string& append(InIt first, InIt last);If InIt is an integer type, the template member
function behaves the same as append((size_type)first, (value_type)last).
Otherwise, the
member functions each append the
operand sequence to the end of the
sequence controlled by *this,
then return *this.
In this
implementation, if a
translator does not support member template functions, the template:
template<class InIt>
basic_string& append(InIt first, InIt last);is replaced by:
basic_string& append(const_pointer first,
const_pointer last);basic_string& assign(const value_type *ptr);
basic_string& assign(const value_type *ptr,
size_type count);
basic_string& assign(const basic_string& right,
size_type roff, size_type count);
basic_string& assign(const basic_string& right);
basic_string& assign(size_type count, value_type ch);
template<class InIt>
basic_string& assign(InIt first, InIt last);If InIt is an integer type, the template member
function behaves the same as assign((size_type)first, (value_type)last).
Otherwise, the
member functions each replace
the sequence controlled by *this with the
operand sequence, then return *this.
In this
implementation, if a
translator does not support member template functions, the template:
template<class InIt>
basic_string& assign(InIt first, InIt last);is replaced by:
basic_string& assign(const_pointer first,
const_pointer last);const_reference at(size_type 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.
basic_string(const value_type *ptr);
basic_string(const value_type *ptr,
const allocator_type& al);
basic_string(const value_type *ptr, size_type count);
basic_string(const value_type *ptr, size_type count,
const allocator_type& al);
basic_string(const basic_string& right);
basic_string(const basic_string& right, size_type roff,
size_type count = npos);
basic_string(const basic_string& right, size_type roff,
size_type count, const allocator_type& al);
basic_string(size_type count, value_type ch);
basic_string(size_type count, value_type ch,
const allocator_type& al);
basic_string();
explicit basic_string(const allocator_type& al);
template <class InIt>
basic_string(InIt first, InIt last);
template <class InIt>
basic_string(InIt first, InIt last, const allocator_type& al);All constructors store an
allocator object and
initialize the controlled sequence. The allocator object is the argument
al, if present. For the copy constructor, it is
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.
If InIt is an integer type in a template constructor,
the operand sequence first, last behaves the same as
(size_type)first, (value_type)last.
In this
implementation, if a
translator does not support member template functions, the templates:
template <class InIt>
basic_string(InIt first, InIt last);
template <class InIt>
basic_string(InIt first, InIt last,
const allocator_type& al);are replaced by:
basic_string(const_pointer first, const_pointer last);
basic_string(const_pointer first, const_pointer last,
const allocator_type& al);const_iterator begin() const;
iterator begin();
The member functions each return a random-access iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
const value_type *c_str() const;
The member function returns a pointer to a non-modifiable
C string constructed by adding a
terminating null element
(value_type()) to the controlled
sequence. Calling any non-const member function for
*this can invalidate the pointer.
size_type capacity() const;
The member function returns the storage currently allocated to hold
the controlled sequence, a value at least as large as
size().
void clear();
The member function calls
erase(
begin(),
end()).
int compare(const basic_string& right) const;
int compare(size_type off, size_type n0,
const basic_string& right) const;
int compare(size_type off, size_type n0,
const basic_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 typename allocator_type::const_pointer
const_pointer;The type is a synonym for allocator_type::const_pointer.
typedef typename allocator_type::const_reference
const_reference;The type is a synonym for allocator_type::const_reference.
typedef reverse_iterator<const_iterator>
const_reverse_iterator;The type describes an object that can serve as a constant reverse
iterator for the controlled sequence.
size_type copy(value_type *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);
basic_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 basic_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 basic_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 basic_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 basic_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 basic_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.
basic_string& insert(size_type off, const value_type *ptr);
basic_string& insert(size_type off, const value_type *ptr,
size_type count);
basic_string& insert(size_type off,
const basic_string& right);
basic_string& insert(size_type off,
const basic_string& right, size_type roff, size_type count);
basic_string& insert(size_type off,
size_type count, value_type ch);
iterator insert(iterator where,
value_type ch = value_type());
template<class InIt>
void insert(iterator where, InIt first, InIt 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.
If InIt is an integer type in the template member function,
the operand sequence first, last behaves the same as
(size_type)first, (value_type)last.
In this
implementation, if a
translator does not support member template functions, the template:
template<class InIt>
void insert(iterator where, InIt first, InIt last);is replaced by:
void insert(iterator where,
const_pointer first, const_pointer last);typedef T0 iterator;
The type describes an object that can serve as a random-access
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T0.
size_type length() const;
The member function returns the length of the controlled sequence
(same as size()).
size_type max_size() const;
The member function returns the length of the longest sequence that
the object can control.
static const size_type npos = -1;
The constant is the largest representable value of type
size_type. It is
assuredly larger than
max_size(), hence
it serves as either a very large value or as a special code.
basic_string& operator+=(value_type ch);
basic_string& operator+=(const value_type *ptr);
basic_string& operator+=(const basic_string& right);
The operators each append the
operand sequence to the end of the
sequence controlled by *this, then return *this.
basic_string& operator=(value_type ch);
basic_string& operator=(const value_type *ptr);
basic_string& operator=(const basic_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 typename 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 typename allocator_type::reference
reference;The type is a synonym for allocator_type::reference.
const_reverse_iterator rend() const;
reverse_iterator rend();
The member functions each return a reverse iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, the function designates the end of the reverse sequence.
basic_string& replace(size_type off, size_type n0,
const value_type *ptr);
basic_string& replace(size_type off, size_type n0,
const value_type *ptr, size_type count);
basic_string& replace(size_type off, size_type n0,
const basic_string& right);
basic_string& replace(size_type off, size_type n0,
const basic_string& right, size_type roff, size_type count);
basic_string& replace(size_type off, size_type n0,
size_type count, value_type ch);
basic_string& replace(iterator first, iterator last,
const value_type *ptr);
basic_string& replace(iterator first, iterator last,
const value_type *ptr, size_type count);
basic_string& replace(iterator first, iterator last,
const basic_string& right);
basic_string& replace(iterator first, iterator last,
size_type count, value_type ch);
template<class InIt>
basic_string&
replace(iterator first, iterator last,
InIt first2, InIt 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.
If InIt is an integer type in the template member function,
the operand sequence first2, last2 behaves the same as
(size_type)first2, (value_type)last2.
In this
implementation, if a
translator does not support member template functions, the template:
template<class InIt>
basic_string& replace(iterator first, iterator last,
InIt first2, InIt last2);is replaced by:
basic_string& replace(iterator first, iterator last,
const_pointer first2, const_pointer last2);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()).
typedef reverse_iterator<iterator>
reverse_iterator;The type describes an object that can serve as a reverse
iterator for the controlled sequence.
size_type rfind(value_type 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 basic_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.
basic_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(basic_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 Tr traits_type;
The type is a synonym for the template parameter Tr.
typedef typename allocator_type::value_type
value_type;The type is a synonym for allocator_type::value_type.
template<class Elem>
class char_traits {
public:
typedef Elem char_type;
typedef T1 int_type;
typedef T2 pos_type;
typedef T3 off_type;
typedef T4 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 template class describes various
character traits
for type Elem.
The template class
basic_string
as well as several iostreams template classes, including
basic_ios, use this information
to manipulate elements of type Elem.
Such an element type must not require explicit construction or
destruction. It must supply a default constructor, a copy constructor,
and an assignment operator, with the expected semantics.
A bitwise copy must have the same effect as an assignment.
Not all parts of the Standard C++ Library rely completely upon the member
functions of char_traits<Elem> to manipulate an element.
Specifically,
formatted input functions and
formatted output functions
make use of the following additional operations,
also with the expected semantics:
operator==(Elem) and operator!=(Elem)
to compare elements(char)ch to convert an element ch
to its corresponding single-byte character code,
or '\0' if no such code exists(Elem)ch to convert a char value ch to
its correponding character code of type Elem
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 Elem char_type;
The type is a synonym for the template parameter Elem.
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 (such as EOF or
WEOF). If the value is also
representable as type Elem,
it must correspond to no valid value of that type.
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 T1 int_type;
The type is (typically) an integer type T1 that
describes an object that can represent any element of the controlled
sequence as well as the value returned by eof().
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 T3 off_type;
The type is a signed integer type T3 that describes an
object that can store a byte offset involved in various stream
positioning operations. It is typically a synonym for
streamoff, but in any case it
has essentially the same properties as that type.
typedef T2 pos_type;
The type is an opaque type T2 that describes an object
that can store all the information needed to restore an arbitrary
file-position indicator
within a stream. It is typically a synonym for
streampos, but in any case it
has essentially the same properties as that type.
typedef T4 state_type;
The type is an opaque type T4 that describes an object
that can represent a
conversion state. It is
typically a synonym for
mbstate_t, but in any
case it has essentially the same properties as that type.
static char_type to_char_type(const int_type& 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.
template<>
class char_traits<char>;The class is an explicit specialization of template class
char_traits
for elements of type char, (so that it
can take advantage of library functions that manipulate objects of this
type).
template<>
class char_traits<wchar_t>;The class is an explicit specialization of template class
char_traits
for elements of type wchar_t (so
that it can take advantage of library functions that manipulate objects
of this type).
template<class Elem, class Tr, class Alloc>
basic_istream<Elem, Tr>& getline(
basic_istream<Elem, Tr>& istr,
basic_string<Elem, Tr, Alloc>& str);
template<class Elem, class Tr, class Alloc>
basic_istream<Elem, Tr>& getline(
basic_istream<Elem, Tr>& istr,
basic_string<Elem, Tr, Alloc>& str,
Elem 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.
template<class Elem, class Tr, class Alloc>
basic_string<Elem, Tr, Alloc> operator+(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
basic_string<Elem, Tr, Alloc> operator+(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
basic_string<Elem, Tr, Alloc> operator+(
const basic_string<Elem, Tr, Alloc>& left,
Elem right);
template<class Elem, class Tr, class Alloc>
basic_string<Elem, Tr, Alloc> operator+(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
basic_string<Elem, Tr, Alloc> operator+(
Elem left,
const basic_string<Elem, Tr, Alloc>& right);The functions each overload operator+ to
concatenate two objects of template class
basic_string.
All effectively return basic_string<Elem, Tr,
Alloc>(left).append(right).
template<class Elem, class Tr, class Alloc>
bool operator!=(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator!=(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
bool operator!=(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);The template functions each overload operator!= to compare
two objects of template class
basic_string. All effectively
return basic_string<Elem, Tr,
Alloc>(left).compare(right) != 0.
template<class Elem, class Tr, class Alloc>
bool operator==(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator==(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
bool operator==(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);The template functions each overload operator== to compare
two objects of template class
basic_string. All effectively
return basic_string<Elem, Tr,
Alloc>(left).compare(right) == 0.
template<class Elem, class Tr, class Alloc>
bool operator<(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator<(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
bool operator<(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);The template functions each overload operator< to
compare two objects of template class
basic_string. All effectively
return basic_string<Elem, Tr,
Alloc>(left).compare(right)
< 0.
template<class Elem, class Tr, class Alloc>
basic_ostream<Elem, Tr>& operator<<(
basic_ostream<Elem, Tr>& ostr,
const basic_string<Elem, Tr, Alloc>& str);The template function overloads operator<< to
insert an object str of template class
basic_string into the stream
ostr The function effectively returns
ostr.write(
str.c_str(),
str.size()).
template<class Elem, class Tr, class Alloc>
bool operator<=(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator<=(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
bool operator<=(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);The template functions each overload operator<= to
compare two objects of template class
basic_string. All effectively
return basic_string<Elem, Tr,
Alloc>(left).compare(right)
<= 0.
template<class Elem, class Tr, class Alloc>
bool operator>(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator>(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
bool operator>(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);The template functions each overload operator> to
compare two objects of template class
basic_string. All effectively
return basic_string<Elem, Tr,
Alloc>(left).compare(right)
> 0.
template<class Elem, class Tr, class Alloc>
bool operator>=(
const basic_string<Elem, Tr, Alloc>& left,
const basic_string<Elem, Tr, Alloc>& right);
template<class Elem, class Tr, class Alloc>
bool operator>=(
const basic_string<Elem, Tr, Alloc>& left,
const Elem *right);
template<class Elem, class Tr, class Alloc>
bool operator>=(
const Elem *left,
const basic_string<Elem, Tr, Alloc>& right);The template functions each overload operator>= to
compare two objects of template class
basic_string. All effectively
return basic_string<Elem, Tr,
Alloc>(left).compare(right)
>= 0.
template<class Elem, class Tr, class Alloc>
basic_istream<Elem, Tr>& operator>>(
basic_istream<Elem, Tr>& istr,
basic_string<Elem, Tr, Alloc>& 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
use_facet<
ctype<Elem> >(
getloc()).
is(
ctype<Elem>::space, 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.
typedef basic_string<char> string;
The type describes a specialization of template class
basic_string specialized for
elements of type char.
template<class Tr, class Alloc>
void swap(
basic_string<Elem, Tr, Alloc>& left,
basic_string<Elem, Tr, Alloc>& right);The template function executes
left.swap(right).
typedef basic_string<wchar_t> wstring;
The type describes a specialization of template class
basic_string for
elements of type wchar_t.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
83 - 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.
namespace std {
class strstreambuf;
class istrstream;
class ostrstream;
class strstream;
};class 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().
class strstream : public iostream {
public:
strstream();
strstream(char *ptr, streamsize count,
ios_base::openmode mode =
ios_base::in | ios_base::out);
strstreambuf *rdbuf() const;
void freeze(bool freezeit = true);
char *str();
streamsize pcount() const;
};The class describes an object that controls
insertion and extraction of elements and encoded objects using 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).
streamsize pcount() const;
The member function returns
rdbuf()->
pcount().
strstream();
strstream(char *ptr, streamsize count,
ios_base::openmode mode =
ios_base::in | ios_base::out);Both constructors initialize the base class by calling
streambuf(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).
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.
84 - 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.
85 - typeinfo
<typeinfo>
Include the standard header <typeinfo>
to define several types associated with the type-identification operator
typeid,
which yields information about both static and dynamic types.
namespace std {
class type_info;
class bad_cast;
class bad_typeid;
};class bad_cast : public exception {
};The class describes an exception thrown to indicate that a
dynamic cast expression,
of the form:
dynamic_cast<type>(expression)
generated a null pointer to initialize a reference.
The value returned by
what()
is an implementation-defined
C string.
None of the member functions throw any exceptions.
class bad_typeid : public exception {
};The class describes an exception thrown to indicate that a
typeid operator encountered a
null pointer. The value returned by
what()
is an implementation-defined
C string.
None of the member functions throw any exceptions.
class type_info {
public:
virtual ~type_info();
bool operator==(const type_info& right) const;
bool operator!=(const type_info& right) const;
bool before(const type_info& right) const;
const char *name() const;
size_t hash_code() const;
private:
type_info(const type_info& right);
type_info& operator=(const type_info& right);
};The class describes type information generated
within the program by the implementation. Objects of this class effectively
store a pointer to a
name for the type,
and an encoded value suitable for comparing two types for equality or
collating order.
The names, encoded values, and collating order for types
are all unspecified and may differ between program executions.
An expression of the form typeid Ty is the only way to
construct a (temporary) typeinfo object. The class has only
a private copy constructor. Since the assignment operator is also
private, you cannot copy or assign objects of class typeinfo
either.
bool operator!=(const type_info& right) const;
The function returns !(*this
== right).
bool operator==(const type_info& right) const;
The function returns a nonzero value if *this
and right represent the same type.
bool before(const type_info& right) const;
The function returns a nonzero value if *this
precedes right in the
collating order for types.
const char *name() const;
The function returns a
C string which specifies the
name of the type.
size_t hash_code() const;
The function returns same value for any two typeinfo
objects which compare equal. Objects that do not compare equal return
different values.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
86 - 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.
87 - valarray
<valarray>
gslice
· gslice_array
· indirect_array
· mask_array
· slice
· slice_array
· valarray
· valarray<bool>
abs
· acos
· asin
· atan
· atan2
· cos
· cosh
· exp
· log
· log10
· operator!=
· operator%
· operator&
· operator&&
· operator>
· operator>>
· operator>=
· operator<
· operator<<
· operator<=
· operator*
· operator+
· operator-
· operator/
· operator==
· operator^
· operator|
· operator||
· pow
· sin
· sinh
· sqrt
· tan
· tanh
Include the standard header <valarray>
to define the template class
valarray and numerous
supporting template classes and functions. These template classes and functions
are permitted unusual latitude, in the interest of improved performance.
Specifically, any function described here as
returning valarray<Ty> may actually return
an object of some other type Other. In that case, any other
function described here that
accepts one or more arguments of type valarray<Ty> must have
overloads that accept arbitrary combinations of those arguments,
each replaced with an argument of type Other. (Put simply,
the only way you can detect such a substitution is to go looking for it.)
namespace std {
class slice;
class gslice;
// TEMPLATE CLASSES
template<class Ty>
class valarray;
template<class Ty>
class slice_array;
template<class Ty>
class gslice_array;
template<class Ty>
class mask_array;
template<class Ty>
class indirect_array;
// TEMPLATE FUNCTIONS
template<class Ty>
valarray<Ty> operator*(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator*(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator*(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator/(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator/(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator/(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator%(const valarray<Ty>& left,
const vararray<Ty>& right);
template<class Ty>
valarray<Ty> operator%(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator%(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator+(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator+(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator+(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator-(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator-(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator-(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator^(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator^(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator^(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator&(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator&(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator&(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator|(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator|(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator|(const Ty& left,
const valarray<Ty>& right);template<class Ty>
valarray<Ty> operator<<(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator<<(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator<<(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator>>(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator>>(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator>>(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator&&(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator&&(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<bool> operator&&(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator||(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator||(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<bool> operator||(const Ty& left,
const valarray<Ty>& right);template<class Ty>
valarray<bool> operator==(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator==(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<bool> operator==(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator!=(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator!=(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<bool> operator!=(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator<(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator<(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<bool> operator<(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator>=(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator>=(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<bool> operator>=(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator>(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator>(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<bool> operator>(const Ty& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator<=(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator<=(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<bool> operator<=(const Ty& left,
const valarray<Ty>& right);template<class Ty>
valarray<Ty> abs(const valarray<Ty>& left);
template<class Ty>
valarray<Ty> acos(const valarray<Ty>& left);
template<class Ty>
valarray<Ty> asin(const valarray<Ty>& left);
template<class Ty>
valarray<Ty> atan(const valarray<Ty>& left);
template<class Ty>
valarray<Ty> atan2(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> atan2(const valarray<Ty> left, const Ty& right);
template<class Ty>
valarray<Ty> atan2(const Ty& left, const valarray<Ty>& right);
template<class Ty>
valarray<Ty> cos(const valarray<Ty>& left);
template<class Ty>
valarray<Ty> cosh(const valarray<Ty>& left);
template<class Ty>
valarray<Ty> exp(const valarray<Ty>& left);
template<class Ty>
valarray<Ty> log(const valarray<Ty>& left);
template<class Ty>
valarray&tt;Ty> log10(const valarray<Ty>& left);
template<class Ty>
valarray<Ty> pow(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> pow(const valarray<Ty> left, const Ty& right);
template<class Ty>
valarray<Ty> pow(const Ty& left, const valarray<Ty>& right);
template<class Ty>
valarray<Ty> sin(const valarray<Ty>& left);
template<class Ty>
valarray<Ty> sinh(const valarray<Ty>& left);
template<class Ty>
valarray<Ty> sqrt(const valarray<Ty>& left);
template<class Ty>
valarray<Ty> tan(const valarray<Ty>& left);
template<class Ty>
valarray<Ty> tanh(const valarray<Ty>& left);
};template<class Ty>
valarray<Ty> abs(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the absolute value of left[I].
template<class Ty>
valarray<Ty> acos(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the arccosine of left[I].
template<class Ty>
valarray<Ty> asin(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the arcsine of left[I].
template<class Ty>
valarray<Ty> atan(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the arctangent of left[I].
template<class Ty>
valarray<Ty> atan2(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> atan2(const valarray<Ty> left, const Ty& right);
template<class Ty>
valarray<Ty> atan2(const Ty& left, const valarray<Ty>& right);The first template function returns an object of class
valarray<Ty>, each of whose
elements I is the arctangent of left[I] / right[I].
The second template function stores in element I
the arctangent of left[I] / right.
The third template function stores in element I
the arctangent of left / right[I].
template<class Ty>
valarray<Ty> cos(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the cosine of left[I].
template<class Ty>
valarray<Ty> cosh(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the hyperbolic cosine of left[I].
template<class Ty>
valarray<Ty> exp(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the exponential of left[I].
class gslice {
public:
gslice();
gslice(size_t off,
const valarray<size_t> lenarr,
const valarray<size_t> incarr);
size_t start() const;
const valarray<size_t> size() const;
const valarray<size_t> stride() const;
};The class stores the parameters that characterize a
gslice_array when an
object of class gslice appears as a subscript
for an object of class
valarray<Ty>.
The stored values include:
- a starting index
- a length vector of class
valarray<size_t> - a stride vector of class
valarray<size_t>
The two vectors must have the same length.
gslice();
gslice(size_t off,
const valarray<size_t> lenarr,
const valarray<size_t> incarr);The default constructor stores zero for the starting index,
and zero-length vectors for the length and stride vectors.
The second constructor stores off
for the starting index, lenarr for the length vector,
and incarr for the stride vector.
const valarray<size_t> size() const;
The member function returns the stored length vector.
size_t start() const;
The member function returns the stored starting index.
const valarray<size_t> stride() const;
The member function returns the stored stride vector.
template<class Ty>
class gslice_array {
public:
typedef Ty value_type;
void operator=(const valarray<Ty> right) const;
void operator=(const Ty& right) const;
void operator*=(const valarray<Ty> right) const;
void operator/=(const valarray<Ty> right) const;
void operator%=(const valarray<Ty> right) const;
void operator+=(const valarray<Ty> right) const;
void operator-=(const valarray<Ty> right) const;
void operator^=(const valarray<Ty> right) const;
void operator&=(const valarray<Ty> right) const;
void operator|=(const valarray<Ty> right) const;
void operator<<=(const valarray<Ty> right) const;
void operator>>=(const valarray<Ty> right) const;
private:
void gslice_array(); // not defined
void gslice_array(
const gslice_array&); // not defined
gslice_array& operator=(
const gslice_array&); // not defined
};The class describes an object that
stores a reference to an object va of class
valarray<Ty>,
along with an object gs of class
gslice which
describes the sequence of elements to select from the
valarray<Ty> object.
You construct a gslice_array<Ty> object only
by writing an expression of the form
va[gs].
The member functions of class gslice_array then
behave like the corresponding function signatures defined
for valarray<Ty>, except that only the sequence
of selected elements is affected.
The sequence is determined as follows. For a length vector
gs.size()
of length N, construct the index
vector valarray<size_t> idx(0, N). This
designates the initial element of the sequence, whose index
K within va is given by the mapping:
K = gs.start();
for (size_t I = 0; I < N; ++I)
K += idx[I] * gs.stride()[I];The successor to an index vector value is given by:
for (size_t I = N; 0 < I--; )
if (++idx[I] < gs.size()[I])
break;
else
idx[I] = 0;For example:
const size_t lv[] = {2, 3};
const size_t dv[] = {7, 2};
const valarray<size_t> len(lv, 2), str(dv, 2);
// va[gslice(3, len, str)] selects elements with
// indices 3, 5, 7, 10, 12, 14template<class Ty>
class indirect_array {
public:
typedef Ty value_type;
void operator=(const valarray<Ty> right) const;
void operator=(const Ty& right) const;
void operator*=(const valarray<Ty> right) const;
void operator/=(const valarray<Ty> right) const;
void operator%=(const valarray<Ty> right) const;
void operator+=(const valarray<Ty> right) const;
void operator-=(const valarray<Ty> right) const;
void operator^=(const valarray<Ty> right) const;
void operator&=(const valarray<Ty> right) const;
void operator|=(const valarray<Ty> right) const;
void operator<<=(const valarray<Ty> right) const;
void operator>>=(const valarray<Ty> right) const;
private:
private:
void indirect_array(); // not defined
void indirect_array(
const indirect_array&); // not defined
indirect_array& operator=(
const indirect_array&); // not defined
};The class describes an object that
stores a reference to an object va of class
valarray<Ty>,
along with an object xa of class
valarray<size_t> which
describes the sequence of elements to select from the
valarray<Ty> object.
You construct an indirect_array<Ty> object only
by writing an expression of the form
va[xa].
The member functions of class indirect_array then
behave like the corresponding function signatures defined
for valarray<Ty>, except that only the sequence
of selected elements is affected.
The sequence consists of
xa.size()
elements, where element I becomes the index
xa[I] within va. For example:
const size_t vi[] = {7, 5, 2, 3, 8};
// va[valarray<size_t>(vi, 5)] selects elements with
// indices 7, 5, 2, 3, 8template<class Ty>
valarray<Ty> log(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the natural logarithm of left[I].
template<class Ty>
valarray<Ty> log10(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the base-10 logarithm of left[I].
template<class Ty>
class mask_array {
public:
typedef Ty value_type;
void operator=(const valarray<Ty> right) const;
void operator=(const Ty& right) const;
void operator*=(const valarray<Ty> right) const;
void operator/=(const valarray<Ty> right) const;
void operator%=(const valarray<Ty> right) const;
void operator+=(const valarray<Ty> right) const;
void operator-=(const valarray<Ty> right) const;
void operator^=(const valarray<Ty> right) const;
void operator&=(const valarray<Ty> right) const;
void operator|=(const valarray<Ty> right) const;
void operator<<=(const valarray<Ty> right) const;
void operator>>=(const valarray<Ty> right) const;
private:
void mask_array(); // not defined
void mask_array(
const mask_array&); // not defined
gslice_array& operator=(
const mask_array&); // not defined
};The class describes an object that
stores a reference to an object va of class
valarray<Ty>,
along with an object ba of class
valarray<bool> which
describes the sequence of elements to select from the
valarray<Ty> object.
You construct a mask_array<Ty> object only
by writing an expression of the form
va[ba].
The member functions of class mask_array then
behave like the corresponding function signatures defined
for valarray<Ty>, except that only the sequence
of selected elements is affected.
The sequence consists of at most
ba.size()
elements. An element J is included only if ba[J]
is true. Thus, there are as many elements in the sequence as there are
true elements in ba.
If I is the index of the lowest true element
in ba, then va[I] is element zero in the
selected sequence. For example:
const bool vb[] = {false, false, true, true, false, true};
// va[valarray<bool>(vb, 56] selects elements with
// indices 2, 3, 5template<class Ty>
valarray<bool> operator!=(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator!=(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<bool> operator!=(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<bool>,
each of whose
elements I is left[I] != right[I].
The second template operator stores in element I
left[I] != right.
The third template operator stores in element I
left != right[I].
template<class Ty>
valarray<Ty> operator%(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator%(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator%(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<Ty>,
each of whose
elements I is left[I] % right[I].
The second template operator stores in element I
left[I] % right.
The third template operator stores in element I
left % right[I].
template<class Ty>
valarray<Ty> operator&(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator&(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator&(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<Ty>,
each of whose
elements I is left[I] & right[I].
The second template operator stores in element I
left[I] & right.
The third template operator stores in element I
left & right[I].
template<class Ty>
valarray<bool> operator&&(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator&&(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<bool> operator&&(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<bool>,
each of whose
elements I is left[I] && right[I].
The second template operator stores in element I
left[I] && right.
The third template operator stores in element I
left && right[I].
template<class Ty>
valarray<bool> operator>(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator>(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<bool> operator>(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<bool>,
each of whose
elements I is left[I] > right[I].
The second template operator stores in element I
left[I] > right.
The third template operator stores in element I
left > right[I].
template<class Ty>
valarray<Ty> operator>>(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator>>(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator>>(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<Ty>,
each of whose
elements I is left[I] >> right[I].
The second template operator stores in element I
left[I] >> right.
The third template operator stores in element I
left >> right[I].
template<class Ty>
valarray<bool> operator>=(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator>=(const valarray<Ty> left, const Ty& right);
template<class Ty>
valarray<bool> operator>=(const Ty& left, const valarray<Ty>& right);The first template operator returns an object of class
valarray<bool>,
each of whose
elements I is left[I] >= right[I].
The second template operator stores in element I
left[I] >= right.
The third template operator stores in element I
left >= right[I].
template<class Ty>
valarray<bool> operator<(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator<(const valarray<Ty> left, const Ty& right);
template<class Ty>
valarray<bool> operator<(const Ty& left, const valarray<Ty>& right);The first template operator returns an object of class
valarray<bool>,
each of whose
elements I is left[I] < right[I].
The second template operator stores in element I
left[I] < right.
The third template operator stores in element I
left < right[I].
template<class Ty>
valarray<Ty> operator<<(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator<<(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator<<(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<Ty>,
each of whose
elements I is left[I] << right[I].
The second template operator stores in element I
left[I] << right.
The third template operator stores in element I
left << right[I].
template<class Ty>
valarray<bool> operator<=(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator<=(const valarray<Ty> left, const Ty& right);
template<class Ty>
valarray<bool> operator<=(const Ty& left, const valarray<Ty>& right);The first template operator retrrns an object of class
valarray<bool>,
each of whose
elements I is left[I] <= right[I].
The second template operator stores in element I
left[I] <= right.
The third template operator stores in element I
left <= right[I].
template<class Ty>
valarray<Ty> operator*(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator*(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator*(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<Ty>,
each of whose
elements I is left[I] * right[I].
The second template operator stores in element I
left[I] * right.
The third template operator stores in element I
left * right[I].
template<class Ty>
valarray<Ty> operator+(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator+(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator+(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<Ty>,
each of whose
elements I is left[I] + right[I].
The second template operator stores in element I
left[I] + right.
The third template operator stores in element I
left + right[I].
template<class Ty>
valarray<Ty> operator-(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator-(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator-(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<Ty>,
each of whose
elements I is left[I] - right[I].
The second template operator stores in element I
left[I] - right.
The third template operator stores in element I
left - right[I].
template<class Ty>
valarray<Ty> operator/(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator/(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator/(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<Ty>,
each of whose
elements I is left[I] / right[I].
The second template operator stores in element I
left[I] / right.
The third template operator stores in element I
left / right[I].
template<class Ty>
valarray<bool> operator==(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator==(const valarray<Ty> left, const Ty& right);
template<class Ty>
valarray<bool> operator==(const Ty& left const valarray<Ty>& right);The first template operator returns an object of class
valarray<bool>,
each of whose
elements I is left[I] == right[I].
The second template operator stores in element I
left[I] == right.
The third template operator stores in element I
left == right[I].
template<class Ty>
valarray<Ty> operator^(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator^(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator^(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<Ty>,
each of whose
elements I is left[I] ^ right[I].
The second template operator stores in element I
left[I] ^ right.
The third template operator stores in element I
left ^ right[I].
template<class Ty>
valarray<Ty> operator|(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> operator|(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<Ty> operator|(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<Ty>,
each of whose
elements I is left[I] | right[I].
The second template operator stores in element I
left[I] | right.
The third template operator stores in element I
left | right[I].
template<class Ty>
valarray<bool> operator||(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<bool> operator||(const valarray<Ty> left,
const Ty& right);
template<class Ty>
valarray<bool> operator||(const Ty& left,
const valarray<Ty>& right);The first template operator returns an object of class
valarray<bool>,
each of whose
elements I is left[I] || right[I].
The second template operator stores in element I
left[I] || right.
The third template operator stores in element I
left || right[I].
template<class Ty>
valarray<Ty> pow(const valarray<Ty>& left,
const valarray<Ty>& right);
template<class Ty>
valarray<Ty> pow(const valarray<Ty> left, const Ty& right);
template<class Ty>
valarray<Ty> pow(const Ty& left, const valarray<Ty>& right);The first template function returns an object of class
valarray<Ty>, each of whose
elements I is left[I] raised to the
right[I] power.
The second template function stores in element I
left[I] raised to the right power.
The third template function stores in element I
left raised to the right[I] power.
template<class Ty>
valarray<Ty> sin(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the sine of left[I].
template<class Ty>
valarray<Ty> sinh(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the hyperbolic sine of left[I].
class slice {
public:
slice();
slice(size_t st, size_t len, size_t str);
size_t start() const;
size_t size() const;
size_t stride() const;
};The class stores the parameters that characterize a
slice_array when an
object of class slice appears as a subscript
for an object of class
valarray<Ty>.
The stored values include:
- a starting index
- a total length
- a stride, or distance between subsequent indices
slice();
slice(size_t st,
const valarray<size_t> len, const valarray<size_t> str);The default constructor stores zeros for the starting index,
total length, and stride. The second constructor stores st
for the starting index, len for the total length,
and str for the stride.
size_t size() const;
The member function returns the stored total length.
size_t start() const;
The member function returns the stored starting index.
size_t stride() const;
The member function returns the stored stride.
template<class Ty>
class slice_array {
public:
typedef Ty value_type;
void operator=(const valarray<Ty> right) const;
void operator=(const Ty& right) const;
void operator*=(const valarray<Ty> right) const;
void operator/=(const valarray<Ty> right) const;
void operator%=(const valarray<Ty> right) const;
void operator+=(const valarray<Ty> right) const;
void operator-=(const valarray<Ty> right) const;
void operator^=(const valarray<Ty> right) const;
void operator&=(const valarray<Ty> right) const;
void operator|=(const valarray<Ty> right) const;
void operator<<=(const valarray<Ty> right) const;
void operator>>=(const valarray<Ty> right) const;
private:
void slice_array(); // not defined
void slice_array(
const slice_array&); // not defined
slice_array& operator=(
const slice_array&); // not defined
};The class describes an object that
stores a reference to an object va of class
valarray<Ty>,
along with an object sl of class
slice which
describes the sequence of elements to select from the
valarray<Ty> object.
You construct a slice_array<Ty> object only
by writing an expression of the form
va[sl].
The member functions of class slice_array then
behave like the corresponding function signatures defined
for valarray<Ty>, except that only the sequence
of selected elements is affected.
The sequence consists of
sl.size()
elements, where element I becomes the index
sl.start() + I *
sl.stride() within va.
For example:
// va[slice(2, 5, 3)] selects elements with
// indices 2, 5, 8, 11, 14
template<class Ty>
valarray<Ty> sqrt(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the square root of left[I].
template<class Ty>
valarray<Ty> tan(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the tangent of left[I].
template<class Ty>
valarray<Ty> tanh(const valarray<Ty>& left);The template function returns an object of class
valarray<Ty>, each of whose
elements I is the hyperbolic tangent of left[I].
apply
· cshift
· max
· min
· operator!
· operator%=
· operator&=
· operator>>=
· operator<<=
· operator*=
· operator+
· operator+=
· operator-
· operator-=
· operator/=
· operator=
· operator[]
· operator^=
· operator|=
· operator~
· resize
· shift
· size
· sum
· valarray
· value_type
template<class Ty>
class valarray {
public:
typedef Ty value_type;
valarray();
explicit valarray(size_t count);
valarray(const Ty& val, size_t count));
valarray(const Ty *ptr, size_t count);
valarray(const slice_array<Ty>& slicearr);
valarray(const gslice_array<Ty>& gslicearr);
valarray(const mask_array<Ty>& maskarr);
valarray(const indirect_array<Ty>& indarr);
valarray<Ty>& operator=(const valarray<Ty>& right);
valarray<Ty>& operator=(const Ty& val);
valarray<Ty>& operator=(const slice_array<Ty>& slicearr);
valarray<Ty>& operator=(const gslice_array<Ty>& gslicearr);
valarray<Ty>& operator=(const mask_array<Ty>& maskarr);
valarray<Ty>& operator=(const indirect_array<Ty>& indarr);
Ty& operator[](size_t off);
slice_array<Ty> operator[](slice slicearr);
gslice_array<Ty> operator[](const gslice& gslicearr);
mask_array<Ty> operator[](const valarray<bool>& boolarr);
indirect_array<Ty>
operator[](const valarray<size_t>& indarr);
Ty operator[](size_t off) const;
valarray<Ty> operator[](slice slicearr) const;
valarray<Ty> operator[](const gslice& gslicearr) const;
valarray<Ty>
operator[](const valarray<bool>& boolarr) const;
valarray<Ty>
operator[](const valarray<size_t>& indarr) const;
valarray<Ty> operator+() const;
valarray<Ty> operator-() const;
valarray<Ty> operator~() const;
valarray<bool> operator!() const;
valarray<Ty>& operator*=(const valarray<Ty>& right);
valarray<Ty>& operator*=(const Ty& right);
valarray<Ty>& operator/=(const valarray<Ty>& right);
valarray<Ty>& operator/=(const Ty& right);
valarray<Ty>& operator%=(const valarray<Ty>& right);
valarray<Ty>& operator%=(const Ty& right);
valarray<Ty>& operator+=(const valarray<Ty>& right);
valarray<Ty>& operator+=(const Ty& right);
valarray<Ty>& operator-=(const valarray<Ty>& right);
valarray<Ty>& operator-=(const Ty& right);
valarray<Ty>& operator^=(const valarray<Ty>& right);
valarray<Ty>& operator^=(const Ty& right);
valarray<Ty>& operator&=(const valarray<Ty>& right);
valarray<Ty>& operator&=(const Ty& right);
valarray<Ty>& operator|=(const valarray<Ty>& right);
valarray<Ty>& operator|=(const Ty& right);
valarray<Ty>& operator<<=(const valarray<Ty>& right);
valarray<Ty>& operator<<=(const Ty& right);
valarray<Ty>& operator>>=(const valarray<Ty>& right);
valarray<Ty>& operator>>=(const Ty& right);
size_t size() const;
Ty sum() const;
Ty max() const;
Ty min() const;
valarray<Ty> shift(int count) const;
valarray<Ty> cshift(int count) const;
valarray<Ty> apply(Ty func(Ty)) const;
valarray<Ty> apply(Ty func(const Ty&)) const;
void resize(size_t newsize);
void resize(size_t newsize, const Ty& val);
};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.
It differs from template class
vector in two important
ways:
- It defines numerous arithmetic operations between corresponding
elements of
valarray<Ty> objects of the same
type and length, such as xarr = cos(yarr) + sin(zarr). - It defines a variety of interesting ways to subscript a
valarray<Ty> object, by overloading
operator[].
An object of class Ty:
- has a public default constructor, destructor,
copy constructor, and assignment operator -- with
conventional behavior
- defines the arithmetic operators and math functions, as needed,
that are defined for the floating-point
types -- with conventional behavior
In particular, no subtle differences may exist between copy construction
and default construction followed by assignment. And none of the operations
on objects of class Ty may throw exceptions.
valarray<Ty> apply(Ty func(Ty)) const;
valarray<Ty> apply(Ty func(const Ty&)) const;
The member function returns an object of class
valarray<Ty>, of length
size(), each of whose
elements I is func((*this)[I]).
valarray<Ty> cshift(int count) const;
The member function returns an object of class
valarray<Ty>, of length
size(), each of whose
elements I is (*this)[(I + count) % size()].
Thus, if element zero is taken as the leftmost element, a positive
value of count shifts the elements circularly left count
places.
Ty max() const;
The member function returns the value of the largest element
of *this, which must have nonzero length.
If the length is greater than one, it compares values
by applying operator<
between pairs of corresponding elements of class Ty.
Ty min() const;
The member function returns the value of the smallest element
of *this, which must have nonzero length.
If the length is greater than one, it compares values
by applying operator<
between pairs of elements of class Ty.
valarray<bool> operator!() const;
The member operator returns an object of class
valarray<bool>, of length
size(), each of whose
elements I is !(*this).
valarray<Ty>& operator%=(const valarray<Ty>& right);
valarray<Ty>& operator%=(const Ty& right);
The member operator replaces each element I
of *this with (*this)[I] % right[I].
It returns *this.
valarray<Ty>& operator&=(const valarray<Ty>& right);
valarray<Ty>& operator&=(const Ty& right);
The member operator replaces each element I
of *this with (*this)[I] & right[I].
It returns *this.
valarray<Ty>& operator>>=(const valarray<Ty>& right);
valarray<Ty>& operator>>=(const Ty& right);
The member operator replaces each element I
of *this with (*this)[I] >> right[I].
It returns *this.
valarray<Ty>& operator<<=(const valarray<Ty>& right);
valarray<Ty>& operator<<=(const Ty& right);
The member operator replaces each element I
of *this with (*this)[I] << right[I].
It returns *this.
valarray<Ty>& operator*=(const valarray<Ty>& right);
valarray<Ty>& operator*=(const Ty& right);
The member operator replaces each element I
of *this with (*this)[I] * right[I].
It returns *this.
valarray<Ty> operator+() const;
The member operator returns an object of class
valarray<Ty>, of length
size(), each of whose
elements I is (*this)[I].
valarray<Ty>& operator+=(const valarray<Ty>& right);
valarray<Ty>& operator+=(const Ty& right);
The member operator replaces each element I
of *this with (*this)[I] + right[I].
It returns *this.
valarray<Ty> operator-() const;
The member operator returns an object of class
valarray<Ty>, of length
size(), each of whose
elements I is -(*this)[I].
valarray<Ty>& operator-=(const valarray<Ty>& right);
valarray<Ty>& operator-=(const Ty& right);
The member operator replaces each element I
of *this with (*this)[I] - right[I].
It returns *this.
valarray<Ty>& operator/=(const valarray<Ty>& right);
valarray<Ty>& operator/=(const Ty& right);
The member operator replaces each element I
of *this with (*this)[I] / right[I].
It returns *this.
valarray<Ty>& operator=(const valarray<Ty>& right);
valarray<Ty>& operator=(const Ty& val);
valarray<Ty>& operator=(const slice_array<Ty>& slicearr);
valarray<Ty>& operator=(const gslice_array<Ty>& gslicearr);
valarray<Ty>& operator=(const mask_array<Ty>& maskarr);
valarray<Ty>& operator=(const indirect_array<Ty>& indarr);The first member operator replaces the controlled sequence with
a copy of the sequence controlled by right.
The second member operator replaces each element of the controlled
sequence with a copy of val.
The remaining member operators replace those elements of the controlled
sequence selected by their arguments, which are generated only by
operator[].
If the value of a member in the replacement controlled sequence
depends on a member in the initial controlled sequence, the result
is undefined.
If the length of the controlled sequence changes, the result is
generally undefined. In this
implementation, however,
the effect is merely to invalidate any pointers or references to
elements in the controlled sequence.
Ty& operator[](size_t off);
slice_array<Ty> operator[](slice slicearr);
gslice_array<Ty> operator[](const gslice& gslicearr);
mask_array<Ty> operator[](const valarray<bool>& boolarr);
indirect_array<Ty> operator[](const valarray<size_t>& indarr);
Ty operator[](size_t off) const;
valarray<Ty> operator[](slice slicearr) const;
valarray<Ty> operator[](const gslice& gslicearr) const;
valarray<Ty> operator[](const valarray<bool>& boolarr) const;
valarray<Ty> operator[](const valarray<size_t>& indarr) const;
The member operator is overloaded to provide several ways to select
sequences of elements from among those controlled by *this.
The first group of five member operators work in conjunction with
various overloads of
operator=
(and other assigning operators) to allow selective replacement
(slicing) of the controlled sequence. The selected elements must
exist.
The first member operator selects element off.
For example:
valarray<char> v0("abcdefghijklmnop", 16);
v0[3] = 'A';
// v0 == valarray<char>("abcAefghijklmnop", 16)The second member operator selects those elements of the controlled
sequence designated by slicearr. For example:
valarray<char> v0("abcdefghijklmnop", 16);
valarray<char> v1("ABCDE", 5);
v0[slice(2, 5, 3)] = v1;
// v0 == valarray<char>("abAdeBghCjkDmnEp", 16)The third member operator selects those elements of the controlled
sequence designated by gslicearr. For example:
valarray<char> v0("abcdefghijklmnop", 16);
valarray<char> v1("ABCDEF", 6);
const size_t lv[] = {2, 3};
const size_t dv[] = {7, 2};
const valarray<size_t> len(lv, 2), str(dv, 2);
v0[gslice(3, len, str)] = v1;
// v0 == valarray<char>("abcAeBgCijDlEnFp", 16)The fourth member operator selects those elements of the controlled
sequence designated by boolarr. For example:
valarray<char> v0("abcdefghijklmnop", 16);
valarray<char> v1("ABC", 3);
const bool vb[] = {false, false, true, true, false, true};
v0[valarray<bool>(vb, 6)] = v1;
// v0 == valarray<char>("abABeCghijklmnop", 16)The fifth member operator selects those elements of the controlled
sequence designated by indarr. For example:
valarray<char> v0("abcdefghijklmnop", 16);
valarray<char> v1("ABCDE", 5);
const size_t vi[] = {7, 5, 2, 3, 8};
v0[valarray<size_t>(vi, 5)] = v1;
// v0 == valarray<char>("abCDeBgAEjklmnop", 16)The second group of five member operators each construct an object
that represents the value(s) selected. The selected elements must
exist.
The sixth member operator returns the value of element off.
For example:
valarray<char> v0("abcdefghijklmnop", 16);
// v0[3] returns 'd'The seventh member operator returns an object of class
valarray<Ty> containing those elements of the controlled
sequence designated by slicearr. For example:
valarray<char> v0("abcdefghijklmnop", 16);
// v0[slice(2, 5, 3)] returns valarray<char>("cfilo", 5)The eighth member operator selects those elements of the controlled
sequence designated by gslicearr. For example:
valarray<char> v0("abcdefghijklmnop", 16);
const size_t lv[] = {2, 3};
const size_t dv[] = {7, 2};
const valarray<size_t> len(lv, 2), str(dv, 2);
// v0[gslice(3, len, str)] returns
// valarray<char>("dfhkmo", 6)The ninth member operator selects those elements of the controlled
sequence designated by boolarr. For example:
valarray<char> v0("abcdefghijklmnop", 16);
const bool vb[] = {false, false, true, true, false, true};
// v0[valarray<bool>(vb, 6)] returns
// valarray<char>("cdf", 3)The last member operator selects those elements of the controlled
sequence designated by indarr. For example:
valarray<char> v0("abcdefghijklmnop", 16);
const size_t vi[] = {7, 5, 2, 3, 8};
// v0[valarray<size_t>(vi, 5)] returns
// valarray<char>("hfcdi", 5)valarray<Ty>& operator^=(const valarray<Ty>& right);
valarray<Ty>& operator^=(const Ty& right);
The member operator replaces each element I
of *this with (*this)[I] ^ right[I].
It returns *this.
valarray<Ty>& operator|=(const valarray<Ty>& right);
valarray<Ty>& operator|=(const Ty& right);
The member operator replaces each element I
of *this with (*this)[I] | right[I].
It returns *this.
valarray<Ty> operator~() const;
The member operator returns an object of class
valarray<Ty>, of length
size(), each of whose
elements I is ~(*this)[I].
void resize(size_t newsize);
void resize(size_t newsize, const 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 remove and
delete elements with subscripts in the range
[newsize, size()).
Any pointers or references to
elements in the controlled sequence are invalidated.
valarray<Ty> shift(int count) const;
The member function returns an object of class
valarray<Ty>, of length
size(), each of whose
elements I is either (*this)[I + count],
if I + count is a valid subscript, or Ty().
Thus, if element zero is taken as the leftmost element, a positive
value of count shifts the elements left count
places, with zero fill.
size_t size() const;
The member function returns the number of elements
in the array.
Ty sum() const;
The member function returns the sum of all elements of *this,
which must have nonzero length. If the length is greater than one,
it adds values to the sum by applying
operator+= between pairs of elements
of class Ty.
valarray();
explicit valarray(size_t count);
valarray(const Ty& val, size_t count));
valarray(const Ty *ptr, size_t count);
valarray(const slice_array<Ty>& slicearr);
valarray(const gslice_array<Ty>& gslicearr);
valarray(const mask_array<Ty>& maskarr);
valarray(const indirect_array<Ty>& indarr);
The first (default) constructor initializes the object to an empty
array. The next three constructors each initialize the object to an array
of count elements as follows:
- For
explicit valarray(size_t count),
each element is initialized with the default constructor. - For
valarray(const Ty& val, size_t count)),
each element is initialized with val. - For
valarray(const Ty *ptr, size_t count),
the element at position I is initialized with
p[I].
Each of the remaining constructors initializes the object to a
valarray<Ty> object determined by the argument.
typedef Ty value_type;
The type is a synonym for the template parameter Ty.
class valarray<bool>
The type is a specialization of template class
valarray, for elements
of type bool.
See also the
Table of Contents and the
Index.
Copyright © 1994-2002
by P.J. Plauger. All rights reserved.
88 - 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.
89 - wchar
<wchar.h>[Added with
Amendment 1]
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.
90 - wctype
<wctype.h>[Added with
Amendment 1]
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.