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/detail/IPRHelper.h"
#include "canvas/Persistency/Common/detail/is_handle.h"
#include "canvas/Persistency/Common/Assns.h"
#include "canvas/Persistency/Common/Ptr.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<Handle>::value>* = 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<typename ProdAColl::value_type>::value>* = 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<typename PtrProdAColl::value_type,
                       art::Ptr<typename PtrProdAColl::value_type::value_type> >::value>* = 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<Handle>::value>* = 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<typename ProdAColl::value_type>::value>* = 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<typename PtrProdAColl::value_type,
                       art::Ptr<typename PtrProdAColl::value_type::value_type> >::value>* = nullptr);

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

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

  // 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<Handle>::value>*)
{
  using ProdA = typename Handle::element_type::value_type;
  detail::IPRHelper<ProdA, ProdB, void, void, DataContainer> finder{dc, detail::input_tag(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<typename ProdAColl::value_type>::value>*)
{
  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(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<typename PtrProdAColl::value_type,
                     art::Ptr<typename PtrProdAColl::value_type::value_type> >::value>*)
{
  using ProdA = typename PtrProdAColl::value_type::value_type;
  detail::IPRHelper<ProdA, ProdB, void, void, DataContainer> finder{dc, detail::input_tag(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(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<Handle>::value>*)
{
  using ProdA = typename Handle::element_type::value_type;
  detail::IPRHelper<ProdA, ProdB, Data, dataColl_t, DataContainer> finder{dc, detail::input_tag(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<typename ProdAColl::value_type>::value>*)
{
  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(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<typename PtrProdAColl::value_type,
                     art::Ptr<typename PtrProdAColl::value_type::value_type> >::value>*)
{
  using ProdA = typename PtrProdAColl::value_type::value_type;
  detail::IPRHelper<ProdA, ProdB, Data, dataColl_t, DataContainer> finder{dc, detail::input_tag(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(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: