872
C + + : T h e C o m p l e t e R e f e r e n c e
Here, CharType is the character type (char or wchar_t) that the stream is operating upon.
ostreambuf_iterator
has the following constructors: ostreambuf_iterator(ostream_type &stream) throw( ); ostreambuf_iterator(streambuf_type *streambuf) throw( );
The first creates an iterator to the stream specified by stream. The type ostream_type is a typedef that specifies the type of the input stream. The second form creates an iterator using the stream buffer specified by streambuf. The type streambuf_type is a typedef that specifies the type of the stream buffer.
The ostreambuf_iterator class defines the following operators: =, *, ++. The member function failed( ) is also defined as shown here: bool failed( ) const throw( );
It returns false if no failure has occurred and true otherwise.
Two Iterator Functions
There are two special functions defined for iterators: advance( ) and distance( ). They are shown here: template <class InIter, class Dist> void advance(InIter &itr, Dist d); template <class InIter> ptrdiff_t distance(InIter start, InIter end);
The advance( ) function increments itr by the amount specified by d. The distance( ) function returns the number of elements between start and end.
The reason for these two functions is that only random-access iterators allow a value to be added to or subtracted from an iterator. The advance( ) and distance( ) functions overcome this restriction. It must be noted, however, that some iterators will not be able to implement these functions efficiently.
Function Objects
Function objects are classes that define operator( ). The STL defines several built-in function objects that your programs may use. You can also define your own function objects. Support for function objects is in the <functional> header. Also defined in
<functional>
are several entities that support function objects. These are binders, negators, and adaptors. Each is described here.
Refer to Chapter 24 for an overview of function objects.
C h a p t e r 3 5 : S T L I t e r a t o r s , A l l o c a t o r s , a n d F u n c t i o n O b j e c t s
873
Function Objects
Function objects come in two varieties: binary and unary. The built-in binary function objects are shown here: plus equal_to less_equal minus not_equal_to logical_and multiplies greater logical_or
Here are the built-in unary function objects.
logical_not negate divides greater_equal
The general form for invoking a function object is shown here:
func_ob<type>( )
For example, modulus less less<int>() invokes less( ) relative to operands of type int.
A base class for all binary function objects is binary_function, shown here: template <class Argument1, class Argument2, class Result> struct binary_function { typedef Argument1 first_argument_type; typedef Argument2 second_argument_type;
}; typedef Result result_type;
The base class for all unary functions is unary_function, shown here: template <class Argument, class Result> struct unary_function { typedef Argument argument_type;
}; typedef Result result_type;
These template classes provide concrete type names for the generic data types used by the function object. Although they are technically a convenience, they are almost always used when creating function objects.
874
C + + : T h e C o m p l e t e R e f e r e n c e
The template specifications for all binary function objects are similar, and the template specifications for all unary function objects are similar. Here are examples of each: template <class T> struct plus : binary_function<T, T, T>
{
};
T operator() (const T &arg1, const T&arg2) const; template <class T> struct negate : unary_function<T, T>
{
};
T operator() (const T &arg) const;
Each operator( ) function returns the specified result.
Binders
Binders bind a value to an argument of a binary function object, producing a unary function object. There are two binders: bind2nd( ) and bind1st( ). Here is how they are defined: template <class BinFunc, class T> binder1st<BinFunc> bind1st(const BinFunc &op, const T &value); template <class BinFunc, class T> binder2nd<BinFunc> bind2nd(const BinFunc &op, const T &value);
Here, op is a binary function object, such as less( ) or greater( ), that provides the desired operation, and value is the value being bound. bind1st( ) returns a unary function object that has op's left-hand operand bound to value. bind2nd( ) returns a unary function object that has op's right-hand operand bound to value. The bind2nd( ) binder is by far the most commonly used. In either case, the outcome of a binder is a unary function object that is bound to the value specified.
The binder1st and binder2nd classes are shown here: template <class BinFunc> class binder1st: public unary_function(typename BinFunc::second_argument_type, typename BinFunc::result_type>
{ protected:
BinFunc op; typename BinFunc::first_argument_type value; public:
C h a p t e r 3 5 : S T L I t e r a t o r s , A l l o c a t o r s , a n d F u n c t i o n O b j e c t s
875 binder1st(const BinFunc & op, const typename BinFunc::first_argument_type & v); result_type operator()(const argument_type & v) const;
}; template <class BinFunc> class binder2nd: public unary_function(typename BinFunc::first_argument_type, typename BinFunc::result_type>
{ protected:
BinFunc op; typename BinFunc::second_argument_type value; public: binder2nd(const BinFunc & op, const typename BinFunc::second_argument_type & v); result_type operator()(const argument_type & v) const;
};
Here, BinFunc is the type of a binary function object. Notice that both classes inherit
unary_function
. This is why the resulting object of bind1st( ) and bind2nd( ) can be used anywhere that a unary function can be.
Negators
Negators return predicates that yield the opposite of whatever predicate they modify.
The negators are not1( ) and not2( ). They are defined like this: template <class UnPred> unary_negate<UnPred> not1(const UnPred &pred); template <class BinPred> binary_negate<BinPred> not2(const BinPred &pred);
The classes are shown here: template <class UnPred> class unary_negate: public unary_function<typename UnPred::argument_type, bool>
{ public:
}; explicit unary_negate(const UnPred & pred); bool operator()(const argument_type & v) const; template <class BinPred> class binary_negate:
876
C + + : T h e C o m p l e t e R e f e r e n c e
{ public: explicit binary_negate(const BinPred & pred); bool operator()(const first_argument_type & v1, const second_argument_type & v2) const;
}; public binary_function<typename BinPred::first_argument_type, typename BinPred::second_argument_type, bool>
In both classes, operator( ) returns the negation of the predicate specified by pred.
Adaptors
The header <functional> defines several classes called adaptors that allow you to adapt a function pointer to a form that can be used by the STL. For example, you can use an adaptor to allow a function such as strcmp( ) to be used as a predicate. Adaptors also exist for member pointers.
The Pointer-to-Function Adaptors
The pointer-to-function adaptors are shown here: template <class Argument, class Result> pointer_to_unary_function<Argument, Result> ptr_fun(Result (*func)(Argument)); template <class Argument1, class Argument2, class Result> pointer_to_binary_function<Argument1, Argument2, Result> ptr_fun(Result (*func)(Argument1, Argument2));
Here, ptr_fun( ) returns either an object of type pointer_to_unary_function or
pointer_to_binary_function
. These classes are shown here: template <class Argument, class Result> class pointer_to_unary_function: public unary_function<Argument, Result>
{ public:
}; explicit pointer_to_unary_function(Result (*func)(Argument));
Result operator()(Argument arg) const;
C h a p t e r 3 5 : S T L I t e r a t o r s , A l l o c a t o r s , a n d F u n c t i o n O b j e c t s
877 template <class Argument1, class Argument2, class Result> class pointer_to_binary_function: public binary_function<Argument1, Argument2, Result>
{ public: explicit pointer_to_binary_function(
Result (* func)(Argument1, Argument2));
};
Result operator()(Argument1 arg1, Argument2 arg2) const;
For unary functions, operator( ) returns
func(arg).
For binary functions, operator( ) returns
func(arg1, arg2);
The type of the result of the operation is specified by the Result generic type.
The Pointer-to-Member Function Adaptors
The pointer-to-member function adaptors are shown here: template<class Result, class T> mem_fun_t<Result, T> mem_fun(Result (T::*func)( )); template<class Result, class T, class Argument> mem_fun1_t<Result, T, Argument> mem_fun1(Result (T::*func)(Argument));
Here, mem_fun( ) returns an object of type mem_fun_t, and mem_fun1( ) returns an object of type mem_fun1_t. These classes are shown here: template <class Result, class T> class mem_fun_t: public unary_function<T *, Result> { public: explicit mem_fun_t(Result (T::* func)());
Result operator() (T * func) const;
878
C + + : T h e C o m p l e t e R e f e r e n c e
}; template <class Result, class T, class Argument> class mem_fun1_t: public binary_function<T *, Argument, Result> { public:
}; explicit mem_fun1_t(Result (T::* func)(Argument));
Result operator() (T *func, Argument arg) const;
Here, the mem_fun_t constructor calls the member function specified as its parameter.
The mem_fun1_t constructor calls the member function specified as its first parameter, passing a value of type Argument as its second parameter.
There are parallel classes and functions for using references to members. The general form of the functions is shown here: template<class Result, class T> mem_fun_ref_t<Result, T> mem_fun_ref(Result (T::*func)( )); template<class Result, class T, class Argument> mem_fun1_ref_t<Result, T, Argument> mem_fun1_ref(Result (T::*func)(Argument));
The classes are shown here: template <class Result, class T> class mem_fun_ref_t: public unary_function<T, Result>
{ public:
}; explicit mem_fun_ref_t(Result (T::* func)());
Result operator()(T & func) const; template <class Result, class T, class Argument> class mem_fun1_ref_t: public binary_function<T, Result, Argument>
{ public:
}; explicit mem_fun1_ref_t(Result (T::* func)(Argument));
Result operator()(T & func, Argument arg) const;
