valuedescriptor.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_containers of the \aliblong.
///
/// Copyright 2013-2026 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib::containers {
 
/// Implements template type \p{TValueDescriptor}, which is, for example, offered by types
/// #"HashTable" and #"LRUCacheTable".
///
/// Specifically, this implementation is used when the custom type to be stored with a container
/// should be associated to a \p{TKkey}-type, which is not included in the stored type itself.
/// Consequently, to associate custom type \p{TMapped} with the key, the #".StoredType"
/// results in <c>std::pair<TKey,TMapped</c>.
///
/// Type definitions #"containers::HashMap" and #"containers::LRUCacheMap"
/// establish a shortcut to their corresponding base type, which incorporates this helper.
/// @tparam TKey    The key type.
/// @tparam TMapped The type of the mapped objects.
template<typename TKey, typename TMapped>
struct TPairDescriptor {
    /// The type stored in the container.<br>
    /// Container types typically publish an alias to this type.
    /// For example, see #"LRUCacheTable::StoredType", or
    /// see #"HashTable::StoredType".
    using StoredType    = std::pair<TKey, TMapped>;
 
    /// The key type. (Exposes template parameter \p{TKey}).<br>
    /// Container types typically publish an alias to this type.
    /// For example, see #"LRUCacheTable::KeyType", or
    /// see #"HashTable::KeyType".
    using KeyType       = TKey;
 
    /// The type associated to a key. (Exposes template parameter \p{TMapped}).
    /// The type of the mapped portion of the data.<br>
    /// Container types typically publish an alias to this type.
    /// For example, see #"LRUCacheTable::MappedType", or
    /// see #"HashTable::MappedType".
    using MappedType    = TMapped;
 
    /// Returns the first element of the given <c>std::pair</c>.
    /// @param src The value to extract from.
    /// @return The key-portion of the given value.
    TKey&       Key(std::pair<TKey, TMapped>& src)                       const { return src.first; }
 
    /// Returns the second element of the given <c>std::pair</c>.
    /// @param src The value to extract from.
    /// @return The mapped-portion of the given value.
    TMapped&    Mapped(std::pair<TKey, TMapped>& src)                   const { return src.second; }
};
 
/// Implements template type \p{TValueDescriptor}, which is, for example, offered by types
/// #"HashTable" and #"LRUCacheTable".
///
/// Specifically, this implementation is used with "sets", hence cases where the full portion
/// of a type that is to be stored in a container should serve as the key to itself.
///
/// Type definitions #"containers::HashSet" and #"containers::LRUCacheSet"
/// establish a shortcut to their corresponding base type, which incorporates this helper.
///
/// @tparam T   The type stored in the container, serving likewise as the key-type.
template<typename T>
struct TIdentDescriptor {
    /// The type stored in the container.<br>
    /// Container types typically publish an alias to this type.
    /// For example, see #"LRUCacheTable::StoredType", or
    /// see #"HashTable::StoredType".
    using StoredType    = T;
 
    /// Exposes template parameter \p{T} and thus equals #".StoredType" and
    /// #".MappedType".<br>
    /// Container types typically publish an alias to this type.
    /// For example, see #"LRUCacheTable::KeyType", or
    /// see #"HashTable::KeyType".
    using KeyType       = T;
 
    /// Exposes template parameter \p{T} and thus equals #".StoredType" and
    /// #".KeyType".<br>
    /// Container types typically publish an alias to this type.
    /// For example, see #"LRUCacheTable::MappedType", or
    /// see #"HashTable::MappedType".
    using MappedType    = T;
 
    /// Returns the given \p{src} as is.
    /// @param src The value to extract from.
    /// @return The given reference.
    KeyType&        Key   (T& src)                                             const { return src; }
 
    /// Returns the given \p{src} as is.
    /// @param src The value to extract from.
    /// @return The given reference.
    MappedType&     Mapped(T& src)                                             const { return src; }
};
 
 
/// Implements template type \p{TValueDescriptor}, which is, for example, offered by types
/// #"HashTable" and #"LRUCacheTable".
///
/// Specifically, this implementation causes a container neither to add a specific key-type to
/// every stored custom object nor to expect instances of a custom object as the key-type itself.
/// Instead, only a subset of the custom type is used as the key-type.
/// @tparam T    The type stored in the container.
/// @tparam TKey The key type which is to be extracted out of \p{T} by the method #".Key".
template<typename T, typename TKey>
struct TSubsetKeyDescriptor {
    /// Exposes template parameter \p{T}.<br>
    /// Container types typically publish an alias to this type.
    /// For example, see #"LRUCacheTable::StoredType", or
    /// see #"HashTable::StoredType".
    using StoredType    = T;
 
    /// Exposes template parameter \p{TKey}.<br>
    /// Container types typically publish an alias to this type.
    /// For example, see #"LRUCacheTable::KeyType", or
    /// see #"HashTable::KeyType".
    using KeyType       = TKey;
 
    /// Exposes template parameter \p{T} and thus equals #".StoredType".<br>
    /// Container types typically publish an alias to this type.
    /// For example, see #"LRUCacheTable::MappedType", or
    /// see #"HashTable::MappedType".
    using MappedType    = T;
 
    /// A custom implementation has to return the key-portion of given \p{src}.
    /// \attention This method is just declared. A type-specific implementation has to be
    ///            provided by the using code!
    /// @param src The stored value to extract the key from.
    /// @return The given reference.
    KeyType&        Key   (T& src);
 
    /// Returns the given \p{src} as is.
    /// @param src The stored value to extract the mapped portion from.
    /// @return The given reference.
    MappedType&     Mapped(T& src)                                             const { return src; }
};
 
} // namespace [alib::containers]