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>
24 
25 #include <rmm/cuda_stream_view.hpp>
26 #include <rmm/device_buffer.hpp>
27 #include <rmm/device_scalar.hpp>
28 
34 namespace CUDF_EXPORT cudf {
48 class scalar {
49  public:
50  virtual ~scalar() = default;
51  scalar& operator=(scalar const& other) = delete;
52  scalar& operator=(scalar&& other) = delete;
53 
59  [[nodiscard]] data_type type() const noexcept;
60 
67  void set_valid_async(bool is_valid, rmm::cuda_stream_view stream = cudf::get_default_stream());
68 
79  [[nodiscard]] bool is_valid(rmm::cuda_stream_view stream = cudf::get_default_stream()) const;
80 
86  bool* validity_data();
87 
93  [[nodiscard]] bool const* validity_data() const;
94 
95  protected:
96  data_type _type{type_id::EMPTY};
98 
99  scalar() = delete;
100 
105  scalar(scalar&& other) = default;
106 
114  scalar(scalar const& other,
117 
130  bool is_valid = false,
133 };
134 
135 namespace detail {
141 template <typename T>
142 class fixed_width_scalar : public scalar {
143  static_assert(is_fixed_width<T>(), "Unexpected non-fixed-width type.");
144 
145  public:
146  using value_type = T;
147 
148  ~fixed_width_scalar() override = default;
149 
155 
156  fixed_width_scalar& operator=(fixed_width_scalar const& other) = delete;
157  fixed_width_scalar& operator=(fixed_width_scalar&& other) = delete;
158 
169 
177 
181  explicit operator value_type() const;
182 
189  [[nodiscard]] T value(rmm::cuda_stream_view stream = cudf::get_default_stream()) const;
190 
195  T* data();
196 
201  [[nodiscard]] T const* data() const;
202 
203  protected:
205 
206  fixed_width_scalar() = delete;
207 
217  bool is_valid = true,
220 
230  bool is_valid = true,
233 };
234 
235 } // namespace detail
236 
242 template <typename T>
244  static_assert(is_numeric<T>(), "Unexpected non-numeric type.");
245 
246  public:
247  numeric_scalar() = delete;
248  ~numeric_scalar() override = default;
249 
254  numeric_scalar(numeric_scalar&& other) = default;
255 
256  numeric_scalar& operator=(numeric_scalar const& other) = delete;
257  numeric_scalar& operator=(numeric_scalar&& other) = delete;
258 
269 
278  numeric_scalar(T value,
279  bool is_valid = true,
282 
292  bool is_valid = true,
295 };
296 
302 template <typename T>
303 class fixed_point_scalar : public scalar {
304  static_assert(is_fixed_point<T>(), "Unexpected non-fixed_point type.");
305 
306  public:
307  using rep_type = typename T::rep;
308  using value_type = T;
309 
310  fixed_point_scalar() = delete;
311  ~fixed_point_scalar() override = default;
312 
318 
319  fixed_point_scalar& operator=(fixed_point_scalar const& other) = delete;
320  fixed_point_scalar& operator=(fixed_point_scalar&& other) = delete;
321 
332 
343  numeric::scale_type scale,
344  bool is_valid = true,
347 
357  bool is_valid = true,
360 
370  bool is_valid = true,
373 
384  numeric::scale_type scale,
385  bool is_valid = true,
388 
396 
403  [[nodiscard]] T fixed_point_value(
405 
409  explicit operator value_type() const;
410 
416 
421  [[nodiscard]] rep_type const* data() const;
422 
423  protected:
425 };
426 
430 class string_scalar : public scalar {
431  public:
433 
434  string_scalar() = delete;
435  ~string_scalar() override = default;
436 
441  string_scalar(string_scalar&& other) = default;
442 
443  // string_scalar(string_scalar const& other) = delete;
444  string_scalar& operator=(string_scalar const& other) = delete;
445  string_scalar& operator=(string_scalar&& other) = delete;
446 
457 
468  string_scalar(std::string const& string,
469  bool is_valid = true,
472 
483  string_scalar(value_type const& source,
484  bool is_valid = true,
487 
499  bool is_valid = true,
502 
515  bool is_valid = true,
518 
522  explicit operator std::string() const;
523 
530  [[nodiscard]] std::string to_string(
532 
540 
545  [[nodiscard]] size_type size() const;
546 
551  [[nodiscard]] char const* data() const;
552 
553  protected:
555 };
556 
563 template <typename T>
565  static_assert(is_chrono<T>(), "Unexpected non-chrono type");
566 
567  public:
568  chrono_scalar() = delete;
569  ~chrono_scalar() override = default;
570 
575  chrono_scalar(chrono_scalar&& other) = default;
576 
577  chrono_scalar& operator=(chrono_scalar const& other) = delete;
578  chrono_scalar& operator=(chrono_scalar&& other) = delete;
579 
590 
599  chrono_scalar(T value,
600  bool is_valid = true,
603 
613  bool is_valid = true,
616 };
617 
624 template <typename T>
625 class timestamp_scalar : public chrono_scalar<T> {
626  public:
627  static_assert(is_timestamp<T>(), "Unexpected non-timestamp type");
629  using rep_type = typename T::rep;
630 
631  timestamp_scalar() = delete;
632 
637  timestamp_scalar(timestamp_scalar&& other) = default;
638 
649 
660  template <typename Duration2>
661  timestamp_scalar(Duration2 const& value,
662  bool is_valid,
665 
672 };
673 
680 template <typename T>
681 class duration_scalar : public chrono_scalar<T> {
682  public:
683  static_assert(is_duration<T>(), "Unexpected non-duration type");
685  using rep_type = typename T::rep;
686 
687  duration_scalar() = delete;
688 
693  duration_scalar(duration_scalar&& other) = default;
694 
705 
715  bool is_valid,
718 
725 };
726 
730 class list_scalar : public scalar {
731  public:
732  list_scalar() = delete;
733  ~list_scalar() override = default;
734 
739  list_scalar(list_scalar&& other) = default;
740 
741  list_scalar& operator=(list_scalar const& other) = delete;
742  list_scalar& operator=(list_scalar&& other) = delete;
743 
751  list_scalar(list_scalar const& other,
754 
766  bool is_valid = true,
769 
779  bool is_valid = true,
782 
787  [[nodiscard]] column_view view() const;
788 
789  private:
790  cudf::column _data;
791 };
792 
796 class struct_scalar : public scalar {
797  public:
798  struct_scalar() = delete;
799  ~struct_scalar() override = default;
800 
805  struct_scalar(struct_scalar&& other) = default;
806  struct_scalar& operator=(struct_scalar const& other) = delete;
807  struct_scalar& operator=(struct_scalar&& other) = delete;
808 
819 
831  bool is_valid = true,
834 
846  bool is_valid = true,
849 
862  bool is_valid = true,
865 
870  [[nodiscard]] table_view view() const;
871 
872  private:
873  table _data;
874 
878  void assert_valid_size();
879 
889  static table init_data(table&& data,
890  bool is_valid,
891  rmm::cuda_stream_view stream,
893 };
894  // end of group
896 } // namespace CUDF_EXPORT cudf
An owning class to represent a timestamp/duration value in device memory.
Definition: scalar.hpp:564
chrono_scalar(T value, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new chrono scalar object.
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=cudf::get_current_device_resource_ref())
Construct a new chrono scalar object from existing device memory.
chrono_scalar(chrono_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new chrono scalar object by deep copying another.
chrono_scalar(chrono_scalar &&other)=default
Move constructor for chrono_scalar.
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:47
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:142
rmm::device_scalar< T > _data
device memory containing the value
Definition: scalar.hpp:204
fixed_width_scalar(fixed_width_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new fixed-width scalar object by deep copying another.
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=cudf::get_current_device_resource_ref())
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=cudf::get_current_device_resource_ref())
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:146
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:681
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:685
duration_scalar(duration_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new duration scalar object by deep copying another.
duration_scalar(rep_type value, bool is_valid, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new duration scalar object from tick counts.
An owning class to represent a fixed_point number in device memory.
Definition: scalar.hpp:303
rmm::device_scalar< rep_type > _data
device memory containing the value
Definition: scalar.hpp:424
fixed_point_scalar(fixed_point_scalar &&other)=default
Move constructor for fixed_point_scalar.
fixed_point_scalar(T value, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new fixed_point scalar object from a fixed_point number.
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=cudf::get_current_device_resource_ref())
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=cudf::get_current_device_resource_ref())
Construct a new fixed_point scalar object from existing device memory.
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:308
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=cudf::get_current_device_resource_ref())
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.
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:307
fixed_point_scalar(fixed_point_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new fixed_point scalar object by deep copying another.
An owning class to represent a list value in device memory.
Definition: scalar.hpp:730
column_view view() const
Returns a non-owning, immutable view to underlying device data.
list_scalar(list_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new list scalar object by deep copying another.
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=cudf::get_current_device_resource_ref())
Construct a new list scalar object from column_view.
list_scalar(list_scalar &&other)=default
Move constructor for list_scalar.
list_scalar(cudf::column &&data, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new list scalar object from existing column.
An owning class to represent a numerical value in device memory.
Definition: scalar.hpp:243
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=cudf::get_current_device_resource_ref())
Construct a new numeric scalar object from existing device memory.
numeric_scalar(T value, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new numeric scalar object.
numeric_scalar(numeric_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new numeric scalar object by deep copying another.
numeric_scalar(numeric_scalar &&other)=default
Move constructor for numeric_scalar.
An owning class to represent a singular value.
Definition: scalar.hpp:48
rmm::device_scalar< bool > _is_valid
Device bool signifying validity.
Definition: scalar.hpp:97
scalar(scalar &&other)=default
Move constructor for scalar.
data_type type() const noexcept
Returns the scalar's logical value type.
scalar(scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new scalar object by deep copying another.
scalar(data_type type, bool is_valid=false, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new scalar object.
An owning class to represent a string in device memory.
Definition: scalar.hpp:430
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(value_type const &source, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
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=cudf::get_current_device_resource_ref())
Construct a new string scalar object from string_view in device memory.
size_type size() const
Returns the size of the string in bytes.
string_scalar(string_scalar &&other)=default
Move constructor for string_scalar.
string_scalar(string_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
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=cudf::get_current_device_resource_ref())
Construct a new string scalar object by moving an existing string data buffer.
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(std::string const &string, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new string scalar object.
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:796
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=cudf::get_current_device_resource_ref())
Construct a new struct scalar object from a host_span of column_views.
table_view view() const
Returns a non-owning, immutable view to underlying device data.
struct_scalar(table &&data, bool is_valid=true, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new struct scalar object from an existing table in device memory.
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=cudf::get_current_device_resource_ref())
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=cudf::get_current_device_resource_ref())
Construct a new struct scalar object by deep copying another.
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:40
An owning class to represent a timestamp value in device memory.
Definition: scalar.hpp:625
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:629
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=cudf::get_current_device_resource_ref())
Construct a new timestamp scalar object from a duration that is convertible to T::duration.
timestamp_scalar(timestamp_scalar const &other, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Construct a new timestamp scalar object by deep copying another.
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
rmm::device_async_resource_ref get_current_device_resource_ref()
Get the current device memory resource reference.
cuda::mr::async_resource_ref< cuda::mr::device_accessible > device_async_resource_ref
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=cudf::get_current_device_resource_ref())
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.