Splitter - SeqAn API Documentation

# Class Splitter
Splits an interval into subintervals.

All Subcl's | Equidistant
Defined in | <seqan/parallel.h>
Signature | `template <typename TValue, typename TSpec> class Splitter;`

## Template Parameters

`TValue` | Type of the interval boundaries.
`TSpec` | Tag to select the way the values are sampled.

## Member Function Overview

- `Splitter::Splitter(beginPos, endPos[, subintervalCount]);, Splitter::Splitter(beginPos, endPos, parallelTag);`
  Constructor

## Interface Function Overview

- `TSize length(splitter);`
  Return the number of elements in the splitter.
- `void resize(splitter, newCount);`
  Change the number of elements in the splitter.

## Interface Metafunction Overview

- `Size<TSplitter>::Type;`
  Returns the size type for the Splitter.
- `Value<TSplitter>::Type;`
  Returns the value type for the Splitter.

## Detailed Description

This class divides an interval into the disjoint union of subintervals and enumerates its boundaries. It can be used to parallelize large for-loops that iterate over a contiguous range of elements. The interval and the number of subintervals can be set in the constructor Splitter. length and resize can be used to retrieve or change the number of subintervals later. In contrast to other containers the Splitter allows one to access one more element than its length would imply to allow to retrieve the right boundary of each subinterval (see example code below).

### Examples

Simple example for equidistant (default) splitting.

    #include <iostream>
    #include <seqan/parallel.h>

    using namespace seqan;

    int main()
    {
        // instantiate a Splitter to divide the interval [10,20) in 3 subintervals
        Splitter<unsigned> splitter(10, 20, 3);

        // output all subintervals
        for (unsigned i = 0; i < length(splitter); ++i)
            std::cout << '[' << splitter[i] << ',' << splitter[i + 1] << ')' << std::endl;

        return 0;
    }

Demo: demos/dox/parallel/splitter_example.cpp

The output is:

    [10,14)
    [14,17)
    [17,20)

## Member Functions Detail

### `Splitter::Splitter(beginPos, endPos[, subintervalCount]); Splitter::Splitter(beginPos, endPos, parallelTag);`

Constructor

#### Parameters

`beginPos` | Left interval boundary.
`endPos` | Right interval boundary.
`subintervalCount` | Number of subintervals. length and resize can be used to retrieve or change the number of subintervals later. Default: The minimum of interval size and the number of available threads (returned by `omp_get_max_threads()`).
`parallelTag` | Tag to generically enable/disable parallelism. If its type is `Parallel`, the default number of subintervals is used. If it is `Serial`, only one subinterval is used. This tag should be used to write generic parallel algorithms and to switch between parallel and serial variants.

#### Data Races

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

## Interface Functions Detail

### `TSize length(splitter);`

Return the number of elements in the splitter.

#### Parameters

`splitter` | The Splitter object to query.

#### Returns

`TSize` | The number of elements in the Splitter, `TSize` is the size type.

#### Data Races

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

### `void resize(splitter, newCount);`

Change the number of elements in the splitter.

#### Parameters

`splitter` | The Splitter object to update.
`newCount` | The updated number of elements in the splitter.

#### Data Races

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

## Interface Metafunctions Detail

### `Size<TSplitter>::Type;`

Returns the size type for the Splitter.

#### Template Parameters

`TSplitter` | The Splitter to query for its size type.

### `Value<TSplitter>::Type;`

Returns the value type for the Splitter.

#### Template Parameters

`TSplitter` | The Splitter to query for its value type.

#### Dox Sources

    /*!
     * @class Splitter
     *
     * @headerfile <seqan/parallel.h>
     *
     * @brief Splits an interval into subintervals.
     *
     * @signature template <typename TValue, typename TSpec> class Splitter;
     *
     * @tparam TValue Type of the interval boundaries.
     * @tparam TSpec Tag to select the way the values are sampled.
     *
     * This class divides an interval into the disjoint union of subintervals and
     * enumerates its boundaries. It can be used to parallelize large for-loops that
     * iterate over a contiguous range of elements. The interval and the number of
     * subintervals can be set in the constructor @link Splitter::Splitter @endlink.
     * @link Splitter#length @endlink and @link Splitter#resize @endlink can be used
     * to retrieve or change the number of subintervals later. In contrast to other
     * containers the Splitter allows one to access one more element than its length
     * would imply to allow to retrieve the right boundary of each subinterval (see
     * example code below).
     *
     * @section Examples
     *
     * Simple example for equidistant (default) splitting.
     *
     * @include demos/dox/parallel/splitter_example.cpp
     *
     * The output is:
     *
     * @include demos/dox/parallel/splitter_example.cpp.stdout
     *
     *
     *
     * @mfn Splitter#Size
     *
     * @brief Returns the size type for the Splitter.
     *
     * @signature Size<TSplitter>::Type;
     *
     * @tparam TSplitter The Splitter to query for its size type.
     *
     * @mfn Splitter#Value
     *
     * @brief Returns the value type for the Splitter.
     *
     * @signature Value<TSplitter>::Type;
     *
     * @tparam TSplitter The Splitter to query for its value type.
     *
     * @fn Splitter::Splitter
     *
     * @brief Constructor
     *
     * @signature Splitter::Splitter(beginPos, endPos[, subintervalCount]);
     * @signature Splitter::Splitter(beginPos, endPos, parallelTag);
     *
     * @param[in] beginPos Left interval boundary.
     * @param[in] endPos Right interval boundary.
     * @param[in] subintervalCount Number of subintervals. @link Splitter#length
     *                             @endlink and @link Splitter#resize @endlink can
     *                             be used to retrieve or change the number of
     *                             subintervals later. Default: The minimum of
     *                             interval size and the number of available threads
     *                             (returned by <tt>omp_get_max_threads()</tt>).
     * @param[in] parallelTag Tag to generically enable/disable parallelism. If its
     *                        type is <tt>Parallel</tt>, the default number of
     *                        subintervals is used. If it is <tt>Serial</tt>, only
     *                        one subinterval is used. This tag should be used to
     *                        write generic parallel algorithms and to switch
     *                        between parallel and serial variants.
     *
     * @fn Splitter#length
     *
     * @brief Return the number of elements in the splitter.
     *
     * @signature TSize length(splitter);
     *
     * @param[in] splitter The Splitter object to query.
     *
     * @return TSize The number of elements in the Splitter, <tt>TSize</tt> is the
     *               size type.
     *
     * @fn Splitter#resize
     *
     * @brief Change the number of elements in the splitter.
     *
     * @signature void resize(splitter, newCount);
     *
     * @param[out] splitter The Splitter object to update.
     * @param[in] newCount The updated number of elements in the splitter.
     */