LSST Applications  21.0.0-172-gfb10e10a+18fedfabac,22.0.0+297cba6710,22.0.0+80564b0ff1,22.0.0+8d77f4f51a,22.0.0+a28f4c53b1,22.0.0+dcf3732eb2,22.0.1-1-g7d6de66+2a20fdde0d,22.0.1-1-g8e32f31+297cba6710,22.0.1-1-geca5380+7fa3b7d9b6,22.0.1-12-g44dc1dc+2a20fdde0d,22.0.1-15-g6a90155+515f58c32b,22.0.1-16-g9282f48+790f5f2caa,22.0.1-2-g92698f7+dcf3732eb2,22.0.1-2-ga9b0f51+7fa3b7d9b6,22.0.1-2-gd1925c9+bf4f0e694f,22.0.1-24-g1ad7a390+a9625a72a8,22.0.1-25-g5bf6245+3ad8ecd50b,22.0.1-25-gb120d7b+8b5510f75f,22.0.1-27-g97737f7+2a20fdde0d,22.0.1-32-gf62ce7b1+aa4237961e,22.0.1-4-g0b3f228+2a20fdde0d,22.0.1-4-g243d05b+871c1b8305,22.0.1-4-g3a563be+32dcf1063f,22.0.1-4-g44f2e3d+9e4ab0f4fa,22.0.1-42-gca6935d93+ba5e5ca3eb,22.0.1-5-g15c806e+85460ae5f3,22.0.1-5-g58711c4+611d128589,22.0.1-5-g75bb458+99c117b92f,22.0.1-6-g1c63a23+7fa3b7d9b6,22.0.1-6-g50866e6+84ff5a128b,22.0.1-6-g8d3140d+720564cf76,22.0.1-6-gd805d02+cc5644f571,22.0.1-8-ge5750ce+85460ae5f3,master-g6e05de7fdc+babf819c66,master-g99da0e417a+8d77f4f51a,w.2021.48
LSST Data Management Base Package
Public Types | Public Member Functions | List of all members
lsst::afw::image::detail::StorableMap Class Referencefinal

A map of Storable supporting strongly-typed access. More...

#include <StorableMap.h>

Public Types

using mapped_type = std::shared_ptr< typehandling::Storable const >
 
using key_type = typehandling::Key< std::string, mapped_type >
 
using value_type = std::pair< key_type const, mapped_type >
 
using size_type = std::size_t
 
using difference_type = std::ptrdiff_t
 
using reference = value_type &
 
using const_reference = value_type const &
 
using pointer = value_type *
 
using const_pointer = value_type const *
 
using const_iterator = _Impl::const_iterator
 
using iterator = _Impl::iterator
 
using reverse_iterator = std::reverse_iterator< iterator >
 
using const_reverse_iterator = std::reverse_iterator< const_iterator >
 
template<typename V >
using Key = lsst::afw::typehandling::Key< std::string, V >
 
using Storable = lsst::afw::typehandling::Storable
 

Public Member Functions

 StorableMap ()
 
 StorableMap (StorableMap const &other)
 
 StorableMap (StorableMap &&other)
 
StorableMapoperator= (StorableMap const &other)
 
StorableMapoperator= (StorableMap &&other)
 
 ~StorableMap () noexcept
 
 StorableMap (std::initializer_list< value_type > init)
 Construct a map from an initializer list. More...
 
template<typename T >
std::shared_ptr< T > at (Key< std::shared_ptr< T >> const &key) const
 Return a the mapped value of the element with key equal to key. More...
 
size_type size () const noexcept
 Return the number of key-value pairs in the map. More...
 
bool empty () const noexcept
 Return true if this map contains no key-value pairs. More...
 
size_type max_size () const noexcept
 Return the maximum number of elements the container is able to hold due to system or library implementation limitations. More...
 
bool contains (std::string const &key) const
 Return true if this map contains a mapping whose key has the specified label. More...
 
template<typename T >
bool contains (Key< std::shared_ptr< T >> const &key) const
 Return true if this map contains a mapping for the specified key. More...
 
void clear () noexcept
 Remove all of the mappings from this map. More...
 
template<typename T >
bool insert (Key< std::shared_ptr< T >> const &key, std::shared_ptr< T > const &value)
 Insert an element into the map, if the map doesn't already contain a mapping with the same or a conflicting key. More...
 
template<typename T >
std::pair< Key< T >, bool > insert (std::string const &key, T const &value)
 Insert an element into the map, if the map doesn't already contain a mapping with a conflicting key. More...
 
template<typename T >
bool erase (Key< T > const &key) noexcept
 Remove the mapping for a key from this map, if it exists. More...
 
bool operator== (StorableMap const &other) const noexcept
 Test for map equality. More...
 
bool operator!= (StorableMap const &other) const noexcept
 Test for map equality. More...
 
iterator begin () noexcept
 Return an iterator to the first element of the map. More...
 
const_iterator begin () const noexcept
 Return an iterator to the first element of the map. More...
 
const_iterator cbegin () const noexcept
 Return an iterator to the first element of the map. More...
 
iterator end () noexcept
 Return an iterator to the element past the end of the map. More...
 
const_iterator end () const noexcept
 Return an iterator to the element past the end of the map. More...
 
const_iterator cend () const noexcept
 Return an iterator to the element past the end of the map. More...
 

Detailed Description

A map of Storable supporting strongly-typed access.

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().

All operations are sensitive to the value type of the key: a contains call requesting a SkyWcs labeled "value", for example, will report no such object if instead there is a Psf labeled "value". At present, a StorableMap does not store type information internally, instead relying on RTTI for type checking.

Definition at line 59 of file StorableMap.h.

Member Typedef Documentation

◆ const_iterator

Definition at line 77 of file StorableMap.h.

◆ const_pointer

Definition at line 69 of file StorableMap.h.

◆ const_reference

Definition at line 67 of file StorableMap.h.

◆ const_reverse_iterator

Definition at line 80 of file StorableMap.h.

◆ difference_type

Definition at line 65 of file StorableMap.h.

◆ iterator

Definition at line 78 of file StorableMap.h.

◆ Key

Definition at line 83 of file StorableMap.h.

◆ key_type

Definition at line 62 of file StorableMap.h.

◆ mapped_type

Definition at line 61 of file StorableMap.h.

◆ pointer

Definition at line 68 of file StorableMap.h.

◆ reference

Definition at line 66 of file StorableMap.h.

◆ reverse_iterator

Definition at line 79 of file StorableMap.h.

◆ size_type

Definition at line 64 of file StorableMap.h.

◆ Storable

Definition at line 84 of file StorableMap.h.

◆ value_type

Definition at line 63 of file StorableMap.h.

Constructor & Destructor Documentation

◆ StorableMap() [1/4]

lsst::afw::image::detail::StorableMap::StorableMap ( )
default

◆ StorableMap() [2/4]

lsst::afw::image::detail::StorableMap::StorableMap ( StorableMap const &  other)
default

◆ StorableMap() [3/4]

lsst::afw::image::detail::StorableMap::StorableMap ( StorableMap &&  other)
default

◆ ~StorableMap()

lsst::afw::image::detail::StorableMap::~StorableMap ( )
defaultnoexcept

◆ StorableMap() [4/4]

lsst::afw::image::detail::StorableMap::StorableMap ( std::initializer_list< value_type init)

Construct a map from an initializer list.

Parameters
initan initializer list of key-value pairs. The keys and values may be of any type that can be converted to std::shared_ptr<typehandling::Storable const>.
Note
If init contains any keys with the same ID, it is unspecified which will be inserted.
See also
std::map::map

Definition at line 42 of file StorableMap.cc.

42 : _contents(init){};

Member Function Documentation

◆ at()

template<typename T >
std::shared_ptr<T> lsst::afw::image::detail::StorableMap::at ( Key< std::shared_ptr< T >> const &  key) const
inline

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

Template Parameters
Tthe type of the element mapped to key. It may be the exact type of the element, if known, or any type to which its pointers can be implicitly converted (e.g., a superclass).
Parameters
keythe key of the element to find
Returns
a pointer to the T mapped to key, if one exists
Exceptions
pex::exceptions::OutOfRangeErrorThrown if the map does not have a T with the specified key.
Exception Safety
Provides strong exception safety.

Definition at line 122 of file StorableMap.h.

122  {
124  "Can only retrieve pointers to subclasses of Storable.");
125  static_assert(std::is_const<T>::value,
126  "Due to implementation constraints, pointers to non-const are not supported.");
127  try {
128  // unordered_map::at(Key<Storable>) does not do any type-checking.
129  mapped_type const& pointer = _contents.at(key);
130 
131  // Null pointer stored; skip dynamic_cast because won't change result.
132  if (pointer == nullptr) {
133  return nullptr;
134  }
135 
136  std::shared_ptr<T> typedPointer = std::dynamic_pointer_cast<T>(pointer);
137  // shared_ptr can be empty without being null. dynamic_pointer_cast
138  // only promises result of failed cast is empty, so test for that.
139  if (typedPointer.use_count() > 0) {
140  return typedPointer;
141  } else {
142  std::stringstream message;
143  message << "Key " << key << " not found, but a key labeled " << key.getId() << " is present.";
144  throw LSST_EXCEPT(pex::exceptions::OutOfRangeError, message.str());
145  }
146  } catch (std::out_of_range const&) {
147  std::throw_with_nested(LSST_EXCEPT(pex::exceptions::OutOfRangeError,
148  "No key labeled " + key.getId() + " found."));
149  }
150  }
#define LSST_EXCEPT(type,...)
Create an exception with a given type.
Definition: Exception.h:48
T at(T... args)
std::shared_ptr< typehandling::Storable const > mapped_type
Definition: StorableMap.h:61
T str(T... args)
T throw_with_nested(T... args)

◆ begin() [1/2]

StorableMap::const_iterator lsst::afw::image::detail::StorableMap::begin ( ) const
noexcept

Return an iterator to the first element of the map.

Returns
An iterator that dereferences to a value_type, i.e. a pair of const Key and shared pointer to const Storable.

Definition at line 56 of file StorableMap.cc.

56  {
57  return StorableMap::const_iterator(_contents.begin());
58 }
T begin(T... args)
_Impl::const_iterator const_iterator
Definition: StorableMap.h:77

◆ begin() [2/2]

StorableMap::iterator lsst::afw::image::detail::StorableMap::begin ( )
noexcept

Return an iterator to the first element of the map.

Returns
An iterator that dereferences to a value_type, i.e. a pair of const Key and shared pointer to const Storable.

Definition at line 63 of file StorableMap.cc.

63 { return StorableMap::iterator(_contents.begin()); };

◆ cbegin()

const_iterator lsst::afw::image::detail::StorableMap::cbegin ( ) const
inlinenoexcept

Return an iterator to the first element of the map.

Returns
An iterator that dereferences to a value_type, i.e. a pair of const Key and shared pointer to const Storable.

Definition at line 330 of file StorableMap.h.

330 { return begin(); }
iterator begin() noexcept
Return an iterator to the first element of the map.
Definition: StorableMap.cc:63

◆ cend()

const_iterator lsst::afw::image::detail::StorableMap::cend ( ) const
inlinenoexcept

Return an iterator to the element past the end of the map.

Returns
An iterator that dereferences to a value_type, i.e. a pair of const Key and shared pointer to const Storable.

Definition at line 344 of file StorableMap.h.

344 { return end(); }
iterator end() noexcept
Return an iterator to the element past the end of the map.
Definition: StorableMap.cc:64

◆ clear()

void lsst::afw::image::detail::StorableMap::clear ( )
noexcept

Remove all of the mappings from this map.

After this call, the map will be empty.

Definition at line 54 of file StorableMap.cc.

54 { _contents.clear(); }
T clear(T... args)

◆ contains() [1/2]

template<typename T >
bool lsst::afw::image::detail::StorableMap::contains ( Key< std::shared_ptr< T >> const &  key) const
inline

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

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

Template Parameters
Tthe type of element being tested for
Parameters
keythe key to search for
Returns
true if this map contains a mapping from the specified key to a T.
Exception Safety
Provides strong exception safety.

Definition at line 201 of file StorableMap.h.

201  {
203  "Can only retrieve pointers to subclasses of Storable.");
204  static_assert(std::is_const<T>::value,
205  "Due to implementation constraints, pointers to non-const are not supported.");
206  if (_contents.count(key) > 0) {
207  // unordered_map::at(Key<Storable>) does not do any type-checking.
208  mapped_type const& pointer = _contents.at(key);
209 
210  // Null pointer stored; dynamic_cast will always return null.
211  if (pointer == nullptr) {
212  return true;
213  }
214 
215  std::shared_ptr<T> typedPointer = std::dynamic_pointer_cast<T>(pointer);
216  // shared_ptr can be empty without being null. dynamic_pointer_cast
217  // only promises result of failed cast is empty, so test for that.
218  return typedPointer.use_count() > 0;
219  } else {
220  return false;
221  }
222  }
T count(T... args)

◆ contains() [2/2]

bool lsst::afw::image::detail::StorableMap::contains ( std::string const &  key) const

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.

Parameters
keythe weakly-typed key to search for
Returns
true if this map contains a mapping for key, regardless of value type.
Exception Safety
Provides strong exception safety.

Definition at line 50 of file StorableMap.cc.

50 { return _contents.count(key_type(key)) == 1; }
typehandling::Key< std::string, mapped_type > key_type
Definition: StorableMap.h:62

◆ empty()

bool lsst::afw::image::detail::StorableMap::empty ( ) const
noexcept

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

Definition at line 46 of file StorableMap.cc.

46 { return _contents.empty(); }
T empty(T... args)

◆ end() [1/2]

StorableMap::const_iterator lsst::afw::image::detail::StorableMap::end ( ) const
noexcept

Return an iterator to the element past the end of the map.

Returns
An iterator that dereferences to a value_type, i.e. a pair of const Key and shared pointer to const Storable.

Definition at line 59 of file StorableMap.cc.

59  {
60  return StorableMap::const_iterator(_contents.end());
61 };
T end(T... args)

◆ end() [2/2]

StorableMap::iterator lsst::afw::image::detail::StorableMap::end ( )
noexcept

Return an iterator to the element past the end of the map.

Returns
An iterator that dereferences to a value_type, i.e. a pair of const Key and shared pointer to const Storable.

Definition at line 64 of file StorableMap.cc.

64 { return StorableMap::iterator(_contents.end()); };

◆ erase()

template<typename T >
bool lsst::afw::image::detail::StorableMap::erase ( Key< T > const &  key)
inlinenoexcept

Remove the mapping for a key from this map, if it exists.

Template Parameters
Tthe type of value the key maps to
Parameters
keythe key to remove
Returns
true if key was removed, false if it was not present.

Definition at line 311 of file StorableMap.h.

311  {
312  // unordered_map::erase(Key<Storable>) does no type checking.
313  if (this->contains(key)) {
314  return _contents.erase(key) > 0;
315  } else {
316  return false;
317  }
318  }
bool contains(std::string const &key) const
Return true if this map contains a mapping whose key has the specified label.
Definition: StorableMap.cc:50
T erase(T... args)

◆ insert() [1/2]

template<typename T >
bool lsst::afw::image::detail::StorableMap::insert ( Key< std::shared_ptr< T >> const &  key,
std::shared_ptr< T > const &  value 
)
inline

Insert an element into the map, if the map doesn't already contain a mapping with the same or a conflicting key.

Template Parameters
Tthe type of value to insert
Parameters
keythe key to insert
valuethe value to insert
Returns
true if the insertion took place, false otherwise.
Exception Safety
Provides strong exception safety.
Note
It is possible for a key with a value type other than T to prevent insertion. Callers can safely assume this->contains(key.getId()) as a postcondition, but not this->contains(key).

Definition at line 263 of file StorableMap.h.

263  {
265  "Can only store shared pointers to subclasses of Storable.");
266  static_assert(std::is_const<T>::value,
267  "Due to implementation constraints, pointers to non-const are not supported.");
268  // unordered_map uses Key<shared_ptr<Storable>> internally, so
269  // any key with the same ID will block emplacement.
270  return _contents.emplace(key, value).second;
271  }
T emplace(T... args)

◆ insert() [2/2]

template<typename T >
std::pair<Key<T>, bool> lsst::afw::image::detail::StorableMap::insert ( std::string const &  key,
T const &  value 
)
inline

Insert an element into the map, if the map doesn't already contain a mapping with a conflicting key.

Template Parameters
Tthe type of value to insert (will not compile unless shared pointer to a subclass of Storable)
Parameters
keythe key to insert
valuethe value to insert
Returns
A pair consisting of a strongly-typed key for the value and a flag that is true if the insertion took place and false otherwise.
Exception Safety
Provides strong exception safety.
Warning
The type of the compiler-generated key may be surprising. Callers should save the returned key if they wish to retrieve the value later.

Definition at line 293 of file StorableMap.h.

293  {
294  auto strongKey = typehandling::makeKey<T>(key);
295  // Construct return value in advance, so that exception from
296  // copying/moving Key is atomic.
297  auto result = std::make_pair(strongKey, false);
298  result.second = insert(strongKey, value);
299  return result;
300  }
py::object result
Definition: _schema.cc:429
bool insert(Key< std::shared_ptr< T >> const &key, std::shared_ptr< T > const &value)
Insert an element into the map, if the map doesn't already contain a mapping with the same or a confl...
Definition: StorableMap.h:263
T make_pair(T... args)

◆ max_size()

StorableMap::size_type lsst::afw::image::detail::StorableMap::max_size ( ) const
noexcept

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.

Definition at line 48 of file StorableMap.cc.

48 { return _contents.max_size(); }
T max_size(T... args)

◆ operator!=()

bool lsst::afw::image::detail::StorableMap::operator!= ( StorableMap const &  other) const
inlinenoexcept

Test for map equality.

Two StorableMap objects are considered equal if they map the same keys to the same values.

Definition at line 234 of file StorableMap.h.

234 { return !(*this == other); }

◆ operator=() [1/2]

StorableMap & lsst::afw::image::detail::StorableMap::operator= ( StorableMap &&  other)
default

◆ operator=() [2/2]

StorableMap & lsst::afw::image::detail::StorableMap::operator= ( StorableMap const &  other)
default

◆ operator==()

bool lsst::afw::image::detail::StorableMap::operator== ( StorableMap const &  other) const
noexcept

Test for map equality.

Two StorableMap objects are considered equal if they map the same keys to the same values.

Definition at line 52 of file StorableMap.cc.

52 { return _contents == other._contents; }

◆ size()

StorableMap::size_type lsst::afw::image::detail::StorableMap::size ( ) const
noexcept

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

Definition at line 44 of file StorableMap.cc.

44 { return _contents.size(); }
T size(T... args)

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