RandomAccessIteratorConcept - SeqAn API Documentation

# Concept RandomAccessIteratorConcept
An iterator allowing random access.

Extends | BidirectionalIteratorConcept, LessThanComparableConcept
All Extended | BidirectionalIteratorConcept, CopyConstructibleConcept, DefaultConstructibleConcept, EqualityComparableConcept, ForwardIteratorConcept, InputIteratorConcept, IteratorAssociatedTypesConcept, LessThanComparableConcept
All Subcl's | MutableRandomAccessIteratorConcept, MutableRootedRandomAccessIteratorConcept, RootedRandomAccessIteratorConcept
Defined in | <seqan/basic.h>
Signature | `RandomAccessIteratorConcept<T>`

## Detailed Description

This function is equivalent to `--iterator`.

### Examples

In the following, `x` is an iterator to type `X`, `t` is a valid rvalue of type `X`, `n` is a distance type.

The following expressions must be valid.

    x += n    // Iterator addition assignment.
    x + n     // Iterator addition.
    n + i     // Iterator addition.
    x -= n    // Iterator subtraction assignment.
    x - n     // Iterator subtraction.
    x - a     // Difference.
    x[n]      // Element operator.

## Member Function Overview

- `TReference TIterator::operator[](pos);`
  C++ built-in array subscript operator.

### Member Functions Inherited From EqualityComparableConcept

- `operator!=`
- `operator==`

### Member Functions Inherited From LessThanComparableConcept

- `operator<`

## Interface Function Overview

- `bool atNil(it);`
  Tests whether iterator is at nil position.
- `TDifference difference(begin, end);`
  The difference between two iterators.
- `void goFurther(iterator, steps);`
  Iterates some steps further.
- `void goNil(it);`
  Moves iterator to nil position.
- `TIterator operator+(lhs, rhs);`
  C++ built-in addition operator.
- `TIterator operator+=(it, diff);`
  C++ built-in addition assignment operator.
- `TIterator operator-=(it, diff);`
  C++ built-in subtraction assignment operator.

### Interface Functions Inherited From BidirectionalIteratorConcept

- `goPrevious`
- `operator--(prefix)`
- `operator--(suffix)`

### Interface Functions Inherited From InputIteratorConcept

- `goNext`
- `operator++(prefix)`
- `operator++(suffix)`
- `operator->`

### Interface Functions Inherited From IteratorAssociatedTypesConcept

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

## Interface Metafunction Overview

- `Difference<T>::Type`
  Type of an object that stores the difference between two iterators.

### Interface Metafunctions Inherited From IteratorAssociatedTypesConcept

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

## Member Functions Detail

### `TReference TIterator::operator[](pos);`

C++ built-in array subscript operator.

#### Template Parameters

`TReference` | The referenced element.

#### Parameters

`pos` | Position to get element at.

#### Data Races

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

## Interface Functions Detail

### `bool atNil(it);`

Tests whether iterator is at nil position.

#### Parameters

`it` | The iterator to query.

#### Returns

`bool` | Whether or not the iterator is at the nil positions (NULL for pointers).

#### Data Races

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

### `TDifference difference(begin, end);`

The difference between two iterators.

#### Parameters

`begin` | Iterator to the first position of a range.
`end` | Iterator behind the last position of a range.

#### Returns

`TDifference` | Length of the range between `begin` and `end`, type from

This function is equivalent to `end - begin`.

Usually, `begin` and `end` have the same type.

#### Data Races

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

### `void goFurther(iterator, steps);`

Iterates some steps further.

#### Parameters

`it` | The iterator to move.
`steps` | Number of steps `iterator` should be moved further.

This function is equivalent to `iterator += steps`.

#### Data Races

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

### `void goNil(it);`

Moves iterator to nil position.

#### Parameters

`it` | The iterator that will be moved.

`it` is set to an invalid position, e.g. `NULL` for pointer types.

#### Data Races

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

### `TIterator operator+(lhs, rhs);`

C++ built-in addition operator.

#### Data Races

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

### `TIterator operator+=(it, diff);`

C++ built-in addition assignment operator.

#### Data Races

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

### `TIterator operator-=(it, diff);`

C++ built-in subtraction assignment operator.

#### Data Races

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

## Interface Metafunctions Detail

### `Difference<T>::Type`

Type of an object that stores the difference between two iterators.

#### Template Parameters

`T` | Type for which the difference type is determined.

#### Returns

`Type` | The difference type.

In most cases this type is `ptrdiff_t`.

#### Dox Sources

    /*!
     * @concept RandomAccessIteratorConcept
     *
     * @headerfile <seqan/basic.h>
     *
     * @extends BidirectionalIteratorConcept
     * @extends LessThanComparableConcept
     *
     * @brief An iterator allowing random access.
     *
     * @signature RandomAccessIteratorConcept<T>
     *
     * This function is equivalent to <tt>--iterator</tt>.
     *
     * @section Examples
     *
     * In the following, <tt>x</tt> is an iterator to type <tt>X</tt>, <tt>t</tt> is
     * a valid rvalue of type <tt>X</tt>, <tt>n</tt> is a distance type.
     *
     * The following expressions must be valid.
     *
     * @code{.cpp}
     * x += n    // Iterator addition assignment.
     * x + n     // Iterator addition.
     * n + i     // Iterator addition.
     * x -= n    // Iterator subtraction assignment.
     * x - n     // Iterator subtraction.
     * x - a     // Difference.
     * x[n]      // Element operator.
     * @endcode
     *
     *
     * @mfn RandomAccessIteratorConcept#Difference
     *
     * @brief Type of an object that stores the difference between two iterators.
     *
     * @signature Difference<T>::Type
     *
     * @tparam T Type for which the difference type is determined.
     *
     * @return Type The difference type.
     *
     * In most cases this type is <tt>ptrdiff_t</tt>.
     *
     * @fn RandomAccessIteratorConcept::operator[]
     *
     * @brief C++ built-in array subscript operator.
     *
     * @signature TReference TIterator::operator[](pos);
     *
     * @tparam TReference The referenced element.
     *
     * @param[in] pos Position to get element at.
     *
     * @fn RandomAccessIteratorConcept#difference
     *
     * @brief The difference between two iterators.
     *
     * @signature TDifference difference(begin, end);
     *
     * @param[in] begin Iterator to the first position of a range.
     * @param[in] end Iterator behind the last position of a range.
     *
     * @return TDifference Length of the range between <tt>begin</tt> and
     *                     <tt>end</tt>, type from
     *
     * This function is equivalent to <tt>end - begin</tt>.
     *
     * Usually, <tt>begin</tt> and <tt>end</tt> have the same type.
     *
     * @fn RandomAccessIteratorConcept#operator+=
     *
     * @brief C++ built-in addition assignment operator.
     *
     * @signature TIterator operator+=(it, diff);
     *
     * @fn RandomAccessIteratorConcept#operator+
     *
     * @brief C++ built-in addition operator.
     *
     * @signature TIterator operator+(lhs, rhs);
     *
     * @fn RandomAccessIteratorConcept#operator-=
     *
     * @brief C++ built-in subtraction assignment operator.
     *
     * @signature TIterator operator-=(it, diff);
     *
     * @fn RandomAccessIteratorConcept#goNil
     *
     * @brief Moves iterator to nil position.
     *
     * @signature void goNil(it);
     *
     * @param[in,out] it The iterator that will be moved.
     *
     * <tt>it</tt> is set to an invalid position, e.g. <tt>NULL</tt> for pointer
     * types.
     *
     * @fn RandomAccessIteratorConcept#goFurther
     *
     * @brief Iterates some steps further.
     *
     * @signature void goFurther(iterator, steps);
     *
     * @param[in,out] it The iterator to move.
     * @param[in] steps Number of steps <tt>iterator</tt> should be moved further.
     *
     * This function is equivalent to <tt>iterator += steps</tt>.
     *
     * @fn RandomAccessIteratorConcept#atNil
     *
     * @brief Tests whether iterator is at nil position.
     *
     * @signature bool atNil(it);
     *
     * @param[in] it The iterator to query.
     *
     * @return bool Whether or not the iterator is at the nil positions (NULL for
     *              pointers).
     */