bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware > Class Template Reference

An associative container with contiguous, predictable storage. More...

#include <bio/ranges/container/dictionary.hpp>

Inheritance diagram for bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >:

Public Types
Associated types
using	mapped_ref_t = std::conditional_t< mapped_t_is_context_aware, mapped_t const &, mapped_t & >
	Usually mapped_t &.
using	value_type = std::tuple< key_t, mapped_t >
	The value_type type.
using	reference = std::tuple< key_t const &, mapped_ref_t >
	The reference type.
using	const_reference = std::tuple< key_t const &, mapped_t const & >
	The const_reference type.
using	difference_type = ptrdiff_t
	The difference_type type.
using	size_type = size_t
	The size_type type.
using	const_iterator = detail::random_access_iterator< dictionary const >
	The const_iterator type.
using	iterator = std::conditional_t< mapped_t_is_context_aware, const_iterator, detail::random_access_iterator< dictionary > >

Public Member Functions
Constructors, destructor and assignment
	dictionary ()=default
	Defaulted.
	dictionary (dictionary const &)=default
	Defaulted.
	dictionary (dictionary &&) noexcept=default
	Defaulted.
dictionary &	operator= (dictionary const &)=default
	Defaulted.
dictionary &	operator= (dictionary &&) noexcept=default
	Defaulted.
	~dictionary ()=default
	Defaulted.
template<typename... value_type_> requires ((std::convertible_to<value_type_, value_type> && ...) && sizeof...(value_type_) > 0)
	dictionary (value_type_ &&... args)
	Construct from a list of values of value_type.
template<meta::different_from< iterator > begin_it_type, typename end_it_type > requires (meta::different_from<const_iterator, begin_it_type> && std::forward_iterator<begin_it_type> && std::sentinel_for<end_it_type, begin_it_type> && std::convertible_to<std::iter_reference_t<begin_it_type>, value_type>)
	dictionary (begin_it_type const begin_it, end_it_type const end_it)
	Construct from two iterators.
	dictionary (iterator const begin_it, iterator const end_it)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
	dictionary (const_iterator const begin_it, const_iterator const end_it)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<meta::different_from< dictionary > other_range_t> requires (std::ranges::input_range<other_range_t>)
	dictionary (other_range_t &&range)
	Construct from a different range.
template<typename... value_type_> requires ((meta::different_from<dictionary, value_type_> && ...) && (meta::different_from<iterator, value_type_> && ...) && (meta::different_from<const_iterator, value_type_> && ...) && (std::convertible_to<value_type_, value_type> && ...) && (sizeof...(value_type_) > 0))
void	assign (value_type_ &&... args)
	Assign from multiple elements.
template<std::ranges::input_range other_range_t> requires std::convertible_to<std::ranges::range_reference_t<other_range_t>, value_type>
void	assign (other_range_t &&range)
	Assign from a different range.
template<meta::different_from< iterator > begin_it_type, typename end_it_type > requires (meta::different_from<const_iterator, begin_it_type> && std::forward_iterator<begin_it_type> && std::sentinel_for<end_it_type, begin_it_type> && std::convertible_to<std::iter_reference_t<begin_it_type>, value_type>)
void	assign (begin_it_type begin_it, end_it_type end_it)
	Assign from pair of iterators.
void	assign (iterator begin_it, iterator end_it)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void	assign (const_iterator begin_it, const_iterator end_it)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Iterators
iterator	begin () noexcept
	Returns the begin iterator.
const_iterator	begin () const noexcept
	Returns the begin iterator.
const_iterator	cbegin () const noexcept
	Returns the begin iterator.
iterator	end () noexcept
	Returns iterator past the end.
const_iterator	end () const noexcept
	Returns iterator past the end.
const_iterator	cend () const noexcept
	Returns iterator past the end.
Element access
reference	at (size_type const i)
	Return the i-th element.
const_reference	at (size_type const i) const
	Return the i-th element.
reference	operator[] (size_type const i) noexcept
	Return the i-th element.
const_reference	operator[] (size_type const i) const noexcept
	Return the i-th element.
reference	front () noexcept
	Return the first element. Calling front on an empty container is undefined.
const_reference	front () const noexcept
	Return the first element. Calling front on an empty container is undefined.
reference	back () noexcept
	Return the last element.
const_reference	back () const noexcept
	Return the last element.
Capacity
bool	empty () const noexcept
	Checks whether the container is empty.
size_type	size () const noexcept
	Returns the number of elements in the container.
size_type	max_size () const noexcept
	Returns the maximum number of elements the container is able to hold.
size_type	capacity () const noexcept
	Returns the number of elements that the container is able to hold without reallocating (see below).
void	reserve (size_type const new_cap)
	Reserve storage in the underlying data types to accomodate for future inserts.
void	shrink_to_fit ()
	Reduce capacity to current size() to free unused memory.
Modifiers
void	clear () noexcept
	Removes all elements from the container.
template<std::convertible_to< value_type > value_type_ = value_type>
void	push_back (value_type_ &&value)
	Appends the given element value to the end of the container.
void	emplace_back (auto &&... args)
	Constructs an element in-place at the end of the container.
void	pop_back ()
	Removes the last element of the container.
value_type	extract_back ()
	Removes and returns the last element of the container.

Friends
Comparison operators
bool	operator== (dictionary const &lhs, dictionary const &rhs) noexcept
	Performs element-wise comparison.
bool	operator<=> (dictionary const &lhs, dictionary const &rhs) noexcept
	Performs element-wise comparison.

Key-based element access
using	het_key_t = key_t const &
	Type used for key-based access.
bool	contains (het_key_t key) const
	Check whether the container has an element with the given key.
size_t	count (het_key_t key) const
	The number of elements in the container with the specified key.
iterator	find (het_key_t key)
	Find an element with the given key.
const_iterator	find (het_key_t key) const
	Find an element with the given key.
mapped_ref_t	at (het_key_t key)
	Access element by key.
mapped_t const &	at (het_key_t key) const
	Access element by key.
mapped_ref_t	operator[] (het_key_t key)
	Access element by key.
mapped_t const &	operator[] (het_key_t key) const
	Access element by key.

Key-based element access (context-aware)
template<small_string key> requires (requires(dictionary d) { get<key>(d); })
decltype(auto)	at (meta::vtag_t< key > key_tag)
	Access element by compile-time string and implicitly call get() on it.
template<small_string key> requires (requires(dictionary const d) { get<key>(d); })
decltype(auto)	at (meta::vtag_t< key > key_tag) const
	Access element by compile-time string and implicitly call get() on it.
template<small_string key> requires (requires(dictionary d) { get<key>(d); })
decltype(auto)	operator[] (meta::vtag_t< key > key_tag)
	Access element by compile-time string and implicitly call get() on it.
template<small_string key> requires (requires(dictionary const d) { get<key>(d); })
decltype(auto)	operator[] (meta::vtag_t< key > key_tag) const
	Access element by compile-time string and implicitly call get() on it.
template<small_string key> requires (mapped_t_is_context_aware && requires { get<key>(get<1>(dict.storage[0])); })
decltype(auto)	get (meta::decays_to< dictionary > auto &&dict)
	Access element by compile-time string and implicitly call get() on it.

Detailed Description

template<typename key_t, typename mapped_t, bool mapped_t_is_context_aware = false>
class bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >

An associative container with contiguous, predictable storage.

Template Parameters

key_t	The key type; must be convertible to std::string_view (e.g. also std::string).
mapped_t	The mapped type; must be an object type.
mapped_t_is_context_aware	See below.

This container behaves like a mixture of std::vector and std::unordered_map.

It has the following properties:

• The element type is std::tuple<key_t, mapped_t>, but the reference type is std::tuple<key_t const &, mapped_t &>.
• Contiguous storage of elements in the same order they are inserted.
• O(1) access to elements via operator[size_t] and ~O(1) push_back (like std::vector).
• ~O(1) access to mapped value via the key (like std::unordered_map).
• The size overhead compared to std::vector: every key stored twice + at least one uint64_t per element.
• The key_type must be convertible to std::string_view, and every key must be unique.
• There is no insert() member, only assign() and push_back() to add elements.
• There is no erase() member, only clear() and pop_back() to remove elements.
• There is no resize() member, but there is a reserve() member.

This data structure is used in several places where the order of elements must be preserved but fast random access by key is still desirable. It usually makes sense when the key-string is short (less than 16 characters), the value_type is large, and the data structure does not need many changes after construction.

Element access

The element type (value_type) of the dictionary is std::tuple<key_t, mapped_t>. Most functions that provide access to the elements, return std::tuple<key_t const &, mapped_t &> (and not std::tuple<key_t &, mapped_t &> or std::tuple<key_t, mapped_t> &). This prevents changes to the key of an element (which would break the container).

Functions that access an element by key, return a reference to the mapped value instead (like for std::unordered_map).

#include <bio/ranges/container/dictionary.hpp>
 
int main()
{
    bio::ranges::dictionary<std::string, std::string> employee_status;
 
    /* add some elements */
    employee_status.emplace_back("Bob", "hired");
    employee_status.emplace_back("Jane", "hired");
    employee_status.emplace_back("Marc", "fired");
    employee_status.emplace_back("Maria", "promoted");
 
    /* Access by position in dictionary; same as insert-order */
    auto && first = employee_status[0];         // a tuple of key and mapped_value
    fmt::print("{}\n", first);                  // prints '("Bob", "hired")'
    //get<0>(first) = "Rob";                    // key cannot be changed
    get<1>(first) = "tired";                    // mapped_value can be changed
    fmt::print("{}\n", employee_status[0]);     // prints '("Bob", "tired")'
 
    /* Access by key */
    auto && jane = employee_status["Jane"];     // the mapped_value belonging to Jane
    fmt::print("{}\n", jane);                   // prints 'hired'
    jane = "wired";                             // can be changed
    fmt::print("{}\n", employee_status["Jane"]);// prints 'wired'
 
    /* No implicit inserts like std::unordered_map */
    //employee_status["Shane"] = "hired";       // DOES NOT WORK.
}

Context-aware mapped value types

If the template parameter mapped_t_is_context_aware is set to true, the reference type of the dictionary becomes std::tuple<key_t const &, mapped_t const &>, i.e. the mapped value in dictionary elements cannot be changed via regular element access.

Additionally, given an object o of type mapped_t, if get<"foo">(o) is valid, this container provides a special interface:

• A get<"foo">(dict) friend function that calls get<"foo">(dict.at("foo")).
• The .at("foo"_vtag) and operator["foo"_vtag] member functions with identical semantics.
• These functions may or may not expose mutable references to the mapped value (or one of its members).

In combination with element types that are derived from std::variant (and additionally provide the aforementioned string-based get-interface), this can be used to create heterogeneous dictionaries, i.e. transparent access to mapped values of different types by string-IDs known at compile-time.

#include <array>
#include <variant>
 
#include <bio/meta/tag/vtag.hpp>
#include <bio/ranges/container/dictionary.hpp>
 
using namespace std::string_literals;
using namespace std::string_view_literals;
using namespace bio::meta::literals;
 
/* A type to hold an optional field in a SAM record.
 *
 * See https://samtools.github.io/hts-specs/SAMtags.pdf for how this is used.
 *
 * These optional fields can have data of different types, e.g. string and int (other types
 * are ignored for this simple example). The way to store this in C++ is a std::variant.
 *
 * Since the relationship between the identifier tag and the type is usually known,
 * we can provide a string-based get<>() interface.
 */
struct sam_optional_field : std::variant<std::string, int32_t>
{
    /* Declare the get<"foo">(obj) interface; overloads for cv-qualified versions omitted here. */
    template <bio::ranges::small_string tag>
    friend decltype(auto) get(sam_optional_field const & me)
    {
        static_assert(contains(as_strings, tag) || contains(as_ints, tag),
                      "Don't know how to choose type for given id.");
 
        if constexpr (contains(as_strings, tag))
        {
            return std::get<std::string>(me);
        }
        else /* is int */
        {
            return std::get<int32_t>(me);
        }
    }
 
private:
    /* Define which tags result in which types; only four example tags defined here. */
    static constexpr auto as_strings = std::array{"CO"sv, "OA"sv};
    static constexpr auto as_ints    = std::array{"AS"sv, "NM"sv};
 
    /* In C++23, you can use std::ranges::contains() instead. */
    static constexpr bool contains(auto const & arr, std::string_view const val)
    {
        return std::ranges::find(arr, val) != arr.end();
    }
};
 
int main()
{
    bio::ranges::dictionary<std::string, sam_optional_field, true> sam_optional_fields;
 
    /* You can easily insert elements of different types, but you need to make sure they match the predefined IDs! */
    sam_optional_fields.emplace_back("CO", "This is a comment.");
    sam_optional_fields.emplace_back("AS", 42);                    // Alignment score 42
    sam_optional_fields.emplace_back("NM", 23);                    // Edit distance 23
    sam_optional_fields.emplace_back("OA", "23M3I11M");            // Original cigar
 
    // std::string s = sam_optional_fields["CO"];   // ["CO"] returns sam_optional_field
    std::string s = sam_optional_fields["CO"_vtag]; // ["CO"_vtag] returns std::string (type "inside variant")
    fmt::print("{}\n", s);                          // prints "This is a comment."
 
    // int32_t i = sam_optional_fields["AS"];       // ["AS"] returns sam_optional_field
    int32_t i = sam_optional_fields["AS"_vtag];     // ["AS"_vtag] returns int (type "inside variant")
    fmt::print("{}\n", i);                          // prints "42"
}

Member Typedef Documentation

iterator

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

using bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::iterator = std::conditional_t<mapped_t_is_context_aware, const_iterator, detail::random_access_iterator<dictionary> >

The iterator type.

Constructor & Destructor Documentation

dictionary() [1/3]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

template<typename... value_type_>
requires ((std::convertible_to<value_type_, value_type> && ...) && sizeof...(value_type_) > 0)

bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::dictionary ( value_type_ &&...  args )

inlineexplicit

Construct from a list of values of value_type.

Template Parameters

value_type_

A parameter pack where each type is equal to value_type.

Parameters

[in]

args

The values to construct from.

Complexity

Linear in the number of elements.

Exceptions

Basic exception gurantee.

dictionary() [2/3]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

template<meta::different_from< iterator > begin_it_type, typename end_it_type >
requires (meta::different_from<const_iterator, begin_it_type> && std::forward_iterator<begin_it_type> && std::sentinel_for<end_it_type, begin_it_type> && std::convertible_to<std::iter_reference_t<begin_it_type>, value_type>)

bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::dictionary ( begin_it_type const  begin_it, end_it_type const  end_it  )

inline

Construct from two iterators.

Template Parameters

begin_it_type	Must model std::forward_iterator and value_type must be constructible from the reference type of begin_it_type.
end_it_type	Must satisfy std::sentinel_for.

Parameters

[in]	begin_it	Begin of range to construct/assign from.
[in]	end_it	End of range to construct/assign from.

Complexity

Linear in the distance between begin_it and end_it.

Exceptions

Basic exception gurantee.

dictionary() [3/3]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

template<meta::different_from< dictionary > other_range_t>
requires (std::ranges::input_range<other_range_t>)

bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::dictionary ( other_range_t &&  range )

inlineexplicit

Construct from a different range.

Template Parameters

other_range_t

The type of range to be inserted; must satisfy std::ranges::input_range and value_type must be constructible from std::ranges::range_reference_t<other_range_t>.

Parameters

[in]

range

The sequences to construct/assign from.

Complexity

Linear in the size of range.

Exceptions

Basic exception gurantee.

Member Function Documentation

assign() [1/3]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

template<meta::different_from< iterator > begin_it_type, typename end_it_type >
requires (meta::different_from<const_iterator, begin_it_type> && std::forward_iterator<begin_it_type> && std::sentinel_for<end_it_type, begin_it_type> && std::convertible_to<std::iter_reference_t<begin_it_type>, value_type>)

void bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::assign ( begin_it_type  begin_it, end_it_type  end_it  )

inline

Assign from pair of iterators.

Template Parameters

begin_it_type	Must satisfy std::forward_iterator and the value_type must be constructible from the reference type of begin_it_type.
end_it_type	Must satisfy std::sentinel_for.

Parameters

[in]	begin_it	Begin of range to construct/assign from.
[in]	end_it	End of range to construct/assign from.

Complexity

Linear in the distance between begin_it and end_it.

Exceptions

Basic exception gurantee.

assign() [2/3]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

template<std::ranges::input_range other_range_t>
requires std::convertible_to<std::ranges::range_reference_t<other_range_t>, value_type>

void bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::assign ( other_range_t &&  range )

inline

Assign from a different range.

Template Parameters

other_range_t

The type of range to be inserted; must satisfy std::ranges::input_range and value_type must be constructible from std::ranges::range_reference_t<other_range_t>.

Parameters

[in]

range

The sequences to construct/assign from.

Complexity

Linear in the size of range.

Exceptions

Basic exception gurantee.

assign() [3/3]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

template<typename... value_type_>
requires ((meta::different_from<dictionary, value_type_> && ...) && (meta::different_from<iterator, value_type_> && ...) && (meta::different_from<const_iterator, value_type_> && ...) && (std::convertible_to<value_type_, value_type> && ...) && (sizeof...(value_type_) > 0))

void bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::assign ( value_type_ &&...  args )

inline

Assign from multiple elements.

Parameters

[in]

args

Multiple elements of value_type; must be at least one.

This replaces the container's contents with the provided elements.

Complexity

Linear in the size of args and/or container size.

Exceptions

Basic exception gurantee.

at() [1/6]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

mapped_ref_t bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::at ( het_key_t  key )

inline

Access element by key.

Parameters

[in]

key

The key to lookup.

Returns

The mapped value belonging to the key.

Exceptions

std::out_of_range

if no element is associated with the key.

Note that this function returns a reference to the mapped object (not a key-value-pair).

Complexity

Amortized constant.

Exceptions

Basic exception guarantee.

at() [2/6]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

mapped_t const & bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::at ( het_key_t  key ) const

inline

Access element by key.

Parameters

[in]

key

The key to lookup.

Returns

The mapped value belonging to the key.

Exceptions

std::out_of_range

if no element is associated with the key.

Note that this function returns a reference to the mapped object (not a key-value-pair).

Complexity

Amortized constant.

Exceptions

Basic exception guarantee.

at() [3/6]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

template<small_string key>
requires (requires(dictionary d) { get<key>(d); })

decltype(auto) bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::at ( meta::vtag_t< key >  key_tag )

inline

Access element by compile-time string and implicitly call get() on it.

Template Parameters

key	The key to lookup.

Parameters

[in]

key_tag

A tag object wrapping the compile-time string.

Returns

get<key>(dict[key])

Exceptions

std::out_of_range

if no element is associated with the key.

This function is only available if mapped_t_is_context_aware is set to true and if get<key>() can be called on an object of type mapped_t.

Note that while dict[key] always returns a const & for context-aware dictionaries, this function may return a writable &.

Complexity

Amortized constant.

Exceptions

Basic exception guarantee.

at() [4/6]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

template<small_string key>
requires (requires(dictionary const d) { get<key>(d); })

decltype(auto) bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::at ( meta::vtag_t< key >  key_tag ) const

inline

Access element by compile-time string and implicitly call get() on it.

Template Parameters

key	The key to lookup.

Parameters

[in]

key_tag

A tag object wrapping the compile-time string.

Returns

get<key>(dict[key])

Exceptions

std::out_of_range

if no element is associated with the key.

This function is only available if mapped_t_is_context_aware is set to true and if get<key>() can be called on an object of type mapped_t.

Note that while dict[key] always returns a const & for context-aware dictionaries, this function may return a writable &.

Complexity

Amortized constant.

Exceptions

Basic exception guarantee.

at() [5/6]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

reference bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::at ( size_type const  i )

inline

Return the i-th element.

Parameters

[in]

i

Index of the element to retrieve.

Exceptions

std::out_of_range

If you access an element behind the last.

Returns

A reference to the value at position i.

Note that this function returns the value_type, i.e. a key-value-pair.

Complexity

Constant.

Exceptions

Throws std::out_of_range if i >= size().

at() [6/6]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

const_reference bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::at ( size_type const  i ) const

inline

Return the i-th element.

Parameters

[in]

i

Index of the element to retrieve.

Exceptions

std::out_of_range

If you access an element behind the last.

Returns

A reference to the value at position i.

Note that this function returns the value_type, i.e. a key-value-pair.

Complexity

Constant.

Exceptions

Throws std::out_of_range if i >= size().

back() [1/2]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

const_reference bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::back ( ) const

inlinenoexcept

Return the last element.

Returns

A reference to the value at the last position.

Note that this function returns a key-value-pair (not the mapped value).

Calling back on an empty container is undefined. In debug mode an assertion checks the size of the container.

Complexity

Constant.

Exceptions

No-throw guarantee.

back() [2/2]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

reference bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::back ( )

inlinenoexcept

Return the last element.

Returns

A reference to the value at the last position.

Note that this function returns a key-value-pair (not the mapped value).

Calling back on an empty container is undefined. In debug mode an assertion checks the size of the container.

Complexity

Constant.

Exceptions

No-throw guarantee.

begin()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

const_iterator bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::begin ( ) const

inlinenoexcept

Returns the begin iterator.

capacity()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

size_type bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::capacity ( ) const

inlinenoexcept

Returns the number of elements that the container is able to hold without reallocating (see below).

Returns

The capacity of the currently allocated storage.

This returns the capacity of the internal storage vector. Depending on the implementation, this may or may not be identical to the capacity of the internal hash-map. Thus, push_back() and emplace_back() within the current capacity are guaranteed to not invalidate any iterators, but may result in the hash-table allocating.

Complexity

Constant.

Exceptions

No-throw guarantee.

cbegin()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

const_iterator bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::cbegin ( ) const

inlinenoexcept

Returns the begin iterator.

cend()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

const_iterator bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::cend ( ) const

inlinenoexcept

Returns iterator past the end.

clear()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

void bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::clear ( )

inlinenoexcept

Removes all elements from the container.

Complexity

Constant.

Exceptions

No-throw guarantee.

contains()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

bool bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::contains ( het_key_t  key ) const

inline

Check whether the container has an element with the given key.

Parameters

[in]

key

The key to lookup.

Returns

true if an element with the key exists, false otherwise.

Complexity

Amortized constant.

Exceptions

No-throw guarantee.

count()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

size_t bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::count ( het_key_t  key ) const

inline

The number of elements in the container with the specified key.

Parameters

[in]

key

The key to lookup.

Returns

1 if an element with the key exists, 0 otherwise.

Since keys are required to be unique, this function can only return 0 or 1.

Complexity

Amortized constant.

Exceptions

No-throw guarantee.

emplace_back()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

void bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::emplace_back ( auto &&...  args )

inline

Constructs an element in-place at the end of the container.

Parameters

args	Arguments used to construct the element.

Exceptions

std::runtime_error

If an element with the key already exists in the container.

Complexity

Constant.

Exceptions

Basic exception guarantee.

empty()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

bool bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::empty ( ) const

inlinenoexcept

Checks whether the container is empty.

Returns

true if the container is empty, false otherwise.

Complexity

Constant.

Exceptions

No-throw guarantee.

end()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

const_iterator bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::end ( ) const

inlinenoexcept

Returns iterator past the end.

extract_back()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

value_type bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::extract_back ( )

inline

Removes and returns the last element of the container.

Calling extract_back() on an empty container is undefined. In debug mode an assertion will be thrown.

No iterators or references except for back() and end() are invalidated.

Complexity

Constant.

Exceptions

Basic exception guarantee.

find() [1/2]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

iterator bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::find ( het_key_t  key )

inline

Find an element with the given key.

Parameters

[in]

key

The key to lookup.

Returns

An iterator to the found element or end() if the key is not found.

Complexity

Amortized constant.

Exceptions

No-throw guarantee.

find() [2/2]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

const_iterator bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::find ( het_key_t  key ) const

inline

Find an element with the given key.

Parameters

[in]

key

The key to lookup.

Returns

An iterator to the found element or end() if the key is not found.

Complexity

Amortized constant.

Exceptions

No-throw guarantee.

front() [1/2]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

const_reference bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::front ( ) const

inlinenoexcept

Return the first element. Calling front on an empty container is undefined.

Returns

A reference to the value at the first position.

Note that this function returns a key-value-pair (not the mapped value).

Calling front on an empty container is undefined. In debug mode an assertion checks the size of the container.

Complexity

Constant.

Exceptions

No-throw guarantee.

front() [2/2]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

reference bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::front ( )

inlinenoexcept

Return the first element. Calling front on an empty container is undefined.

Returns

A reference to the value at the first position.

Note that this function returns a key-value-pair (not the mapped value).

Calling front on an empty container is undefined. In debug mode an assertion checks the size of the container.

Complexity

Constant.

Exceptions

No-throw guarantee.

max_size()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

size_type bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::max_size ( ) const

inlinenoexcept

Returns the maximum number of elements the container is able to hold.

Returns

The number of elements in the container.

This value typically reflects the theoretical limit on the size of the container. At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available.

Complexity

Constant.

Exceptions

No-throw guarantee.

operator[]() [1/6]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

mapped_ref_t bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::operator[] ( het_key_t  key )

inline

Access element by key.

Parameters

[in]

key

The key to lookup.

Returns

The mapped value belonging to the key.

Exceptions

std::out_of_range

if no element is associated with the key.

This function is identical to .at(key). It never inserts elements like the respective function in std::unordered_map would do; instead it throws an exception if an element with the given key does not exist.

Complexity

Amortized constant.

Exceptions

Basic exception guarantee.

operator[]() [2/6]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

mapped_t const & bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::operator[] ( het_key_t  key ) const

inline

Access element by key.

Parameters

[in]

key

The key to lookup.

Returns

The mapped value belonging to the key.

Exceptions

std::out_of_range

if no element is associated with the key.

This function is identical to .at(key). It never inserts elements like the respective function in std::unordered_map would do; instead it throws an exception if an element with the given key does not exist.

Complexity

Amortized constant.

Exceptions

Basic exception guarantee.

operator[]() [3/6]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

template<small_string key>
requires (requires(dictionary d) { get<key>(d); })

decltype(auto) bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::operator[] ( meta::vtag_t< key >  key_tag )

inline

Access element by compile-time string and implicitly call get() on it.

Template Parameters

key	The key to lookup.

Parameters

[in]

key_tag

A tag object wrapping the compile-time string.

Returns

get<key>(dict[key])

Exceptions

std::out_of_range

if no element is associated with the key.

This function is only available if mapped_t_is_context_aware is set to true and if get<key>() can be called on an object of type mapped_t.

Note that while dict[key] always returns a const & for context-aware dictionaries, this function may return a writable &.

Complexity

Amortized constant.

Exceptions

Basic exception guarantee.

operator[]() [4/6]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

template<small_string key>
requires (requires(dictionary const d) { get<key>(d); })

decltype(auto) bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::operator[] ( meta::vtag_t< key >  key_tag ) const

inline

Access element by compile-time string and implicitly call get() on it.

Template Parameters

key	The key to lookup.

Parameters

[in]

key_tag

A tag object wrapping the compile-time string.

Returns

get<key>(dict[key])

Exceptions

std::out_of_range

if no element is associated with the key.

This function is only available if mapped_t_is_context_aware is set to true and if get<key>() can be called on an object of type mapped_t.

Note that while dict[key] always returns a const & for context-aware dictionaries, this function may return a writable &.

Complexity

Amortized constant.

Exceptions

Basic exception guarantee.

operator[]() [5/6]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

const_reference bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::operator[] ( size_type const  i ) const

inlinenoexcept

Return the i-th element.

Parameters

i	The element to retrieve.

Returns

A reference to the value at position i.

Note that this function returns a key-value-pair (not the mapped value).

Accessing an element behind the last causes undefined behaviour. In debug mode an assertion checks the size of the container.

Complexity

Constant.

Exceptions

No-throw guarantee.

operator[]() [6/6]

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

reference bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::operator[] ( size_type const  i )

inlinenoexcept

Return the i-th element.

Parameters

i	The element to retrieve.

Returns

A reference to the value at position i.

Note that this function returns a key-value-pair (not the mapped value).

Accessing an element behind the last causes undefined behaviour. In debug mode an assertion checks the size of the container.

Complexity

Constant.

Exceptions

No-throw guarantee.

pop_back()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

void bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::pop_back ( )

inline

Removes the last element of the container.

Calling pop_back() on an empty container is undefined. In debug mode an assertion will be thrown.

No iterators or references except for back() and end() are invalidated.

Complexity

Constant.

Exceptions

No-throw guarantee.

push_back()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

template<std::convertible_to< value_type > value_type_ = value_type>

void bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::push_back ( value_type_ &&  value )

inline

Appends the given element value to the end of the container.

Parameters

value

The value to append.

Exceptions

std::runtime_error

If an element with the key already exists in the container.

Complexity

Constant.

Exceptions

Strong exception guarantee.

reserve()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

void bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::reserve ( size_type const  new_cap )

inline

Reserve storage in the underlying data types to accomodate for future inserts.

Parameters

[in]

new_cap

The desired capacity.

This reserves the specified capacity in both internal data structures to prevent reallocation on subsequent back insertions. It never reduces the capacity(); use shrink_to_fit() for that.

Complexity

Average case: linear in new_cap. Worst case: quadratic in new_cap.

Exceptions

Basic exception guarantee.

shrink_to_fit()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

void bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::shrink_to_fit ( )

inline

Reduce capacity to current size() to free unused memory.

This only reduces the capacity of the internal storage vector, not of the hash-map.

Complexity

Worst case: linear in size().

Exceptions

Basic exception guarantee.

size()

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

size_type bio::ranges::dictionary< key_t, mapped_t, mapped_t_is_context_aware >::size ( ) const

inlinenoexcept

Returns the number of elements in the container.

Returns

The number of elements in the container.

Complexity

Constant.

Exceptions

No-throw guarantee.

Friends And Related Function Documentation

get

template<typename key_t , typename mapped_t , bool mapped_t_is_context_aware = false>

template<small_string key>
requires (mapped_t_is_context_aware && requires { get<key>(get<1>(dict.storage[0])); })

decltype(auto) get ( meta::decays_to< dictionary< key_t, mapped_t, mapped_t_is_context_aware > > auto &&  dict )

friend

Access element by compile-time string and implicitly call get() on it.

Template Parameters

key	The key to lookup.

Parameters

[in,out]

dict

An object of this type.

Returns

get<key>(dict[key])

Exceptions

std::out_of_range

if no element is associated with the key.

This function is only available if mapped_t_is_context_aware is set to true and if get<key>() can be called on an object of type mapped_t.

Note that while dict[key] always returns a const & for context-aware dictionaries, this function may return a writable &.

Complexity

Amortized constant.

Exceptions

Basic exception guarantee.

---

The documentation for this class was generated from the following file:

• bio/ranges/container/dictionary.hpp