FindMany.h

Go to the documentation of this file.

#ifndef canvas_Persistency_Common_FindMany_h
#define canvas_Persistency_Common_FindMany_h
////////////////////////////////////////////////////////////////////////
// FindMany
//
// A smart query object used as the main way of accessing associated
// objects in an association (one-to-one, one-to-many or many-to-many).
//
// 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. Compare with
// the corresponding interface for FindOne.
//
// Notes:
//
// * ProdB and Data are the only template arguments that must be
// specified when constructing a FindMany. Any other items
// are deducible from arguments.
//
// * The FindMany needs a source of objects of type A, a
// data container (e.g. an event) and an input tag corresponding to
// the underlying association collection from which to create itself.
//
// * When constructed, the FindMany 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
// vector will be empty.
//
// * 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. Note that, because of the possible one-to-many
// association, these functions all return (or take as a reference in
// the case of get()) vectors, viz:
//   * at() returns a const reference to a vector of const* (FindMany)
//   or Ptr (FindManyP).
//   * data returns a const reference to a vector of data objects.
//   * get() takes references to a vector of const* or Ptr as
//   appropriate, and a vector of data objects (if the data type is not
//   void).
//
// Useful type aliases.
//
// using assoc_t = ProdB;
// using data_t = Data;
// using value_type = std::vector<assoc_t const*>; // FindMany
// using value_type = std::vector<art::Ptr<assoc_t>>; // FindManyP
// using size_type = typename std::vector<value_type>::size_type;
// using const_reference = value_type const&;
// using reference = value_type&;
// using data_const_reference = typename std::vector<data_t const*> const&;
// using data_reference = typename std::vector<data_t const*>&;
//
// Constructors.
//
// // From Handle or ValidHandle to collection of A.
// FindMany<ProdB>(Handle<ProdAColl> const&,
//                 DataContainer const&,
//                 InputTag const&);
// FindMany<ProdB, Data>(Handle<ProdAColl> const&,
//                       DataContainer const&,
//                       InputTag const&);
//
// // From sequence of pointer to A (including View<A>).
// FindMany<ProdB>(View<ProdA> const&,
//                 DataContainer const&,
//                 InputTag const&);
// FindMany<ProdB, Data>(View<ProdA> const&,
//                       DataContainer const&,
//                       InputTag const&);
//
// // From arbitrary sequence of Ptr<A>.
// FindMany<ProdB>(PtrProdAColl const&,
//                 DataContainer const&,
//                 InputTag const&);
// FindMany<ProdB, Data>(PtrProdAColl const&,
//                       DataContainer const&,
//                       InputTag const&);
//
// // From an initializer list of Ptr<A>.
// FindMany<ProdB>(<brace-enclosed initializer list>,
//                 DataContainer const&,
//                 InputTag const&);
// FindMany<ProdB, Data>(<brace-enclosed initializer list>,
//                       DataContainer const&,
//                       InputTag const&);
//
// Modifiers.
//
// <NONE>.
//
// Accessors.
//
// size_type size() const;
// const_reference at(size_type) const;
// const_data_reference data(size_type) const;
// size_type get(size_type,
//               reference)
//   const; // Returns number of elements appended.
// size_type get(size_type,
//               reference,
//               data_reference)
//   const; // *Must* be used for FindMany<ProdB, Data>.
//
// Comparison operations.
//
// bool operator == (FindMany 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/Persistency/Provenance/ProductToken.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 FindMany;

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

////////////////////////////////////////////////////////////////////////
// Implementation of the specialization.
template <typename ProdB>
class art::FindMany<ProdB, void>
{
public:
#ifdef ART_IPR_BY_PTR
  using bColl_t = std::vector<std::vector<Ptr<ProdB>>>;
#else
  using bColl_t = std::vector<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;

  using assoc_t = ProdB;

  template <typename Handle, typename DataContainer, typename Tag>
  FindMany(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>
  FindMany(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>
  FindMany(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>
  FindMany(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).
  const_reference at(size_type i) const;

  size_type get(size_type i, reference item) const;

  bool operator==(FindMany<ProdB, void> const& other) const;

protected:
  FindMany() = 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_{nullptr};
};

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

public:
  using dataColl_t = std::vector<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 = typename dataColl_t::const_pointer;
  using data_const_reference = typename dataColl_t::const_reference;
  using data_reference = typename dataColl_t::reference;

  using data_t = Data;

  template <typename Handle, typename DataContainer, typename Tag>
  FindMany(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>
  FindMany(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>
  FindMany(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>
  FindMany(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).
  data_const_reference data(size_type i) const;

  // Associated item and extra-data object by index (bounds-checked).
  size_type get(size_type i, reference item, data_reference data) const;

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

private:
  dataColl_t dataCollection_{};
};

////////////////////////////////////////////////////////////////////////
// Base class implementation.
template <typename ProdB>
template <typename Handle, typename DataContainer, typename Tag>
art::FindMany<ProdB, void>::FindMany(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<ProdA, ProdB, void>(tag)};
  storedException_ = finder(*aCollection, bCollection_);
}

template <typename ProdB>
template <typename ProdAColl, typename DataContainer, typename Tag>
art::FindMany<ProdB, void>::FindMany(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::FindMany<ProdB, void>::FindMany(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::FindMany<ProdB, void>::FindMany(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::FindMany<ProdB, void>::size() const -> size_type
{
  throwIfInvalid();
  return bCollection_.size();
}

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

template <typename ProdB>
inline auto art::FindMany<ProdB, void>::at(size_type const i) const
  -> const_reference
{
  throwIfInvalid();
  return bCollection_.at(i);
}

template <typename ProdB>
inline auto art::FindMany<ProdB, void>::get(size_type const i, reference item) const -> size_type
{
  throwIfInvalid();
  const_reference ref(bCollection_.at(i));
  item.insert(item.end(), ref.begin(), ref.end());
  return ref.size();
}

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

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

template <typename ProdB>
inline void art::FindMany<ProdB, void>::throwIfInvalid() const
{
  if (!isValid()) {
    throw Exception(
      errors::LogicError, "Invalid FindMany", *storedException_)
      << "Attempt to use a FindMany 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::FindMany<ProdB, Data>::FindMany(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<ProdA, ProdB, void>(tag)};
  base::setStoredException(
    finder(*aCollection, base::bCollection(), dataCollection_));
}

template <typename ProdB, typename Data>
template <typename ProdAColl, typename DataContainer, typename Tag>
art::FindMany<ProdB, Data>::FindMany(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, void>(tag)};
  base::setStoredException(finder(view, base::bCollection(), dataCollection_));
}

template <typename ProdB, typename Data>
template <typename PtrProdAColl, typename DataContainer, typename Tag>
art::FindMany<ProdB, Data>::FindMany(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::FindMany<ProdB, Data>::FindMany(
  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 auto art::FindMany<ProdB, Data>::data(size_type const i) const -> data_const_reference
{
  base::throwIfInvalid();
  return dataCollection_.at(i);
}

template <typename ProdB, typename Data>
inline auto art::FindMany<ProdB, Data>::get(size_type const i,
                      reference item,
                      data_reference data) const -> size_type
{
  size_type result = base::get(i, item); // Will check validity.
  data_const_reference ref(dataCollection_.at(i));
  data.insert(data.end(), ref.begin(), ref.end());
  ;
  return result;
}

template <typename ProdB, typename Data>
inline bool art::FindMany<ProdB, Data>::operator==(FindMany<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_FindMany_h */

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