Component bdlb_nulloutputiterator [Package bdlb]

Provide an output iterator type that discards output. More...

Namespaces
namespace	bdlb

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Basic Use of bdlb::NullOutputIterator

Purpose:

Provide an output iterator type that discards output.

Classes:

bdlb::NullOutputIterator	output iterator template that discards the output
bdlb::NullOutputIterator::AssignmentProxy	proxy for assignment

See also:

bdlb_nullinputiterator

Description:

This component provides a mechanism, bdlb::NullOutputIterator, that defines an output iterator with the following attributes:

• Meets exactly the requirements for an output iterator according to the C++ Standard (C++98, Section 24.1.2 [lib.output.iterators]).
• De-referencing an iterator and assigning to the returned value has no effect.
• Incrementing an iterator has no effect.

This iterator type is typically used to call functions purely for their side-effects, discarding the normal output. It is also useful for testing whether a template function will compile when presented with a pure output iterator. This component also provides a template bdlb::NullOutputIterator::AssignmentProxy, that is used as the return type of bdlb::NullOutputIterator::operator*. The AssignmentProxy provides an operator= that does nothing, so that the result of the iterator's operator* can be assigned to even if the value type of the bdlb::NullOutputIterator does not provide a default constructor:

  class ValueType {
      // ... data members ...

    public:
      ValueType(int value) { ... implementation elided ... }

      // ... rest of class definition elided ...

  };

  ValueType v(42);
  bdlb::NullOutputIterator<ValueType> i;

  // With a non-proxy return type for 'operator*' it would be difficult to
  // provide a value for the lefthand side of this expression:

  *i = v;

Usage:

This section illustrates intended use of this component.

Example 1: Basic Use of bdlb::NullOutputIterator:

In the following example we use a bdlb::NullOutputIterator to enable us to call a function to capture its return code, while ignoring the output provided through an iterator.

First, we define a function runningSum that returns output both through an output iterator and through a return status code:

  template <class IN_ITER, class OUT_ITER>
  typename bsl::iterator_traits<OUT_ITER>::value_type
  runningSum(IN_ITER first, IN_ITER last, OUT_ITER output)
  {
      typename bsl::iterator_traits<OUT_ITER>::value_type total = 0;
      while (first != last) {
          total += *first++;
          *output++ = total;
      }
      return total;
  }

Now, we define a function average that captures the total sum returned by runningSum and uses a bdlb::NullOutputIterator to facilitate calling the function, and ignoring the output it provides through its output iterator parameter:

  int average(int values[], int numValues)
  {
      // ... input validation elided ...
      return runningSum(values, values + numValues,
                        bdlb::NullOutputIterator<int>()) / numValues;
  }

Finally, we invoke function average on user array and validate result.

  void usageExample()
  {
      const int myArray[5] = { 3, 4, 5, 7, 11 };

      int averageValue = average(myArray, 5);
      assert( averageValue == 6 );
  }