Deprecate libcudf regex APIs accepting pattern strings directly (#12891)

Deprecates the libcudf regex APIs that do not accept `cudf::strings::regex_program` objects.
The libcudf regex functions were converted to accept `regex_program` objects instead of a pattern string and regex-flags directly in PR #11927
Most of this is removing calls to the deprecated functions in the gtests.
The declarations in the headers had to be reordered to make the reference links work in the doxygen output.

These deprecated functions will be removed in a future release.

Authors:
  - David Wendt (https://github.com/davidwendt)

Approvers:
  - Vukasin Milovanovic (https://github.com/vuule)
  - Nghia Truong (https://github.com/ttnghia)

URL: #12891

cpp/benchmarks/string/contains.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021-2022, NVIDIA CORPORATION.
+ * Copyright (c) 2021-2023, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,6 +23,7 @@
 #include <cudf/filling.hpp>
 #include <cudf/strings/contains.hpp>
 #include <cudf/strings/findall.hpp>
+#include <cudf/strings/regex/regex_program.hpp>
 #include <cudf/strings/strings_column_view.hpp>
 #include <cudf/utilities/default_stream.hpp>
 
@@ -83,18 +84,19 @@ static void BM_contains(benchmark::State& state, contains_type ct)
   auto input = cudf::strings_column_view(col->view());
 
   auto pattern = patterns[pattern_index];
+  auto program = cudf::strings::regex_program::create(pattern);
 
   for (auto _ : state) {
     cuda_event_timer raii(state, true, cudf::get_default_stream());
     switch (ct) {
       case contains_type::contains:  // contains_re and matches_re use the same main logic
-        cudf::strings::contains_re(input, pattern);
+        cudf::strings::contains_re(input, *program);
         break;
       case contains_type::count:  // counts occurrences of matches
-        cudf::strings::count_re(input, pattern);
+        cudf::strings::count_re(input, *program);
         break;
       case contains_type::findall:  // returns occurrences of all matches
-        cudf::strings::findall(input, pattern);
+        cudf::strings::findall(input, *program);
         break;
     }
   }

cpp/benchmarks/string/extract.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021-2022, NVIDIA CORPORATION.
+ * Copyright (c) 2021-2023, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,6 +23,7 @@
 #include <cudf_test/column_wrapper.hpp>
 
 #include <cudf/strings/extract.hpp>
+#include <cudf/strings/regex/regex_program.hpp>
 #include <cudf/strings/strings_column_view.hpp>
 
 #include <random>
@@ -59,10 +60,11 @@ static void BM_extract(benchmark::State& state, int groups)
   auto input = cudf::gather(
     cudf::table_view{{samples_column}}, map->view(), cudf::out_of_bounds_policy::DONT_CHECK);
   cudf::strings_column_view strings_view(input->get_column(0).view());
+  auto prog = cudf::strings::regex_program::create(pattern);
 
   for (auto _ : state) {
     cuda_event_timer raii(state, true);
-    auto results = cudf::strings::extract(strings_view, pattern);
+    auto results = cudf::strings::extract(strings_view, *prog);
   }
 
   state.SetBytesProcessed(state.iterations() * strings_view.chars_size());

cpp/benchmarks/string/replace_re.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021-2022, NVIDIA CORPORATION.
+ * Copyright (c) 2021-2023, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -22,6 +22,7 @@
 
 #include <cudf_test/column_wrapper.hpp>
 
+#include <cudf/strings/regex/regex_program.hpp>
 #include <cudf/strings/replace_re.hpp>
 #include <cudf/strings/strings_column_view.hpp>
 #include <cudf/utilities/default_stream.hpp>
@@ -40,18 +41,20 @@ static void BM_replace(benchmark::State& state, replace_type rt)
   auto const column = create_random_column(cudf::type_id::STRING, row_count{n_rows}, profile);
   cudf::strings_column_view input(column->view());
   cudf::test::strings_column_wrapper repls({"#", ""});
+  auto prog         = cudf::strings::regex_program::create("\\d+");
+  auto prog_backref = cudf::strings::regex_program::create("(\\d+)");
 
   for (auto _ : state) {
     cuda_event_timer raii(state, true, cudf::get_default_stream());
     switch (rt) {
       case replace_type::replace_re:  // contains_re and matches_re use the same main logic
-        cudf::strings::replace_re(input, "\\d+");
+        cudf::strings::replace_re(input, *prog);
         break;
       case replace_type::replace_re_multi:  // counts occurrences of pattern
         cudf::strings::replace_re(input, {"\\d+", "\\s+"}, cudf::strings_column_view(repls));
         break;
       case replace_type::replace_backref:  // returns occurrences of matches
-        cudf::strings::replace_with_backrefs(input, "(\\d+)", "#\\1X");
+        cudf::strings::replace_with_backrefs(input, *prog_backref, "#\\1X");
         break;
     }
   }

cpp/include/cudf/strings/contains.hpp

@@ -34,33 +34,6 @@ struct regex_program;
  * @brief Strings APIs for regex contains, count, matches
  */
 
-/**
- * @brief Returns a boolean column identifying rows which
- * match the given regex pattern.
- *
- * @code{.pseudo}
- * Example:
- * s = ["abc","123","def456"]
- * r = contains_re(s,"\\d+")
- * r is now [false, true, true]
- * @endcode
- *
- * Any null string entries return corresponding null output column entries.
- *
- * See the @ref md_regex "Regex Features" page for details on patterns supported by this API.
- *
- * @param strings Strings instance for this operation.
- * @param pattern Regex pattern to match to each string.
- * @param flags Regex flags for interpreting special characters in the pattern.
- * @param mr Device memory resource used to allocate the returned column's device memory.
- * @return New column of boolean results for each string.
- */
-std::unique_ptr<column> contains_re(
-  strings_column_view const& strings,
-  std::string_view pattern,
-  regex_flags const flags             = regex_flags::DEFAULT,
-  rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
-
 /**
  * @brief Returns a boolean column identifying rows which
  * match the given regex_program object
@@ -89,26 +62,29 @@ std::unique_ptr<column> contains_re(
 
 /**
  * @brief Returns a boolean column identifying rows which
- * matching the given regex pattern but only at the beginning the string.
+ * match the given regex pattern.
  *
  * @code{.pseudo}
  * Example:
  * s = ["abc","123","def456"]
- * r = matches_re(s,"\\d+")
- * r is now [false, true, false]
+ * r = contains_re(s,"\\d+")
+ * r is now [false, true, true]
  * @endcode
  *
  * Any null string entries return corresponding null output column entries.
  *
  * See the @ref md_regex "Regex Features" page for details on patterns supported by this API.
  *
+ * @deprecated Use @link contains_re contains_re(strings_column_view const&,
+ * regex_program const&, rmm::mr::device_memory_resource*) @endlink
+ *
  * @param strings Strings instance for this operation.
  * @param pattern Regex pattern to match to each string.
  * @param flags Regex flags for interpreting special characters in the pattern.
  * @param mr Device memory resource used to allocate the returned column's device memory.
  * @return New column of boolean results for each string.
  */
-std::unique_ptr<column> matches_re(
+[[deprecated]] std::unique_ptr<column> contains_re(
   strings_column_view const& strings,
   std::string_view pattern,
   regex_flags const flags             = regex_flags::DEFAULT,
@@ -141,27 +117,30 @@ std::unique_ptr<column> matches_re(
   rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
 /**
- * @brief Returns the number of times the given regex pattern
- * matches in each string.
+ * @brief Returns a boolean column identifying rows which
+ * matching the given regex pattern but only at the beginning the string.
  *
  * @code{.pseudo}
  * Example:
- * s = ["abc","123","def45"]
- * r = count_re(s,"\\d")
- * r is now [0, 3, 2]
+ * s = ["abc","123","def456"]
+ * r = matches_re(s,"\\d+")
+ * r is now [false, true, false]
  * @endcode
  *
  * Any null string entries return corresponding null output column entries.
  *
  * See the @ref md_regex "Regex Features" page for details on patterns supported by this API.
  *
+ * @deprecated Use @link matches_re matches_re(strings_column_view const&,
+ * regex_program const&, rmm::mr::device_memory_resource*) @endlink
+ *
  * @param strings Strings instance for this operation.
- * @param pattern Regex pattern to match within each string.
+ * @param pattern Regex pattern to match to each string.
  * @param flags Regex flags for interpreting special characters in the pattern.
  * @param mr Device memory resource used to allocate the returned column's device memory.
- * @return New INT32 column with counts for each string.
+ * @return New column of boolean results for each string.
  */
-std::unique_ptr<column> count_re(
+[[deprecated]] std::unique_ptr<column> matches_re(
   strings_column_view const& strings,
   std::string_view pattern,
   regex_flags const flags             = regex_flags::DEFAULT,
@@ -193,6 +172,36 @@ std::unique_ptr<column> count_re(
   regex_program const& prog,
   rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
+/**
+ * @brief Returns the number of times the given regex pattern
+ * matches in each string.
+ *
+ * @code{.pseudo}
+ * Example:
+ * s = ["abc","123","def45"]
+ * r = count_re(s,"\\d")
+ * r is now [0, 3, 2]
+ * @endcode
+ *
+ * Any null string entries return corresponding null output column entries.
+ *
+ * See the @ref md_regex "Regex Features" page for details on patterns supported by this API.
+ *
+ * @deprecated Use @link count_re count_re(strings_column_view const&,
+ * regex_program const&, rmm::mr::device_memory_resource*) @endlink
+ *
+ * @param strings Strings instance for this operation.
+ * @param pattern Regex pattern to match within each string.
+ * @param flags Regex flags for interpreting special characters in the pattern.
+ * @param mr Device memory resource used to allocate the returned column's device memory.
+ * @return New INT32 column with counts for each string.
+ */
+[[deprecated]] std::unique_ptr<column> count_re(
+  strings_column_view const& strings,
+  std::string_view pattern,
+  regex_flags const flags             = regex_flags::DEFAULT,
+  rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
+
 /**
  * @brief Returns a boolean column identifying rows which
  * match the given like pattern.