Replace begin-end output iterator pair with a single iterator

Doing it like this follows the STL library. The previous versions of these functions are still available but are deprecated.
SSoelvsten · Oct 23, 2024 · 970854f · 970854f
1 parent eb2d4a3
commit 970854f
Show file tree

Hide file tree

Showing 8 changed files with 519 additions and 534 deletions.
diff --git a/docs/tutorial/functional.md b/docs/tutorial/functional.md
@@ -43,20 +43,16 @@ adiar::bdd _ = adiar::bdd_exists(f, xs.begin(), xs.end());
 ```
 
 Reversely, one can also parse information from Adiar's algorithms back into
-one's own data structures with a pair of iterators. For example, the variables
+one's own data structures with an output iterator. For example, the variables
 within a BDD can be copied (in *ascending* order) into a `std::vector` with the
 `adiar::bdd_support` function as follows.
 
 ```cpp
-std::vector<int> xs(adiar::bdd_varcount(f));
+std::vector<int> xs;
 
-adiar::bdd_support(f, xs.begin(), xs.end());
+adiar::bdd_support(f, std::back_inserter(xs));
 ```
 
-Here, we initialise the vector with `adiar::bdd_varcount` many
-default-initialized values to be sure that the range `xs.begin()` to `xs.end()`
-is big enough to fit the entire result.
-
 Generators and Consumers
 ==================================
 

diff --git a/src/adiar/bdd.h b/src/adiar/bdd.h
@@ -1950,24 +1950,18 @@ namespace adiar
   /// \param f
   ///    BDD of interest.
   ///
-  /// \param begin
-  ///    Single-pass forward iterator for where to place the output.
-  ///
-  /// \param end
-  ///    Marks the end for `begin`.
-  ///
-  /// \returns An iterator to the first entry that still is left empty.
+  /// \param iter
+  ///    Single-pass output iterator for where to place the output.
   ///
-  /// \throws out_of_range
-  ///    If the distance between `begin` and `end` is not big enough to contain all variables in
-  ///    `f`.
+  /// \returns The output iterator at its final state.
   //////////////////////////////////////////////////////////////////////////////////////////////////
-  template <typename ForwardIt>
-  ForwardIt
-  bdd_support(const bdd& f, ForwardIt begin, ForwardIt end)
+  template <typename OutputIt,
+            typename = enable_if<!is_convertible<OutputIt, consumer<bdd::label_type>>>>
+  OutputIt
+  bdd_support(const bdd& f, OutputIt iter)
   {
-    bdd_support(f, make_consumer(begin, end));
-    return begin;
+    bdd_support(f, make_consumer<bdd::label_type>(iter));
+    return iter;
   }
 
   //////////////////////////////////////////////////////////////////////////////////////////////////
@@ -2078,23 +2072,17 @@ namespace adiar
   ///    BDD of interest.
   ///
   /// \param begin
-  ///    Single-pass forward *mutable* iterator for where to place the output.
+  ///    Single-pass output iterator for where to place the output.
   ///
-  /// \param end
-  ///    Marks the end for `begin`.
-  ///
-  /// \returns An iterator to the first entry that still is left empty.
-  ///
-  /// \throws out_of_range
-  ///    If the distance between `begin` and `end` is not big enough to contain all variables in
-  ///    `f`.
+  /// \returns The output iterator at its final state.
   //////////////////////////////////////////////////////////////////////////////////////////////////
-  template <typename ForwardIt, typename = enable_if<is_mutable<typename ForwardIt::reference>>>
-  ForwardIt
-  bdd_satmin(const bdd& f, ForwardIt begin, ForwardIt end)
+  template <typename OutputIt,
+            typename = enable_if<!is_convertible<OutputIt, consumer<pair<bdd::label_type, bool>>> && !is_convertible<OutputIt, bdd>>>
+  OutputIt
+  bdd_satmin(const bdd& f, OutputIt iter)
   {
-    bdd_satmin(f, make_consumer(begin, end));
-    return begin;
+    bdd_satmin(f, make_consumer<pair<bdd::label_type, bool>>(iter));
+    return iter;
   }
 
   //////////////////////////////////////////////////////////////////////////////////////////////////
@@ -2181,23 +2169,17 @@ namespace adiar
   ///    BDD of interest.
   ///
   /// \param begin
-  ///    Single-pass forward *mutable* iterator for where to place the output.
-  ///
-  /// \param end
-  ///    Marks the end for `begin`.
+  ///    Single-pass output iterator for where to place the output.
   ///
-  /// \returns An iterator to the first entry that still is left empty.
-  ///
-  /// \throws out_of_range
-  ///    If the distance between `begin` and `end` is not big enough to contain all variables in
-  ///    `f`.
+  /// \returns The output iterator at its final state.
   //////////////////////////////////////////////////////////////////////////////
-  template <typename ForwardIt, typename = enable_if<is_mutable<typename ForwardIt::reference>>>
-  ForwardIt
-  bdd_satmax(const bdd& f, ForwardIt begin, ForwardIt end)
+  template <typename OutputIt,
+            typename = enable_if<!is_convertible<OutputIt, consumer<pair<bdd::label_type, bool>>> && !is_convertible<OutputIt, bdd>>>
+  OutputIt
+  bdd_satmax(const bdd& f, OutputIt iter)
   {
-    bdd_satmax(f, make_consumer(begin, end));
-    return begin;
+    bdd_satmax(f, make_consumer<pair<bdd::label_type, bool>>(iter));
+    return iter;
   }
 
   ////////////////////////////////////////////////////////////////////////////////////////////////////

diff --git a/src/adiar/deprecated.h b/src/adiar/deprecated.h
@@ -5,6 +5,80 @@ namespace adiar
 {
   // LCOV_EXCL_START
 
+  //////////////////////////////////////////////////////////////////////////////////////////////////
+  /// \brief Copy all of the variable labels (in \em ascending order) that occur in the BDD into the
+  ///        given container.
+  //////////////////////////////////////////////////////////////////////////////////////////////////
+  template <typename ForwardIt>
+  [[deprecated("Use an output iterator")]]
+  ForwardIt
+  bdd_support(const bdd& f, ForwardIt begin, ForwardIt end)
+  {
+    bdd_support(f, make_consumer(begin, end));
+    return begin;
+  }
+
+  //////////////////////////////////////////////////////////////////////////////////////////////////
+  /// \brief The lexicographically smallest x such that f(x) is true.
+  //////////////////////////////////////////////////////////////////////////////////////////////////
+  template <typename ForwardIt, typename = enable_if<is_mutable<typename ForwardIt::reference>>>
+  [[deprecated("Use an output iterator (Did you mean to provide values? Use a constant iterator, for now)")]]
+  ForwardIt
+  bdd_satmin(const bdd& f, ForwardIt begin, ForwardIt end)
+  {
+    bdd_satmin(f, make_consumer(begin, end));
+    return begin;
+  }
+
+  //////////////////////////////////////////////////////////////////////////////////////////////////
+  /// \brief The lexicographically largest x such that f(x) is true.
+  //////////////////////////////////////////////////////////////////////////////
+  template <typename ForwardIt, typename = enable_if<is_mutable<typename ForwardIt::reference>>>
+  [[deprecated("Use an output iterator (Did you mean to provide values? Use a constant iterator, for now)")]]
+  ForwardIt
+  bdd_satmax(const bdd& f, ForwardIt begin, ForwardIt end)
+  {
+    bdd_satmax(f, make_consumer(begin, end));
+    return begin;
+  }
+
+  //////////////////////////////////////////////////////////////////////////////////////////////////
+  /// \brief Copy all of the variable labels (in \em ascending order) that occur in the family into
+  ///        the given container.
+  //////////////////////////////////////////////////////////////////////////////////////////////////
+  template <typename ForwardIt>
+  [[deprecated("Use an output iterator")]]
+  ForwardIt
+  zdd_support(const zdd& A, ForwardIt begin, ForwardIt end)
+  {
+    zdd_support(A, make_consumer(begin, end));
+    return begin;
+  }
+
+  //////////////////////////////////////////////////////////////////////////////////////////////////
+  /// \brief Retrieves the lexicographically smallest set a in A.
+  //////////////////////////////////////////////////////////////////////////////////////////////////
+  template <typename ForwardIt>
+  [[deprecated("Use an output iterator")]]
+  ForwardIt
+  zdd_minelem(const zdd& A, ForwardIt begin, ForwardIt end)
+  {
+    zdd_minelem(A, make_consumer(begin, end));
+    return begin;
+  }
+
+  //////////////////////////////////////////////////////////////////////////////////////////////////
+  /// \brief Retrieves the lexicographically largest set a in A.
+  //////////////////////////////////////////////////////////////////////////////////////////////////
+  template <typename ForwardIt>
+  [[deprecated("Use an output iterator")]]
+  ForwardIt
+  zdd_maxelem(const zdd& A, ForwardIt begin, ForwardIt end)
+  {
+    zdd_maxelem(A, make_consumer(begin, end));
+    return begin;
+  }
+
   // LCOV_EXCL_STOP
 }
 

diff --git a/src/adiar/zdd.h b/src/adiar/zdd.h
@@ -1480,23 +1480,17 @@ namespace adiar
   ///    ZDD of interest.
   ///
   /// \param begin
-  ///    Single-pass forward iterator for where to place the output.
-  ///
-  /// \param end
-  ///    Marks the end for `begin`.
-  ///
-  /// \returns An iterator to the first entry that still is left empty.
+  ///    Single-pass output iterator for where to place the output.
   ///
-  /// \throws out_of_range
-  ///    If the distance between `begin` and `end` is not big enough to contain all variables in
-  ///    `A`.
+  /// \returns The output iterator at its final state.
   //////////////////////////////////////////////////////////////////////////////////////////////////
-  template <typename ForwardIt>
-  ForwardIt
-  zdd_support(const zdd& A, ForwardIt begin, ForwardIt end)
+  template <typename OutputIt,
+            typename = enable_if<!is_convertible<OutputIt, consumer<zdd::label_type>>>>
+  OutputIt
+  zdd_support(const zdd& A, OutputIt iter)
   {
-    zdd_support(A, make_consumer(begin, end));
-    return begin;
+    zdd_support(A, make_consumer<zdd::label_type>(iter));
+    return iter;
   }
 
   //////////////////////////////////////////////////////////////////////////////////////////////////
@@ -1597,21 +1591,15 @@ namespace adiar
   /// \param begin
   ///    Single-pass forward iterator for where to place the output.
   ///
-  /// \param end
-  ///    Marks the end for `begin`.
-  ///
-  /// \returns An iterator to the first entry that still is left empty.
-  ///
-  /// \throws out_of_range
-  ///    If the distance between `begin` and `end` is not big enough to contain all variables in
-  ///    `A`.
-  //////////////////////////////////////////////////////////////////////////////
-  template <typename ForwardIt>
-  ForwardIt
-  zdd_minelem(const zdd& A, ForwardIt begin, ForwardIt end)
+  /// \returns The output iterator at its final state.
+  //////////////////////////////////////////////////////////////////////////////////////////////////
+  template <typename OutputIt,
+            typename = enable_if<!is_convertible<OutputIt, consumer<zdd::label_type>>>>
+  OutputIt
+  zdd_minelem(const zdd& A, OutputIt iter)
   {
-    zdd_minelem(A, make_consumer(begin, end));
-    return begin;
+    zdd_minelem(A, make_consumer<zdd::label_type>(iter));
+    return iter;
   }
 
   //////////////////////////////////////////////////////////////////////////////////////////////////
@@ -1649,23 +1637,17 @@ namespace adiar
   ///    Set of sets of interest.
   ///
   /// \param begin
-  ///    Single-pass forward iterator for where to place the output.
+  ///    Single-pass output iterator for where to place the output.
   ///
-  /// \param end
-  ///    Marks the end for `begin`.
-  ///
-  /// \returns An iterator to the first entry that still is left empty.
-  ///
-  /// \throws out_of_range
-  ///    If the distance between `begin` and `end` is not big enough to contain all variables in
-  ///    `A`.
+  /// \returns The output iterator at its final state.
   //////////////////////////////////////////////////////////////////////////////////////////////////
-  template <typename ForwardIt>
-  ForwardIt
-  zdd_maxelem(const zdd& A, ForwardIt begin, ForwardIt end)
+  template <typename OutputIt,
+            typename = enable_if<!is_convertible<OutputIt, consumer<zdd::label_type>>>>
+  OutputIt
+  zdd_maxelem(const zdd& A, OutputIt iter)
   {
-    zdd_maxelem(A, make_consumer(begin, end));
-    return begin;
+    zdd_maxelem(A, make_consumer<zdd::label_type>(iter));
+    return iter;
   }
 
   /// \}