|
| |
|
| Category: iterators | | Component type: function |
Prototype
Value_type is overloaded; it is in fact five different functions.
template <class T, class Distance>
inline T* value_type(const input_iterator<T, Distance>&);
template <class T, class Distance>
inline T* value_type(const forward_iterator<T, Distance>&);
template <class T, class Distance>
inline T* value_type(const bidirectional_iterator<T, Distance>&);
template <class T, class Distance>
inline T* value_type(const random_access_iterator<T, Distance>&);
template <class T> inline T* value_type(const T*);
Description
Value_type is an iterator_tags function: it is used to determine the value type associated with an iterator. An iterator's value type is the type of object returned when the iterator is dereferenced; OutputIterator do not have value types (OutputIterator may only be used for storing values, not for accessing values), but InputIterator, ForwardIterator, BidirectionalIterator, and RandomAccessIterator do. [1] In some cases, such as an algorithm that must declare a local variable that holds a value returned from dereferencing an iterator, it is necessary to find out an iterator's value type. Accordingly, value_type(Iter) returns (T*) 0, where T is Iter's value type.
Although value_type looks like a single function whose return type depends on its argument type, in reality it is a set of functions; the name value_type is overloaded. The function value_type must be overloaded for every iterator type [1].
In practice, ensuring that value_type is defined requires essentially no work at all. It is already defined for pointers, and for the base classes input_iterator, forward_iterator, bidirectional_iterator, and random_access_iterator. If you are implementing a new type of forward iterator, for example, you can simply derive it from the base class forward_iterator; this means that value_type (along with iterator_category and distance_type) will automatically be defined for your iterator. These base classes are empty: they contain no member functions or member variables, but only type information. Using them should therefore incur no overhead.
Note that, while the function value_type was present in the original STL, it is no longer present in the most recent draft C++ standard: it has been replaced by the iterator_traits class At present both mechanisms are supported [2], but eventually value_type will be removed.
Definition
Defined in the standard header iterator, and in the nonstandard backward-compatibility header iterator.h. This function is no longer part of the C++ standard, although it was present in early drafts of the standard. It is retained in this implementation for backward compatibility.
Requirements on types
The argument of value_type must be an InputIterator, ForwardIterator, BidirectionalIterator, or RandomAccessIterator. [1]
Preconditions
None. Value_type's argument is even permitted to be a singular iterator.
Complexity
At most amortized constant time. In many cases, a compiler should be able to optimize away value_type entirely.
Example
This example uses the value_type iterator tag function in order to declare a temporary variable of an iterator's value type.
template <class ForwardIterator1, class ForwardIterator2, class ValueType>
inline void __iter_swap(ForwardIterator1 a, ForwardIterator2 b, ValueType*) {
T tmp = *a;
*a = *b;
*b = tmp;
}
template <class ForwardIterator1, class ForwardIterator2>
inline void iter_swap(ForwardIterator1 a, ForwardIterator2 b) {
__iter_swap(a, b, value_type(a));
}
Notes
[1] Note that distance_type is not defined for OutputIterator or for trivial. In the case of OutputIterator, this is because an OutputIterator does not have a value type: it is not possible to dereference an OutputIterator and obtain a value. In the case of trivial, this is because the concept was introduced only for conceptual clarity, in order to separate the axioms related to an object that refers to another object from those related to iteration over a range. In fact, the STL does not define any types that are trivial. Although built-in C pointers may be trivial, the C type system does not allow a distinction between pointers that are trivial and pointers that are RandomAccessIterator into C arrays. Consequently, there is no trivial category tag or iterator base.
[2] The iterator_traits class relies on a C++ feature known as partial specialization. Many of today's compilers don't implement the complete standard; in particular, many compilers do not support partial specialization. If your compiler does not support partial specialization, then you will not be able to use iterator_traits, and you will have to continue using the functions iterator_category, distance_type, and value_type. This is one reason that those functions have not yet been removed.
See also
The iterator_tags overview, iterator_traits, iterator_category, distance_type, output_iterator_tag, input_iterator_tag, forward_iterator_tag, bidirectional_iterator_tag, random_access_iterator_tag
