/*!
* @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<B></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.
*/