# Concept ContainerConcept
A container is an object that stores other objects (elements).

Extends | AssignableConcept, DestructibleConcept
All Extended | AssignableConcept, DestructibleConcept
All Subcl's | ForwardContainerConcept, RandomAccessContainerConcept, ReversibleContainerConcept, SegmentableConcept, StringConcept
Defined in | <seqan/basic.h>
Signature | `ContainerConcept<T>`

## Detailed Description

Containers store multiple entries of the same type (the element type) and provide means to access these items. More specific, each container has an iterator type that is used for accessing its elements.

There is no guarantee for the elements to be in a particular order (the order can vary between two iterations) and no guarantee for the time complexity of element access. Furthermore, there is no guarantee that there can be more than one iterator in the container. Modification of a container through an iterator invalidates all other iterators.

Refinements of the Container concept or specific implementations can provide these guarantees, however.

A container owns its elements and the elements are destructed when their owning container is destructed. The elements must fulfill the concepts AssignableConcept and DestructibleConcept.

## Member Function Overview

### Member Functions Inherited From AssignableConcept

- `operator=`

## Interface Function Overview

- `void append(target, source);`
  Concatenate a container to another.
- `void appendValue(target, val[, tag]);`
  Append a value to a container.
- `TIterator begin(c[, tag]);`
  Returns an iterator to the beginning of the container.
- `TDirIter directionIterator(streamBuf, dirTag);`
  Returns direction iterator for a container.
- `bool empty(c);`
  Returns whether the container is empty.
- `TIterator end(c[, tag]);`
  Returns an iterator to the end of the container.
- `TVoidPtr getObjectId(cont);`
  A value that identifies the underlying sequence.
- `TSize length(c);`
  Returns the size of the container.
- `void moveValue(container, pos, value);`
  Move a value into a container at a given position.
- `void shrinkToFit(cont);`
  Resizes container to minimum capacity.
- `void swap(c1, c2);`
  Swap the contents of two containers.
- `void write(container, iter, n);`
  Write to a container.
- `void writeValue(container, val);`
  Write a value at the end of a container.

### Interface Functions Inherited From AssignableConcept

- `assign`
- `move`
- `set`

## Interface Metafunction Overview

- `DefaultGetIteratorSpec<TContainer>::Type`
  Returns the default iterator specialization for functions.
- `DefaultIteratorSpec<TContainer>::Type`
  Returns the default iterator specialization.
- `Size<TContainer>::Type`
  Returns the type for distances between two iterators.
- `DirectionIterator<TContainer>::Type;`
  Return the direction iterator for the given direction.
- `GetValue<TContainer>::Type`
  Returns the get-value type of the container.
- `Iterator<TContainer[, TSpec]>::Type`
  Returns the iterator type of the container.
- `Positin<TContainer>::Type`
  Returns the position type of a container.
- `Reference<TContainer>::Type`
  Returns the reference type of the container.
- `Size<TContainer>::Type`
  Returns the size type of a container.
- `Value<TContainer>::Type`
  Returns the value type of the container.

## Interface Functions Detail

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

Concatenate a container to another.

#### Parameters

`target` | The container to append `source` to.
`source` | This container will be appended to `source`.

#### Data Races

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

### `void appendValue(target, val[, tag]);`

Append a value to a container.

#### Parameters

`target` | The container to append `val` to.
`val` | The value to append to `target`.
`tag` | The resize tag to use. Defaults to What DefaultOverflowImplicit returns for the type of `target`.

#### Data Races

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

### `TIterator begin(c[, tag]);`

Returns an iterator to the beginning of the container.

#### Parameters

`c` | The container to get the begin iterator for (type `TContainer`).
`tag` | An optional tag for selecting the type of the iterator. One of `Standard` and `Rooted`. When left out, DefaultGetIteratorSpec of `TContainer` is used.

#### Returns

`TIterator` | Iterator to the beginning of the container, the type is selected by Iterator with the given (or default) tag.

When empty, `begin(c) == end(c)`.

#### Data Races

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

### `TDirIter directionIterator(streamBuf, dirTag);`

Returns direction iterator for a container.

#### Parameters

`streamBuf` | The container object to compute iterator for.
`dirTag` | Direction tag, one of the DirectionTags.

#### Returns

`TDirIter` | The resulting DirectionIterator.

#### Data Races

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

### `bool empty(c);`

Returns whether the container is empty.

#### Parameters

`c` | The container to query.

#### Returns

`bool` | Whether or not the container is empty.

#### Data Races

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

### `TIterator end(c[, tag]);`

Returns an iterator to the end of the container.

#### Parameters

`c` | The container to get the end iterator for (type `TContainer`).
`tag` | An optional tag for selecting the type of the iterator. One of `Standard` and `Rooted`. When left out, DefaultGetIteratorSpec of `TContainer` is used.

#### Returns

`TIterator` | Iterator to the end of the container, the type is selected by Iterator with the given (or default) tag.

When empty, `begin(c) == end(c)`.

#### Data Races

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

### `TVoidPtr getObjectId(cont);`

A value that identifies the underlying sequence.

#### Parameters

`cont` | The object for which to determine the id.

#### Returns

`TVoidPtr` | a `void const *` value identying the object.

Two sequences should have the same id, if they share the same resource, e.g. the same memory buffer.

The exact semantic of the returned id can vary for different classes. Typically, the id of a string is a `void const *` to the end of the string.

#### Examples

    String<char> str = "hallo seqan";
    bool b1 = (getObjectId(str) == getObjectId(infix(str, 3, 7));   //true
    bool b2 = (getObjectId(str) == getObjectId(String<char>(str))); //false
    bool b3 = (getObjectId(str) == getObjectId(toCString(str)));

In this example, `b1` is `true</tt., since the segment object returned by `infix()` is just a filter and uses the buffer of it's host object str.`

`String<char>(str)` constructs a temporary copy of `str`, so these two strings have different id values.

The result of the last comparison depends on the implementation of `toCString` and cannot be predicted at compile time.

#### Data Races

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

### `TSize length(c);`

Returns the size of the container.

#### Parameters

`c` | The container to query for its size.

#### Returns

`TSize` | The number of elements in the container.

#### Data Races

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

### `void moveValue(container, pos, value);`

Move a value into a container at a given position.

#### Parameters

`container` | The container to manipulate.
`pos` | The position of the item in the container to manipulate.
`value` | The value to move to `container[pos]`.

#### Data Races

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

### `void shrinkToFit(cont);`

Resizes container to minimum capacity.

#### Parameters

`cont` | The container to shrink.

#### Data Races

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

### `void swap(c1, c2);`

Swap the contents of two containers.

#### Parameters

`c1` | The first container.
`c2` | The second container.

Swaps the contents of `c1` and `c2`. The `swap` function must be defined in the same namespace as the container for Koenig lookup to work. In the heart of sorting algorithms, for example, the swap function is properly used as follows. This way, both the generic `std::swap` and the specialized `swap` function of the container are available:

    TContainer c1, c2; // ...
    using std::swap;
    swap(c1, c2);

#### Data Races

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

### `void write(container, iter, n);`

Write to a container.

#### Parameters

`container` | The container to append to.
`iter` | The forward iterator to take the values from.
`n` | Number of elements to write from `iter`.

This function reads `n` values from `iter` and appends them to the back of `container`.

#### Data Races

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

### `void writeValue(container, val);`

Write a value at the end of a container.

#### Parameters

`container` | to append to.
`val` | The value to append.

#### Data Races

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

#### See Also

- appendValue

## Interface Metafunctions Detail

### `DefaultGetIteratorSpec<TContainer>::Type`

Returns the default iterator specialization for functions.

#### Template Parameters

`TContainer` | The Container type to query.

#### Returns

`Type` | The iterator specialization tag type.

Used by functions such as begin and end for the `TSpec` parameter.

### `DefaultIteratorSpec<TContainer>::Type`

Returns the default iterator specialization.

#### Template Parameters

`TContainer` | The Container type to query.

#### Returns

`Type` | The iterator specialization tag type.

Used by Iterator to select the default value for `TSpec`.

### `Size<TContainer>::Type`

Returns the type for distances between two iterators.

#### Template Parameters

`TContainer` | The Container type to query.

#### Returns

`Type` | The type to use for storing iterator distances sizes.

This must be the same type as the distance type of the containers iterators.

### `DirectionIterator<TContainer>::Type;`

Return the direction iterator for the given direction.

#### Template Parameters

`TContainer` | The container to query for its direction iterator.

#### Returns

`Type` | The resulting direction iterator.

### `GetValue<TContainer>::Type`

Returns the get-value type of the container.

#### Template Parameters

`TContainer` | The Container to query.

#### Returns

`Type` | The get-value type of the container.

The get-value type of the container is a type for efficient read-only access to the elements in the container. For small types (e.g. `int`), this can be a copy (thus `int`), for larger types, this can be a const reference to the value type.

#### Valid Expressions

The variable v has the get-value type of the container TContainer whereas it is an iterator into the container. Thus, we can store a get-value in v.

    GetValue<TContainer>::Type v = *it;

### `Iterator<TContainer[, TSpec]>::Type`

Returns the iterator type of the container.

#### Template Parameters

`TContainer` | The Container type to query.
`TSpec` | Optionally, a tag for selecting the kind of iterator. If not given, then DefaultIteratorSpec of TContainer is used. When given, one of `Standard` and `Rooted`.

#### Returns

`Type` | The iterator type.

Different from the STL the `const` attribute of `TContainer` determines whether the resturned iterator is a const iterator or a non-const iterator.

### `Positin<TContainer>::Type`

Returns the position type of a container.

#### Template Parameters

`TContainer` | The Container type to query.

#### Returns

`Type` | The type to use for storing container positions.

### `Reference<TContainer>::Type`

Returns the reference type of the container.

#### Template Parameters

`TContainer` | The Container to query.

#### Returns

`Type` | The reference type of the container.

Different from STL containers, the const-ness of `TContainer` decides whether the returned type is a const reference or a reference for modifying elements.

Note that the reference type is not guaranteed to be `TValue &` if the value type of the container is `TValue`. The reference can be implemented as a proxy, similar to `std::vector<bool>`.

#### Valid Expressions

The variable r has the reference type of the container TContainer whereas it is an iterator into the container. Thus, we can store a reference to a value in the container in r. Then, we can assign the value of v, a value of the container.

    Reference<TContainer>::Type r = *it;  // reference into container
    r = v;  // updates value in container, thus also *it

### `Size<TContainer>::Type`

Returns the size type of a container.

#### Template Parameters

`TContainer` | The Container type to query.

#### Returns

`Type` | The type to use for storing container sizes.

### `Value<TContainer>::Type`

Returns the value type of the container.

#### Template Parameters

`TContainer` | The Container to query.

#### Returns

`Type` | The element type of the container.

The value type is the type that can be used for storing copies of the elements in the container.

#### Valid Expressions

The variable v has the value type of the container TContainer whereas it is an iterator into the container. Thus, copies of values from TContainer (*it) ca be stored in v.

    Value<TContainer>::Type v = *it;

#### Dox Sources

    /*!
     * @concept ContainerConcept
     *
     * @headerfile <seqan/basic.h>
     *
     * @extends AssignableConcept
     * @extends DestructibleConcept
     *
     * @brief A container is an object that stores other objects (<i>elements</i>).
     *
     * @signature ContainerConcept<T>
     *
     * Containers store multiple entries of the same type (the <i>element type</i>)
     * and provide means to access these items. More specific, each container has an
     * iterator type that is used for accessing its elements.
     *
     * There is no guarantee for the elements to be in a particular order (the order
     * can vary between two iterations) and no guarantee for the time complexity of
     * element access. Furthermore, there is no guarantee that there can be more
     * than one iterator in the container. Modification of a container through an
     * iterator invalidates all other iterators.
     *
     * Refinements of the Container concept or specific implementations can provide
     * these guarantees, however.
     *
     * A container owns its elements and the elements are destructed when their
     * owning container is destructed. The elements must fulfill the concepts @link
     * AssignableConcept @endlink and @link DestructibleConcept @endlink.
     *
     * @mfn ContainerConcept#Value
     *
     * @brief Returns the value type of the container.
     *
     * @signature Value<TContainer>::Type
     *
     * @tparam TContainer The Container to query.
     *
     * @return Type The element type of the container.
     *
     * The value type is the type that can be used for storing copies of the
     * elements in the container.
     *
     * @section Valid Expressions
     *
     * The variable v has the value type of the container TContainer whereas it is
     * an iterator into the container. Thus, copies of values from TContainer (*it)
     * ca be stored in v.
     *
     * @code{.cpp}
     * Value<TContainer>::Type v = *it;
     * @endcode
     *
     *
     * @mfn ContainerConcept#GetValue
     *
     * @brief Returns the get-value type of the container.
     *
     * @signature GetValue<TContainer>::Type
     *
     * @tparam TContainer The Container to query.
     *
     * @return Type The get-value type of the container.
     *
     * The get-value type of the container is a type for efficient read-only access
     * to the elements in the container. For small types (e.g. <tt>int</tt>), this
     * can be a copy (thus <tt>int</tt>), for larger types, this can be a const
     * reference to the value type.
     *
     * @section Valid Expressions
     *
     * The variable v has the get-value type of the container TContainer whereas it
     * is an iterator into the container. Thus, we can store a get-value in v.
     *
     * @code{.cpp}
     * GetValue<TContainer>::Type v = *it;
     * @endcode
     *
     *
     * @mfn ContainerConcept#Reference
     *
     * @brief Returns the reference type of the container.
     *
     * @signature Reference<TContainer>::Type
     *
     * @tparam TContainer The Container to query.
     *
     * @return Type The reference type of the container.
     *
     * Different from STL containers, the const-ness of <tt>TContainer</tt> decides
     * whether the returned type is a const reference or a reference for modifying
     * elements.
     *
     * Note that the reference type is not guaranteed to be <tt>TValue &amp;</tt> if
     * the value type of the container is <tt>TValue</tt>. The reference can be
     * implemented as a proxy, similar to <tt>std::vector&lt;bool&gt;</tt>.
     *
     * @section Valid Expressions
     *
     * The variable r has the reference type of the container TContainer whereas it
     * is an iterator into the container. Thus, we can store a reference to a value
     * in the container in r. Then, we can assign the value of v, a value of the
     * container.
     *
     * @code{.cpp}
     * Reference<TContainer>::Type r = *it;  // reference into container
     * r = v;  // updates value in container, thus also *it
     * @endcode
     *
     *
     * @mfn ContainerConcept#Iterator
     *
     * @brief Returns the iterator type of the container.
     *
     * @signature Iterator<TContainer[, TSpec]>::Type
     *
     * @tparam TContainer The Container type to query.
     * @tparam TSpec Optionally, a tag for selecting the kind of iterator. If not
     *               given, then @link ContainerConcept#DefaultIteratorSpec @endlink
     *               of TContainer is used. When given, one of <tt>Standard</tt> and
     *               <tt>Rooted</tt>.
     *
     * @return Type The iterator type.
     *
     * Different from the STL the <tt>const</tt> attribute of <tt>TContainer</tt>
     * determines whether the resturned iterator is a const iterator or a non-const
     * iterator.
     *
     * @see ContainerIteratorTags
     *
     * @mfn ContainerConcept#Size
     *
     * @brief Returns the size type of a container.
     *
     * @signature Size<TContainer>::Type
     *
     * @tparam TContainer The Container type to query.
     *
     * @return Type The type to use for storing container sizes.
     *
     * @mfn ContainerConcept#Position
     *
     * @brief Returns the position type of a container.
     *
     * @signature Positin<TContainer>::Type
     *
     * @tparam TContainer The Container type to query.
     *
     * @return Type The type to use for storing container positions.
     *
     * @mfn ContainerConcept#Difference
     *
     * @brief Returns the type for distances between two iterators.
     *
     * @signature Size<TContainer>::Type
     *
     * @tparam TContainer The Container type to query.
     *
     * @return Type The type to use for storing iterator distances sizes.
     *
     * This must be the same type as the distance type of the containers iterators.
     *
     * @mfn ContainerConcept#DefaultIteratorSpec
     *
     * @brief Returns the default iterator specialization.
     *
     * @signature DefaultIteratorSpec<TContainer>::Type
     *
     * @tparam TContainer The Container type to query.
     *
     * @return Type The iterator specialization tag type.
     *
     * Used by @link ContainerConcept#Iterator @endlink to select the default value
     * for <tt>TSpec</tt>.
     *
     * @see ContainerConcept#Iterator
     *
     * @mfn ContainerConcept#DefaultGetIteratorSpec
     *
     * @brief Returns the default iterator specialization for functions.
     *
     * @signature DefaultGetIteratorSpec<TContainer>::Type
     *
     * @tparam TContainer The Container type to query.
     *
     * @return Type The iterator specialization tag type.
     *
     * Used by functions such as @link ContainerConcept#begin @endlink and @link
     * ContainerConcept#end @endlink for the <tt>TSpec</tt> parameter.
     *
     * @see ContainerConcept#Iterator
     *
     * @mfn ContainerConcept#DirectionIterator
     *
     * @brief Return the direction iterator for the given direction.
     *
     * @signature DirectionIterator<TContainer>::Type;
     *
     * @tparam TContainer The container to query for its direction iterator.
     *
     * @return Type The resulting direction iterator.
     *
     * @fn ContainerConcept#begin
     *
     * @brief Returns an iterator to the beginning of the container.
     *
     * @signature TIterator begin(c[, tag]);
     *
     * @param[in] c The container to get the begin iterator for (type
     *              <tt>TContainer</tt>).
     * @param[in] tag An optional tag for selecting the type of the iterator. One of
     *                <tt>Standard</tt> and <tt>Rooted</tt>. When left out, @link
     *                ContainerConcept#DefaultGetIteratorSpec @endlink of
     *                <tt>TContainer</tt> is used.
     *
     * @return TIterator Iterator to the beginning of the container, the type is
     *                   selected by @link ContainerConcept#Iterator @endlink with
     *                   the given (or default) tag.
     *
     * When empty, <tt>begin(c) == end(c)</tt>.
     *
     * @fn ContainerConcept#end
     *
     * @brief Returns an iterator to the end of the container.
     *
     * @signature TIterator end(c[, tag]);
     *
     * @param[in] c The container to get the end iterator for (type
     *              <tt>TContainer</tt>).
     * @param[in] tag An optional tag for selecting the type of the iterator. One of
     *                <tt>Standard</tt> and <tt>Rooted</tt>. When left out, @link
     *                ContainerConcept#DefaultGetIteratorSpec @endlink of
     *                <tt>TContainer</tt> is used.
     *
     * @return TIterator Iterator to the end of the container, the type is selected
     *                   by @link ContainerConcept#Iterator @endlink with the given
     *                   (or default) tag.
     *
     * When empty, <tt>begin(c) == end(c)</tt>.
     *
     * @fn ContainerConcept#length
     *
     * @brief Returns the size of the container.
     *
     * @signature TSize length(c);
     *
     * @param[in] c The container to query for its size.
     *
     * @return TSize The number of elements in the container.
     *
     * @fn ContainerConcept#empty
     *
     * @brief Returns whether the container is empty.
     *
     * @signature bool empty(c);
     *
     * @param[in] c The container to query.
     *
     * @return bool Whether or not the container is empty.
     *
     * @fn ContainerConcept#swap
     *
     * @brief Swap the contents of two containers.
     *
     * @signature void swap(c1, c2);
     *
     * @param[in,out] c1 The first container.
     * @param[in,out] c2 The second container.
     *
     * Swaps the contents of <tt>c1</tt> and <tt>c2</tt>. The <tt>swap</tt> function
     * must be defined in the same namespace as the container for Koenig lookup to
     * work. In the heart of sorting algorithms, for example, the swap function is
     * properly used as follows. This way, both the generic <tt>std::swap</tt> and
     * the specialized <tt>swap</tt> function of the container are available:
     *
     * @code{.cpp}
     * TContainer c1, c2; // ...
     * using std::swap;
     * swap(c1, c2);
     * @endcode
     *
     *
     * @fn ContainerConcept#writeValue
     *
     * @brief Write a value at the end of a container.
     *
     * @signature void writeValue(container, val);
     *
     * @param[in,out] container to append to.
     * @param[in] val The value to append.
     *
     * @see ContainerConcept#appendValue
     *
     * @fn ContainerConcept#write
     *
     * @brief Write to a container.
     *
     * @signature void write(container, iter, n);
     *
     * @param[in,out] container The container to append to.
     * @param[in,out] iter The @link ForwardIteratorConcept forward iterator
     *                     @endlink to take the values from.
     * @param[in] n Number of elements to write from <tt>iter</tt>.
     *
     * This function reads <tt>n</tt> values from <tt>iter</tt> and appends them to
     * the back of <tt>container</tt>.
     *
     * @fn ContainerConcept#getObjectId
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief A value that identifies the underlying sequence.
     *
     * @signature TVoidPtr getObjectId(cont);
     *
     * @param[in] cont The object for which to determine the id.
     *
     * @return TVoidPtr a <tt>void const *</tt> value identying the object.
     *
     * Two sequences should have the same id, if they share the same resource, e.g.
     * the same memory buffer.
     *
     * The exact semantic of the returned id can vary for different classes.
     * Typically, the id of a string is a <tt>void const *</tt> to the end of the
     * string.
     *
     * @section Examples
     *
     * @code{.cpp}
     * String<char> str = "hallo seqan";
     * bool b1 = (getObjectId(str) == getObjectId(infix(str, 3, 7));   //true
     * bool b2 = (getObjectId(str) == getObjectId(String<char>(str))); //false
     * bool b3 = (getObjectId(str) == getObjectId(toCString(str)));
     * @endcode
     *
     *
     * In this example, <tt>b1</tt> is <tt>true</tt., since the segment object
     * returned by <tt>infix()</tt> is just a filter and uses the buffer of it's
     * host object str.
     *
     * <tt>String&lt;char&gt;(str)</tt> constructs a temporary copy of <tt>str</tt>,
     * so these two strings have different id values.
     *
     * The result of the last comparison depends on the implementation of
     * <tt>toCString</tt> and cannot be predicted at compile time.
     *
     * @fn ContainerConcept#moveValue
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Move a value into a container at a given position.
     *
     * @signature void moveValue(container, pos, value);
     *
     * @param[in,out] container The container to manipulate.
     * @param[in] pos The position of the item in the container to manipulate.
     * @param[in,out] value The value to move to <tt>container[pos]</tt>.
     *
     * @fn ContainerConcept#append
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Concatenate a container to another.
     *
     * @signature void append(target, source);
     *
     * @param[in,out] target The @link ContainerConcept container @endlink to append
     *                       <tt>source</tt> to.
     * @param[in] source This @link ContainerConcept container @endlink will be
     *                   appended to <tt>source</tt>.
     *
     * @fn ContainerConcept#appendValue
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Append a value to a container.
     *
     * @signature void appendValue(target, val[, tag]);
     *
     * @param[in,out] target The container to append <tt>val</tt> to.
     * @param[in] val The value to append to <tt>target</tt>.
     * @param[in] tag The resize tag to use. Defaults to What
     *                DefaultOverflowImplicit returns for the type of
     *                <tt>target</tt>.
     *
     * @fn ContainerConcept#shrinkToFit
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Resizes container to minimum capacity.
     *
     * @signature void shrinkToFit(cont);
     *
     * @param[in] cont The container to shrink.
     *
     * @fn ContainerConcept#directionIterator
     *
     * @brief Returns direction iterator for a container.
     *
     * @signature TDirIter directionIterator(streamBuf, dirTag);
     *
     * @param[in] streamBuf The @link ContainerConcept container @endlink object to
     *                      compute iterator for.
     * @param[in] dirTag Direction tag, one of the @link DirectionTags @endlink.
     *
     * @return TDirIter The resulting @link ContainerConcept#DirectionIterator
     *                  @endlink.
     */