Template Class GenericMap

Inheritance Relationships

Derived Type

Class Documentation

template<typename K>
class GenericMap

Interface for a heterogeneous map.

Objects of type GenericMap cannot necessarily have keys added or removed, although mutable values can be modified as usual. In Python, a GenericMap behaves like a collections.abc.Mapping. See MutableGenericMap for a GenericMap that must allow insertions and deletions.

A

Key for the map is parameterized by both the key type K and a corresponding value type V. The map is indexed uniquely by a value of type K; no two entries in the map may have identical values of Key::getId().
Template Parameters
  • K: the key type of the map.

All operations are sensitive to the value type of the key: a contains call requesting an integer labeled “value”, for example, will report no such integer if instead there is a string labeled “value”. For Python compatibility, a GenericMap does not store type information internally, instead relying on RTTI for type checking.

All subclasses must guarantee, as a class invariant, that every value in the map is implicitly nothrow-convertible to the type indicated by its key. For example, MutableGenericMap ensures this by appropriately templating all operations that create new key-value pairs.

A GenericMap may contain primitive types, strings, Storable, and shared pointers to Storable as values. It does not support unique pointers to Storable because such pointers are read destructively. For safety reasons, it may not contain references, C-style pointers, or arrays to any type. Due to implementation restrictions, const types (except pointers to const Storable) are not currently supported.

Subclassed by lsst::afw::typehandling::MutableGenericMap< K >

Unnamed Group

template<typename T, typename std::enable_if_t<!detail::IS_SMART_PTR< T >, int > = 0>T& lsst::afw::typehandling::GenericMap::at(Key < K, T > const & key)

Return a reference to the mapped value of the element with key equal to key.

Return

a reference to the T mapped to key, if one exists

Note

This implementation calls unsafeLookup once, then uses templates and RTTI to determine if the value is of the expected type.

Template Parameters
  • T: the type of the element mapped to key. It may be the exact type of the element, if known, or any type to which its references or pointers can be implicitly converted (e.g., a superclass). For example, references to built-in types are not convertible, so you can’t retrieve an int with T=long.

Parameters
  • key: the key of the element to find

Exceptions
  • pex::exceptions::OutOfRangeError: Thrown if the map does not have a T with the specified key Provides strong exception safety.

template<typename T, typename std::enable_if_t<!detail::IS_SMART_PTR< T >, int > = 0>T const& lsst::afw::typehandling::GenericMap::at(Key < K, T > const & key) const
template<typename T, typename std::enable_if_t< std::is_base_of< Storable, T >::value, int > = 0>std::shared_ptr<T> lsst::afw::typehandling::GenericMap::at(Key < K, std::shared_ptr< T >> const & key) const

Unnamed Group

virtual bool operator==(GenericMap const &other) const

Test for map equality.

Two GenericMap objects are considered equal if they map the same keys to the same values. The two objects do not need to have the same implementation class. If either class orders its keys, the order is ignored.

Note

This implementation calls keys on both objects and compares the results. If the two objects have the same keys, it calls unsafeLookup for each key and compares the values.

bool operator!=(GenericMap const &other) const

Unnamed Group

template<>
using ConstValueReference = decltype(_typeToConstRef(std::declval<StorableType>()))

A type-agnostic reference to the value stored inside the map.

These are the reference equivalents (T const& or T&) of StorableType.

template<>
using ValueReference = decltype(_typeToRef(std::declval<StorableType>()))

Unnamed Group

virtual ConstValueReference unsafeLookup(K key) const = 0

Return a reference to the mapped value of the element with key equal to key.

This method is the primary way to implement the GenericMap interface.

Return

the value mapped to key, if one exists

Parameters
  • key: the key of the element to find

Exceptions
  • pex::exceptions::OutOfRangeError: Thrown if the map does not have a value with the specified key Must provide strong exception safety.

ValueReference unsafeLookup(K key)

Public Types

template<>
using key_type = K
template<>
using size_type = std::size_t
template<>
using difference_type = std::ptrdiff_t

Public Functions

virtual ~GenericMap()
virtual size_type size() const = 0

Return the number of key-value pairs in the map.

virtual bool empty() const = 0

Return true if this map contains no key-value pairs.

virtual size_type max_size() const = 0

Return the maximum number of elements the container is able to hold due to system or library implementation limitations.

Note

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.

template<typename T>
size_type count(Key<K, T> const &key) const

Return the number of elements mapped to the specified key.

Provides strong exception safety.

Return

number of T with key key, that is, either 1 or 0.

Template Parameters
  • T: the value corresponding to key

Parameters
  • key: key value of the elements to count

Note

This implementation calls contains.

virtual bool contains(K const &key) const = 0

Return true if this map contains a mapping whose key has the specified label.

More formally, this method returns true if and only if this map contains a mapping with a key k such that k.getId() == key. There can be at most one such mapping.

Provides strong exception safety.

Return

true if this map contains a mapping for key, regardless of value type.

Parameters
  • key: the weakly-typed key to search for

template<typename T>
bool contains(Key<K, T> const &key) const

Return true if this map contains a mapping for the specified key.

This is equivalent to testing whether at(key) would succeed.

Provides strong exception safety.

Return

true if this map contains a mapping from the specified key to a T

Template Parameters
  • T: the value corresponding to key

Parameters
  • key: the key to search for

Note

This implementation calls contains(K const&) const. If the call returns true, it calls unsafeLookup, then uses templates and RTTI to determine if the value is of the expected type. The performance of this method depends strongly on the performance of contains(K const&).

virtual std::vector<K> const &keys() const = 0

Return the set of all keys, without type information.

Return

a read-only view of all keys currently in the map, in the same iteration order as this object. The view will be updated by changes to the underlying map.

Warning

Do not modify this map while iterating over its keys.

Warning

Do not store the returned reference in variables that outlive the map; destroying the map will invalidate the reference.

Note

The keys are returned as a list, rather than a set, so that subclasses can give them a well-defined iteration order.

template<class Visitor>
auto apply(Visitor &&visitor) const

Apply an operation to each key-value pair in the map.

Provides the same level of exception safety as

Visitor, or strong exception safety if Visitor cannot throw.
Return

if Visitor has a return value, a std::vector of values returned from applying visitor to each key in keys, in that order. Otherwise, void.

Template Parameters
  • Visitor: a callable that takes a key and a value. See below for exact requirements.

Parameters
  • visitor: the visitor to apply

A Visitor must define one or more operator() that take a weakly-typed key and a value. Each operator() must return the same type (which may be void). Through any combination of overloading or templates, the visitor must accept values of the following types:

  • either bool or bool const&

  • either int or int const&

  • either long or long const&

  • either long long or long long const&

  • either float or float const&

  • either double or double const&

  • std::string const&

  • Storable const&

  • std::shared_ptr<Storable const>

An example visitor that prints each key-value pair to standard output:

template <typename K>
class Printer {
public:
    template <typename V>
    void operator()(K const& key, V const& value) {
        std::cout << key << ": " << value << "," << std::endl;
    }

    void operator()(K const& key, Storable const& value) {
        std::cout << key << ": ";
        try {
            std::cout << value;
        } catch (UnsupportedOperationException const&) {
            std::cout << "[unprintable]";
        }
        std::cout << "," << std::endl;
    }

    void operator()(K const& key, std::shared_ptr<Storable const> value) {
        if (value != nullptr) {
            operator()(key, *value);
        } else {
            operator()(key, "null");
        }
    }
};
Note

This implementation calls keys, then calls unsafeLookup for each key before passing the result to visitor.

template<class Visitor>
auto apply(Visitor &&visitor)

Apply a modifying operation to each key-value pair in the map.

Provides basic exception safety if

Visitor is exception-safe.
Return

if Visitor has a return value, a std::vector of values returned from applying visitor to each key in keys, in that order. Otherwise, void.

Template Parameters
  • Visitor: a callable that takes a key and a value. Requirements as for apply(Visitor&&) const, except that it may take non-const references to values.

Parameters
  • visitor: the visitor to apply

Note

This implementation calls keys, then calls unsafeLookup for each key before passing the result to visitor.

Protected Types

template<>
using StorableType = boost::variant<bool, int, long, long long, float, double, std::string, PolymorphicValue, std::shared_ptr<Storable const>>

The types that can be stored in a map.

Keys of any subclass of Storable are implemented using PolymorphicValue to preserve type.