Namespace lsst::afw::typehandling

namespace typehandling

Functions

template<typename V, typename K>
constexpr Key<K, V> makeKey(K const &id)

Factory function for Key, to enable type parameter inference.

Provides the same exception safety as the copy-constructor of

K.
Return

a key of the desired type

Parameters
  • id: the key ID to create.

Calling this function prevents you from having to explicitly name the key type:

auto key = makeKey<int>("foo");

template<typename K, typename V>
std::ostream &operator<<(std::ostream &os, Key<K, V> const &key)

Output operator for Key.

The output will use C++ template notation for the key; for example, a key “foo” pointing to an int may print as "foo<int>".

Provides basic exception safety if the output operator of

K is exception-safe.
Return

a reference to os

Parameters
  • os: the desired output stream

  • key: the key to print

Warning

the type name is compiler-specific and may be mangled or unintuitive; for example, some compilers say “i” instead of “int”

void swap(PolymorphicValue &lhs, PolymorphicValue &rhs)

Swap specialization for PolymorphicValue.

std::string declareGenericMapRestrictions(std::string const &className, std::string const &keyName)
LSST_EXCEPTION_TYPE (UnsupportedOperationException, pex::exceptions::RuntimeError, lsst::afw::typehandling::UnsupportedOperationException) class Storable std::ostream& lsst::afw::typehandling::operator<<(std::ostream & os, Storable const & storable)

Exception thrown by Storable operations for unimplemented operations.

As with all RuntimeError, callers should assume that this exception may be thrown at any time. Interface supporting iteration over heterogenous containers.

Storable may be subclassed by either C++ or Python classes. Many operations defined by Storable are optional, and may throw UnsupportedOperationException if they are not defined.

Note

Any C++ subclass X of Storable that supports Python subclasses must have a pybind11 wrapper that uses StorableHelper<X> (or a subclass) and lsst::utils::python::PySharedPtr. Output operator for Storable.

Return

a reference to os

Parameters
  • os: the desired output stream

  • storable: the object to print

Exceptions
  • UnsupportedOperationException: Thrown if storable does not have an implementation of Storable::toString.

template<typename K>
class GenericMap
#include <GenericMap.h>

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 >

template<typename K, typename V>
class Key
#include <Key.h>

Key for type-safe lookup in a GenericMap.

Key objects are equality-comparable, hashable, sortable, or printable if and only if K is comparable, hashable, sortable, or printable, respectively. Key can be used in compile-time expressions if and only if K can (in particular, Key<std::string, V> cannot).

Template Parameters
  • K: the logical type of the key (e.g., a string)

  • V: the type of the value mapped to this key

template<typename K>
class MutableGenericMap : public lsst::afw::typehandling::GenericMap<K>
#include <GenericMap.h>

Interface for a GenericMap that allows element addition and removal.

In Python, a MutableGenericMap behaves like a collections.abc.MutableMapping.

Note

Unlike standard library maps, this class does not support operator[] or insert_or_assign. This is because these operations would have surprising behavior when dealing with keys of different types but the same Key::getId().

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

class PolymorphicValue
#include <PolymorphicValue.h>

Container that passes Storable objects by value while preserving type.

This class is implicitly convertible to and from a reference to Storable, but behaves like a value: changing the internal Storable changes the object’s state, and copying the object creates a new Storable.

Note

While a PolymorphicValue is always initialized with a Storable, it may become empty if it is the source of a move-construction or move-assignment. Conversion of an empty value to Storable& throws.

template<typename K>
class SimpleGenericMap : public lsst::afw::typehandling::MutableGenericMap<K>
#include <SimpleGenericMap.h>

A GenericMap that allows insertion and deletion of arbitrary values.

In Python, a SimpleGenericMap behaves like a dict. In particular, it will iterate over keys in the order they were added.

Template Parameters
  • K: the key type of the map. Must be hashable.

template<class Base = Storable>
class StorableHelper : public Base
#include <python.h>

“Trampoline” for Storable to let it be used as a base class in Python.

Subclasses of Storable that are wrapped in pybind11 should have a similar helper that subclasses StorableHelper<subclass>. This helper can be skipped if the subclass neither adds any virtual methods nor implements any abstract methods.

See

pybind11 documentation

Template Parameters
  • Base: the exact (most specific) class being wrapped

namespace detail

Variables

template<typename, typename = void>
constexpr bool IS_SMART_PTR = false
namespace test

Functions

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestConstAt, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestAt, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestEquals, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestConstVisitor, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestModifyingVoidVisitor, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestModifyingReturningVisitor, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestMutableEquals, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestSize, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestMutableSize, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestWeakContains, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestContains, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestKeys, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestKeyOrder, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestClearIdempotent, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestClear, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestInsertInt, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestWeakInsertInt, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestInsertString, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestWeakInsertString, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestInsertStorable, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestInterleavedInserts, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestErase, GenericMapFactory)
BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestInsertEraseInsert, GenericMapFactory)
template<class GenericMapFactory>
void addGenericMapTestCases(boost::unit_test::test_suite *const suite)

Create generic test cases for a specific GenericMap implementation.

Template Parameters
  • GenericMapFactory: a subclass of GenericFactory that creates the desired implementation. Must be default-constructible.

Parameters
  • suite: the test suite to add the tests to.

template<class GenericMapFactory>
void addMutableGenericMapTestCases(boost::unit_test::test_suite *const suite)

Create generic test cases for a specific MutableGenericMap implementation.

The tests will include all those added by addGenericMapTestCases.

Template Parameters
  • GenericMapFactory: a subclass of GenericFactory that creates the desired implementation. Must be default-constructible.

Parameters
  • suite: the test suite to add the tests to.

template<class GenericMapFactory>
void addGenericMapTestCases()

Create generic test cases for a specific GenericMap implementation.

The tests will be added to the master test suite.

Template Parameters
  • GenericMapFactory: a subclass of GenericFactory that creates the desired implementation. Must be default-constructible.

template<class GenericMapFactory>
void addMutableGenericMapTestCases()

Create generic test cases for a specific MutableGenericMap implementation.

The tests will be added to the master test suite. They will include all tests added by addGenericMapTestCases.

Template Parameters
  • GenericMapFactory: a subclass of GenericFactory that creates the desired implementation. Must be default-constructible.

class GenericFactory
#include <test.h>

Abstract factory that creates GenericMap and MutableGenericMap instances as needed.