[REVIEW] string conversion for duration types (to_durations, from_durations)

CHANGELOG.md

@@ -40,6 +40,7 @@
 - PR #5654 Adding support for `cudf.DataFrame.sample` and `cudf.Series.sample`
 - PR #5607 Add Java bindings for duration types
 - PR #5612 Add `is_hex` strings API
+- PR #5625 String conversion to and from duration types
 - PR #5659 Added support for rapids-compose for Java bindings and other enhancements
 - PR #5637 Parameterize Null comparator behaviour in Joins
 - PR #5623 Add `is_ipv4` strings API

conda/recipes/libcudf/meta.yaml

@@ -125,6 +125,7 @@ test:
     - test -f $PREFIX/include/cudf/strings/contains.hpp
     - test -f $PREFIX/include/cudf/strings/convert/convert_booleans.hpp
     - test -f $PREFIX/include/cudf/strings/convert/convert_datetime.hpp
+    - test -f $PREFIX/include/cudf/strings/convert/convert_durations.hpp
     - test -f $PREFIX/include/cudf/strings/convert/convert_floats.hpp
     - test -f $PREFIX/include/cudf/strings/convert/convert_integers.hpp
     - test -f $PREFIX/include/cudf/strings/convert/convert_ipv4.hpp

cpp/CMakeLists.txt

@@ -527,6 +527,7 @@ add_library(cudf
             src/strings/contains.cu
             src/strings/convert/convert_booleans.cu
             src/strings/convert/convert_datetime.cu
+            src/strings/convert/convert_durations.cu
             src/strings/convert/convert_floats.cu
             src/strings/convert/convert_hex.cu
             src/strings/convert/convert_integers.cu

cpp/benchmarks/CMakeLists.txt

@@ -245,3 +245,11 @@ set(SUBWORD_TOKENIZER_BENCH_SRC
   "${CMAKE_CURRENT_SOURCE_DIR}/text/subword_benchmark.cpp")
 
 ConfigureBench(SUBWORD_TOKENIZER_BENCH "${SUBWORD_TOKENIZER_BENCH_SRC}")
+
+###################################################################################################
+# - convert to string benchmark -------------------------------------------------------------------
+
+set(DURATION_TO_STRING_BENCH_SRC
+  "${CMAKE_CURRENT_SOURCE_DIR}/string/convert_durations_benchmark.cpp")
+
+ConfigureBench(DURATION_TO_STRING_BENCH "${DURATION_TO_STRING_BENCH_SRC}")

cpp/benchmarks/string/convert_durations_benchmark.cpp

@@ -0,0 +1,112 @@
+/*
+ * Copyright (c) 2020, NVIDIA CORPORATION.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <benchmark/benchmark.h>
+
+#include <cudf/strings/convert/convert_durations.hpp>
+#include <cudf/types.hpp>
+
+#include <tests/utilities/base_fixture.hpp>
+#include <tests/utilities/column_utilities.hpp>
+#include <tests/utilities/column_wrapper.hpp>
+#include <tests/utilities/cudf_gtest.hpp>
+
+#include <algorithm>
+#include <random>
+
+#include "../fixture/benchmark_fixture.hpp"
+#include "../synchronization/synchronization.hpp"
+#include "cudf/column/column_view.hpp"
+#include "cudf/wrappers/durations.hpp"
+
+class DurationsToString : public cudf::benchmark {
+};
+template <class TypeParam>
+void BM_convert_from_durations(benchmark::State& state)
+{
+  const cudf::size_type source_size = state.range(0);
+
+  // Every element is valid
+  auto data = cudf::test::make_counting_transform_iterator(
+    0, [source_size](auto i) { return TypeParam{i - source_size / 2}; });
+
+  cudf::test::fixed_width_column_wrapper<TypeParam> source_durations(data, data + source_size);
+
+  for (auto _ : state) {
+    cuda_event_timer raii(state, true);  // flush_l2_cache = true, stream = 0
+    cudf::strings::from_durations(source_durations, "%D days %H:%M:%S");
+  }
+
+  state.SetBytesProcessed(state.iterations() * source_size * sizeof(TypeParam));
+}
+
+class StringToDurations : public cudf::benchmark {
+};
+template <class TypeParam>
+void BM_convert_to_durations(benchmark::State& state)
+{
+  const cudf::size_type source_size = state.range(0);
+
+  // Every element is valid
+  auto data = cudf::test::make_counting_transform_iterator(
+    0, [source_size](auto i) { return TypeParam{i - source_size / 2}; });
+
+  cudf::test::fixed_width_column_wrapper<TypeParam> source_durations(data, data + source_size);
+  auto results = cudf::strings::from_durations(source_durations, "%D days %H:%M:%S");
+  cudf::strings_column_view source_string(*results);
+  auto output_type = cudf::data_type(cudf::type_to_id<TypeParam>());
+
+  for (auto _ : state) {
+    cuda_event_timer raii(state, true);  // flush_l2_cache = true, stream = 0
+    cudf::strings::to_durations(source_string, output_type, "%D days %H:%M:%S");
+  }
+
+  state.SetBytesProcessed(state.iterations() * source_size * sizeof(TypeParam));
+}
+
+#define DSBM_BENCHMARK_DEFINE(name, type)                                 \
+  BENCHMARK_DEFINE_F(DurationsToString, name)(::benchmark::State & state) \
+  {                                                                       \
+    BM_convert_from_durations<type>(state);                               \
+  }                                                                       \
+  BENCHMARK_REGISTER_F(DurationsToString, name)                           \
+    ->RangeMultiplier(1 << 5)                                             \
+    ->Range(1 << 10, 1 << 25)                                             \
+    ->UseManualTime()                                                     \
+    ->Unit(benchmark::kMicrosecond);
+
+#define SDBM_BENCHMARK_DEFINE(name, type)                                 \
+  BENCHMARK_DEFINE_F(StringToDurations, name)(::benchmark::State & state) \
+  {                                                                       \
+    BM_convert_to_durations<type>(state);                                 \
+  }                                                                       \
+  BENCHMARK_REGISTER_F(StringToDurations, name)                           \
+    ->RangeMultiplier(1 << 5)                                             \
+    ->Range(1 << 10, 1 << 25)                                             \
+    ->UseManualTime()                                                     \
+    ->Unit(benchmark::kMicrosecond);
+
+DSBM_BENCHMARK_DEFINE(from_durations_D, cudf::duration_D);
+DSBM_BENCHMARK_DEFINE(from_durations_s, cudf::duration_s);
+DSBM_BENCHMARK_DEFINE(from_durations_ms, cudf::duration_ms);
+DSBM_BENCHMARK_DEFINE(from_durations_us, cudf::duration_us);
+DSBM_BENCHMARK_DEFINE(from_durations_ns, cudf::duration_ns);
+
+SDBM_BENCHMARK_DEFINE(to_durations_D, cudf::duration_D);
+SDBM_BENCHMARK_DEFINE(to_durations_s, cudf::duration_s);
+SDBM_BENCHMARK_DEFINE(to_durations_ms, cudf::duration_ms);
+SDBM_BENCHMARK_DEFINE(to_durations_us, cudf::duration_us);
+SDBM_BENCHMARK_DEFINE(to_durations_ns, cudf::duration_ns);

cpp/include/cudf/strings/convert/convert_datetime.hpp

@@ -33,18 +33,18 @@ namespace strings {
  *
  * | Specifier | Description |
  * | :-------: | ----------- |
- * | %%d | Day of the month: 01-31 |
- * | %%m | Month of the year: 01-12 |
- * | %%y | Year without century: 00-99 |
- * | %%Y | Year with century: 0001-9999 |
- * | %%H | 24-hour of the day: 00-23 |
- * | %%I | 12-hour of the day: 01-12 |
- * | %%M | Minute of the hour: 00-59|
- * | %%S | Second of the minute: 00-59 |
- * | %%f | 6-digit microsecond: 000000-999999 |
- * | %%z | UTC offset with format ±HHMM Example +0500 |
- * | %%j | Day of the year: 001-366 |
- * | %%p | Only 'AM', 'PM' or 'am', 'pm' are recognized |
+ * | \%d | Day of the month: 01-31 |
+ * | \%m | Month of the year: 01-12 |
+ * | \%y | Year without century: 00-99 |
+ * | \%Y | Year with century: 0001-9999 |
+ * | \%H | 24-hour of the day: 00-23 |
+ * | \%I | 12-hour of the day: 01-12 |
+ * | \%M | Minute of the hour: 00-59|
+ * | \%S | Second of the minute: 00-59 |
+ * | \%f | 6-digit microsecond: 000000-999999 |
+ * | \%z | UTC offset with format ±HHMM Example +0500 |
+ * | \%j | Day of the year: 001-366 |
+ * | \%p | Only 'AM', 'PM' or 'am', 'pm' are recognized |
  *
  * Other specifiers are not currently supported.
  *
@@ -81,19 +81,19 @@ std::unique_ptr<column> to_timestamps(
  *
  * | Specifier | Description |
  * | :-------: | ----------- |
- * | %%d | Day of the month: 01-31 |
- * | %%m | Month of the year: 01-12 |
- * | %%y | Year without century: 00-99 |
- * | %%Y | Year with century: 0001-9999 |
- * | %%H | 24-hour of the day: 00-23 |
- * | %%I | 12-hour of the day: 01-12 |
- * | %%M | Minute of the hour: 00-59|
- * | %%S | Second of the minute: 00-59 |
- * | %%f | 6-digit microsecond: 000000-999999 |
- * | %%z | Always outputs "+0000" |
- * | %%Z | Always outputs "UTC" |
- * | %%j | Day of the year: 001-366 |
- * | %%p | Only 'AM' or 'PM' |
+ * | \%d | Day of the month: 01-31 |
+ * | \%m | Month of the year: 01-12 |
+ * | \%y | Year without century: 00-99 |
+ * | \%Y | Year with century: 0001-9999 |
+ * | \%H | 24-hour of the day: 00-23 |
+ * | \%I | 12-hour of the day: 01-12 |
+ * | \%M | Minute of the hour: 00-59|
+ * | \%S | Second of the minute: 00-59 |
+ * | \%f | 6-digit microsecond: 000000-999999 |
+ * | \%z | Always outputs "+0000" |
+ * | \%Z | Always outputs "UTC" |
+ * | \%j | Day of the year: 001-366 |
+ * | \%p | Only 'AM' or 'PM' |
  *
  * No checking is done for invalid formats or invalid timestamp values.
  * All timestamps values are formatted to UTC.

cpp/include/cudf/strings/convert/convert_durations.hpp

@@ -0,0 +1,128 @@
+/*
+ * Copyright (c) 2020, NVIDIA CORPORATION.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#pragma once
+
+#include <cudf/column/column.hpp>
+#include <cudf/strings/strings_column_view.hpp>
+
+namespace cudf {
+namespace strings {
+/**
+ * @addtogroup strings_convert
+ * @{
+ */
+
+/**
+ * @brief Returns a new duration column converting a strings column into
+ * durations using the provided format pattern.
+ *
+ * The format pattern can include the following specifiers:
+ * "%%,%n,%t,%D,%H,%I,%M,%S,%p,%R,%T,%r,%OH,%OI,%OM,%OS"
+ *
+ * | Specifier | Description | Range |
+ * | :-------: | ----------- | ---------------- |
+ * | %% | A literal % character | % |
+ * | \%n | A newline character | \\n |
+ * | \%t | A horizontal tab character | \\t |
+ * | \%D | Days | -2,147,483,648 to 2,147,483,647 |
+ * | \%H | 24-hour of the day | 00 to 23 |
+ * | \%I | 12-hour of the day | 00 to 11 |
+ * | \%M | Minute of the hour | 00 to 59 |
+ * | \%S | Second of the minute | 00 to 59.999999999 |
+ * | \%OH | same as %H but without sign | 00 to 23 |
+ * | \%OI | same as %I but without sign | 00 to 11 |
+ * | \%OM | same as %M but without sign | 00 to 59 |
+ * | \%OS | same as %S but without sign | 00 to 59 |
+ * | \%p | AM/PM designations associated with a 12-hour clock | 'AM' or 'PM' |
+ * | \%R | Equivalent to "%H:%M" |  |
+ * | \%T | Equivalent to "%H:%M:%S" |  |
+ * | \%r | Equivalent to "%OI:%OM:%OS %p" |  |
+ *
+ * Other specifiers are not currently supported.
+ *
+ * Invalid formats are not checked. If the string contains unexpected
+ * or insufficient characters, that output row entry's duration value is undefined.
+ *
+ * Any null string entry will result in a corresponding null row in the output column.
+ *
+ * The resulting time units are specified by the `duration_type` parameter.
+ *
+ * @throw cudf::logic_error if duration_type is not a duration type.
+ *
+ * @param strings Strings instance for this operation.
+ * @param duration_type The duration type used for creating the output column.
+ * @param format String specifying the duration format in strings.
+ * @param mr Device memory resource used to allocate the returned column's device memory.
+ * @return New duration column.
+ */
+std::unique_ptr<column> to_durations(
+  strings_column_view const& strings,
+  data_type duration_type,
+  std::string const& format,
+  rmm::mr::device_memory_resource* mr = rmm::mr::get_default_resource());
+
+/**
+ * @brief Returns a new strings column converting a duration column into
+ * strings using the provided format pattern.
+ *
+ * The format pattern can include the following specifiers:
+ * "%%,%n,%t,%D,%H,%I,%M,%S,%p,%R,%T,%r,%OH,%OI,%OM,%OS"
+ *
+ * | Specifier | Description | Range |
+ * | :-------: | ----------- | ---------------- |
+ * | %% | A literal % character | % |
+ * | \%n | A newline character | \\n |
+ * | \%t | A horizontal tab character | \\t |
+ * | \%D | Days | -2,147,483,648 to 2,147,483,647 |
+ * | \%H | 24-hour of the day | 00 to 23 |
+ * | \%I | 12-hour of the day | 00 to 11 |
+ * | \%M | Minute of the hour | 00 to 59 |
+ * | \%S | Second of the minute | 00 to 59.999999999 |
+ * | \%OH | same as %H but without sign | 00 to 23 |
+ * | \%OI | same as %I but without sign | 00 to 11 |
+ * | \%OM | same as %M but without sign | 00 to 59 |
+ * | \%OS | same as %S but without sign | 00 to 59 |
+ * | \%p | AM/PM designations associated with a 12-hour clock | 'AM' or 'PM' |
+ * | \%R | Equivalent to "%H:%M" |  |
+ * | \%T | Equivalent to "%H:%M:%S" |  |
+ * | \%r | Equivalent to "%OI:%OM:%OS %p" |  |
+ *
+ * No checking is done for invalid formats or invalid duration values. Formatting sticks to
+ * specifications of `std::formatter<std::chrono::duration>` as much as possible.
+ *
+ * Any null input entry will result in a corresponding null entry in the output column.
+ *
+ * The time units of the input column influence the number of digits in decimal of seconds.
+ * It uses 3 digits for milliseconds, 6 digits for microseconds and 9 digits for nanoseconds.
+ * If duration value is negative, only one negative sign is written to output string. The specifiers
+ * with signs are "%H,%I,%M,%S,%R,%T".
+ *
+ * @throw cudf::logic_error if `durations` column parameter is not a duration type.
+ *
+ * @param durations Duration values to convert.
+ * @param format The string specifying output format.
+ *        Default format is ""%d days %H:%M:%S".
+ * @param mr Device memory resource used to allocate the returned column's device memory.
+ * @return New strings column with formatted durations.
+ */
+std::unique_ptr<column> from_durations(
+  column_view const& durations,
+  std::string const& format           = "%D days %H:%M:%S",
+  rmm::mr::device_memory_resource* mr = rmm::mr::get_default_resource());
+
+/** @} */  // end of doxygen group
+}  // namespace strings
+}  // namespace cudf