NameStoreCache - SeqAn API Documentation

# Class NameStoreCache
Fast mapping from string names to numeric ids.

Defined in | <seqan/misc/name_store_cache.h>
Signature | `template <typename TNameStore[, typename TName]> class NameStoreCache;`

## Template Parameters

`TNameStore` | The type to use for the name store. Usually a StringSet of CharString.
`TName` | The type to use for the names, defaults to `Value<TNameStore>::Type`.

## Member Function Overview

- `NameStoreCache::NameStoreCache();, NameStoreCache::NameStoreCache(other);, NameStoreCache::NameStoreCache(nameStore);`
  Constructors.

## Interface Function Overview

- `void appendName(cache, name);`
  Append a name to a name store and register it in the cache.
- `void clear(cache);`
  Reset the NameStoreCache (not the name store).
- `bool empty(cache);`
  Query whether there are any entries in the cache (not the name store).
- `bool getIdByName(idx, cache, name);`
  Get id/index of a string in a name store using a NameStoreCache.
- `TPos nameToId(cache, name);`
  Translate a name to a numeric id, adding the name to the store and cache if new.
- `void refresh(cache);`
  Rebuild the name store cache.

## Detailed Description

NameStore objects store a binary search tree (using `std::map<>`) on a StringSet (the name store). They store a pointer to this name store but not the name store itself.

When adding values to the name store using appendName, the cache (i.e, the binary search tree) is automatically updated. When modifying the name store when not using appendName, you have to use refresh to update the cache after modifying and before querying.

The fast lookups can be performed using getIdByName and nameToId. The query function nameToId, the cache can also be modified (and thus updated).

### Example

The demo below shows how to initialize a NameStoreCache with an existing name store, lookup existing names, add new names, and add names during lookup.

    #include <iostream>

    #include <seqan/sequence.h>
    #include <seqan/misc/name_store_cache.h>

    using namespace seqan2;

    int main()
    {
        typedef StringSet<CharString>      TNameStore;
        typedef NameStoreCache<TNameStore> TNameStoreCache;

        // Used below.
        unsigned idx = 0;
        bool success = false;

        // Define the name store and cache.
        TNameStore      nameStore;

        // Append two names to the name store without the cache.
        appendValue(nameStore, "I");
        appendValue(nameStore, "II");

        // Construct the name store.  The name store knows about both "I" and "II".
        TNameStoreCache nameStoreCache(nameStore);
        success = getIdByName(idx, nameStoreCache, "I");
        std::cout << "lookup I   => success=" << success << ", idx=" << idx << "\n";
        success = getIdByName(idx, nameStoreCache, "II");
        std::cout << "lookup II  => success=" << success << ", idx=" << idx << "\n";

        // Append value through cache.
        appendName(nameStoreCache, "III");
        success = getIdByName(idx, nameStoreCache, "III");
        std::cout << "lookup III => success=" << success << ", idx=" << idx << "\n";

        // Append value and query at the same time.
        idx = nameToId(nameStoreCache, "IV");
        std::cout << "lookup IV  => idx=" << idx << ", length(nameStore)="
                  << length(nameStore) << "\n";

        return 0;
    }

Demo: demos/dox/misc/name_store_cache.cpp

Here is the output:

    lookup I   => success=1, idx=0
    lookup II  => success=1, idx=1
    lookup III => success=1, idx=2
    lookup IV  => idx=3, length(nameStore)=4

## Member Functions Detail

### `NameStoreCache::NameStoreCache(); NameStoreCache::NameStoreCache(other); NameStoreCache::NameStoreCache(nameStore);`

Constructors.

#### Parameters

`other` | The other NameStoreCache to copy from.
`nameStore` | A NameStore for which a pointer is stored.

NameStore cache offers the default constructor, copy constructor, and construction using an existing name store.

#### Data Races

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

## Interface Functions Detail

### `void appendName(cache, name);`

Append a name to a name store and register it in the cache.

#### Parameters

`cache` | The NameStoreCache to use for faster access.
`name` | The name to append to the store (Value of `TNameStore`).

The NameStoreCache only registers update to the name store when performed by this function.

#### Data Races

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

### `void clear(cache);`

Reset the NameStoreCache (not the name store).

#### Parameters

`cache` | The NameStoreCache to clear.

#### Data Races

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

### `bool empty(cache);`

Query whether there are any entries in the cache (not the name store).

#### Parameters

`cache` | The NameStoreCache to clear.

#### Returns

`bool` | `true` if the NameStoreCache is empty.

#### Data Races

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

### `bool getIdByName(idx, cache, name);`

Get id/index of a string in a name store using a NameStoreCache.

#### Parameters

`idx` | The variable to store the index in the store of (IntegerConcept).
`cache` | The NameStoreCache to use for speeding up the lookup.
`name` | The name to search in the name store (Value of `TNameStore`).

#### Returns

`bool` | `true` if the name could be found and `false` otherwise.

#### Data Races

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

### `TPos nameToId(cache, name);`

Note.

Since `cache` is modified if `name` is not known in cache, it is a non-const parameter for this function.

Translate a name to a numeric id, adding the name to the store and cache if new.

#### Parameters

`cache` | The NameStoreCache use for translating the name to a numeric id.
`name` | The name to add (Value of `TNameStore`).

#### Returns

`TPos` | The numeric id of the name in the store and cache (Position of `TNameStore`).

If `name` is in `cache` then its numeric position/index/id in the name store is returned. If it is not in the name store then it is appended to the name store and registered with the NameStoreCache.

#### Data Races

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

### `void refresh(cache);`

Rebuild the name store cache.

#### Parameters

`nameStore` | The NameStoreCache to rebuild.

Use this after modifying the underlying NameStore before querying.

#### Data Races

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

#### Dox Sources

    /*!
     * @class NameStoreCache
     *
     * @headerfile <seqan/misc/name_store_cache.h>
     *
     * @brief Fast mapping from string names to numeric ids.
     *
     * @signature template <typename TNameStore[, typename TName]> class
     *            NameStoreCache;
     *
     * @tparam TNameStore The type to use for the name store. Usually a @link
     *                    StringSet @endlink of @link CharString @endlink.
     * @tparam TName The type to use for the names, defaults to
     *               <tt>Value&lt;TNameStore&gt;::Type</tt>.
     *
     * NameStore objects store a binary search tree (using
     * <tt>std::map&lt;&gt;</tt>) on a @link StringSet @endlink (the name store).
     * They store a pointer to this name store but not the name store itself.
     *
     * When adding values to the name store using @link NameStoreCache#appendName
     * @endlink, the cache (i.e, the binary search tree) is automatically updated.
     * When modifying the name store when not using @link NameStoreCache#appendName
     * @endlink, you have to use @link NameStoreCache#refresh @endlink to update the
     * cache after modifying and before querying.
     *
     * The fast lookups can be performed using @link NameStoreCache#getIdByName
     * @endlink and @link NameStoreCache#nameToId @endlink. The query function @link
     * NameStoreCache#nameToId @endlink, the cache can also be modified (and thus
     * updated).
     *
     * @section Example
     *
     * The demo below shows how to initialize a NameStoreCache with an existing name
     * store, lookup existing names, add new names, and add names during lookup.
     *
     * @include demos/dox/misc/name_store_cache.cpp
     *
     * Here is the output:
     *
     * @include demos/dox/misc/name_store_cache.cpp.stdout
     *
     *
     *
     * @fn NameStoreCache::NameStoreCache
     *
     * @brief Constructors.
     *
     * @signature NameStoreCache::NameStoreCache();
     * @signature NameStoreCache::NameStoreCache(other);
     * @signature NameStoreCache::NameStoreCache(nameStore);
     *
     * @param[in] other The other NameStoreCache to copy from.
     * @param[in] nameStore A NameStore for which a pointer is stored.
     *
     * NameStore cache offers the default constructor, copy constructor, and
     * construction using an existing name store.
     *
     * @fn NameStoreCache#clear
     *
     * @brief Reset the NameStoreCache (not the name store).
     *
     * @signature void clear(cache);
     *
     * @param[in,out] cache The NameStoreCache to clear.
     *
     * @fn NameStoreCache#empty
     *
     * @brief Query whether there are any entries in the cache (not the name store).
     *
     * @signature bool empty(cache);
     *
     * @param[in,out] cache The NameStoreCache to clear.
     *
     * @return bool <tt>true</tt> if the NameStoreCache is empty.
     *
     * @fn NameStoreCache#refresh
     *
     * @brief Rebuild the name store cache.
     *
     * @signature void refresh(cache);
     *
     * @param[in,out] nameStore The NameStoreCache to rebuild.
     *
     * Use this after modifying the underlying NameStore before querying.
     *
     * @fn NameStoreCache#appendName
     *
     * @brief Append a name to a name store and register it in the cache.
     *
     * @signature void appendName(cache, name);
     *
     * @param[in,out] cache The NameStoreCache to use for faster access.
     * @param[in] name The name to append to the store (@link ContainerConcept#Value
     *                 @endlink of <tt>TNameStore</tt>).
     *
     * The NameStoreCache only registers update to the name store when performed by
     * this function.
     *
     * @fn NameStoreCache#getIdByName
     *
     * @brief Get id/index of a string in a name store using a NameStoreCache.
     *
     * @signature bool getIdByName(idx, cache, name);
     *
     * @param[out] idx The variable to store the index in the store of (@link
     *                 IntegerConcept @endlink).
     * @param[in] cache The NameStoreCache to use for speeding up the lookup.
     * @param[in] name The name to search in the name store (@link
     *                 ContainerConcept#Value @endlink of <tt>TNameStore</tt>).
     *
     * @return bool <tt>true</tt> if the name could be found and <tt>false</tt>
     *              otherwise.
     *
     * @fn NameStoreCache#nameToId
     *
     * @brief Translate a name to a numeric id, adding the name to the store and
     *        cache if new.
     *
     * @note Since <tt>cache</tt> is modified if <tt>name</tt> is not known in
     *       cache, it is a <b>non-const</b> parameter for this function.
     *
     * @signature TPos nameToId(cache, name);
     *
     * @param[in,out] cache The NameStoreCache use for translating the name to a
     *                      numeric id.
     * @param[in] name The name to add (@link ContainerConcept#Value @endlink of
     *                 <tt>TNameStore</tt>).
     *
     * @return TPos The numeric id of the name in the store and cache (@link
     *              ContainerConcept#Position Position @endlink of
     *              <tt>TNameStore</tt>).
     *
     * If <tt>name</tt> is in <tt>cache</tt> then its numeric position/index/id in
     * the name store is returned. If it is not in the name store then it is
     * appended to the name store and registered with the NameStoreCache.
     */