scalar.hpp
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2019-2024, NVIDIA CORPORATION.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #pragma once
17 
18 #include <cudf/column/column.hpp>
19 #include <cudf/table/table.hpp>
20 #include <cudf/types.hpp>
23 
24 #include <rmm/cuda_stream_view.hpp>
25 #include <rmm/device_buffer.hpp>
26 #include <rmm/device_scalar.hpp>
28 #include <rmm/resource_ref.hpp>
29 
35 namespace CUDF_EXPORT cudf {
49 class scalar {
50  public:
51  virtual ~scalar() = default;
52  scalar& operator=(scalar const& other) = delete;
53  scalar& operator=(scalar&& other) = delete;
54 
60  [[nodiscard]] data_type type() const noexcept;
61 
68  void set_valid_async(bool is_valid, rmm::cuda_stream_view stream = cudf::get_default_stream());
69 
80  [[nodiscard]] bool is_valid(rmm::cuda_stream_view stream = cudf::get_default_stream()) const;
81 
87  bool* validity_data();
88 
94  [[nodiscard]] bool const* validity_data() const;
95 
96  protected:
97  data_type _type{type_id::EMPTY};
99 
100  scalar() = delete;
101 
106  scalar(scalar&& other) = default;
107 
115  scalar(scalar const& other,
118 
131  bool is_valid = false,
134 };
135 
136 namespace detail {
142 template <typename T>
143 class fixed_width_scalar : public scalar {
144  static_assert(is_fixed_width<T>(), "Unexpected non-fixed-width type.");
145 
146  public:
147  using value_type = T;
148 
149  ~fixed_width_scalar() override = default;
150 
156 
157  fixed_width_scalar& operator=(fixed_width_scalar const& other) = delete;
158  fixed_width_scalar& operator=(fixed_width_scalar&& other) = delete;
159 
170 
178 
182  explicit operator value_type() const;
183 
190  [[nodiscard]] T value(rmm::cuda_stream_view stream = cudf::get_default_stream()) const;
191 
196  T* data();
197 
202  [[nodiscard]] T const* data() const;
203 
204  protected:
206 
207  fixed_width_scalar() = delete;
208 
218  bool is_valid = true,
221 
231  bool is_valid = true,
234 };
235 
236 } // namespace detail
237 
243 template <typename T>
245  static_assert(is_numeric<T>(), "Unexpected non-numeric type.");
246 
247  public:
248  numeric_scalar() = delete;
249  ~numeric_scalar() override = default;
250 
255  numeric_scalar(numeric_scalar&& other) = default;
256 
257  numeric_scalar& operator=(numeric_scalar const& other) = delete;
258  numeric_scalar& operator=(numeric_scalar&& other) = delete;
259 
270 
279  numeric_scalar(T value,
280  bool is_valid = true,
283 
293  bool is_valid = true,
296 };
297 
303 template <typename T>
304 class fixed_point_scalar : public scalar {
305  static_assert(is_fixed_point<T>(), "Unexpected non-fixed_point type.");
306 
307  public:
308  using rep_type = typename T::rep;
309  using value_type = T;
310 
311  fixed_point_scalar() = delete;
312  ~fixed_point_scalar() override = default;
313 
319 
320  fixed_point_scalar& operator=(fixed_point_scalar const& other) = delete;
321  fixed_point_scalar& operator=(fixed_point_scalar&& other) = delete;
322 
333 
344  numeric::scale_type scale,
345  bool is_valid = true,
348 
358  bool is_valid = true,
361 
371  bool is_valid = true,
374 
385  numeric::scale_type scale,
386  bool is_valid = true,
389 
397 
404  [[nodiscard]] T fixed_point_value(
406 
410  explicit operator value_type() const;
411 
417 
422  [[nodiscard]] rep_type const* data() const;
423 
424  protected:
426 };
427 
431 class string_scalar : public scalar {
432  public:
434 
435  string_scalar() = delete;
436  ~string_scalar() override = default;
437 
442  string_scalar(string_scalar&& other) = default;
443 
444  // string_scalar(string_scalar const& other) = delete;
445  string_scalar& operator=(string_scalar const& other) = delete;
446  string_scalar& operator=(string_scalar&& other) = delete;
447 
458 
469  string_scalar(std::string const& string,
470  bool is_valid = true,
473 
484  string_scalar(value_type const& source,
485  bool is_valid = true,
488 
500  bool is_valid = true,
503 
516  bool is_valid = true,
519 
523  explicit operator std::string() const;
524 
531  [[nodiscard]] std::string to_string(
533 
541 
546  [[nodiscard]] size_type size() const;
547 
552  [[nodiscard]] char const* data() const;
553 
554  protected:
556 };
557 
564 template <typename T>
566  static_assert(is_chrono<T>(), "Unexpected non-chrono type");
567 
568  public:
569  chrono_scalar() = delete;
570  ~chrono_scalar() override = default;
571 
576  chrono_scalar(chrono_scalar&& other) = default;
577 
578  chrono_scalar& operator=(chrono_scalar const& other) = delete;
579  chrono_scalar& operator=(chrono_scalar&& other) = delete;
580 
591 
600  chrono_scalar(T value,
601  bool is_valid = true,
604 
614  bool is_valid = true,
617 };
618 
625 template <typename T>
626 class timestamp_scalar : public chrono_scalar<T> {
627  public:
628  static_assert(is_timestamp<T>(), "Unexpected non-timestamp type");
630  using rep_type = typename T::rep;
631 
632  timestamp_scalar() = delete;
633 
638  timestamp_scalar(timestamp_scalar&& other) = default;
639 
650 
661  template <typename Duration2>
662  timestamp_scalar(Duration2 const& value,
663  bool is_valid,
666 
673 };
674 
681 template <typename T>
682 class duration_scalar : public chrono_scalar<T> {
683  public:
684  static_assert(is_duration<T>(), "Unexpected non-duration type");
686  using rep_type = typename T::rep;
687 
688  duration_scalar() = delete;
689 
694  duration_scalar(duration_scalar&& other) = default;
695 
706 
716  bool is_valid,
719 
726 };
727 
731 class list_scalar : public scalar {
732  public:
733  list_scalar() = delete;
734  ~list_scalar() override = default;
735 
740  list_scalar(list_scalar&& other) = default;
741 
742  list_scalar& operator=(list_scalar const& other) = delete;
743  list_scalar& operator=(list_scalar&& other) = delete;
744 
752  list_scalar(list_scalar const& other,
755 
767  bool is_valid = true,
770 
780  bool is_valid = true,
783 
788  [[nodiscard]] column_view view() const;
789 
790  private:
791  cudf::column _data;
792 };
793 
797 class struct_scalar : public scalar {
798  public:
799  struct_scalar() = delete;
800  ~struct_scalar() override = default;
801 
806  struct_scalar(struct_scalar&& other) = default;
807  struct_scalar& operator=(struct_scalar const& other) = delete;
808  struct_scalar& operator=(struct_scalar&& other) = delete;
809 
820 
832  bool is_valid = true,
835 
847  bool is_valid = true,
850 
863  bool is_valid = true,
866 
871  [[nodiscard]] table_view view() const;
872 
873  private:
874  table _data;
875 
879  void assert_valid_size();
880 
890  static table init_data(table&& data,
891  bool is_valid,
892  rmm::cuda_stream_view stream,
894 };
895  // end of group
897 } // namespace CUDF_EXPORT cudf
An owning class to represent a timestamp/duration value in device memory.
Definition: scalar.hpp:565
chrono_scalar(chrono_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new chrono scalar object by deep copying another.
chrono_scalar(rmm::device_scalar< T > &&data, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new chrono scalar object from existing device memory.
chrono_scalar(chrono_scalar &&other)=default
Move constructor for chrono_scalar.
chrono_scalar(T value, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new chrono scalar object.
A non-owning, immutable view of device data as a column of elements, some of which may be null as ind...
A container of nullable device data as a column of elements.
Definition: column.hpp:48
Indicator for the logical data type of an element in a column.
Definition: types.hpp:243
An owning class to represent a fixed-width type value in device memory.
Definition: scalar.hpp:143
rmm::device_scalar< T > _data
device memory containing the value
Definition: scalar.hpp:205
void set_value(T value, rmm::cuda_stream_view stream=cudf::get_default_stream())
Set the value of the scalar.
T value(rmm::cuda_stream_view stream=cudf::get_default_stream()) const
Get the value of the scalar.
fixed_width_scalar(fixed_width_scalar &&other)=default
Move constructor for fixed_width_scalar.
fixed_width_scalar(T value, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new fixed width scalar object.
fixed_width_scalar(rmm::device_scalar< T > &&data, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new fixed width scalar object from existing device memory.
T const * data() const
Returns a const raw pointer to the value in device memory.
T value_type
Type of the value held by the scalar.
Definition: scalar.hpp:147
fixed_width_scalar(fixed_width_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new fixed-width scalar object by deep copying another.
T * data()
Returns a raw pointer to the value in device memory.
An owning class to represent a duration value in device memory.
Definition: scalar.hpp:682
duration_scalar(rep_type value, bool is_valid, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new duration scalar object from tick counts.
rep_type count(rmm::cuda_stream_view stream)
Returns the duration in number of ticks.
duration_scalar(duration_scalar &&other)=default
Move constructor for duration_scalar.
typename T::rep rep_type
The duration's underlying representation type.
Definition: scalar.hpp:686
duration_scalar(duration_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new duration scalar object by deep copying another.
An owning class to represent a fixed_point number in device memory.
Definition: scalar.hpp:304
fixed_point_scalar(T value, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new fixed_point scalar object from a fixed_point number.
rmm::device_scalar< rep_type > _data
device memory containing the value
Definition: scalar.hpp:425
fixed_point_scalar(fixed_point_scalar &&other)=default
Move constructor for fixed_point_scalar.
rep_type value(rmm::cuda_stream_view stream=cudf::get_default_stream()) const
Get the value of the scalar.
T value_type
The value type of the fixed_point number.
Definition: scalar.hpp:309
fixed_point_scalar(rep_type value, numeric::scale_type scale, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new fixed_point scalar object from already shifted value and scale.
rep_type const * data() const
Returns a const raw pointer to the value in device memory.
T fixed_point_value(rmm::cuda_stream_view stream=cudf::get_default_stream()) const
Get the decimal32, decimal64 or decimal128.
fixed_point_scalar(rep_type value, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new fixed_point scalar object from a value and default 0-scale.
fixed_point_scalar(rmm::device_scalar< rep_type > &&data, numeric::scale_type scale, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new fixed_point scalar object from existing device memory.
fixed_point_scalar(fixed_point_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new fixed_point scalar object by deep copying another.
rep_type * data()
Returns a raw pointer to the value in device memory.
typename T::rep rep_type
The representation type of the fixed_point number.
Definition: scalar.hpp:308
An owning class to represent a list value in device memory.
Definition: scalar.hpp:731
column_view view() const
Returns a non-owning, immutable view to underlying device data.
list_scalar(cudf::column_view const &data, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new list scalar object from column_view.
list_scalar(cudf::column &&data, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new list scalar object from existing column.
list_scalar(list_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new list scalar object by deep copying another.
list_scalar(list_scalar &&other)=default
Move constructor for list_scalar.
An owning class to represent a numerical value in device memory.
Definition: scalar.hpp:244
numeric_scalar(numeric_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new numeric scalar object by deep copying another.
numeric_scalar(numeric_scalar &&other)=default
Move constructor for numeric_scalar.
numeric_scalar(T value, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new numeric scalar object.
numeric_scalar(rmm::device_scalar< T > &&data, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new numeric scalar object from existing device memory.
An owning class to represent a singular value.
Definition: scalar.hpp:49
rmm::device_scalar< bool > _is_valid
Device bool signifying validity.
Definition: scalar.hpp:98
scalar(scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new scalar object by deep copying another.
scalar(scalar &&other)=default
Move constructor for scalar.
scalar(data_type type, bool is_valid=false, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new scalar object.
data_type type() const noexcept
Returns the scalar's logical value type.
An owning class to represent a string in device memory.
Definition: scalar.hpp:431
string_scalar(string_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new string scalar object by deep copying another string_scalar.
string_scalar(rmm::device_buffer &&data, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new string scalar object by moving an existing string data buffer.
std::string to_string(rmm::cuda_stream_view stream=cudf::get_default_stream()) const
Get the value of the scalar in a host std::string.
string_scalar(std::string const &string, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new string scalar object.
size_type size() const
Returns the size of the string in bytes.
string_scalar(string_scalar &&other)=default
Move constructor for string_scalar.
value_type value(rmm::cuda_stream_view stream=cudf::get_default_stream()) const
Get the value of the scalar as a string_view.
string_scalar(value_type const &source, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new string scalar object from string_view.
string_scalar(rmm::device_scalar< value_type > &data, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new string scalar object from string_view in device memory.
char const * data() const
Returns a raw pointer to the string in device memory.
A non-owning, immutable view of device data that is a variable length char array representing a UTF-8...
Definition: string_view.hpp:44
An owning class to represent a struct value in device memory.
Definition: scalar.hpp:797
table_view view() const
Returns a non-owning, immutable view to underlying device data.
struct_scalar(table_view const &data, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new struct scalar object from table_view.
struct_scalar(struct_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new struct scalar object by deep copying another.
struct_scalar(host_span< column_view const > data, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new struct scalar object from a host_span of column_views.
struct_scalar(table &&data, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new struct scalar object from an existing table in device memory.
struct_scalar(struct_scalar &&other)=default
Move constructor for struct_scalar.
A set of cudf::column_view's of the same size.
Definition: table_view.hpp:200
A set of cudf::column's of the same size.
Definition: table.hpp:41
An owning class to represent a timestamp value in device memory.
Definition: scalar.hpp:626
timestamp_scalar(timestamp_scalar &&other)=default
Move constructor for timestamp_scalar.
typename T::rep rep_type
The underlying representation type of the timestamp.
Definition: scalar.hpp:630
timestamp_scalar(timestamp_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new timestamp scalar object by deep copying another.
rep_type ticks_since_epoch(rmm::cuda_stream_view stream)
Returns the duration in number of ticks since the UNIX epoch.
timestamp_scalar(Duration2 const &value, bool is_valid, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Construct a new timestamp scalar object from a duration that is convertible to T::duration.
Class definition for cudf::column.
rmm::cuda_stream_view const get_default_stream()
Get the current default stream.
scale_type
The scale type for fixed_point.
Definition: fixed_point.hpp:43
cuda::mr::async_resource_ref< cuda::mr::device_accessible > device_async_resource_ref
device_memory_resource * get_current_device_resource()
std::unique_ptr< cudf::column > is_valid(cudf::column_view const &input, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
Creates a column of type_id::BOOL8 elements where for every element in input true indicates the value...
int32_t size_type
Row index type for columns and tables.
Definition: types.hpp:95
cuDF interfaces
Definition: aggregation.hpp:35
C++20 std::span with reduced feature set.
Definition: span.hpp:231
Class definition for cudf::table.
Type declarations for libcudf.