Introduce explicitly named getLinked[From|To] and deprecate tag-dispatch versions (#936)

* Use function names to differentiate instead of tag-dispatch

Calling the tag-dispatched versions is slightly clunky and we can still
keep the getLinked that do the "right thing" automatically with this.
The main difference is that for links with the same FromT and ToT we now
need to call an explicitly named function. Given that most links have
different types this should not be too big of a problem.

* Fix copy-paste typo

Author: tmadlener

include/podio/LinkNavigator.h

@@ -28,11 +28,12 @@ namespace detail::links {
   };
 
   /// Simple struct tag for overload selection in LinkNavigator below
-  struct ReturnFromTag {};
+  struct [[deprecated("The tagged versions of getLinked are deprecated use getLinkedFrom instead")]] ReturnFromTag {};
   /// Simple struct tag for overload selection in LinkNavigator below
-  struct ReturnToTag {};
+  struct [[deprecated("The tagged versions of getLinked are deprecated use getLinkedTo instead")]] ReturnToTag {};
 } // namespace detail::links
 
+/// NOTE: This can go at the same time as the deprecated tags below are removed
 #if !defined(__CLING__)
   #define INLCONSTEXPR inline constexpr
 #else
@@ -41,11 +42,13 @@ namespace detail::links {
 /// Tag variable to select the lookup of *From* objects have links with a *To*
 /// object in podio::LinkNavigator::getLinked
 // INLCONSTEXPR detail::links::ReturnFromTag ReturnFrom;
-INLCONSTEXPR detail::links::ReturnFromTag ReturnFrom;
+[[deprecated("The tagged versions of getLinked are deprecated use getLinkedFrom instead")]] INLCONSTEXPR
+    detail::links::ReturnFromTag ReturnFrom;
 /// Tag variable to select the lookup of *To* objects that have links with a
 /// *From* object in podio::LinkNavigator::getLinked
 // INLCONSTEXPR detail::links::ReturnToTag ReturnTo;
-INLCONSTEXPR detail::links::ReturnToTag ReturnTo;
+[[deprecated("The tagged versions of getLinked are deprecated use getLinkedTo instead")]] INLCONSTEXPR
+    detail::links::ReturnToTag ReturnTo;
 #undef INLCONSTEXPR
 
 /// A helper class to more easily handle one-to-many links.
@@ -92,7 +95,7 @@ class LinkNavigator {
   ///
   /// @returns A vector of all objects and their weights that have links with
   ///          the passed object
-  std::vector<WeightedObject<FromT>> getLinked(const ToT& object, podio::detail::links::ReturnFromTag) const {
+  std::vector<WeightedObject<FromT>> getLinkedFrom(const ToT& object) const {
     const auto& [begin, end] = m_to2from.equal_range(object);
     std::vector<WeightedObject<FromT>> result;
     result.reserve(std::distance(begin, end));
@@ -103,9 +106,15 @@ class LinkNavigator {
     return result;
   }
 
+  [[deprecated("Use getLinkedFrom instead")]]
+  std::vector<WeightedObject<FromT>> getLinked(const ToT& object, podio::detail::links::ReturnFromTag) const {
+    return getLinkedFrom(object);
+  }
+
+  [[deprecated("Use getLinkedFrom instead")]]
   std::vector<WeightedObject<FromT>> getLinked(const typename ToT::mutable_type& object,
                                                podio::detail::links::ReturnFromTag) const {
-    return getLinked(ToT(object), podio::ReturnFrom);
+    return getLinkedFrom(ToT(object));
   }
 
   /// Get all the *From* objects and weights that have links with the passed
@@ -122,15 +131,14 @@ class LinkNavigator {
   template <typename ToU = ToT>
     requires(!std::same_as<FromT, ToU>)
   std::vector<WeightedObject<FromT>> getLinked(const ToT& object) const {
-
-    return getLinked(object, podio::ReturnFrom);
+    return getLinkedFrom(object);
   }
 
   /// Overload for cppyy that makes things work with mutable handles
   template <typename ToU = ToT>
     requires(!std::same_as<FromT, ToU>)
   std::vector<WeightedObject<FromT>> getLinked(const typename ToT::mutable_type& object) const {
-    return getLinked(ToT(object), podio::ReturnFrom);
+    return getLinkedFrom(ToT(object));
   }
 
   /// Get all the *To* objects and weights that have links with the passed
@@ -148,7 +156,7 @@ class LinkNavigator {
   ///
   /// @returns A vector of all objects and their weights that have links with
   ///          the passed object
-  std::vector<WeightedObject<ToT>> getLinked(const FromT& object, podio::detail::links::ReturnToTag) const {
+  std::vector<WeightedObject<ToT>> getLinkedTo(const FromT& object) const {
     const auto& [begin, end] = m_from2to.equal_range(object);
     std::vector<WeightedObject<ToT>> result;
     result.reserve(std::distance(begin, end));
@@ -159,9 +167,15 @@ class LinkNavigator {
     return result;
   }
 
+  [[deprecated("Use getLinkedTo instead")]]
+  std::vector<WeightedObject<ToT>> getLinked(const FromT& object, podio::detail::links::ReturnToTag) const {
+    return getLinkedTo(object);
+  }
+
+  [[deprecated("Use getLinkedTo instead")]]
   std::vector<WeightedObject<ToT>> getLinked(const typename FromT::mutable_type& object,
                                              podio::detail::links::ReturnToTag) const {
-    return getLinked(FromT(object), podio::ReturnTo);
+    return getLinkedTo(FromT(object));
   }
 
   /// Get all the *To* objects and weights that have links with the passed
@@ -178,14 +192,14 @@ class LinkNavigator {
   template <typename FromU = FromT>
     requires(!std::same_as<FromU, ToT>)
   std::vector<WeightedObject<ToT>> getLinked(const FromT& object) const {
-    return getLinked(object, podio::ReturnTo);
+    return getLinkedTo(object);
   }
 
   /// Overload for cppyy that makes things work with mutable handles
   template <typename FromU = FromT>
     requires(!std::same_as<FromU, ToT>)
   std::vector<WeightedObject<ToT>> getLinked(const typename FromT::mutable_type& object) const {
-    return getLinked(FromT(object), podio::ReturnTo);
+    return getLinkedTo(FromT(object));
   }
 
 private:

tests/unittests/links.cpp

@@ -748,24 +748,24 @@ TEST_CASE("LinkNavigator same types", "[links]") {
   link.setWeight(0.66f);
 
   auto navigator = podio::LinkNavigator{linkColl};
-  auto linkedClusters = navigator.getLinked(clusters[1], podio::ReturnTo);
+  auto linkedClusters = navigator.getLinkedTo(clusters[1]);
   REQUIRE(linkedClusters.size() == 1);
   REQUIRE(linkedClusters[0].o == clusters[2]);
   REQUIRE(linkedClusters[0].weight == 0.66f);
 
-  linkedClusters = navigator.getLinked(clusters[1], podio::ReturnFrom);
+  linkedClusters = navigator.getLinkedFrom(clusters[1]);
   REQUIRE(linkedClusters.size() == 1);
   REQUIRE(linkedClusters[0].o == clusters[0]);
   REQUIRE(linkedClusters[0].weight == 0.5f);
 
   using Catch::Matchers::UnorderedEquals;
   using podio::detail::links::WeightedObject;
   using WeightedObjVec = std::vector<WeightedObject<ExampleCluster>>;
-  linkedClusters = navigator.getLinked(clusters[0], podio::ReturnTo);
+  linkedClusters = navigator.getLinkedTo(clusters[0]);
   REQUIRE_THAT(linkedClusters,
                UnorderedEquals(WeightedObjVec{WeightedObject(clusters[1], 0.5f), WeightedObject{clusters[2], 0.25f}}));
 
-  linkedClusters = navigator.getLinked(clusters[2], podio::ReturnFrom);
+  linkedClusters = navigator.getLinkedFrom(clusters[2]);
   REQUIRE_THAT(linkedClusters,
                UnorderedEquals(WeightedObjVec{WeightedObject{clusters[0], 0.25f}, WeightedObject{clusters[1], 0.66f}}));
 }