StorableMap.h

Go to the documentation of this file.

// -*- LSST-C++ -*-
/*
 * This file is part of afw.
 *
 * Developed for the LSST Data Management System.
 * This product includes software developed by the LSST Project
 * (https://www.lsst.org).
 * See the COPYRIGHT file at the top-level directory of this distribution
 * for details of code ownership.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

#ifndef LSST_AFW_IMAGE_DETAIL_STORABLEMAP_H
#define LSST_AFW_IMAGE_DETAIL_STORABLEMAP_H

#include <exception>
#include <memory>
#include <sstream>
#include <string>
#include <type_traits>
#include <unordered_map>
#include <utility>

#include "lsst/pex/exceptions.h"
#include "lsst/afw/typehandling/Key.h"
#include "lsst/afw/typehandling/Storable.h"

namespace lsst {
namespace afw {
namespace image {
namespace detail {

class StorableMap final {
public:
    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*;

private:
    using _Impl = std::unordered_map<key_type, mapped_type>;

public:
    // These definitions may be replaced with adapters if we need
    // StorableMap's iterators to behave differently from _Impl's.
    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;

    StorableMap();
    StorableMap(StorableMap const& other);
    StorableMap(StorableMap&& other);
    StorableMap& operator=(StorableMap const& other);
    StorableMap& operator=(StorableMap&& other);
    ~StorableMap() noexcept;

    StorableMap(std::initializer_list<value_type> init);

    template <typename T>
    std::shared_ptr<T> at(Key<std::shared_ptr<T>> const& key) const {
        static_assert(std::is_base_of<Storable, T>::value,
                      "Can only retrieve pointers to subclasses of Storable.");
        static_assert(std::is_const<T>::value,
                      "Due to implementation constraints, pointers to non-const are not supported.");
        try {
            // unordered_map::at(Key<Storable>) does not do any type-checking.
            mapped_type const& pointer = _contents.at(key);

            // Null pointer stored; skip dynamic_cast because won't change result.
            if (pointer == nullptr) {
                return nullptr;
            }

            std::shared_ptr<T> typedPointer = std::dynamic_pointer_cast<T>(pointer);
            // shared_ptr can be empty without being null. dynamic_pointer_cast
            // only promises result of failed cast is empty, so test for that.
            if (typedPointer.use_count() > 0) {
                return typedPointer;
            } else {
                std::stringstream message;
                message << "Key " << key << " not found, but a key labeled " << key.getId() << " is present.";
                throw LSST_EXCEPT(pex::exceptions::OutOfRangeError, message.str());
            }
        } catch (std::out_of_range const&) {
            std::throw_with_nested(LSST_EXCEPT(pex::exceptions::OutOfRangeError,
                                               "No key labeled " + key.getId() + " found."));
        }
    }

    size_type size() const noexcept;

    bool empty() const noexcept;

    size_type max_size() const noexcept;

    bool contains(std::string const& key) const;

    template <typename T>
    bool contains(Key<std::shared_ptr<T>> const& key) const {
        static_assert(std::is_base_of<Storable, T>::value,
                      "Can only retrieve pointers to subclasses of Storable.");
        static_assert(std::is_const<T>::value,
                      "Due to implementation constraints, pointers to non-const are not supported.");
        if (_contents.count(key) > 0) {
            // unordered_map::at(Key<Storable>) does not do any type-checking.
            mapped_type const& pointer = _contents.at(key);

            // Null pointer stored; dynamic_cast will always return null.
            if (pointer == nullptr) {
                return true;
            }

            std::shared_ptr<T> typedPointer = std::dynamic_pointer_cast<T>(pointer);
            // shared_ptr can be empty without being null. dynamic_pointer_cast
            // only promises result of failed cast is empty, so test for that.
            return typedPointer.use_count() > 0;
        } else {
            return false;
        }
    }

    bool operator==(StorableMap const& other) const noexcept;

    bool operator!=(StorableMap const& other) const noexcept { return !(*this == other); }

    void clear() noexcept;

    template <typename T>
    bool insert(Key<std::shared_ptr<T>> const& key, std::shared_ptr<T> const& value) {
        static_assert(std::is_base_of<Storable, T>::value,
                      "Can only store shared pointers to subclasses of Storable.");
        static_assert(std::is_const<T>::value,
                      "Due to implementation constraints, pointers to non-const are not supported.");
        // unordered_map uses Key<shared_ptr<Storable>> internally, so
        // any key with the same ID will block emplacement.
        return _contents.emplace(key, value).second;
    }

    template <typename T>
    std::pair<Key<T>, bool> insert(std::string const& key, T const& value) {
        auto strongKey = typehandling::makeKey<T>(key);
        // Construct return value in advance, so that exception from
        // copying/moving Key is atomic.
        auto result = std::make_pair(strongKey, false);
        result.second = insert(strongKey, value);
        return result;
    }

    template <typename T>
    bool erase(Key<T> const& key) noexcept {
        // unordered_map::erase(Key<Storable>) does no type checking.
        if (this->contains(key)) {
            return _contents.erase(key) > 0;
        } else {
            return false;
        }
    }

    iterator begin() noexcept;
    const_iterator begin() const noexcept;
    const_iterator cbegin() const noexcept { return begin(); }

    iterator end() noexcept;
    const_iterator end() const noexcept;
    const_iterator cend() const noexcept { return end(); }

private:
    _Impl _contents;
};

}  // namespace detail
}  // namespace image
}  // namespace afw
}  // namespace lsst

#endif