ZipIterator - SeqAn API Documentation

# Spec ZipIterator
Zips multiple iterators over different containers into a single iterator.

Extends | Iter
Implements | IteratorAssociatedTypesConcept
All Extended | Iter
All Impl'd | IteratorAssociatedTypesConcept
Defined in | <seqan/basic.h>
Signature | `class Iter<std::tuple<TIteratorTypes...>, ZipIterator>;`

## Template Parameters

`TIteratorTypes` | A template parameter pack with one or more Iterator types.

## Member Function Overview

### Member Functions Inherited From Iter

- `Iter`

## Interface Function Overview

- `Iter() Iter(TIteratorTypes... args)`
  Constructor.

### Interface Functions Inherited From IteratorAssociatedTypesConcept

- `operator*`
- `value`
- `getValue`

## Interface Metafunction Overview

- `typename Container<TZipIterator>::Type;`
  Retruns the Container type of the ZipIterator.
- `typename GetValue<TZipIterator>::Type;`
  Retruns the GetValue type of the ZipIterator.
- `typename GetValue<TZipIterator>::Type;`
  Retruns the Reference type of the ZipIterator.
- `typename Value<TZipIterator>::Type;`
  Retruns the Value type of the ZipIterator.

### Interface Metafunctions Inherited From Iter

- `Container`
- `IterComplementConst`
- `IterMakeConst`
- `Spec`

### Interface Metafunctions Inherited From IteratorAssociatedTypesConcept

- `Difference`
- `GetValue`
- `Pointer`
- `Reference`
- `Value`

## Detailed Description

Note:

Throws an assertion if `sizeof...(TIteratorTypes) == 0` is true.

This iterator ties together different iterator types for different containers of the same size. It allows one to operate on a single iterator, if multiple containers need to be traversed simultaneously. Note, that all operations are still executed in a serial fashion. If the zip iterator is dereferenced it returns a std::tuple containing the dereferenced values of all embedded iterators. The metafunctions Value, GetValue and Reference are overloaded accordingly.

To easily create a zip iterator one can use the helper function makeZipIterator.

### Example

The following example demonstrates the function of the zip iterator:

    #include <iostream>

    #include <seqan/basic.h>
    #include <seqan/sequence.h>
    #include <seqan/stream.h>

    using namespace seqan2;

    int main()
    {
        StringSet<CharString> names;
        StringSet<CharString> surnames;
        String<int>           ages;

        appendValue(names, "John");
        appendValue(names, "Johnny");
        appendValue(names, "Garfield");

        appendValue(surnames, "Doe");
        appendValue(surnames, "Donny");
        appendValue(surnames, "the Cat");

        appendValue(ages, 98);
        appendValue(ages, 20);
        appendValue(ages, 42);

        auto it = makeZipIterator(begin(names), begin(surnames), begin(ages));
        auto itEnd = makeZipIterator(end(names), end(surnames), end(ages));

        for (; it != itEnd; ++it)
            std::cout << std::get<1>(*it) << ", " << std::get<0>(*it) << ": " << std::get<2>(*it) << std::endl;

        return 0;
    }

Demo: demos/dox/basic/zip_iterator.cpp

This outputs the following to the console:

    Doe, John: 98
    Donny, Johnny: 20
    the Cat, Garfield: 42

## Interface Functions Detail

### `Iter() Iter(TIteratorTypes... args)`

Constructor.

#### Parameters

`args` | The iterator instances to create the ZipIterator from. Default constructors are not listed.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

## Interface Metafunctions Detail

### `typename Container<TZipIterator>::Type;`

Retruns the Container type of the ZipIterator.

#### Template Parameters

`TZipIterator` | The type of the ZipIterator.

#### Returns

`TRes` | A std::tuple containing the container types of all iterator types embedded in the `TZipIterator` type.

### `typename GetValue<TZipIterator>::Type;`

Retruns the GetValue type of the ZipIterator.

#### Template Parameters

`TZipIterator` | The type of the ZipIterator.

#### Returns

`TRes` | A std::tuple containing the value types of all iterator types embedded in the `TZipIterator` type.

### `typename GetValue<TZipIterator>::Type;`

Retruns the Reference type of the ZipIterator.

#### Template Parameters

`TZipIterator` | The type of the ZipIterator.

#### Returns

`TRes` | A std::tuple containing the value types of all iterator types embedded in the `TZipIterator` type.

### `typename Value<TZipIterator>::Type;`

Retruns the Value type of the ZipIterator.

#### Template Parameters

`TZipIterator` | The type of the ZipIterator.

#### Returns

`TRes` | A std::tuple containing the value types of all iterator types embedded in the `TZipIterator` type.

#### Dox Sources

    /*!
     * @class ZipIterator
     *
     * @implements IteratorAssociatedTypesConcept
     *
     * @extends Iter
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Zips multiple iterators over different containers into a single
     *        iterator.
     *
     * @note Throws an assertion if <tt>sizeof...(TIteratorTypes) == 0</tt> is true.
     *
     * @signature class Iter<std::tuple<TIteratorTypes...>, ZipIterator>;
     *
     * @tparam TIteratorTypes A template parameter pack with one or more @link
     *                        ContainerConcept#Iterator @endlink types.
     *
     * This iterator ties together different iterator types for different containers
     * of the same size. It allows one to operate on a single iterator, if multiple
     * containers need to be traversed simultaneously. Note, that all operations are
     * still executed in a serial fashion. If the zip iterator is dereferenced it
     * returns a <a
     * href="https://en.cppreference.com/w/cpp/utility/tuple">std::tuple</a>
     * containing the dereferenced values of all embedded iterators. The
     * metafunctions @link Value @endlink, @link GetValue @endlink and @link
     * Reference @endlink are overloaded accordingly.
     *
     * To easily create a zip iterator one can use the helper function @link
     * makeZipIterator @endlink.
     *
     * @section Example
     *
     * The following example demonstrates the function of the zip iterator:
     *
     * @include demos/dox/basic/zip_iterator.cpp
     *
     * This outputs the following to the console:
     *
     * @include demos/dox/basic/zip_iterator.cpp.stdout
     *
     * @fn ZipIterator#ZipIterator
     *
     * @brief Constructor.
     *
     * @signature Iter() Iter(TIteratorTypes... args)
     *
     * @param args The iterator instances to create the @link ZipIterator @endlink
     *             from. Default constructors are not listed.
     *
     * @mfn ZipIterator#Container
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Retruns the Container type of the @link ZipIterator @endlink.
     *
     * @signature typename Container<TZipIterator>::Type;
     *
     * @tparam TZipIterator The type of the @link ZipIterator @endlink.
     *
     * @return TRes A <a href="https://en.cppreference.com/w/cpp/utility/tuple">std:
     *              :tuple</a> containing the container types of all iterator types
     *              embedded in the <tt>TZipIterator</tt> type.
     *
     * @mfn ZipIterator#Value
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Retruns the Value type of the @link ZipIterator @endlink.
     *
     * @signature typename Value<TZipIterator>::Type;
     *
     * @tparam TZipIterator The type of the @link ZipIterator @endlink.
     *
     * @return TRes A <a href="https://en.cppreference.com/w/cpp/utility/tuple">std:
     *              :tuple</a> containing the value types of all iterator types
     *              embedded in the <tt>TZipIterator</tt> type.
     *
     * @mfn ZipIterator#GetValue
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Retruns the GetValue type of the @link ZipIterator @endlink.
     *
     * @signature typename GetValue<TZipIterator>::Type;
     *
     * @tparam TZipIterator The type of the @link ZipIterator @endlink.
     *
     * @return TRes A <a href="https://en.cppreference.com/w/cpp/utility/tuple">std:
     *              :tuple</a> containing the value types of all iterator types
     *              embedded in the <tt>TZipIterator</tt> type.
     *
     * @mfn ZipIterator#Reference
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Retruns the Reference type of the @link ZipIterator @endlink.
     *
     * @signature typename GetValue<TZipIterator>::Type;
     *
     * @tparam TZipIterator The type of the @link ZipIterator @endlink.
     *
     * @return TRes A <a href="https://en.cppreference.com/w/cpp/utility/tuple">std:
     *              :tuple</a> containing the value types of all iterator types
     *              embedded in the <tt>TZipIterator</tt> type.
     */