Deprecate libcudf regex APIs accepting pattern strings directly

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.