AssociatedData.h

Go to the documentation of this file.

#ifndef LARDATA_RECOBASEPROXY_PROXYBASE_ASSOCIATEDDATA_H
#define LARDATA_RECOBASEPROXY_PROXYBASE_ASSOCIATEDDATA_H

// LArSoft libraries
#include "larcorealg/CoreUtils/MetaUtils.h" // util::is_not_same<>
#include "lardata/RecoBaseProxy/ProxyBase/AssnsNodeAsTuple.h"
#include "lardata/RecoBaseProxy/ProxyBase/AssnsTraits.h"
#include "lardata/Utilities/CollectionView.h"
#include "lardata/Utilities/TupleLookupByTag.h" // util::add_tag_t, ...

// framework libraries
#include "canvas/Persistency/Common/Assns.h"
#include "canvas/Persistency/Common/Ptr.h"

// C/C++ standard libraries
#include <vector>
// #include <tuple> // std::tuple_element_t<>, std::get()
#include <algorithm> // std::min()
#include <cassert>
#include <cstdlib>     // std::size_t
#include <iterator>    // std::distance(), std::forward_iterator_tag, ...
#include <memory>      // std::addressof()
#include <type_traits> // std::is_same<>, std::enable_if_t<>, ...
#include <utility>     // std::forward(), std::declval(), ...

namespace proxy {

  //----------------------------------------------------------------------------
  //----------------------------------------------------------------------------
  namespace details {

    //--------------------------------------------------------------------------
    //---  general infrastructure
    //--------------------------------------------------------------------------

    template <typename Iter, typename DataIter, typename ValueType = typename DataIter::value_type>
    class IteratorWrapperBase : private DataIter {
    protected:
      using data_iterator_t = DataIter;

    public:
      using iterator = Iter; 

      using typename data_iterator_t::difference_type;
      using value_type = ValueType;
      using pointer = std::add_pointer_t<value_type>;
      using reference = std::add_lvalue_reference_t<value_type>;
      using iterator_category = std::forward_iterator_tag;

      IteratorWrapperBase() = default;

      IteratorWrapperBase(data_iterator_t const& from) : data_iterator_t(from) {}

      iterator& operator++()
      {
        data_iterator_t::operator++();
        return asIterator();
      }

      bool operator!=(data_iterator_t const& other) const { return other != asDataIterator(); }

      bool operator!=(iterator const& other) const { return operator!=(other.asDataIterator()); }

      auto operator[](std::size_t index) const -> decltype(auto)
      {
        return asIterator().transform(asDataIterator() + index);
      }

      auto operator*() const -> decltype(auto) { return asIterator().transform(asDataIterator()); }

      auto operator->() const -> decltype(auto) { return makeValuePointer(operator*()); }

    protected:
      static auto transform(data_iterator_t const&) -> decltype(auto)
      {
        return data_iterator_t::operator*();
      }

      data_iterator_t const& asDataIterator() const
      {
        return static_cast<data_iterator_t const&>(*this);
      }

    private:
      template <typename Value>
      class ValuePtr {
        Value value; 
      public:
        ValuePtr(Value const& value) : value(value) {}
        auto operator->() const -> decltype(auto) { return std::addressof(value); }
      }; // class ValuePtr<>
      template <typename Value>
      static ValuePtr<Value> makeValuePointer(Value&& value)
      {
        return {std::forward<Value>(value)};
      }

      iterator const& asIterator() const { return static_cast<iterator const&>(*this); }
      iterator& asIterator() { return static_cast<iterator&>(*this); }

    }; // IteratorWrapperBase<>

#if 0

    template <std::size_t N, typename TupleIter>
    class tuple_element_iterator:
      public IteratorWrapperBase<
        tuple_element_iterator<N, TupleIter>,
        TupleIter,
        std::tuple_element_t<N, typename TupleIter::value_type>
        >
    {
      using base_iterator_t = IteratorWrapperBase<
        tuple_element_iterator<N, TupleIter>,
        TupleIter,
        std::tuple_element_t<N, typename TupleIter::value_type>
        >;

        public:
      using base_iterator_t::base_iterator_t;

      tuple_element_iterator(base_iterator_t const& from)
        : base_iterator_t(from) {}

      static auto transform(TupleIter const& v) -> decltype(auto)
        {return std::get<N>(*v); }

    }; // tuple_element_iterator

#endif // 0
    //--------------------------------------------------------------------------
    //--- BEGIN iterators for art::Assns
    //--------------------------------------------------------------------------

    //--------------------------------------------------------------------------

    template <typename ArtAssnsIterValue>
    class AssnsNode : private ArtAssnsIterValue {

      using base_t = ArtAssnsIterValue;            
      using this_t = AssnsNode<ArtAssnsIterValue>; 
      using node_t = ArtAssnsIterValue;            

      using assns_node_traits_t = lar::util::assns_traits<node_t>;

    public:
      using main_t = typename assns_node_traits_t::left_t;

      using value_t = typename assns_node_traits_t::right_t;

      using data_t = typename assns_node_traits_t::data_t;

      using mainptr_t = typename assns_node_traits_t::leftptr_t;

      using valueptr_t = typename assns_node_traits_t::rightptr_t;

      using dataptr_t = typename assns_node_traits_t::dataptr_t;


      valueptr_t const& valuePtr() const { return base_t::second; }

      value_t const& value() const { return *valuePtr(); }



      mainptr_t const& mainPtr() const { return base_t::first; }

      main_t const& main() const { return *mainPtr(); }



      // the templates are needed to activate "SFINAE" on std::enable_if
      template <typename Node = node_t>
      static constexpr bool hasMetadata()
      {
        return lar::util::assns_has_metadata_v<Node>;
      }

      template <typename Node = node_t>
      std::enable_if_t<hasMetadata<Node>(), dataptr_t> dataPtr() const
      {
        return base_t::data;
      }

      // this is even more complicate, since if `data_t` is void we can't write
      // `data_t const&` as type of enable_if, because it does not depend on
      // templates and therefore it may be unconditionally evaluated;
      // and C++ does not like references to `void`...
      template <typename Node = node_t>
      std::enable_if_t<hasMetadata<Node>(), typename lar::util::assns_traits<Node>::data_t const&>
      data() const
      {
        return *dataPtr();
      }



      operator valueptr_t const&() const& { return valuePtr(); }

      operator valueptr_t() const&& { return valuePtr(); }

      value_t const& operator*() const { return value(); }

      valueptr_t operator->() const { return valuePtr(); }

      auto key() const -> decltype(auto) { return valuePtr().key(); }

      auto id() const -> decltype(auto) { return valuePtr().id(); }

      static this_t const& makeFrom(node_t const& from) { return static_cast<this_t const&>(from); }

    }; // class AssnsNode<>

    template <typename ArtAssnsIterValue>
    bool operator==(AssnsNode<ArtAssnsIterValue> const& A,
                    typename AssnsNode<ArtAssnsIterValue>::valueptr_t const& B)
    {
      return A.valuePtr() == B;
    }
    template <typename ArtAssnsIterValue>
    bool operator==(typename AssnsNode<ArtAssnsIterValue>::valueptr_t const& A,
                    AssnsNode<ArtAssnsIterValue> const& B)
    {
      return A == B.valuePtr();
    }
    template <typename ArtAssnsIterValue>
    bool operator!=(AssnsNode<ArtAssnsIterValue> const& A,
                    typename AssnsNode<ArtAssnsIterValue>::valueptr_t const& B)
    {
      return A.valuePtr() != B;
    }
    template <typename ArtAssnsIterValue>
    bool operator!=(typename AssnsNode<ArtAssnsIterValue>::valueptr_t const& A,
                    AssnsNode<ArtAssnsIterValue> const& B)
    {
      return A != B.valuePtr();
    }

    template <typename ArtAssnsIterValue>
    AssnsNode<ArtAssnsIterValue> const& makeAssnsNode(ArtAssnsIterValue const& from)
    {
      return AssnsNode<ArtAssnsIterValue>::makeFrom(from);
    }

  } // namespace details
} // namespace proxy

// we interrupt this namespace for an urgent specialization...
namespace lar {
  namespace util {

    // specialization for the art node wrapper
    template <typename ArtAssnsIterValue>
    struct assns_metadata_type<proxy::details::AssnsNode<ArtAssnsIterValue>>
      : assns_metadata_type<ArtAssnsIterValue> {};

  } // namespace util
} // namespace lar

// back to what we were doing:
namespace proxy {
  namespace details {

    //--------------------------------------------------------------------------
    template <typename ArtAssnsIter>
    struct AssnsIterTraits : public lar::util::assns_traits<typename ArtAssnsIter::value_type> {
      using art_node_t = typename ArtAssnsIter::value_type;
      using node_t = AssnsNode<art_node_t>;
    }; // struct AssnsIterTraits

    template <typename ArtAssnsIter>
    class assns_node_iterator
      : public IteratorWrapperBase<assns_node_iterator<ArtAssnsIter>,
                                   ArtAssnsIter,
                                   typename AssnsIterTraits<ArtAssnsIter>::node_t> {
      using base_iterator_t = IteratorWrapperBase<assns_node_iterator<ArtAssnsIter>,
                                                  ArtAssnsIter,
                                                  typename AssnsIterTraits<ArtAssnsIter>::node_t>;

      using art_assns_iter_t = ArtAssnsIter;
      using traits_t = AssnsIterTraits<art_assns_iter_t>;

      using AssnsNode_t = typename traits_t::node_t;
      using ArtAssnsNode_t = typename traits_t::art_node_t;

    public:
      using base_iterator_t::base_iterator_t;

      assns_node_iterator(base_iterator_t const& from) : base_iterator_t(from) {}

      AssnsNode_t const& info() const { return base_iterator_t::operator*(); }

      AssnsNode_t const& operator()() const { return info(); }

      //--- BEGIN Access to the full association information -------------------

      using main_t = typename AssnsNode_t::main_t;
      using value_t = typename AssnsNode_t::value_t;
      using data_t = typename AssnsNode_t::data_t;
      using mainptr_t = typename AssnsNode_t::mainptr_t;
      using valueptr_t = typename AssnsNode_t::valueptr_t;
      using dataptr_t = typename AssnsNode_t::dataptr_t;

      valueptr_t valuePtr() const { return info().valuePtr(); }

      value_t const& value() const { return info().value(); }

      mainptr_t mainPtr() const { return info().mainPtr(); }

      main_t const& main() const { return info().main(); }

      // see the comments on AssnsNode for the need of all these decorations
      template <typename Node = AssnsNode_t>
      static constexpr bool hasMetadata()
      {
        return lar::util::assns_has_metadata_v<Node>;
      }

      template <typename ArtNode = ArtAssnsNode_t>
      std::enable_if_t<hasMetadata<ArtNode>(), dataptr_t> dataPtr() const
      {
        return info().dataPtr();
      }

      template <typename ArtNode = ArtAssnsNode_t>
      std::enable_if_t<hasMetadata<ArtNode>(),
                       typename lar::util::assns_traits<ArtNode>::data_t const&>
      data() const
      {
        return info().data();
      }

      //--- END Access to the full association information ---------------------

      /*
       * Associations with metadata have an iterator with value type
       * art::AssnsNode, while the value for the ones without have just a
       * std::pair.
       * The std::pair returned by the one without metadata is a reference to an
       * element of the original collection.
       * Instead, the art::AssnsNode returned by the art::Assns iterator is a
       * temporary put together copying information from the original pair
       * collection and from the parallel metadata collection.
       * Therefore, in the first case we can return references to the existing
       * data, while in the latter we can't and we have to return the results by
       * value.
       * In this implementation we compromise and return always the data by
       * value; the values are art pointers, or plain pointers, so the copy
       * should not be extremely taxing. It is possible to change this, at the
       * cost of additional complexity of the implementation.
       */
      static AssnsNode_t const& transform(art_assns_iter_t const& v) { return makeAssnsNode(*v); }

    }; // class assns_node_iterator<>

    //--- END iterators for art::Assns -----------------------------------------

    //--------------------------------------------------------------------------
    //--- stuff for associated data (a form of auxiliary data)
    //--------------------------------------------------------------------------

    template <typename BoundaryIter>
    class BoundaryListRangeBase : private BoundaryIter {
      using boundary_iterator_t = BoundaryIter;

      auto boundaryIter() const { return static_cast<BoundaryIter const&>(*this); }

    public:
      BoundaryListRangeBase(boundary_iterator_t const& it) : boundary_iterator_t(it) {}

      auto begin() const -> decltype(auto) { return *(boundaryIter()); }

      auto end() const -> decltype(auto) { return *(std::next(boundaryIter())); }

    }; // BoundaryListRangeBase<>

    template <typename BoundaryIter>
    class BoundaryListRange : public lar::CollectionView<BoundaryListRangeBase<BoundaryIter>> {
      // A CollectionView can't be constructed except from deriver classes;
      // we define here such a class.

      using rangebase_t = BoundaryListRangeBase<BoundaryIter>;
      using base_t = lar::CollectionView<rangebase_t>;

    public:
      using boundary_iterator_t = BoundaryIter;

      BoundaryListRange(boundary_iterator_t const& iBegin) : base_t(rangebase_t(iBegin)) {}

    }; // class BoundaryListRange<>

    template <typename BoundaryIter>
    BoundaryListRange<BoundaryIter> makeBoundaryListRange(BoundaryIter const& iBegin)
    {
      return {iBegin};
    }

    template <typename BoundaryIter>
    class BoundaryListRangeIterator
      : public IteratorWrapperBase<BoundaryListRangeIterator<BoundaryIter>, BoundaryIter> {
      using base_t = IteratorWrapperBase<BoundaryListRangeIterator<BoundaryIter>, BoundaryIter>;

    public:
      using boundary_iterator_t = BoundaryIter; 

      using rangeview_t = decltype(makeBoundaryListRange(std::declval<boundary_iterator_t>()));

      using value_type = rangeview_t;
      using pointer = std::add_pointer_t<std::decay_t<value_type>>;
      using reference = std::add_lvalue_reference_t<std::decay_t<value_type>>;

      using base_t::base_t; // import constructors (explicitly allowed)

      static auto transform(BoundaryIter const& iter) { return makeBoundaryListRange(iter); }

    }; // class BoundaryListRangeIterator<>

    template <typename Iter>
    class BoundaryList {
      using boundarylist_t = BoundaryList<Iter>;

    public:
      using data_iterator_t = Iter;
      using boundaries_t = std::vector<data_iterator_t>;

      using range_iterator_t = BoundaryListRangeIterator<typename boundaries_t::const_iterator>;

      // BoundaryListRange<data_iterator_t> const&
      using range_ref_t = typename range_iterator_t::value_type;

      using range_t = lar::RangeAsCollection_t<data_iterator_t>;

      explicit BoundaryList(boundaries_t&& boundaries) : boundaries(std::move(boundaries))
      {
        assert(this->boundaries.size() >= 1);
      }

      std::size_t nRanges() const { return boundaries.size() - 1; }
      data_iterator_t const& rangeBegin(std::size_t i) const
      {
        return boundaries[std::min(i, nRanges())];
      }
      data_iterator_t const& rangeEnd(std::size_t i) const { return rangeBegin(i + 1); }

      std::size_t size() const { return nRanges(); }
      range_iterator_t begin() const { return {boundaries.begin()}; }
      range_iterator_t end() const { return {std::prev(boundaries.end())}; }
      range_ref_t rangeRef(std::size_t i) const { return {std::next(boundaries.begin(), i)}; }
      range_t range(std::size_t i) const
      {
        return lar::makeCollectionView(rangeBegin(i), rangeEnd(i));
      }

      auto operator[](std::size_t i) const -> decltype(auto) { return range(i); }

    private:
      boundaries_t boundaries;

    }; // class BoundaryList

    template <typename Main, typename Aux, typename Metadata /* = void */, typename Tag /* = Aux */
              >
    class AssociatedData {
      using This_t = AssociatedData<Main, Aux, Metadata, Tag>; 

    public:
      using assns_t = art::Assns<Main, Aux, Metadata>;

    private:
      using associated_data_iterator_t = assns_node_iterator<lar::util::assns_iterator_t<assns_t>>;
      //  = tuple_element_iterator<1U, lar::util::assns_iterator_t<assns_t>>;

    public:
      using tag = Tag; 

      using group_ranges_t = BoundaryList<associated_data_iterator_t>;

      using auxiliary_data_t = util::add_tag_t<typename group_ranges_t::range_t, tag>;

      // constructor is not part of the interface
      AssociatedData(group_ranges_t&& groups) : fGroups(std::move(groups)) {}

      auto begin() const -> decltype(auto) { return fGroups.begin(); }

      auto end() const -> decltype(auto) { return fGroups.end(); }

      auto getRange(std::size_t i) const -> decltype(auto)
      {
        return util::makeTagged<tag>(fGroups.range(i));
      }

      auto operator[](std::size_t index) const -> decltype(auto)
      {
        static_assert(std::is_convertible<decltype(getRange(index)), auxiliary_data_t>(),
                      "Inconsistent data types.");
        return getRange(index);
      }

      template <typename TestTag>
      static constexpr bool hasTag()
      {
        return std::is_same<TestTag, tag>();
      }

    private:
      group_ranges_t fGroups;

    }; // class AssociatedData<>

    //--------------------------------------------------------------------------

  } // namespace details

  //----------------------------------------------------------------------------

  template <typename Tag, typename Assns>
  auto makeAssociatedData(Assns const& assns, std::size_t minSize = 0);

  template <typename Assns>
  auto makeAssociatedData(Assns const& assns, std::size_t minSize = 0)
  {
    return makeAssociatedData<typename Assns::right_t>(assns, minSize);
  }


  template <typename Tag, typename MainColl, typename Assns>
  auto makeAssociatedData(MainColl const& mainColl, Assns const& assns)
  {
    return makeAssociatedData<Tag>(assns, mainColl.size());
  }

  template <typename MainColl, typename Assns>
  auto makeAssociatedData(MainColl const& mainColl, Assns const& assns)
  {
    return makeAssociatedData<typename Assns::right_t>(mainColl, assns);
  }

  //----------------------------------------------------------------------------

} // namespace proxy

//------------------------------------------------------------------------------
//--- template implementation
//------------------------------------------------------------------------------
namespace proxy {

  namespace details {

    //--------------------------------------------------------------------------
    //--- associationRangeBoundaries() implementation
    //--------------------------------------------------------------------------
    template <std::size_t GroupKey, typename Iter>
    typename BoundaryList<Iter>::boundaries_t
    associationRangesImpl(Iter begin, Iter end, std::size_t expectedSize /* = 0 */)
    {
      constexpr auto KeyIndex = GroupKey;

      auto extractKey = [](auto const& assn) { return std::get<KeyIndex>(assn).key(); };

      typename BoundaryList<Iter>::boundaries_t boundaries;
      boundaries.reserve(expectedSize + 1);
      boundaries.push_back(begin);
      std::size_t current = 0;
      for (auto it = begin; it != end; ++it) {
        auto const key = extractKey(*it);
        if (key == current) continue;
        if (key < current) {
          auto index = std::distance(begin, it);
          throw std::runtime_error(
            "associationRanges() got input element #" + std::to_string(index - 1) + " with key " +
            std::to_string(current) + " and the next with key " + std::to_string(key) + "!");
        }
        boundaries.insert(boundaries.end(), key - current, it);
        current = key;
      } // for
      boundaries.push_back(end);
      return boundaries;
    } // associationRangesImpl()

    //--------------------------------------------------------------------------
    template <std::size_t GroupKey, typename Iter>
    auto associationRangeBoundaries(Iter begin, Iter end)
    {
      return associationRangesImpl<GroupKey, Iter>(begin, end);
    }

    //--------------------------------------------------------------------------
    template <std::size_t GroupKey, typename Iter>
    auto associationRangeBoundaries(Iter begin, Iter end, std::size_t n)
    {
      auto boundaries = associationRangesImpl<GroupKey, Iter>(begin, end, n);
      if (boundaries.size() <= n) {
        boundaries.insert(boundaries.end(), n + 1 - boundaries.size(), boundaries.back());
        assert(boundaries.size() == (n + 1));
      }
      return boundaries;
    } // associationRangeBoundaries(Iter, Iter, std::size_t)

    //--------------------------------------------------------------------------
    template <std::size_t GroupKey, typename Iter>
    BoundaryList<Iter> associationRanges(Iter begin, Iter end)
    {
      return BoundaryList<Iter>(associationRangeBoundaries<GroupKey>(begin, end));
    }

    template <std::size_t GroupKey, typename Iter>
    BoundaryList<Iter> associationRanges(Iter begin, Iter end, std::size_t n)
    {
      return BoundaryList<Iter>(associationRangeBoundaries<GroupKey>(begin, end, n));
    }

    //--------------------------------------------------------------------------

  } // namespace details

  //----------------------------------------------------------------------------
  template <typename Tag, typename Assns>
  auto makeAssociatedData(Assns const& assns, std::size_t minSize /* = 0 */)
  {
    using Main_t = typename Assns::left_t;
    using Aux_t = typename Assns::right_t;
    using Metadata_t = lar::util::assns_metadata_t<Assns>;
    using AssociatedData_t = details::AssociatedData<Main_t, Aux_t, Metadata_t, Tag>;

    // associationRangeBoundaries() produces iterators to association elements,
    // (i.e. tuples)
    using std::begin;
    using std::end;
    auto ranges = details::associationRangeBoundaries<0U>(begin(assns), end(assns), minSize);
    // we convert those iterators into iterators to the right associated item
    // (it takes a few steps)
    using group_ranges_t = typename AssociatedData_t::group_ranges_t;
    return AssociatedData_t(
      group_ranges_t(typename group_ranges_t::boundaries_t(ranges.begin(), ranges.end())));
  } // makeAssociatedDataFrom(assns)

  //----------------------------------------------------------------------------

} // namespace proxy
//------------------------------------------------------------------------------

#endif // LARDATA_RECOBASEPROXY_PROXYBASE_ASSOCIATEDDATA_H