UnionFind - SeqAn API Documentation

# Class UnionFind
Union-Find data structure.

Defined in | <seqan/misc/union_find.h>
Signature | `template <typename T> class UnionFind;`

## Template Parameters

`T` | The integer type the data structure operates on.

## Interface Function Overview

- `void clear(uf);`
  Clear the Union-Find data structure.
- `TValue findSet(uf, q);`
  Return set identifier, given an element identifier.
- `void joinSets(uf, left, right);`
  UNION() operation for Union-Find data structure.
- `TSize length(uf);`
  Returns the number of entries in the Union-Find object.
- `TSize resize(uf, size, tag);`
  Allocate number of elements for the Union-Find object.
- `TSize resizeVertexMap(uf, g);`
  Resize Union-Find data structure to appropriate size for a vertex map.
- `void reserve(uf, size, tag);`
  Reserve memory for the Union-Find object.

## Interface Metafunction Overview

- `GetValue<TUnionFind>::Type`
  Returns the get-value type for the given UnionFind specialization.
- `Size<TUnionFind>::Type`
  Returns the size type for the given UnionFind specialization.
- `Value<TUnionFind>::Type`
  Returns the value type for the given UnionFind specialization.

## Detailed Description

The data structure uses union by rank and path compresison to achieve almost linear running time.

Note that internally T is used as signed, so not the whole range is available if T is unsigned.

## Interface Functions Detail

### `void clear(uf);`

Clear the Union-Find data structure.

#### Parameters

`uf` | The Union-Find object to clear

#### Data Races

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

### `TValue findSet(uf, q);`

Return set identifier, given an element identifier.

#### Parameters

`uf` | The Union-Find object to query.
`q` | The value to get the set identifier for.

#### Returns

`TValue` | Identifier of the set that `q` is in (Metafunction: Value).

#### Data Races

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

#### See Also

- joinSets

### `void joinSets(uf, left, right);`

UNION() operation for Union-Find data structure.

#### Parameters

`uf` | The type the data structure operates on.
`left` | Representant of the left set to union.
`right` | Representant of the right set to union.

This function is called `join` and not `union` since `union` is a reserved keyword in the C and C++ programming languages.

Note that you most likely want to put return values of `findSet()` as the values for `left` and `right`.

#### Data Races

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

#### See Also

- findSet

### `TSize length(uf);`

Returns the number of entries in the Union-Find object.

#### Parameters

`uf` | The Union-Find object to query.

#### Returns

`TSize` | The length of the Union-Find object (Metafunction: Size).

#### Data Races

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

### `TSize resize(uf, size, tag);`

Allocate number of elements for the Union-Find object.

#### Parameters

`uf` | The Union-Find object to resize.
`size` | The number of elements to reserve.
`tag` | The tag to use for reserving (defaults to `Generous()`).

#### Returns

`TSize` | The new length of the Union-Find object (Metafunction: Size).

The UF dat structure is resized to the given `size`, the value for each element is set to -1, i.e. they are singletons by default.

#### Data Races

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

### `TSize resizeVertexMap(uf, g);`

Resize Union-Find data structure to appropriate size for a vertex map.

#### Parameters

`uf` | The Union-Find object to resize.
`g` | The graph to use for getting an upper bound on the maximum used vertex ID, which determines the size.

#### Returns

`TSize` | New size of the vertex map (Metafunction: Size).

#### Data Races

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

### `void reserve(uf, size, tag);`

Reserve memory for the Union-Find object.

#### Parameters

`uf` | The Union-Find object to reserve memory in.
`size` | The number of elements to reserve.
`tag` | The tag to use for reserving (defaults to `Generous()`).

#### Data Races

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

## Interface Metafunctions Detail

### `GetValue<TUnionFind>::Type`

Returns the get-value type for the given UnionFind specialization.

#### Template Parameters

`TUnionFind` | The UnionFind specialization to query for its get-value type.

### `Size<TUnionFind>::Type`

Returns the size type for the given UnionFind specialization.

#### Template Parameters

`TUnionFind` | The UnionFind specialization to query for its size type.

### `Value<TUnionFind>::Type`

Returns the value type for the given UnionFind specialization.

#### Template Parameters

`TUnionFind` | The UnionFind specialization to query for its value type.

#### Dox Sources

    /*!
     * @class UnionFind
     *
     * @headerfile <seqan/misc/union_find.h>
     *
     * @brief Union-Find data structure.
     *
     * @signature template <typename T> class UnionFind;
     *
     * @tparam T The integer type the data structure operates on.
     *
     * The data structure uses union by rank and path compresison to achieve almost
     * linear running time.
     *
     * Note that internally T is used as signed, so not the whole range is available
     * if T is unsigned.
     *
     * @mfn UnionFind#Value
     *
     * @brief Returns the value type for the given UnionFind specialization.
     *
     * @signature Value<TUnionFind>::Type
     *
     * @tparam TUnionFind The UnionFind specialization to query for its value type.
     *
     * @mfn UnionFind#GetValue
     *
     * @brief Returns the get-value type for the given UnionFind specialization.
     *
     * @signature GetValue<TUnionFind>::Type
     *
     * @tparam TUnionFind The UnionFind specialization to query for its get-value
     *                    type.
     *
     * @mfn UnionFind#Size
     *
     * @brief Returns the size type for the given UnionFind specialization.
     *
     * @signature Size<TUnionFind>::Type
     *
     * @tparam TUnionFind The UnionFind specialization to query for its size type.
     *
     * @fn UnionFind#clear
     *
     * @brief Clear the Union-Find data structure.
     *
     * @signature void clear(uf);
     *
     * @param[in,out] uf The Union-Find object to clear
     *
     * @fn UnionFind#length
     *
     * @brief Returns the number of entries in the Union-Find object.
     *
     * @signature TSize length(uf);
     *
     * @param[in] uf The Union-Find object to query.
     *
     * @return TSize The length of the Union-Find object (Metafunction: @link
     *               UnionFind#Size @endlink).
     *
     * @fn UnionFind#reverse
     *
     * @brief Reserve memory for the Union-Find object.
     *
     * @signature void reserve(uf, size, tag);
     *
     * @param[in,out] uf The Union-Find object to reserve memory in.
     * @param[in] size The number of elements to reserve.
     * @param[in] tag The tag to use for reserving (defaults to
     *                <tt>Generous()</tt>).
     *
     * @fn UnionFind#resize
     *
     * @brief Allocate number of elements for the Union-Find object.
     *
     * @signature TSize resize(uf, size, tag);
     *
     * @param[in,out] uf The Union-Find object to resize.
     * @param[in] size The number of elements to reserve.
     * @param[in] tag The tag to use for reserving (defaults to
     *                <tt>Generous()</tt>).
     *
     * @return TSize The new length of the Union-Find object (Metafunction: @link
     *               UnionFind#Size @endlink).
     *
     * The UF dat structure is resized to the given <tt>size</tt>, the value for
     * each element is set to -1, i.e. they are singletons by default.
     *
     * @fn UnionFind#resizeVertexMap
     *
     * @brief Resize Union-Find data structure to appropriate size for a vertex map.
     *
     * @signature TSize resizeVertexMap(uf, g);
     *
     * @param[in,out] uf The Union-Find object to resize.
     * @param[in] g The graph to use for getting an upper bound on the maximum used
     *              vertex ID, which determines the size.
     *
     * @return TSize New size of the vertex map (Metafunction: @link UnionFind#Size
     *               @endlink).
     *
     * @fn UnionFind#findSet
     *
     * @brief Return set identifier, given an element identifier.
     *
     * @signature TValue findSet(uf, q);
     *
     * @param[in] uf The Union-Find object to query.
     * @param[in] q The value to get the set identifier for.
     *
     * @return TValue Identifier of the set that <tt>q</tt> is in (Metafunction:
     *                @link UnionFind#Value @endlink).
     *
     * @see UnionFind#joinSets
     *
     * @fn UnionFind#joinSets
     *
     * @brief UNION() operation for Union-Find data structure.
     *
     * @signature void joinSets(uf, left, right);
     *
     * @param[in,out] uf The type the data structure operates on.
     * @param[in] left Representant of the left set to union.
     * @param[in] right Representant of the right set to union.
     *
     * This function is called <tt>join</tt> and not <tt>union</tt> since
     * <tt>union</tt> is a reserved keyword in the C and C++ programming languages.
     *
     * Note that you most likely want to put return values of <tt>findSet()</tt> as
     * the values for <tt>left</tt> and <tt>right</tt>.
     *
     * @see UnionFind#findSet
     */