/*!
* @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<TNameStore>::Type</tt>.
*
* NameStore objects store a binary search tree (using
* <tt>std::map<></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.
*/