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

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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

using rep_type = typename T::rep#

The representation type of the fixed_point number.

using value_type = T#

The value type of the fixed_point number.

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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.

rep_type *data()#

Returns a raw pointer to the value in device memory.

Returns:

A raw pointer to the value in device memory

rep_type const *data() const#

Returns a const raw pointer to the value in device memory.

Returns:

a const raw pointer to the value in device memory

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 Types

using rep_type = typename T::rep#

The underlying representation type of the timestamp.

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 Types

using rep_type = typename T::rep#

The duration’s underlying representation type.

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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 = cudf::get_current_device_resource_ref())#

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

Contents: