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

Interface Function Overview

Interface Functions Inherited From AssignableConcept

Interface Metafunction Overview

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

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;