FindOne.h

Go to the documentation of this file.

#ifndef canvas_Persistency_Common_FindOne_h
#define canvas_Persistency_Common_FindOne_h
// FindOne
//
// A smart query object used as the main way of accessing associated
// objects in a one-to-one association.
//
// Given an Assns associating A with B (or B with A) (possibly with an
// associated data object D) and a source ACOLL of A objects to be
// found in the Assns, allow indexed access to the B and/or D objects
// associated with the A objects in ACOLL.
//
// Interface.
//
// For ease of understanding, the interface is presented here; reading
// the rest of the header is not for the faint of heart.
//
// Notes:
//
// * ProdB and Data (if needed) are the only template arguments that
// must be specified when constructing a FindOne. Any other
// items are deducible from arguments.
//
// * An attempt to create a FindOne where one of the listed
// A objects actually has multiple B objects associated with it will
// result in an exception: use FindMany{,P} instead.
//
// * The FindOne needs a source of objects of type A, a
// data container (e.g. event and an input tag corresponding to the
// underlying association collection from which to create itself.
//
// * When constructed, the FindOne will obtain and
// interrogate the correct Assns and provide access to the B (and/or D)
// object(s) associated with each supplied A object in the order in
// which the A objects were specified.
//
// * If the specified A does not have an associated B or D then the
// cet::maybe_ref will be invalid.
//
// * If the required association collection has an extra data object D
// with each association then it *must* be specified as a template
// argument, even if it is not relevant to the current query.
//
// * *All* indexed accessors (at(), data(), get()) are bounds-checked.
//
// Useful type aliases.
//
// using assoc_t = ProdB;
// using data_t = Data;
// using size_type = typename std::vector<assoc_t const*>::size_type; // FindOne
// using size_type = typename std::vector<art::Ptr<assoc_t> >::size_type; // FindOneP
//
// Constructors.
//
// // From Handle or ValidHandle to collection of A.
// FindOne<ProdB>(Handle<ProdAColl> const&,
//                DataContainer const&,
//                InputTag const&);
// FindOne<ProdB, Data>(Handle<ProdAColl> const&,
//                      DataContainer const&,
//                      InputTag const&);
//
// // From sequence of pointer to A (including View<A>).
// FindOne<ProdB>(View<ProdA> const&,
//                DataContainer const&,
//                InputTag const&);
// FindOne<ProdB, Data>(View<ProdA> const&,
//                      DataContainer const&,
//                      InputTag const&);
//
// // From arbitrary sequence of Ptr<A>.
// FindOne<ProdB>(PtrProdAColl const&,
//                DataContainer const&,
//                InputTag const&);
// FindOne<ProdB, Data>(PtrProdAColl const&,
//                      DataContainer const&,
//                      InputTag const&);
//
// // From an initializer list of Ptr<A>.
// FindOne<ProdB>(<brace-enclosed initializer list>,
//                DataContainer const&,
//                InputTag const&);
// FindOne<ProdB, Data>(<brace-enclosed initializer list>,
//                      DataContainer const&,
//                      InputTag const&);
//
// Modifiers.
//
// <NONE>.
//
// Accessors.
//
// size_type size() const;
// cet::maybe_ref<assoc_t const> at(size_type) const; // FindOne
// art::Ptr<assoc_t> const& at(size_type) const; // FindOneP
// cet::maybe_ref<data_t const> data(size_type) const;
// void get(size_type,
//          cet::maybe_ref<assoc_t const>&) const; // FindOne
// void get(size_type,
//          art::Ptr<assoc_t>&) const; // FindOneP
// void get(size_type,
//          cet::maybe_ref<assoc_t const>&,
//          cet::maybe_ref<data_t const>&)
//   const; // *Must* be used for FindOne<ProdB, Data>.
// void get(size_type,
//          art::Ptr<assoc_t>&,
//          cet::maybe_ref<data_t const>&)
//   const; // *Must* be used for FindOneP<ProdB, Data>.
//
// Comparison operations.
//
// bool operator == (FindOne const& other) const;
//
#include "canvas/Persistency/Common/Assns.h"
#include "canvas/Persistency/Common/Ptr.h"
#include "canvas/Persistency/Common/detail/IPRHelper.h"
#include "canvas/Persistency/Common/detail/is_handle.h"
#include "canvas/Utilities/InputTag.h"
#include "cetlib/maybe_ref.h"

#include <initializer_list>
#include <vector>

/* #undef ART_IPR_BY_PTR */

namespace art {
  // General template
  template <typename ProdB, typename DATA = void>
  class FindOne;

  // Specialization.
  template <typename ProdB>
  class FindOne<ProdB, void>;
}

// Implementation of the specialization.
template <typename ProdB>
class art::FindOne<ProdB, void>
{
public:
  using assoc_t = ProdB;

#ifdef ART_IPR_BY_PTR
  using bColl_t = std::vector<Ptr<assoc_t>>;
#else
  using bColl_t = std::vector<ProdB const*>;
#endif
  using value_type = typename bColl_t::value_type;
  using size_type = typename bColl_t::size_type;
  using difference_type = typename bColl_t::difference_type;
  using const_reference = typename bColl_t::const_reference;
  using reference = typename bColl_t::reference;

  template <typename Handle, typename DataContainer, typename Tag>
  FindOne(
    Handle const& aCollection,
    DataContainer const& dc,
    Tag const& tag,
    std::enable_if_t<detail::is_handle_v<Handle>>* = nullptr);

  template <typename ProdAColl, typename DataContainer, typename Tag>
  FindOne(
    ProdAColl const& view,
    DataContainer const& dc,
    Tag const& tag,
    std::enable_if_t<std::is_pointer_v<typename ProdAColl::value_type>>* =
      nullptr);

  template <typename PtrProdAColl, typename DataContainer, typename Tag>
  FindOne(
    PtrProdAColl const& aPtrColl,
    DataContainer const& dc,
    Tag const& tag,
    std::enable_if_t<std::is_same_v<
      typename PtrProdAColl::value_type,
      art::Ptr<typename PtrProdAColl::value_type::value_type>>>* =
      nullptr);

  template <typename ProdA, typename DataContainer, typename Tag>
  FindOne(std::initializer_list<Ptr<ProdA>> const& ptrs,
                       DataContainer const& dc,
                       Tag const& tag);

  // Is this a valid query (did we find an Assns)?
  bool isValid() const;

  // Number of query results
  size_type size() const;

  // Associated item by index (bounds-checked).
#ifdef ART_IPR_BY_PTR
  Ptr<assoc_t> const& at(size_type i) const;
  void get(size_type i, Ptr<assoc_t> & item) const;
#else
  cet::maybe_ref<assoc_t const> at(size_type i) const;
  void get(size_type i, cet::maybe_ref<assoc_t const> & item) const;
#endif
  bool operator==(FindOne<ProdB, void> const& other) const;

protected:
  FindOne() = default;
  bColl_t& bCollection() { return bCollection_; }

  void setStoredException(std::shared_ptr<art::Exception const> && e);
  void throwIfInvalid() const;

private:
  bColl_t bCollection_{};
  std::shared_ptr<art::Exception const> storedException_{};
};

template <typename ProdB, typename Data>
class art::FindOne : private art::FindOne<ProdB, void>
{
private:
  using base = FindOne<ProdB, void>;

public:
  using dataColl_t = std::vector<Data const*>;
  using value_type = typename base::value_type;
  using size_type = typename base::size_type;
  using difference_type = typename base::difference_type;
  using const_reference = typename base::const_reference;
  using reference = typename base::reference;
  using assoc_t = typename base::assoc_t;

  using data_const_pointer = Data const*;
  using data_const_reference = Data const&;
  using data_reference = Data&;
  using data_t = Data;

  template <typename Handle, typename DataContainer, typename Tag>
  FindOne(
    Handle const& aCollection,
    DataContainer const& dc,
    Tag const& tag,
    std::enable_if_t<detail::is_handle_v<Handle>>* = nullptr);

  template <typename ProdAColl, typename DataContainer, typename Tag>
  FindOne(
    ProdAColl const& view,
    DataContainer const& dc,
    Tag const& tag,
    std::enable_if_t<std::is_pointer_v<typename ProdAColl::value_type>>* =
      nullptr);

  template <typename PtrProdAColl, typename DataContainer, typename Tag>
  FindOne(
    PtrProdAColl const& aPtrColl,
    DataContainer const& dc,
    Tag const& tag,
    std::enable_if_t<std::is_same_v<
      typename PtrProdAColl::value_type,
      art::Ptr<typename PtrProdAColl::value_type::value_type>>>* = nullptr);

  template <typename ProdA, typename DataContainer, typename Tag>
  FindOne(std::initializer_list<Ptr<ProdA>> const& ptrs,
                       DataContainer const& dc,
                       Tag const& tag);

  using base::at;
  using base::get;
  using base::isValid;
  using base::size;

  // Association extra-data object by index (bounds-checked).
  cet::maybe_ref<Data const> data(size_type i) const;

  // Associated item and extra-data object by index (bounds-checked).
  void get(size_type i,
#ifdef ART_IPR_BY_PTR
           art::Ptr<assoc_t> & item,
#else
           cet::maybe_ref<assoc_t const> & item,
#endif
           cet::maybe_ref<Data const> & data) const;

  bool operator==(FindOne<ProdB, Data> const& other) const;

private:
  dataColl_t dataCollection_{};
};

// Base class implementation.
template <typename ProdB>
template <typename Handle, typename DataContainer, typename Tag>
art::FindOne<ProdB, void>::FindOne(
  Handle const& aCollection,
  DataContainer const& dc,
  Tag const& tag,
  std::enable_if_t<detail::is_handle_v<Handle>>*)
{
  using ProdA = typename Handle::element_type::value_type;
  detail::IPRHelper<ProdA, ProdB, void, void, DataContainer> finder{
    dc, detail::input_tag<ProdA, ProdB, void>(tag)};
  storedException_ = finder(*aCollection, bCollection_);
}

template <typename ProdB>
template <typename ProdAColl, typename DataContainer, typename Tag>
art::FindOne<ProdB, void>::FindOne(
  ProdAColl const& view,
  DataContainer const& dc,
  Tag const& tag,
  std::enable_if_t<std::is_pointer_v<typename ProdAColl::value_type>>*)
{
  using ProdA =
    std::remove_const_t<std::remove_pointer_t<typename ProdAColl::value_type>>;
  detail::IPRHelper<ProdA, ProdB, void, void, DataContainer> finder{
    dc, detail::input_tag<ProdA, ProdB, void>(tag)};
  storedException_ = finder(view, bCollection_);
}

template <typename ProdB>
template <typename PtrProdAColl, typename DataContainer, typename Tag>
art::FindOne<ProdB, void>::FindOne(
  PtrProdAColl const& aPtrColl,
  DataContainer const& dc,
  Tag const& tag,
  std::enable_if_t<std::is_same_v<
    typename PtrProdAColl::value_type,
    art::Ptr<typename PtrProdAColl::value_type::value_type>>>*)
{
  using ProdA = typename PtrProdAColl::value_type::value_type;
  detail::IPRHelper<ProdA, ProdB, void, void, DataContainer> finder{
    dc, detail::input_tag<ProdA, ProdB, void>(tag)};
  storedException_ = finder(aPtrColl, bCollection_);
}

template <typename ProdB>
template <typename ProdA, typename DataContainer, typename Tag>
art::FindOne<ProdB, void>::FindOne(
  std::initializer_list<Ptr<ProdA>> const& ptrs,
  DataContainer const& dc,
  Tag const& tag)
{
  detail::IPRHelper<ProdA, ProdB, void, void, DataContainer> finder{
    dc, detail::input_tag<ProdA, ProdB, void>(tag)};
  storedException_ = finder(ptrs, bCollection_);
}

template <typename ProdB>
inline auto
art::FindOne<ProdB, void>::size() const -> size_type
{
  throwIfInvalid();
  return bCollection_.size();
}

template <typename ProdB>
inline bool
art::FindOne<ProdB, void>::isValid() const
{
  return storedException_.get() == nullptr;
}

template <typename ProdB>
inline auto
art::FindOne<ProdB, void>::at(size_type const i) const
  ->
#ifdef ART_IPR_BY_PTR
  art::Ptr<assoc_t> const&
#else
  cet::maybe_ref<assoc_t const>
#endif
{
  throwIfInvalid();
#ifdef ART_IPR_BY_PTR
  return bCollection_.at(i);
#else
  return cet::maybe_ref<assoc_t const>{*bCollection_.at(i)};
#endif
}

template <typename ProdB>
inline void
art::FindOne<ProdB, void>::get(size_type const i,
#ifdef ART_IPR_BY_PTR
                                            Ptr<assoc_t>& item
#else
                                            cet::maybe_ref<assoc_t const>& item
#endif
                                            ) const
{
  throwIfInvalid();
#ifdef ART_IPR_BY_PTR
  item = bCollection_.at(i);
#else
  item.reseat(*bCollection_.at(i));
#endif
}

template <typename ProdB>
inline bool
art::FindOne<ProdB, void>::operator==(
  FindOne<ProdB, void> const& other) const
{
  throwIfInvalid();
  return bCollection_ == other.bCollection_;
}

template <typename ProdB>
inline void
art::FindOne<ProdB, void>::setStoredException(
  std::shared_ptr<art::Exception const>&& e)
{
  storedException_ = std::move(e);
}

template <typename ProdB>
inline void
art::FindOne<ProdB, void>::throwIfInvalid() const
{
  if (!isValid()) {
    throw Exception(
      errors::LogicError, "Invalid FindOne", *storedException_)
      << "Attempt to use a FindOne where the underlying "
         "art::Assns product was not found.";
  }
}

// Derived class implementation.
template <typename ProdB, typename Data>
template <typename Handle, typename DataContainer, typename Tag>
art::FindOne<ProdB, Data>::FindOne(
  Handle const& aCollection,
  DataContainer const& dc,
  Tag const& tag,
  std::enable_if_t<detail::is_handle_v<Handle>>*)
{
  using ProdA = typename Handle::element_type::value_type;
  detail::IPRHelper<ProdA, ProdB, Data, dataColl_t, DataContainer> finder{
    dc, detail::input_tag<ProdA, ProdB, Data>(tag)};
  base::setStoredException(
    finder(*aCollection, base::bCollection(), dataCollection_));
}

template <typename ProdB, typename Data>
template <typename ProdAColl, typename DataContainer, typename Tag>
art::FindOne<ProdB, Data>::FindOne(
  ProdAColl const& view,
  DataContainer const& dc,
  Tag const& tag,
  std::enable_if_t<std::is_pointer_v<typename ProdAColl::value_type>>*)
{
  using ProdA =
    std::remove_const_t<std::remove_pointer_t<typename ProdAColl::value_type>>;
  detail::IPRHelper<ProdA, ProdB, Data, dataColl_t, DataContainer> finder{
    dc, detail::input_tag<ProdA, ProdB, Data>(tag)};
  base::setStoredException(finder(view, base::bCollection(), dataCollection_));
}

template <typename ProdB, typename Data>
template <typename PtrProdAColl, typename DataContainer, typename Tag>
art::FindOne<ProdB, Data>::FindOne(
  PtrProdAColl const& aPtrColl,
  DataContainer const& dc,
  Tag const& tag,
  std::enable_if_t<std::is_same_v<
    typename PtrProdAColl::value_type,
    art::Ptr<typename PtrProdAColl::value_type::value_type>>>*)
{
  using ProdA = typename PtrProdAColl::value_type::value_type;
  detail::IPRHelper<ProdA, ProdB, Data, dataColl_t, DataContainer> finder{
    dc, detail::input_tag<ProdA, ProdB, Data>(tag)};
  base::setStoredException(
    finder(aPtrColl, base::bCollection(), dataCollection_));
}

template <typename ProdB, typename Data>
template <typename ProdA, typename DataContainer, typename Tag>
art::FindOne<ProdB, Data>::FindOne(
  std::initializer_list<Ptr<ProdA>> const& ptrs,
  DataContainer const& dc,
  Tag const& tag)
{
  detail::IPRHelper<ProdA, ProdB, Data, dataColl_t, DataContainer> finder{
    dc, detail::input_tag<ProdA, ProdB, Data>(tag)};
  base::setStoredException(finder(ptrs, base::bCollection(), dataCollection_));
}

template <typename ProdB, typename Data>
inline cet::maybe_ref<Data const>
art::FindOne<ProdB, Data>::data(size_type i) const
{
  base::throwIfInvalid();
  return cet::maybe_ref<Data const>{*dataCollection_.at(i)};
}

template <typename ProdB, typename Data>
inline void
art::FindOne<ProdB, Data>::get(size_type const i,
#ifdef ART_IPR_BY_PTR
                      Ptr<assoc_t>& item,
#else
                      cet::maybe_ref<assoc_t const>& item,
#endif
                      cet::maybe_ref<Data const>& data) const
{
  base::get(i, item); // Will check validity.
  data.reseat(*dataCollection_.at(i));
}

template <typename ProdB, typename Data>
inline bool
art::FindOne<ProdB, Data>::operator==(FindOne<ProdB, Data> const& other) const
{
  return this->base::operator==(other) && // Will check validity.
         dataCollection_ == other.dataCollection_;
}

#undef ART_IPR_BY_PTR

#endif /* canvas_Persistency_Common_FindOne_h */

// Local Variables:
// mode: c++
// End: