Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

Concept OutputIterator

OutputIterator

Description

An output iterator is an iterator that can write a sequence of values. It is single-pass (old values of the iterator cannot be re-used), and write-only.

An output iterator represents a position in a (possibly infinite) sequence. Therefore, the iterator can point into the sequence (returning a value when dereferenced and being incrementable), or be off-the-end (and not dereferenceable or incrementable).

Associated types

  • value_type

    std::iterator_traits<Iter>::value_type

    The stated value type of the iterator (should be void for an output iterator that does not model some other iterator concept).

  • difference_type

    std::iterator_traits<Iter>::difference_type

    The difference type of the iterator

  • category

    std::iterator_traits<Iter>::iterator_category

    The category of the iterator

Notation

Iter
A type playing the role of iterator-type in the OutputIterator concept.
ValueType
A type playing the role of value-type in the OutputIterator concept.
i, j
Objects of type Iter
x
Object of type ValueType

Type expressions

The type Iter must be a model of Assignable.

The type ValueType must be a model of Assignable.

The type Iter must be a model of DefaultConstructible.

The type Iter must be a model of EqualityComparable.

Category tag

category must be derived from std::output_iterator_tag, a model of DefaultConstructible, and a model of CopyConstructible.

Difference type properties

difference_type must be a model of SignedInteger.

Valid expressions

Name Expression Type Precondition Semantics Postcondition

Dereference

*i

i is incrementable (not off-the-end)

   

Dereference and assign

*i = x

i is incrementable (not off-the-end)

 

*i may not be written to again until it has been incremented.

Preincrement

++i

Iter &

i is incrementable (not off-the-end)

   

Postincrement

i++

i is incrementable (not off-the-end)

Equivalent to (void)(++i)

i is dereferenceable or off-the-end

Postincrement, dereference, and assign

*i++ = x

i is incrementable (not off-the-end)

Equivalent to {*i = t; ++i;}

i is dereferenceable or off-the-end

Complexity

All iterator operations must take amortized constant time.

Models

  • std::ostream_iterator, ...
  • std::insert_iterator, ...
  • std::front_insert_iterator, ...
  • std::back_insert_iterator, ...

PrevUpHomeNext