Pipe - SeqAn API Documentation

# Class Pipe
Pipes are pop-passive pipeline modules.

All Subcl's | Caster, Counter, Echoer, EditEnvironment, Filter, Joiner, Namer, Sampler, Shifter, Source, Tupler
Defined in | <seqan/pipe.h>
Signature | `template <typename TInput, typename TSpec> class Pipe;`

## Template Parameters

`TSpec` | The specializing type.
`TInput` | The type of the pipeline module this module reads from. Use Bundle2, Bundle3, etc. to read from more than one module.

## Member Function Overview

- `Pipe::Pipe(in);`
  Constructor

## Interface Function Overview

- `void assign(target, source);`
  Assigns one object to another object.
- `bool atEnd(pipe);`
  Check whether the Pipe object is at end.
- `bool beginRead(object);`
  Initiates a read process.
- `bool endRead(object);`
  Terminates a read process.
- `TValue front(object);`
  Gets the first element of the remaining stream.
- `TSize length(pipe);`
  Length of the pipe.
- `void pop(pipe[, ref]);`
  Pops the first element of the remaining stream.

## Interface Metafunction Overview

- `Size<TPipe>::Type;`
  Return size type of the Pipe specialization.
- `Value<TPipe>::Type;`
  Return value type of the Pipe specialization.

## Detailed Description

Use Value to get the output type of a given Pipe (returns `Value<TInput>::Type` by default).

Use Size to get the size type of a given Pipe (returns `Size<TInput>::Type` by default).

## Member Functions Detail

### `Pipe::Pipe(in);`

Constructor

#### Parameters

`in` | Reference to an input pipe.

#### Data Races

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

## Interface Functions Detail

### `void assign(target, source);`

Assigns one object to another object.

#### Parameters

`target` | Reference to assign to.
`source` | Value to assign.

Assign value of source to target.

#### Data Races

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

### `bool atEnd(pipe);`

Check whether the Pipe object is at end.

#### Parameters

`pipe` | The Pipe object to query.

#### Returns

`bool` | true in case of the pipe being at the end, false otherwise.

#### Data Races

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

### `bool beginRead(object);`

Initiates a read process.

#### Parameters

`object` | A pop-passive pipeline module.

#### Returns

`bool` | true on success, false on failure.

`beginRead` rewinds the output stream, prepares `object` for succeeding reads, and typically calls `beginRead` of the input pipeline modules.

A read process must be terminated with endRead. Nested read processes are not allowed.

#### Data Races

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

#### See Also

- endRead

### `bool endRead(object);`

Terminates a read process.

#### Parameters

`object` | A pop-passive pipeline module.

#### Returns

`bool` | true on success, false on failure.

`endRead` closes the output stream, frees resources possibly allocated by beginRead, and typically calls `endRead` of the input pipeline modules.

#### Data Races

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

#### See Also

- beginRead

### `TValue front(object);`

Gets the first element of the remaining stream.

#### Parameters

`object` | A pop-passive pipeline module.

#### Returns

`TValue` | The first element of the remaining input stream. Return type is `Value<TObject>::Type` for `object` type `TObject`.

Pipe#front or Pipe#pop can only be called within a read process surrounded by beginRead and endRead.

#### Data Races

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

#### See Also

- pop

### `TSize length(pipe);`

Length of the pipe.

#### Parameters

`pipe` | The Pipe to query for its size.

#### Returns

`TSize` | The size of the pipe.

#### Data Races

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

### `void pop(pipe[, ref]);`

Pops the first element of the remaining stream.

#### Parameters

`pipe` | A pop-passive pipeline module.
`ref` | Reference to the result. Result type is `Value<TObject>::Type` for `object` type `TObject`. Returns the first element of the remaining input stream.

In contrast to Pipe#front this function also steps one element further.

Pipe#front or Pipe#pop can only be called within a read process surrounded by beginRead and endRead.

#### Data Races

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

## Interface Metafunctions Detail

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

Return size type of the Pipe specialization.

#### Template Parameters

`TPipe` | The Pipe specialization to query.

#### Returns

`Type` | The resulting size type.

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

Return value type of the Pipe specialization.

#### Template Parameters

`TPipe` | The Pipe specialization to query.

#### Returns

`Type` | The resulting value type.

#### Dox Sources

    /*!
     * @class Pipe
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Pipes are pop-passive pipeline modules.
     *
     * @signature template <typename TInput, typename TSpec> class Pipe;
     *
     * @tparam TSpec The specializing type.
     * @tparam TInput The type of the pipeline module this module reads from. Use
     *                Bundle2, Bundle3, etc. to read from more than one module.
     *
     * Use @link Pipe#Value @endlink to get the output type of a given Pipe (returns
     * <tt>Value&lt;TInput&gt;::Type</tt> by default).
     *
     * Use Size to get the size type of a given Pipe (returns
     * <tt>Size&lt;TInput&gt;::Type</tt> by default).
     *
     * @mfn Pipe#Value
     *
     * @brief Return value type of the Pipe specialization.
     *
     * @signature Value<TPipe>::Type;
     *
     * @tparam TPipe The Pipe specialization to query.
     *
     * @return Type The resulting value type.
     *
     * @mfn Pipe#Size
     *
     * @brief Return size type of the Pipe specialization.
     *
     * @signature Size<TPipe>::Type;
     *
     * @tparam TPipe The Pipe specialization to query.
     *
     * @return Type The resulting size type.
     *
     * @fn Pipe::Pipe
     *
     * @brief Constructor
     *
     * @signature Pipe::Pipe(in);
     *
     * @param[in] in Reference to an input pipe.
     *
     * @fn Pipe#length
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Length of the pipe.
     *
     * @signature TSize length(pipe);
     *
     * @param[in] pipe The Pipe to query for its size.
     *
     * @return TSize The size of the pipe.
     *
     * @fn Pipe#front
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Gets the first element of the remaining stream.
     *
     * @signature TValue front(object);
     *
     * @param[in] object A pop-passive pipeline module.
     *
     * @return TValue The first element of the remaining input stream. Return type
     *                is <tt>Value&lt;TObject&gt;::Type</tt> for <tt>object</tt>
     *                type <tt>TObject</tt>.
     *
     * Pipe#front or Pipe#pop can only be called within a read process surrounded by
     * beginRead and endRead.
     *
     * @see Pipe#pop
     *
     * @fn Pipe#pop
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Pops the first element of the remaining stream.
     *
     * @signature void pop(pipe[, ref]);
     *
     * @param[in,out] pipe A pop-passive pipeline module.
     * @param[out] ref Reference to the result. Result type is
     *                 <tt>Value&lt;TObject&gt;::Type</tt> for <tt>object</tt> type
     *                 <tt>TObject</tt>. Returns the first element of the remaining
     *                 input stream.
     *
     * In contrast to Pipe#front this function also steps one element further.
     *
     * Pipe#front or Pipe#pop can only be called within a read process surrounded by
     * beginRead and endRead.
     *
     * @fn Pipe#atEnd
     *
     * @brief Check whether the @link Pipe @endlink object is at end.
     *
     * @signature bool atEnd(pipe);
     *
     * @param[in] pipe The @link Pipe @endlink object to query.
     *
     * @return bool true in case of the pipe being at the end, false otherwise.
     *
     * @fn Pipe#beginRead
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Initiates a read process.
     *
     * @signature bool beginRead(object);
     *
     * @param[in,out] object A pop-passive pipeline module.
     *
     * @return bool true on success, false on failure.
     *
     * <tt>beginRead</tt> rewinds the output stream, prepares <tt>object</tt> for
     * succeeding reads, and typically calls <tt>beginRead</tt> of the input
     * pipeline modules.
     *
     * A read process must be terminated with endRead. Nested read processes are not
     * allowed.
     *
     * @see Pipe#endRead
     *
     * @fn Pipe#endRead
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Terminates a read process.
     *
     * @signature bool endRead(object);
     *
     * @param[in,out] object A pop-passive pipeline module.
     *
     * @return bool true on success, false on failure.
     *
     * <tt>endRead</tt> closes the output stream, frees resources possibly allocated
     * by beginRead, and typically calls <tt>endRead</tt> of the input pipeline
     * modules.
     *
     * @see Pipe#beginRead
     *
     * @fn Pipe#assign
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Assigns one object to another object.
     *
     * @signature void assign(target, source);
     *
     * @param[out] target Reference to assign to.
     * @param[in] source Value to assign.
     *
     * Assign value of source to target.
     */