Scalar Classes#
- group scalar_classes
-
class scalar#
- #include <scalar.hpp>
An owning class to represent a singular value.
A scalar is a singular value of any of the supported datatypes in cudf. Classes derived from this class are used to represent a scalar. Objects of derived classes should be upcasted to this class while passing to an external libcudf API.
Subclassed by cudf::detail::fixed_width_scalar< T >, cudf::fixed_point_scalar< T >, cudf::list_scalar, cudf::string_scalar, cudf::struct_scalar
Public Functions
-
data_type type() const noexcept#
Returns the scalar’s logical value type.
- Returns:
The scalar’s logical value type
-
void set_valid_async(bool is_valid, rmm::cuda_stream_view stream = cudf::get_default_stream())#
Updates the validity of the value.
- Parameters:
is_valid – true: set the value to valid. false: set it to null.
stream – CUDA stream used for device memory operations.
-
bool is_valid(rmm::cuda_stream_view stream = cudf::get_default_stream()) const#
Indicates whether the scalar contains a valid value.
Note
Using the value when
is_valid() == false
is undefined behavior. In addition, this function does a stream synchronization.- Parameters:
stream – CUDA stream used for device memory operations.
- Returns:
true Value is valid
- Returns:
false Value is invalid/null
-
bool *validity_data()#
Returns a raw pointer to the validity bool in device memory.
- Returns:
Raw pointer to the validity bool in device memory
-
bool const *validity_data() const#
Return a const raw pointer to the validity bool in device memory.
- Returns:
Raw pointer to the validity bool in device memory
-
data_type type() const noexcept#
-
template<typename T>
class numeric_scalar : public cudf::detail::fixed_width_scalar<T># - #include <scalar.hpp>
An owning class to represent a numerical value in device memory.
- Template Parameters:
T – the data type of the numerical value.
Public Functions
-
numeric_scalar(numeric_scalar &&other) = default#
Move constructor for numeric_scalar.
- Parameters:
other – The other numeric_scalar to move from.
-
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.
- Parameters:
other – The scalar to copy.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
- Parameters:
value – The initial value of the scalar.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
- Parameters:
data – The scalar’s data in device memory.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
template<typename T>
class fixed_point_scalar : public cudf::scalar# - #include <scalar.hpp>
An owning class to represent a fixed_point number in device memory.
- Template Parameters:
T – the data type of the fixed_point number.
Public Types
Public Functions
-
fixed_point_scalar(fixed_point_scalar &&other) = default#
Move constructor for fixed_point_scalar.
- Parameters:
other – The other fixed_point_scalar to move from.
-
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.
- Parameters:
other – The scalar to copy.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
- Parameters:
value – The initial shifted value of the fixed_point scalar.
scale – The scale of the fixed_point scalar.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
- Parameters:
value – The initial value of the fixed_point scalar.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
- Parameters:
value – The fixed_point number from which the fixed_point scalar will be initialized.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
- Parameters:
data – The scalar’s data in device memory.
scale – The scale of the fixed_point scalar.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
rep_type value(rmm::cuda_stream_view stream = cudf::get_default_stream()) const#
Get the value of the scalar.
- Parameters:
stream – CUDA stream used for device memory operations.
- Returns:
The value of the scalar
-
T fixed_point_value(rmm::cuda_stream_view stream = cudf::get_default_stream()) const#
Get the decimal32, decimal64 or decimal128.
- Parameters:
stream – CUDA stream used for device memory operations.
- Returns:
The decimal32, decimal64 or decimal128 value
-
explicit operator value_type() const#
Explicit conversion operator to get the value of the scalar on the host.
-
class string_scalar : public cudf::scalar#
- #include <scalar.hpp>
An owning class to represent a string in device memory.
Public Types
-
using value_type = cudf::string_view#
The value type of the string scalar.
Public Functions
-
string_scalar(string_scalar &&other) = default#
Move constructor for string_scalar.
- Parameters:
other – The other string_scalar to move from.
-
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.
- Parameters:
other – The other string_scalar to copy.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
- Throws:
std::overflow_error – If the size of the input string exceeds cudf::size_type
- Parameters:
string – The value of the string.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
Note that this function copies the data pointed by string_view.
- Parameters:
source – The string_view pointing the string value to copy.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
Note that this function copies the data pointed by string_view.
- Parameters:
data – The device_scalar of string_view pointing to the string value to copy.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
Note that this constructor moves the existing buffer into the internal data buffer; no copy is performed.
- Parameters:
data – The existing buffer to take over.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
explicit operator std::string() const#
Explicit conversion operator to get the value of the scalar in a host std::string.
-
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.
- Parameters:
stream – CUDA stream used for device memory operations.
- Returns:
The value of the scalar in a host std::string
-
value_type value(rmm::cuda_stream_view stream = cudf::get_default_stream()) const#
Get the value of the scalar as a string_view.
- Parameters:
stream – CUDA stream used for device memory operations.
- Returns:
The value of the scalar as a string_view
-
size_type size() const#
Returns the size of the string in bytes.
- Returns:
The size of the string in bytes
-
char const *data() const#
Returns a raw pointer to the string in device memory.
- Returns:
a raw pointer to the string in device memory
-
using value_type = cudf::string_view#
-
template<typename T>
class chrono_scalar : public cudf::detail::fixed_width_scalar<T># - #include <scalar.hpp>
An owning class to represent a timestamp/duration value in device memory.
See also
cudf/wrappers/timestamps.hpp, cudf/wrappers/durations.hpp for a list of allowed types.
- Template Parameters:
T – the data type of the timestamp/duration value.
Subclassed by cudf::duration_scalar< T >, cudf::timestamp_scalar< T >
Public Functions
-
chrono_scalar(chrono_scalar &&other) = default#
Move constructor for chrono_scalar.
- Parameters:
other – The other chrono_scalar to move from.
-
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.
- Parameters:
other – The scalar to copy.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
- Parameters:
value – The initial value of the scalar.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
- Parameters:
data – The scalar’s data in device memory.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
template<typename T>
class timestamp_scalar : public cudf::chrono_scalar<T># - #include <scalar.hpp>
An owning class to represent a timestamp value in device memory.
See also
cudf/wrappers/timestamps.hpp for a list of allowed types.
- Template Parameters:
T – the data type of the timestamp value.
Public Functions
-
timestamp_scalar(timestamp_scalar &&other) = default#
Move constructor for timestamp_scalar.
- Parameters:
other – The other timestamp_scalar to move from.
-
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.
- Parameters:
other – The scalar to copy.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
template<typename Duration2>
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.
- Parameters:
value – Duration representing number of ticks since the UNIX epoch or another duration that is convertible to timestamps duration.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
rep_type ticks_since_epoch(rmm::cuda_stream_view stream)#
Returns the duration in number of ticks since the UNIX epoch.
- Parameters:
stream – CUDA stream used for device memory operations.
- Returns:
The duration in number of ticks since the UNIX epoch
-
template<typename T>
class duration_scalar : public cudf::chrono_scalar<T># - #include <scalar.hpp>
An owning class to represent a duration value in device memory.
See also
cudf/wrappers/durations.hpp for a list of allowed types.
- Template Parameters:
T – the data type of the duration value.
Public Functions
-
duration_scalar(duration_scalar &&other) = default#
Move constructor for duration_scalar.
- Parameters:
other – The other duration_scalar to move from.
-
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.
- Parameters:
other – The scalar to copy.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
- Parameters:
value – Integer representing number of ticks since the UNIX epoch.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
rep_type count(rmm::cuda_stream_view stream)#
Returns the duration in number of ticks.
- Parameters:
stream – CUDA stream used for device memory operations.
- Returns:
The duration in number of ticks
-
class list_scalar : public cudf::scalar#
- #include <scalar.hpp>
An owning class to represent a list value in device memory.
Public Functions
-
list_scalar(list_scalar &&other) = default#
Move constructor for list_scalar.
- Parameters:
other – The other list_scalar to move from.
-
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.
- Parameters:
other – The scalar to copy.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
The input column_view is copied.
- Parameters:
data – The column data to copy.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
- Parameters:
data – The column to take ownership of.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
column_view view() const#
Returns a non-owning, immutable view to underlying device data.
- Returns:
A non-owning, immutable view to underlying device data
-
list_scalar(list_scalar &&other) = default#
-
class struct_scalar : public cudf::scalar#
- #include <scalar.hpp>
An owning class to represent a struct value in device memory.
Public Functions
-
struct_scalar(struct_scalar &&other) = default#
Move constructor for struct_scalar.
- Parameters:
other – The other struct_scalar to move from.
-
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.
- Parameters:
other – The scalar to copy.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
The input table_view is deep-copied.
- Parameters:
data – The table data to copy.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
The input column_views are deep-copied.
- Parameters:
data – The column_views to copy.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
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.
Note that this constructor moves the existing table data into the internal table data; no copies are performed.
- Parameters:
data – The existing table data to take over.
is_valid – Whether the value held by the scalar is valid.
stream – CUDA stream used for device memory operations.
mr – Device memory resource to use for device memory allocation.
-
table_view view() const#
Returns a non-owning, immutable view to underlying device data.
- Returns:
A non-owning, immutable view to underlying device data
-
struct_scalar(struct_scalar &&other) = default#
-
class scalar#
Contents: