Scalar Classes

group Scalar

class scalar

#include <cudf/scalar/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.

Value and storage constructors are explicit to prevent implicit temporaries from allocating device memory on the default stream and resource before being copied on another stream.

Subclassed by cudf::fixed_point_scalar< numeric::decimal32 >, cudf::fixed_point_scalar< numeric::decimal64 >, cudf::fixed_point_scalar< numeric::decimal128 >, 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,

cuda::stream_ref 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(

cuda::stream_ref 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 <cudf/scalar/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,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit numeric_scalar(

T value,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit numeric_scalar(

scalar const &data,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources mr = cudf::get_current_device_resource_ref()

)

Construct a new numeric scalar object from another scalar.

The input scalar’s type must exactly match this scalar’s type.

Throws:

cudf::data_type_error – if the input scalar type does not match.

Parameters:

• data – The scalar to copy.

• stream – CUDA stream used for device memory operations.

• mr – Device memory resource to use for device memory allocation.

explicit numeric_scalar(

rmm::device_scalar<T> &&data,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources mr = cudf::get_current_device_resource_ref()

)

Construct a new numeric scalar object from existing device memory.

Deprecated:

Use the cudf::scalar constructor instead.

Deprecated:

Use the cudf::scalar constructor instead.

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 <cudf/scalar/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,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit fixed_point_scalar(

rep_type value,

numeric::scale_type scale,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit fixed_point_scalar(

rep_type value,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit fixed_point_scalar(

T value,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit fixed_point_scalar(

scalar const &data,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources mr = cudf::get_current_device_resource_ref()

)

Construct a new fixed_point scalar object from another scalar.

The input scalar’s type ID must match this scalar’s type. The input scalar’s scale is preserved.

Throws:

cudf::data_type_error – if the input scalar type ID does not match.

Parameters:

• data – The scalar to copy.

• stream – CUDA stream used for device memory operations.

• mr – Device memory resource to use for device memory allocation.

explicit fixed_point_scalar(

rmm::device_scalar<rep_type> &&data,

numeric::scale_type scale,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources mr = cudf::get_current_device_resource_ref()

)

Construct a new fixed_point scalar object from existing device memory.

Deprecated:

Use the cudf::scalar constructor instead.

Deprecated:

Use the cudf::scalar constructor instead.

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(

cuda::stream_ref 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(

cuda::stream_ref 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

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 <cudf/scalar/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,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit string_scalar(

std::string_view string,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit string_scalar(

value_type const &source,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit string_scalar(

scalar const &data,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources mr = cudf::get_current_device_resource_ref()

)

Construct a new string scalar object from another scalar.

The input scalar’s type must be STRING.

Throws:

cudf::data_type_error – if the input scalar type is not STRING.

Parameters:

• data – The scalar to copy.

• stream – CUDA stream used for device memory operations.

• mr – Device memory resource to use for device memory allocation.

explicit string_scalar(

rmm::device_scalar<value_type> &data,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

Deprecated:

Use the cudf::scalar constructor instead.

Deprecated:

Use the cudf::scalar constructor instead.

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.

explicit string_scalar(

rmm::device_buffer &&data,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

std::string to_string(

cuda::stream_ref 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(

cuda::stream_ref 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 <cudf/scalar/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,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit chrono_scalar(

T value,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit chrono_scalar(

scalar const &data,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources mr = cudf::get_current_device_resource_ref()

)

Construct a new chrono scalar object from another scalar.

The input scalar’s type must exactly match this scalar’s type.

Throws:

cudf::data_type_error – if the input scalar type does not match.

Parameters:

• data – The scalar to copy.

• stream – CUDA stream used for device memory operations.

• mr – Device memory resource to use for device memory allocation.

explicit chrono_scalar(

rmm::device_scalar<T> &&data,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources mr = cudf::get_current_device_resource_ref()

)

Construct a new chrono scalar object from existing device memory.

Deprecated:

Use the cudf::scalar constructor instead.

Deprecated:

Use the cudf::scalar constructor instead.

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 <cudf/scalar/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,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

inline explicit timestamp_scalar(

scalar const &data,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources mr = cudf::get_current_device_resource_ref()

)

Construct a new timestamp scalar object from another scalar.

The input scalar’s type must exactly match this scalar’s type.

Throws:

cudf::data_type_error – if the input scalar type does not match.

Parameters:

• data – 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>
explicit timestamp_scalar(

Duration2 const &value,

bool is_valid,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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(cuda::stream_ref 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 <cudf/scalar/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,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

inline explicit duration_scalar(

scalar const &data,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources mr = cudf::get_current_device_resource_ref()

)

Construct a new duration scalar object from another scalar.

The input scalar’s type must exactly match this scalar’s type.

Throws:

cudf::data_type_error – if the input scalar type does not match.

Parameters:

• data – The scalar to copy.

• stream – CUDA stream used for device memory operations.

• mr – Device memory resource to use for device memory allocation.

explicit duration_scalar(

rep_type value,

bool is_valid,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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(cuda::stream_ref 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 <cudf/scalar/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,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit list_scalar(

cudf::column_view const &data,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit list_scalar(

cudf::column &&data,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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 <cudf/scalar/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,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit struct_scalar(

table_view const &data,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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.

explicit struct_scalar(

std::span<column_view const> data,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources mr = cudf::get_current_device_resource_ref()

)

Construct a new struct scalar object from a 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.

explicit struct_scalar(

table &&data,

bool is_valid = true,

cuda::stream_ref stream = cudf::get_default_stream(),

cudf::memory_resources 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:

• Scalar Factories
  • make_numeric_scalar()
  • make_timestamp_scalar()
  • make_duration_scalar()
  • make_fixed_width_scalar()
  • make_string_scalar()
  • make_default_constructed_scalar()
  • make_empty_scalar_like()
  • make_fixed_width_scalar()
  • make_fixed_point_scalar()
  • make_list_scalar()
  • make_struct_scalar()
  • make_struct_scalar()