[TEST] add tests and examples and deprecate old views::to

doc/tutorial/alphabet/alphabet_gc_content.cpp

@@ -32,7 +32,7 @@ int main (int argc, char * argv[])
         sequence.push_back( seqan3::assign_char_to(c, seqan3::dna5{}) );
 
     // Optional: use views for the conversion. Views will be introduced in the next chapter.
-    //std::vector<seqan3::dna5> sequence = input | seqan3::views::char_to<seqan3::dna5> | seqan3::views::to<std::vector>();
+    //std::vector<seqan3::dna5> sequence = input | seqan3::views::char_to<seqan3::dna5> | seqan3::ranges::to<std::vector>();
 
     // Initialise an array with count values for dna5 symbols.
     std::array<size_t, seqan3::dna5::alphabet_size> count{}; // default initialised with zeroes
@@ -56,5 +56,5 @@ void alternatively()
 {
     std::string input{};
     // if something changes in here, please update above:
-    std::vector<seqan3::dna5> sequence = input | seqan3::views::char_to<seqan3::dna5> | seqan3::views::to<std::vector>();
+    std::vector<seqan3::dna5> sequence = input | seqan3::views::char_to<seqan3::dna5> | seqan3::ranges::to<std::vector>();
 }

doc/tutorial/ranges/to.cpp

@@ -0,0 +1,42 @@
+#include <deque>
+#include <forward_list>
+#include <list>
+#include <vector>
+
+#include <seqan3/utility/range/to.hpp>
+
+int main()
+{
+    auto lst = std::views::iota(1, 10); // some range over the numbers 1-10
+
+    // convert range to vector using pipe syntax
+    auto vec0 = lst | seqan3::ranges::to<std::vector<int>>();
+    static_assert(std::same_as<decltype(vec0), std::vector<int>>);
+
+    // convert range to vector but auto deducing the element type
+    auto vec1 = lst | seqan3::ranges::to<std::vector>();
+    static_assert(std::same_as<decltype(vec1), std::vector<int>>);
+
+    // convert range to vector using function call syntax
+    auto vec2 = seqan3::ranges::to<std::vector<int>>(lst);
+    static_assert(std::same_as<decltype(vec2), std::vector<int>>);
+
+    // using function call syntax and auto deducing element type
+    auto vec3 = seqan3::ranges::to<std::vector>(lst);
+    static_assert(std::same_as<decltype(vec3), std::vector<int>>);
+
+    // convert nested ranges into nested containers
+    auto nested_lst = std::list<std::forward_list<int>>{{1, 2, 3}, {4, 5, 6, 7}};
+    auto vec4 = nested_lst | seqan3::ranges::to<std::vector<std::vector<int>>>();
+    static_assert(std::same_as<decltype(vec4), std::vector<std::vector<int>>>);
+
+    // different supported container types
+    auto vec5 = lst | seqan3::ranges::to<std::list>();
+    static_assert(std::same_as<decltype(vec5), std::list<int>>);
+
+    auto vec6 = lst | seqan3::ranges::to<std::deque>();
+    static_assert(std::same_as<decltype(vec6), std::deque<int>>);
+
+
+
+}

include/seqan3/utility/range/to.hpp

@@ -50,14 +50,16 @@ struct to_fn
 public:
     /*!\brief Converts a template-template into a container.
      * \tparam urng_t The type of the range being processed.
+     * \tparam Args   The types of the arguments for the constructor.
      * \param  urng   The range being processed.
+     * \param  args   Arguments to pass to the constructor of the container.
      */
-    template <std::ranges::range urng_t>
-    constexpr auto operator()(urng_t && urng) const
+    template <std::ranges::range urng_t, typename ...Args>
+    constexpr auto operator()(urng_t && urng, Args &&... args) const
     {
         using V = std::decay_t<decltype(*urng.begin())>;
 
-        auto r = T{};
+        auto r = T(std::forward<Args>(args)...);
 
         // reserve memory if functionality is available
         if constexpr (std::ranges::sized_range<urng_t>
@@ -81,71 +83,109 @@ struct to_template_template_fn
 {
     /*!\brief Converts a template-template into a container.
      * \tparam urng_t The type of the range being processed.
+     * \tparam Args   The types of the arguments for the constructor.
      * \param  urng   The range being processed.
+     * \param  args   Arguments to pass to the constructor of the container.
      */
-    template <std::ranges::range urng_t>
-    constexpr auto operator()(urng_t && urng) const
+    template <std::ranges::range urng_t, typename... Args>
+    constexpr auto operator()(urng_t && urng, Args &&... args) const
     {
         using value_t = std::decay_t<decltype(*urng.begin())>;
         auto adapter  = to_fn<U<value_t>>{};
-        return adapter(std::forward<urng_t>(urng));
+        return adapter(std::forward<urng_t>(urng), std::forward<Args>(args)...);
     }
 };
 
 }
-#if 1
 namespace seqan3::ranges {
 
 
-/*!\brief A to view
- * \ingroup utility_views
+/*!\brief Converts a range to a container.
+ * \ingroup utility_range
  * \details
- * TODO some example
- * \noapi{}
+ * Converts a range into a container allowing pipe syntax.
+ * \include doc/tutorial/ranges/to.cpp
+ * \stableapi{}
  */
-template <typename T>
-constexpr auto to() {
-    return detail::adaptor_from_functor{detail::to_fn<T>{}};
+template <typename T, typename... Args>
+constexpr auto to(Args &&... args) {
+    return detail::adaptor_from_functor{detail::to_fn<T>{}, std::forward<Args>(args)...};
 }
 
-/*!\brief A to viewi
- * \ingroup utility_views
- * \details same as `to` but for template templates
- * TODO some example
- * \noapi{}
+/*!\brief Converts a range to a container.
+ * \ingroup utility_range
+ * \details
+ * Converts a range into a container allowing pipe syntax and
+ * enabling auto deduction of container value type.
+ * Same as seqan3::ranges::to but for template templates.
+ * \stableapi{}
+ */
+template <template<class...> typename T, typename... Args>
+constexpr auto to(Args &&... args) {
+    return detail::adaptor_from_functor{detail::to_template_template_fn<T>{}, std::forward<Args>(args)...};
+}
+
+/*!\brief Converts a range to a container.
+ * \ingroup utility_range
+ * \details
+ * Converts a range into a container using function syntax.
+ * \stableapi{}
  */
-template <template<class...> typename T>
-constexpr auto to() {
-    return detail::adaptor_from_functor{detail::to_template_template_fn<T>{}};
 
+template <typename T, std::ranges::range urng_t, typename... Args>
+constexpr auto to(urng_t && urng, Args &&... args) {
+    return detail::adaptor_from_functor{detail::to_fn<T>{}, std::forward<Args>(args)...}(std::forward<urng_t>(urng));
 }
 
+/*!\brief Converts a range to a container.
+ * \ingroup utility_range
+ * \details
+ * Converts a range into a container using function syntax and
+ * auto deducing container value type.
+ * \stableapi{}
+ */
+template <template<class...> typename T, std::ranges::range urng_t, typename... Args>
+constexpr auto to(urng_t && urng, Args &&... args) {
+    return detail::adaptor_from_functor{detail::to_template_template_fn<T>{}, std::forward<Args>(args)...}(std::forward<urng_t>(urng));
 }
-#endif
+}
+
 namespace seqan3::views {
 
+/*!\brief Converts a range to a container.
+ * \ingroup utility_views
+ * \deprecated Use seqan3::ranges::to instead.
+ */
+template <typename T, typename... Args>
+SEQAN3_DEPRECATED_330 constexpr auto to(Args &&... args) {
+    return ranges::to<T>(std::forward<Args>(args)...);
+}
 
-/*!\brief A to view
+/*!\brief Converts a range to a container.
  * \ingroup utility_views
- * \details
- * TODO some example
- * \noapi{}
+ * \deprecated Use seqan3::ranges::to instead.
  */
-template <typename T>
-constexpr auto to() {
-    return detail::adaptor_from_functor{detail::to_fn<T>{}};
+template <template<class...> typename T, typename... Args>
+SEQAN3_DEPRECATED_330 constexpr auto to(Args &&... args) {
+    return ranges::to<T>(std::forward<Args>(args)...);
 }
 
-/*!\brief A to viewi
+/*!\brief Converts a range to a container.
  * \ingroup utility_views
- * \details same as `to` but for template templates
- * TODO some example
- * \noapi{}
+ * \deprecated Use seqan3::ranges::to instead.
  */
-template <template<class...> typename T>
-constexpr auto to() {
-    return detail::adaptor_from_functor{detail::to_template_template_fn<T>{}};
+template <typename T, std::ranges::range urng_t, typename... Args>
+SEQAN3_DEPRECATED_330 constexpr auto to(urng_t && urng, Args &&... args) {
+    return ranges::to<T>(std::forward<urng_t>(urng), std::forward<Args>(args)...);
+}
 
+/*!\brief Converts a range to a container.
+ * \ingroup utility_views
+ * \deprecated Use seqan3::ranges::to instead.
+ */
+template <template<class...> typename T, std::ranges::range urng_t, typename... Args>
+SEQAN3_DEPRECATED_330 constexpr auto to(urng_t && urng, Args &&... args) {
+    return ranges::to<T>(std::forward<urng_t>(urng), std::forward<Args>(args)...);
 }
 
 }

include/seqan3/utility/views/to.hpp

@@ -14,6 +14,5 @@
 
 #include <seqan3/utility/range/to.hpp>
 
-//!TODO what version will we remove the header?
 SEQAN3_DEPRECATED_HEADER(
-    "This header is deprecated and will be removed in SeqAn-3.?.0; Please #include <seqan3/utility/range/to.hpp> instead.")
+    "This header is deprecated and will be removed in SeqAn-3.3.0; Please #include <seqan3/utility/range/to.hpp> instead.")

test/unit/utility/range/CMakeLists.txt

@@ -0,0 +1,3 @@
+add_subdirectories ()
+
+seqan3_test (to_test.cpp)