Utility Types#

group Types

Defines

CUDF_ENABLE_IF(...)#

Convenience macro for SFINAE as an unnamed template parameter.

Example:

// This function will participate in overload resolution only if T is an integral type
template <typename T, CUDF_ENABLE_IF(std::is_integral_v<T> )>
void foo();

Typedefs

using size_type = int32_t#: Row index type for columns and tables.

using bitmask_type = uint32_t#: Bitmask type stored as 32-bit unsigned integer.

using valid_type = uint8_t#: Valid type in host memory.

using thread_index_type = int64_t#: Thread index type in kernels.

typedef uint32_t char_utf8#: UTF-8 characters are 1-4 bytes.

template<typename...> using void_t = void#: Utility metafunction that maps a sequence of any types to the type void.

template<typename L, typename R> using less_comparable = decltype(cuda::std::declval<L>() < cuda::std::declval<R>())#: Checks if two types are comparable using less operator (i.e. <).

template<typename L, typename R> using greater_comparable = decltype(cuda::std::declval<L>() > cuda::std::declval<R>())#: Checks if two types are comparable using greater operator (i.e. >).

template<typename L, typename R> using equality_comparable = decltype(cuda::std::declval<L>() == cuda::std::declval<R>())#: Checks if two types are comparable using equality operator (i.e. ==).

template<typename ...Ts> using has_common_type = typename detail::has_common_type_impl<void, Ts...>::type#: Checks if types have a common type.

template<typename T> using is_timestamp_t = cuda::std::disjunction<cuda::std::is_same<cudf::timestamp_D, T>, cuda::std::is_same<cudf::timestamp_h, T>, cuda::std::is_same<cudf::timestamp_m, T>, cuda::std::is_same<cudf::timestamp_s, T>, cuda::std::is_same<cudf::timestamp_ms, T>, cuda::std::is_same<cudf::timestamp_us, T>, cuda::std::is_same<cudf::timestamp_ns, T>>#: Checks if a type is a timestamp type.

template<typename T> using is_duration_t = cuda::std::disjunction<cuda::std::is_same<cudf::duration_D, T>, cuda::std::is_same<cudf::duration_h, T>, cuda::std::is_same<cudf::duration_m, T>, cuda::std::is_same<cudf::duration_s, T>, cuda::std::is_same<cudf::duration_ms, T>, cuda::std::is_same<cudf::duration_us, T>, cuda::std::is_same<cudf::duration_ns, T>>#: Checks if a type is a duration type.

Enums

enum class order : bool#

Indicates the order in which elements should be sorted.

Values:

enumerator ASCENDING#: Elements ordered from small to large.

enumerator DESCENDING#: Elements ordered from large to small.

enum class null_policy : bool#

Enum to specify whether to include nulls or exclude nulls.

Values:

enumerator EXCLUDE#: exclude null elements

enumerator INCLUDE#: include null elements

enum class nan_policy : bool#

Enum to treat NaN floating point value as null or non-null element.

Values:

enumerator NAN_IS_NULL#: treat nans as null elements

enumerator NAN_IS_VALID#: treat nans as valid elements (non-null)

enum class nan_equality#

Enum to consider different elements (of floating point types) holding NaN value as equal or unequal.

Values:

enumerator ALL_EQUAL#: All NaNs compare equal, regardless of sign.

enumerator UNEQUAL#: All NaNs compare unequal (IEEE754 behavior)

enum class null_equality : bool#

Enum to consider two nulls as equal or unequal.

Values:

enumerator EQUAL#: nulls compare equal

enumerator UNEQUAL#: nulls compare unequal

enum class null_order : bool#

Indicates how null values compare against all other values.

Values:

enumerator AFTER#: NULL values ordered after all other values.

enumerator BEFORE#: NULL values ordered before all other values.

enum class sorted : bool#

Indicates whether a collection of values is known to be sorted.

Values:

enumerator NO#

enumerator YES#

enum class mask_state : int32_t#

Controls the allocation/initialization of a null mask.

Values:

enumerator UNALLOCATED#: Null mask not allocated, (all elements are valid)

enumerator UNINITIALIZED#: Null mask allocated, but not initialized.

enumerator ALL_VALID#: Null mask allocated, initialized to all elements valid.

enumerator ALL_NULL#: Null mask allocated, initialized to all elements NULL.

enum class interpolation : int32_t#

Interpolation method to use when the desired quantile lies between two data points i and j.

Values:

enumerator LINEAR#: Linear interpolation between i and j.

enumerator LOWER#: Lower data point (i)

enumerator HIGHER#: Higher data point (j)

enumerator MIDPOINT#: (i + j)/2

enumerator NEAREST#: i or j, whichever is nearest

enum class type_id : int32_t#

Identifies a column’s logical element type.

Values:

enumerator EMPTY#: Always null with no underlying data.

enumerator INT8#: 1 byte signed integer

enumerator INT16#: 2 byte signed integer

enumerator INT32#: 4 byte signed integer

enumerator INT64#: 8 byte signed integer

enumerator UINT8#: 1 byte unsigned integer

enumerator UINT16#: 2 byte unsigned integer

enumerator UINT32#: 4 byte unsigned integer

enumerator UINT64#: 8 byte unsigned integer

enumerator FLOAT32#: 4 byte floating point

enumerator FLOAT64#: 8 byte floating point

enumerator BOOL8#: Boolean using one byte per value, 0 == false, else true.

enumerator TIMESTAMP_DAYS#: point in time in days since Unix Epoch in int32

enumerator TIMESTAMP_SECONDS#: point in time in seconds since Unix Epoch in int64

enumerator TIMESTAMP_MILLISECONDS#: point in time in milliseconds since Unix Epoch in int64

enumerator TIMESTAMP_MICROSECONDS#: point in time in microseconds since Unix Epoch in int64

enumerator TIMESTAMP_NANOSECONDS#: point in time in nanoseconds since Unix Epoch in int64

enumerator DURATION_DAYS#: time interval of days in int32

enumerator DURATION_SECONDS#: time interval of seconds in int64

enumerator DURATION_MILLISECONDS#: time interval of milliseconds in int64

enumerator DURATION_MICROSECONDS#: time interval of microseconds in int64

enumerator DURATION_NANOSECONDS#: time interval of nanoseconds in int64

enumerator DICTIONARY32#: Dictionary type using int32 indices.

enumerator STRING#: String elements.

enumerator LIST#: List elements.

enumerator DECIMAL32#: Fixed-point type with int32_t.

enumerator DECIMAL64#: Fixed-point type with int64_t.

enumerator DECIMAL128#: Fixed-point type with __int128_t.

enumerator STRUCT#: Struct elements.

enumerator NUM_TYPE_IDS#: Total number of type ids.

enum class null_aware : bool#

A function is null-aware if its output value uses the input validity.

For example, ADD is not null-aware, but IS_NULL and NULL_LOGICAL_AND are null-aware.

Values:

enumerator NO#: The function is not null-aware.

enumerator YES#: The function is null-aware.

enum class output_nullability : uint8_t#

Indicates the null output policy of a function.

This policy determines whether a null-mask should be excluded from the output column.

For example, consider a null-aware IS_NULL function:

void is_null(optional<bool> * out, optional<int> a){
  *out = !a.has_value();
}

using output_nullability::PRESERVE a null-mask may be produced. with output_nullability::ALL_VALID a null-mask will not be produced and all values are considered valid. It is undefined behaviour to use ALL_VALID with a UDF that produces null values.

Values:

enumerator PRESERVE#: A null-mask may be produced if needed.

enumerator ALL_VALID#: A null-mask is not produced and all values are considered valid even if null values are produced

enum class error_policy : uint8_t#

Indicates whether a function nullifies its output on error.

Values:

enumerator PROPAGATE#: The function propagates errors.

enumerator NULLIFY#: The function nullifies its output on error.

enum class udf_source_type : uint8_t#

Indicates the source language of a user defined function (UDF) to be used in JIT APIs.

Values:

enumerator CUDA#: The UDF is a CUDA function.

enumerator PTX#: The UDF is a PTX function.

Functions

column_view bit_cast(column_view const &input, data_type type)#

Zero-copy cast between types with the same size and compatible underlying representations.

This is similar to reinterpret_cast or bit_cast in that it gives a view of the same raw bits as a different type. Unlike reinterpret_cast however, this cast is only allowed on types that have the same width and compatible representations. For example, the way timestamp types are laid out in memory is equivalent to an integer representing a duration since a fixed epoch; bit-casting to the same integer type (INT32 for days, INT64 for others) results in a raw view of the duration count. A FLOAT32 can also be bit-casted into INT32 and treated as an integer value. However, an INT32 column cannot be bit-casted to INT64 as the sizes differ, nor can a string_view column be casted into a numeric type column as their data representations are not compatible.

The validity of the conversion can be checked with cudf::is_bit_castable().

Throws:

cudf::logic_error – if the specified cast is not possible, i.e., is_bit_castable(input.type(), type) is false.

Parameters:

input – The column_view to cast from
type – The data_type to cast to

Returns:

New column_view wrapping the same data as input but cast to type

mutable_column_view bit_cast( mutable_column_view const &input, data_type type )#

Zero-copy cast between types with the same size and compatible underlying representations.

The validity of the conversion can be checked with cudf::is_bit_castable().

Throws:

cudf::logic_error – if the specified cast is not possible, i.e., is_bit_castable(input.type(), type) is false.

Parameters:

input – The mutable_column_view to cast from
type – The data_type to cast to

Returns:

New mutable_column_view wrapping the same data as input but cast to type

template<typename T> size_type distance(T f, T l)#

Similar to std::distance but returns cudf::size_type and performs static_cast

Template Parameters:

T – Iterator type

Parameters:

f – “first” iterator
l – “last” iterator

Returns:

The distance between first and last

constexpr bool operator==(data_type const &lhs, data_type const &rhs)#

Compares two data_type objects for equality.

// TODO Define exactly what it means for two data_types to be equal. e.g., are two timestamps with different resolutions equal? How about decimals with different scale/precision?

Parameters:

lhs – The first data_type to compare
rhs – The second data_type to compare

Returns:

true lhs is equal to rhs

Returns:

false lhs is not equal to rhs

inline bool operator!=(data_type const &lhs, data_type const &rhs)#

Compares two data_type objects for inequality.

// TODO Define exactly what it means for two data_types to be equal. e.g., are two timestamps with different resolutions equal? How about decimals with different scale/precision?

Parameters:

lhs – The first data_type to compare
rhs – The second data_type to compare

Returns:

true lhs is not equal to rhs

Returns:

false lhs is equal to rhs

std::size_t size_of(data_type t)#

Returns the size in bytes of elements of the specified data_type

Note

Only fixed-width types are supported

Throws:: cudf::logic_error – if is_fixed_width(element_type) == false
Parameters:: t – The data_type to get the size of
Returns:: Size in bytes of an element of the specified data_type

template<typename T> inline constexpr bool has_atomic_support()#

Indicates whether the type T has support for atomics.

Template Parameters:: T – The type to verify
Returns:: true T has support for atomics
Returns:: false T no support for atomics

inline constexpr bool has_atomic_support(data_type type)#

Indicates whether type has support for atomics.

Parameters:: type – The data_type to verify
Returns:: true type has support for atomics
Returns:: false type no support for atomics

template<typename L, typename R> inline constexpr bool is_relationally_comparable( )#

Indicates whether objects of types L and R can be relationally compared.

Given two objects L l, and R r, returns true if l < r and l > r are well-formed expressions.

Template Parameters:

L – Type of the first object
R – Type of the second object

Returns:

true Objects of types L and R can be relationally be compared

Returns:

false Objects of types L and R cannot be compared

bool is_relationally_comparable(data_type type)#

Checks whether data_type type supports relational comparisons.

Parameters:: type – Data_type for comparison.
Returns:: true If type supports relational comparisons.
Returns:: false If type does not support relational comparisons.

template<typename L, typename R> inline constexpr bool is_equality_comparable( )#

Indicates whether objects of types L and R can be compared for equality.

Given two objects L l, and R r, returns true if l == r is a well-formed expression.

Template Parameters:

L – Type of the first object
R – Type of the second object

Returns:

true Objects of types L and R can be compared for equality

Returns:

false Objects of types L and R cannot be compared

bool is_equality_comparable(data_type type)#

Checks whether data_type type supports equality comparisons.

Parameters:: type – Data_type for comparison.
Returns:: true If type supports equality comparisons.
Returns:: false If type does not support equality comparisons.

template<typename T> inline constexpr bool is_numeric()#

Indicates whether the type T is a numeric type.

Template Parameters:: T – The type to verify
Returns:: true T is numeric
Returns:: false T is not numeric

bool is_numeric(data_type type)#

Indicates whether type is a numeric data_type.

“Numeric” types are fundamental integral/floating point types such as INT* or FLOAT*. Types that wrap a numeric type are not considered numeric, e.g., TIMESTAMP.

Parameters:: type – The data_type to verify
Returns:: true type is numeric
Returns:: false type is not numeric

template<typename T> inline constexpr bool is_index_type()#

Indicates whether the type T is a index type.

A type T is considered an index type if it is valid to use elements of type T to index into a column. I.e., index types are integral types such as ‘INT*’ apart from ‘bool’.

Template Parameters:: T – The type to verify
Returns:: true T is index type
Returns:: false T is not index type

bool is_index_type(data_type type)#

Indicates whether the type type is a index type.

A type T is considered an index type if it is valid to use elements of type T to index into a column. I.e., index types are integral types such as ‘INT*’ apart from ‘bool’.

Parameters:: type – The data_type to verify
Returns:: true type is index type
Returns:: false type is not index type

template<typename T> inline constexpr bool is_signed()#

Indicates whether the type T is a signed numeric type.

Template Parameters:: T – The type to verify
Returns:: true T is signed numeric

bool is_signed(data_type type)#

Indicates whether type is a signed numeric data_type.

“Signed Numeric” types include fundamental integral types such as INT* but can also be FLOAT* types.

Parameters:: type – The data_type to verify
Returns:: true type is signed numeric

template<typename T> inline constexpr bool is_unsigned()#

Indicates whether the type T is a unsigned numeric type.

Template Parameters:: T – The type to verify
Returns:: true T is unsigned numeric
Returns:: false T is signed numeric

bool is_unsigned(data_type type)#

Indicates whether type is a unsigned numeric data_type.

“Unsigned Numeric” types are fundamental integral types such as UINT*.

Parameters:: type – The data_type to verify
Returns:: true type is unsigned numeric
Returns:: false type is signed numeric

template<typename Iterator> inline constexpr bool is_signed_iterator( )#

Indicates whether the Iterator value type is unsigned.

Template Parameters:: Iterator – The type to verify
Returns:: true if the iterator’s value type is unsigned

template<typename T> inline constexpr bool is_integral()#

Indicates whether the type T is an integral type.

Template Parameters:: T – The type to verify
Returns:: true T is integral
Returns:: false T is not integral

bool is_integral(data_type type)#

Indicates whether type is a integral data_type.

“Integral” types are fundamental integer types such as INT* and UINT*.

Parameters:: type – The data_type to verify
Returns:: true type is integral
Returns:: false type is integral

template<typename T> inline constexpr bool is_integral_not_bool()#

Indicates whether the type T is an integral type but not bool type.

Template Parameters:: T – The type to verify
Returns:: true T is integral but not bool
Returns:: false T is not integral or is bool

bool is_integral_not_bool(data_type type)#

Indicates whether type is a integral data_type and not BOOL8.

“Integral” types are fundamental integer types such as INT* and UINT*.

Parameters:: type – The data_type to verify
Returns:: true type is integral but not bool
Returns:: false type is integral or is bool

template<typename T> inline constexpr bool is_numeric_not_bool()#

Indicates whether the type T is a numeric type but not bool type.

Template Parameters:: T – The type to verify
Returns:: true T is numeric but not bool
Returns:: false T is not numeric or is bool

bool is_numeric_not_bool(data_type type)#

Indicates whether type is a numeric data_type but not BOOL8.

“Numeric” types are integral/floating point types such as INT* or FLOAT*.

Parameters:: type – The data_type to verify
Returns:: true type is numeric but not bool
Returns:: false type is not numeric or is bool

template<typename T> inline constexpr bool is_floating_point()#

Indicates whether the type T is a floating point type.

Template Parameters:: T – The type to verify
Returns:: true T is floating point
Returns:: false T is not floating point

bool is_floating_point(data_type type)#

Indicates whether type is a floating point data_type.

“Floating point” types are fundamental floating point types such as FLOAT*.

Parameters:: type – The data_type to verify
Returns:: true type is floating point
Returns:: false type is not floating point

template<typename T> inline constexpr bool is_byte()#

Indicates whether T is a std::byte type.

Template Parameters:: T – The type to verify
Returns:: true type is std::byte
Returns:: false type is not std::byte

template<typename T> inline constexpr bool is_boolean()#

Indicates whether T is a Boolean type.

Parameters:: type – The data_type to verify
Returns:: true type is Boolean
Returns:: false type is not Boolean

bool is_boolean(data_type type)#

Indicates whether type is a Boolean data_type.

Parameters:: type – The data_type to verify
Returns:: true type is a Boolean
Returns:: false type is not a Boolean

template<typename T> inline constexpr bool is_timestamp()#

Indicates whether the type T is a timestamp type.

Template Parameters:: T – The type to verify
Returns:: true T is a timestamp
Returns:: false T is not a timestamp

bool is_timestamp(data_type type)#

Indicates whether type is a timestamp data_type.

“Timestamp” types are int32_t or int64_t durations since the unix epoch.

Parameters:: type – The data_type to verify
Returns:: true type is a timestamp
Returns:: false type is not a timestamp

template<typename T> inline constexpr bool is_fixed_point()#

Indicates whether the type T is a fixed-point type.

Template Parameters:: T – The type to verify
Returns:: true T is a fixed-point type
Returns:: false T is not a fixed-point type

bool is_fixed_point(data_type type)#

Indicates whether type is a fixed point data_type.

Parameters:: type – The data_type to verify
Returns:: true type is a fixed point type
Returns:: false type is not a fixed point type

template<typename T> inline constexpr bool is_duration()#

Indicates whether the type T is a duration type.

Template Parameters:: T – The type to verify
Returns:: true T is a duration
Returns:: false T is not a duration

bool is_duration(data_type type)#

Indicates whether type is a duration data_type.

“Duration” types are int32_t or int64_t tick counts representing a time interval.

Parameters:: type – The data_type to verify
Returns:: true type is a duration
Returns:: false type is not a duration

template<typename T> inline constexpr bool is_chrono()#

Indicates whether the type T is a chrono type.

Template Parameters:: T – The type to verify
Returns:: true T is a duration or a timestamp type
Returns:: false T is neither a duration nor a timestamp type

bool is_chrono(data_type type)#

Indicates whether type is a chrono data_type.

Chrono types include cudf timestamp types, which represent a point in time, and cudf duration types that represent a time interval.

Parameters:: type – The data_type to verify
Returns:: true type is a chrono type
Returns:: false type is not a chrono type

template<typename T> constexpr bool is_rep_layout_compatible()#

Indicates whether T is layout compatible with its “representation” type.

For example, in a column, a decimal32 is concretely represented by a single int32_t, but the decimal32 type itself contains both the integer representation and the scale. Therefore, decimal32 is not layout compatible with int32_t.

As further example, duration_ns is distinct from its concrete int64_t representation type, but they are layout compatible.

Returns:: true if T is layout compatible with its “representation” type

template<typename T> inline constexpr bool is_dictionary()#

Indicates whether the type T is a dictionary type.

Template Parameters:: T – The type to verify
Returns:: true T is a dictionary-type
Returns:: false T is not dictionary-type

bool is_dictionary(data_type type)#

Indicates whether type is a dictionary data_type.

Parameters:: type – The data_type to verify
Returns:: true type is a dictionary type
Returns:: false type is not a dictionary type

template<typename T> inline constexpr bool is_dictionary_key()#

Indicates whether the type T is a valid dictionary key type.

Template Parameters:: T – The type to verify
Returns:: true T can be a dictionary key type
Returns:: false T cannot be a dictionary key type

bool is_dictionary_key(data_type type)#

Indicates whether type is a valid dictionary type.

Parameters:: type – The data_type to verify
Returns:: true type can be a dictionary key type
Returns:: false type cannot be a dictionary type

template<typename T> inline constexpr bool is_fixed_width()#

Indicates whether elements of type T are fixed-width.

Elements of a fixed-width type all have the same size in bytes.

Template Parameters:: T – The C++ type to verify
Returns:: true T corresponds to a fixed-width element type
Returns:: false T corresponds to a variable-width element type

bool is_fixed_width(data_type type)#

Indicates whether elements of type are fixed-width.

Elements of a fixed-width type all have the same size in bytes.

Parameters:: type – The data_type to verify
Returns:: true type is fixed-width
Returns:: false type is variable-width

template<typename T> inline constexpr bool is_compound()#

Indicates whether the type T is a compound type.

columns with “compound” elements are logically a single column of elements, but may be concretely implemented with two or more columns. For example, a STRING column could contain a column of offsets and a child column of characters.

Template Parameters:: T – The type to verify
Returns:: true T corresponds to a “compound” type
Returns:: false T corresponds to a “simple” type

bool is_compound(data_type type)#

Indicates whether elements of type are compound.

Parameters:: type – The data_type to verify
Returns:: true type is a compound type
Returns:: false type is a simple type

template<typename T> inline constexpr bool is_nested()#

Indicates whether T is a nested type.

“Nested” types are distinct from compound types in that they can have an arbitrarily deep list of descendants of the same type. Strings are not a nested type, but lists are.

Parameters:: T – The type to verify
Returns:: true T is a nested type
Returns:: false T is not a nested type

bool is_nested(data_type type)#

Indicates whether type is a nested type.

“Nested” types are distinct from compound types in that they can have an arbitrarily deep list of descendants of the same type. Strings are not a nested type, but lists are.

Parameters:: type – The data_type to verify
Returns:: true type is a nested type
Returns:: false type is not a nested type

bool is_bit_castable(data_type from, data_type to)#

Indicates whether from is bit-castable to to.

This casting is based on std::bit_cast. Data types that have the same size and are trivially copyable are eligible for this casting.

See cudf::bit_cast() which returns a zero-copy column_view when casting between bit-castable types.

Parameters:

from – The data_type to convert from
to – The data_type to convert to

Returns:

true if the types are castable

Variables

template<typename ...Ts> constexpr bool has_common_type_v = detail::has_common_type_impl<void, Ts...>::value#: Helper variable template for has_common_type<>::value.

struct order_info#

#include <cudf/types.hpp>

Indicates how a collection of values has been ordered.

Public Members

sorted is_sorted#: Indicates whether the collection is sorted.

order ordering#: Indicates the order in which the values are sorted.

null_order null_ordering#: Indicates how null values compare against all other values.

class data_type#

#include <cudf/types.hpp>

Indicator for the logical data type of an element in a column.

Simple types can be entirely described by their id(), but some types require additional metadata to fully describe elements of that type.

Public Functions

data_type(data_type const&) = default#: Copy constructor.

data_type(data_type&&) = default#: Move constructor.

data_type &operator=(data_type const&) = default#

Copy assignment operator for data_type.

Returns:: Reference to this object

data_type &operator=(data_type&&) = default#

Move assignment operator for data_type.

Returns:: Reference to this object

inline explicit constexpr data_type(type_id id)#

Construct a new data_type object.

Parameters:: id – The type’s identifier

inline explicit data_type(type_id id, int32_t scale)#

Construct a new data_type object for numeric::fixed_point

Parameters:

id – The fixed_point’s identifier
scale – The fixed_point’s scale (see fixed_point::_scale)

inline constexpr type_id id() const noexcept#

Returns the type identifier.

Returns:: The type identifier

inline constexpr int32_t scale() const noexcept#

Returns the scale (for fixed_point types)

Returns:: The scale

template<typename From, typename To> struct is_convertible : public cuda::std::is_convertible<From, To>#

template<typename Duration1, typename Duration2> struct is_convertible<cudf::detail::timestamp<Duration1>, cudf::detail::timestamp<Duration2>> : public cuda::std::is_convertible<cudf::detail::time_point<Duration1>::duration, cudf::detail::time_point<Duration2>::duration>#