Holder - SeqAn API Documentation

# Class Holder
Manages relationship to another object.

All Subcl's | SimpleHolder, TristateHolder
Defined in | <seqan/basic.h>
Signature | `template <typename TValue[, typename TSpec> class Holder;`

## Template Parameters

`TSpec` | The specializing type. Default: `Tristate`
`TValue` | Type of the managed object.

## Interface Function Overview

- `void assignValue(object, value);`
  Assigns value to item.
- `void clear(holder);`
  Clear/destruct the Holder's value.
- `void create(holder[, object]);`
  Makes an object to owner of its content.
- `void detach(holder);`
  Makes an object independent from other objects.
- `bool empty(holder);`
  Test a Holder for being empty.
- `TGetValue getValue(holder);`
  Return the get-value of the holder.
- `void moveValue(holder, value);`
  Move a value of into a holder.
- `void setValue(holder, object);`
  Makes holder dependent.
- `TReference value(holder);`
  Return a reference to the value of the holder.

## Interface Metafunction Overview

- `GetValue<THolder>::Type;`
  Return get-value type of Holder.
- `Reference<THolder>::Type;`
  Return the reference type of a Holder.
- `Spec<THolder>::Type;`
  Return the specialization tag for a Holder.
- `Value<THolder>::Type;`
  Return value type of Holder.

## Detailed Description

### Remarks

The main purpose of this class is to facilitate the handling of member objects. If we want class `A` to be dependent on or the owner of another object of class `B`, then we add a data member of type `Holder<B>` to `A`. `Holder` offers some useful access functions and stores the kind of relationship between `A` and `B`.

## See Also

- create
- setValue

## Interface Functions Detail

### `void assignValue(object, value);`

Assigns value to item.

#### Parameters

`object` | An object that holds a value or points to a value. Types: Holder, Iter Concepts: Concept.BasicOutputIteratorConcept
`value` | A value that is assigned to the item `object` holds or points to.

This function is similar to assign. The difference is, that `assignValue` just changes a value stored in `object` or the value `object` points to, while assign changes the whole object.

If `object` is a container (that is `pos` is not specified), the whole content of `object` is replaced by `value`.

If `value` is not used again after calling this function, then consider to use moveValue that could be faster in some cases instead.

#### Data Races

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

#### See Also

- assign
- moveValue

### `void clear(holder);`

Clear/destruct the Holder's value.

#### Parameters

`holder` | The Holder to clear.

#### Data Races

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

### `void create(holder[, object]);`

Makes an object to owner of its content.

#### Parameters

`holder` | The Holder to create the object of.
`object` | Object from which a copy is made and stored in `holder`.

After this operation, `holder` will be in state 'owner'. If `object` is specified, `holder` will hold a copy of `object` at the end of this function. If `object` is not specified, the action depends on the former state of `holder`:

- If the state of `holder` was 'empty', a new object is default constructed and stored into `holder`.
- If the state of `holder` was 'dependent', a copy of the former object is made and stored into `holder`.
- If the state of `holder` was already 'owner', nothing happens.

It is guaranteed, that after calling this function `source` and `target` can be used independently.

#### Data Races

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

### `void detach(holder);`

Makes an object independent from other objects.

#### Parameters

`holder` | The Holder to detach.

#### Remarks

After this function, `holder` does not depends from any other entity outside of `holder`, like a source or a host, and dependent(holer) returns `false`

#### Data Races

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

### `bool empty(holder);`

Test a Holder for being empty.

#### Parameters

`holder` | A Holder.

#### Returns

`bool` | `true` if `holder` contains no elements, otherwise `false`.

#### Remarks

`empty(x)` is guaranteed to be at least as fast as `length(me) == 0`, but can be significantly faster in some cases.

#### Data Races

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

#### See Also

- emptyHost

### `TGetValue getValue(holder);`

Return the get-value of the holder.

#### Parameters

`holder` | The Holder to query for its get-value type.

#### Returns

`TGetValue` | The get-value of the Holder.

#### Data Races

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

### `void moveValue(holder, value);`

Move a value of into a holder.

#### Parameters

`holder` | The Holder to manipulate.
`value` | The value to move into `holder`.

#### Data Races

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

### `void setValue(holder, object);`

Makes holder dependent.

#### Parameters

`holder` | A holder object. Types: Holder
`object` | Object from which `holder` will be dependent.

After this operation, `holder` will be dependent in state 'dependent'.

#### Data Races

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

### `TReference value(holder);`

Return a reference to the value of the holder.

#### Parameters

`holder` | The Holder to query for its reference.

#### Returns

`TReference` | The reference of the Holder's value.

#### Data Races

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

## Interface Metafunctions Detail

### `GetValue<THolder>::Type;`

Return get-value type of Holder.

#### Template Parameters

`THolder` | The Holder to query for its value type.

#### Returns

`Type` | The get-value type for its holder.

### `Reference<THolder>::Type;`

Return the reference type of a Holder.

#### Template Parameters

`THolder` | The holder to query for its reference type.

#### Returns

`Type` | The resulting reference type.

### `Spec<THolder>::Type;`

Return the specialization tag for a Holder.

#### Template Parameters

`THolder` | The Holder to query for its value type.

#### Returns

`Type` | The resulting specialization tag.

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

Return value type of Holder.

#### Template Parameters

`THolder` | The Holder to query for its value type.

#### Returns

`Type` | The value type for its holder.

#### Dox Sources

    /*!
     * @class Holder
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Manages relationship to another object.
     *
     * @signature template <typename TValue[, typename TSpec> class Holder;
     *
     * @tparam TSpec The specializing type. Default: <tt>Tristate</tt>
     * @tparam TValue Type of the managed object.
     *
     * @section Remarks
     *
     * The main purpose of this class is to facilitate the handling of member
     * objects. If we want class <tt>A</tt> to be dependent on or the owner of
     * another object of class <tt>B</tt>, then we add a data member of type
     * <tt>Holder&lt;B&gt;</tt> to <tt>A</tt>. <tt>Holder</tt> offers some useful
     * access functions and stores the kind of relationship between <tt>A</tt> and
     * <tt>B</tt>.
     *
     * @see Holder#create
     * @see Holder#setValue
     *
     * @mfn Holder#GetValue
     *
     * @brief Return get-value type of Holder.
     *
     * @signature GetValue<THolder>::Type;
     *
     * @tparam THolder The Holder to query for its value type.
     *
     * @return Type The get-value type for its holder.
     *
     * @mfn Holder#Value
     *
     * @brief Return value type of Holder.
     *
     * @signature Value<THolder>::Type;
     *
     * @tparam THolder The Holder to query for its value type.
     *
     * @return Type The value type for its holder.
     *
     * @mfn Holder#Spec
     *
     * @brief Return the specialization tag for a Holder.
     *
     * @signature Spec<THolder>::Type;
     *
     * @tparam THolder The Holder to query for its value type.
     *
     * @return Type The resulting specialization tag.
     *
     * @mfn Holder#Reference
     *
     * @brief Return the reference type of a Holder.
     *
     * @signature Reference<THolder>::Type;
     *
     * @tparam THolder The holder to query for its reference type.
     *
     * @return Type The resulting reference type.
     *
     * @fn Holder#create
     *
     * @brief Makes an object to owner of its content.
     *
     * @signature void create(holder[, object]);
     *
     * @param[in,out] holder The Holder to create the object of.
     * @param[in] object Object from which a copy is made and stored in
     *                   <tt>holder</tt>.
     *
     * After this operation, <tt>holder</tt> will be in state 'owner'. If
     * <tt>object</tt> is specified, <tt>holder</tt> will hold a copy of
     * <tt>object</tt> at the end of this function. If <tt>object</tt> is not
     * specified, the action depends on the former state of <tt>holder</tt>:
     *
     * <ul> <li>If the state of <tt>holder</tt> was 'empty', a new object is default
     * constructed and stored into <tt>holder</tt>.</li> <li>If the state of
     * <tt>holder</tt> was 'dependent', a copy of the former object is made and
     * stored into <tt>holder</tt>.</li> <li>If the state of <tt>holder</tt> was
     * already 'owner', nothing happens.</li> </ul>
     *
     * It is guaranteed, that after calling this function <tt>source</tt> and
     * <tt>target</tt> can be used independently.
     *
     * @fn Holder#detach
     *
     * @brief Makes an object independent from other objects.
     *
     * @signature void detach(holder);
     *
     * @param[in,out] holder The Holder to detach.
     *
     * @section Remarks
     *
     * After this function, <tt>holder</tt> does not depends from any other entity
     * outside of <tt>holder</tt>, like a source or a host, and dependent(holer)
     * returns <tt>false</tt>
     *
     * @fn Holder#setValue
     *
     * @brief Makes holder dependent.
     *
     * @signature void setValue(holder, object);
     *
     * @param[in,out] holder A holder object. Types: Holder
     * @param[in] object Object from which <tt>holder</tt> will be dependent.
     *
     * After this operation, <tt>holder</tt> will be dependent in state 'dependent'.
     *
     * @fn Holder#empty
     *
     * @brief Test a Holder for being empty.
     *
     * @signature bool empty(holder);
     *
     * @param[in] holder A Holder.
     *
     * @return bool <tt>true</tt> if <tt>holder</tt> contains no elements, otherwise
     *              <tt>false</tt>.
     *
     * @section Remarks
     *
     * <tt>empty(x)</tt> is guaranteed to be at least as fast as <tt>length(me) ==
     * 0</tt>, but can be significantly faster in some cases.
     *
     * @see HostedConcept#emptyHost
     *
     * @fn Holder#assignValue
     *
     * @headerfile <seqan/basic.h>
     * @headerfile <seqan/sequence.h>
     *
     * @brief Assigns value to item.
     *
     * @signature void assignValue(object, value);
     *
     * @param[in,out] object An object that holds a value or points to a value.
     *                       Types: Holder, Iter Concepts:
     *                       Concept.BasicOutputIteratorConcept
     * @param[in] value A value that is assigned to the item <tt>object</tt> holds
     *                  or points to.
     *
     * This function is similar to @link AssignableConcept#assign @endlink. The
     * difference is, that <tt>assignValue</tt> just changes a value stored in
     * <tt>object</tt> or the value <tt>object</tt> points to, while @link
     * AssignableConcept#assign @endlink changes the whole object.
     *
     * If <tt>object</tt> is a container (that is <tt>pos</tt> is not specified),
     * the whole content of <tt>object</tt> is replaced by <tt>value</tt>.
     *
     * If <tt>value</tt> is not used again after calling this function, then
     * consider to use @link Holder#moveValue @endlink that could be faster in some
     * cases instead.
     *
     * @see AssignableConcept#assign
     * @see Holder#moveValue
     *
     * @fn Holder#clear
     *
     * @brief Clear/destruct the Holder's value.
     *
     * @signature void clear(holder);
     *
     * @param[in,out] holder The Holder to clear.
     *
     * @fn Holder#value
     *
     * @brief Return a reference to the value of the holder.
     *
     * @signature TReference value(holder);
     *
     * @param[in] holder The Holder to query for its reference.
     *
     * @return TReference The reference of the Holder's value.
     *
     * @fn Holder#moveValue
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Move a value of into a holder.
     *
     * @signature void moveValue(holder, value);
     *
     * @param[in,out] holder The Holder to manipulate.
     * @param[in,out] value The value to move into <tt>holder</tt>.
     *
     * @fn Holder#getValue
     *
     * @brief Return the get-value of the holder.
     *
     * @signature TGetValue getValue(holder);
     *
     * @param[in] holder The Holder to query for its get-value type.
     *
     * @return TGetValue The get-value of the Holder.
     */