bdlb_functionoutputiterator

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Adapting a Free-Function to an Output Iterator
    • Example 2: Adapting A Functor to An Output Iterator

Purpose

Provides an output iterator for a client-supplied functor.

Classes

• bdlb::FunctionOutputIterator: function output iterator template

See also

bdlb_nulloutputiterator

Description

This component provides an iterator template mechanism, bdlb::FunctionOutputIterator, that adapts a client supplied functor (or function pointer) to a C++ compliant output iterator. This component allows clients to create custom output iterators easily.

A bdlb::FunctionOutputIterator instance's template parameter type FUNCTION must be a functor (or function) that can be called as if it has the following signature:

void operator()(const TYPE&)'

where TYPE is the type of the object that will be assigned (by clients) to the dereferenced iterator. For example:

void myFunction(const int& value) {};
typedef void (*MyFunctionPtr)(const int&);
typedef bdlb::FunctionOutputIterator<MyFunctionPtr> MyFunctionIterator;
 
MyFunctionIterator it(&foo);
*it = 5;                       // Calls 'myFunction(5)'!

Notice that assigning 5 to the dereferenced output iterator invokes the function with the value 5.

The provided output iterator has the following attributes:

• Meets the requirements for an output iterator according to the C++ Standard (C++11, Section 24.2.4 [output.iterators]).
• Dereferencing an iterator and assigning to the result leads to a call of the functional object owned by the iterator. The value assigned to the dereferenced iterator is passed to a call of the function or functor held by the iterator as a constant reference. In other words, the assignment *it = value is equivalent to function(value).
• Incrementing an iterator is a no-op.

Usage

This section illustrates intended use of this component.

Example 1: Adapting a Free-Function to an Output Iterator

Suppose we want use a provided function foo, that prints integers in some predefined format, to print each unique element of an array. Instead of manually writing a loop and checking for duplicate elements, we would like to use a standard algorithm such as unique_copy . However, unique_copy takes in an output iterator instead of a free function. We can use bdlb::FunctionOutputIterator to adapt foo into an output iterator that is acceptable by unique_copy .

First, we define the type Function and a function of that type foo:

typedef void (*Function)(const int&);
 
void foo(const int& value)
{
    bsl::cout << value << " ";
}

Then, we define a data sequence to process:

enum { NUM_VALUES_1 = 7 };
const int array1[NUM_VALUES_1] = { 2, 3, 3, 5, 7, 11, 11 };

Next, we use bdlb::FunctionOutputIterator to wrap foo for use in the algorithm bsl::unqiue_copy:

unique_copy(
    array1,
    array1 + NUM_VALUES,
    bdlb::FunctionOutputIterator<Function>(&foo));

Notice, that each time bsl::unique_copy copies an element from the supplied range and assigns it to the output iterator, the function foo is called for the element.

Finally, the resulting console output:

2 3 5 7 11

Example 2: Adapting A Functor to An Output Iterator

The following example demonstrates using a bdlb::FunctionOutputIterator with a user defined functor object. Consider the Accumulator class for accumulating integer values into a total. We want to adapt Accumulator for use with the algorithm bsl::unique_copy.

First, we define an Accumulator class that will total the values supplied to the increment method:

/// This class provides a value accumulating functionality.
class Accumulator {
 
    // DATA
    int d_sum;
  public:
    // CREATORS
    Accumulator() : d_sum(0) {};
 
    // MANIPULATORS
    void increment(int value) { d_sum += value; };
 
    // ACCESSORS
    int total() const { return d_sum; }
};

Next, we define a functor, AccumulatorFunctor, that adapts Accumulator to a function object:

/// This class implements a function object that invokes 'increment' in
/// response of calling operator()(int).
class AccumulatorFunctor {
 
    // DATA
    Accumulator *d_accumulator_p;  // accumulator (held, not owned)
 
  public:
    // CREATORS
    explicit AccumulatorFunctor(Accumulator *accumulator)
    : d_accumulator_p(accumulator)
    {}
 
    // MANIPULATORS
    void operator()(int value) { d_accumulator_p->increment(value); };
};

Then, we define data sequence to process:

enum { NUM_VALUES_2 = 7 };
const int   array2[NUM_VALUES_2] = { 2, 3, 3, 5, 7, 11, 11 };

Next, we create a bdlb::FunctionOutputIterator for AccumulatorFunctor and supply it to the bsl::unique_copy algorithm to accumulate a sequence of values:

Accumulator accumulator;
unique_copy(
    array2,
    array2 + NUM_VALUES_2,
    bdlb::FunctionOutputIterator<AccumulatorFunctor>(
        AccumulatorFunctor(&accumulator)));

Finally, we observe that accumulator holds the accumulated total of unique values in array:

assert(28 == accumulator.total());