A non-owning, mutable view of device data as a column of elements, some of which may be null as indicated by a bitmask. More...

#include <column_view.hpp>

Inheritance diagram for cudf::mutable_column_view:

Public Member Functions
	mutable_column_view (mutable_column_view const &)=default
	Copy constructor.

	mutable_column_view (mutable_column_view &&)=default
	Move constructor.

mutable_column_view &	operator= (mutable_column_view const &)=default
	Copy assignment operator. More...

mutable_column_view &	operator= (mutable_column_view &&)=default
	Move assignment operator. More...

	mutable_column_view (data_type type, size_type size, void data, bitmask_type null_mask, size_type null_count, size_type offset=0, std::vector< mutable_column_view > const &children={})
	Construct a `mutable_column_view` from pointers to device memory for the elements and bitmask of the column. More...

template<typename T = void, CUDF_ENABLE_IF(std::is_same_v< T, void > or is_rep_layout_compatible< T >()) >
T *	head () const noexcept
	Returns pointer to the base device memory allocation casted to the specified type. More...

template<typename T , CUDF_ENABLE_IF(is_rep_layout_compatible< T >()) >
T *	data () const noexcept
	Returns the underlying data casted to the specified type, plus the offset. More...

template<typename T , CUDF_ENABLE_IF(is_rep_layout_compatible< T >()) >
T *	begin () const noexcept
	Return first element (accounting for offset) after underlying data is casted to the specified type. More...

template<typename T , CUDF_ENABLE_IF(is_rep_layout_compatible< T >()) >
T *	end () const noexcept
	Return one past the last element after underlying data is casted to the specified type. More...

bitmask_type *	null_mask () const noexcept
	Returns raw pointer to the underlying bitmask allocation. More...

void	set_null_count (size_type new_null_count)
	Set the null count. More...

mutable_column_view	child (size_type child_index) const noexcept
	Returns a reference to the specified child. More...

size_type	num_children () const noexcept
	Returns the number of child columns. More...

auto	child_begin () const noexcept
	Returns iterator to the beginning of the ordered sequence of child column-views. More...

auto	child_end () const noexcept
	Returns iterator to the end of the ordered sequence of child column-views. More...

	operator column_view () const
	Converts a mutable view into an immutable view. More...

Public Member Functions inherited from cudf::detail::column_view_base
template<typename T = void, CUDF_ENABLE_IF(std::is_same_v< T, void > or is_rep_layout_compatible< T >()) >
T const *	head () const noexcept
	Returns pointer to the base device memory allocation casted to the specified type. More...

template<typename T , CUDF_ENABLE_IF(is_rep_layout_compatible< T >()) >
T const *	data () const noexcept
	Returns the underlying data casted to the specified type, plus the offset. More...

template<typename T , CUDF_ENABLE_IF(is_rep_layout_compatible< T >()) >
T const *	begin () const noexcept
	Return first element (accounting for offset) after underlying data is casted to the specified type. More...

template<typename T , CUDF_ENABLE_IF(is_rep_layout_compatible< T >()) >
T const *	end () const noexcept
	Return one past the last element after underlying data is casted to the specified type. More...

size_type	size () const noexcept
	Returns the number of elements in the column. More...

bool	is_empty () const noexcept
	Returns true if `size()` returns zero, or false otherwise. More...

data_type	type () const noexcept
	Returns the element `data_type` More...

bool	nullable () const noexcept
	Indicates if the column can contain null elements, i.e., if it has an allocated bitmask. More...

size_type	null_count () const
	Returns the count of null elements. More...

size_type	null_count (size_type begin, size_type end) const
	Returns the count of null elements in the range [begin, end) More...

bool	has_nulls () const
	Indicates if the column contains null elements, i.e., `null_count() > 0` More...

bool	has_nulls (size_type begin, size_type end) const
	Indicates if the column contains null elements in the range [begin, end), i.e., `null_count(begin, end) > 0` More...

bitmask_type const *	null_mask () const noexcept
	Returns raw pointer to the underlying bitmask allocation. More...

size_type	offset () const noexcept
	Returns the index of the first element relative to the base memory allocation, i.e., what is returned from `head<T>()`. More...

Protected Member Functions
void const *	get_data () const noexcept override
	Returns pointer to the base device memory allocation. More...

Protected Member Functions inherited from cudf::detail::column_view_base
	column_view_base (column_view_base const &)=default
	Copy constructor.

	column_view_base (column_view_base &&)=default
	Move constructor.

column_view_base &	operator= (column_view_base const &)=default
	Copy assignment operator. More...

column_view_base &	operator= (column_view_base &&)=default
	Move assignment operator. More...

	column_view_base (data_type type, size_type size, void const data, bitmask_type const null_mask, size_type null_count, size_type offset=0)
	Construct a `column_view_base` from pointers to device memory for the elements and bitmask of the column. More...

Friends
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. More...

Additional Inherited Members
Protected Attributes inherited from cudf::detail::column_view_base
data_type	_type {type_id::EMPTY}
	Element type.

size_type	_size {}
	Number of elements.

void const *	_data {}
	Pointer to device memory containing elements.

bitmask_type const *	_null_mask {}

size_type	_null_count {}
	The number of null elements.

size_type	_offset {}

Detailed Description

A non-owning, mutable view of device data as a column of elements, some of which may be null as indicated by a bitmask.

A mutable_column_view can be constructed implicitly from a cudf::column, or may be constructed explicitly from a pointer to pre-existing device memory.

Unless otherwise noted, the memory layout of the mutable_column_view's data and bitmask is expected to adhere to the Arrow Physical Memory Layout Specification: https://arrow.apache.org/docs/memory_layout.html

Because mutable_column_view is non-owning, no device memory is allocated nor freed when mutable_column_view objects are created or destroyed.

To enable zero-copy slicing, a mutable_column_view has an offset that indicates the index of the first element in the column relative to the base device memory allocation. By default, offset() is zero.

Definition at line 497 of file column_view.hpp.

Constructor & Destructor Documentation

◆ mutable_column_view()

cudf::mutable_column_view::mutable_column_view	(	data_type	type,
		size_type	size,
		void *	data,
		bitmask_type *	null_mask,
		size_type	null_count,
		size_type	offset = `0`,
		std::vector< mutable_column_view > const &	children = `{}`
	)

Construct a mutable_column_view from pointers to device memory for the elements and bitmask of the column.

If type is EMPTY, the specified null_count will be ignored and null_count() will always return the same value as size()

Exceptions

cudf::logic_error	if `size < 0`
cudf::logic_error	if `size > 0` but `data == nullptr`
cudf::logic_error	if `type.id() == EMPTY` but `data != nullptr` or `null_mask != nullptr`
cudf::logic_error	if `null_count > 0`, but `null_mask == nullptr`
cudf::logic_error	if `offset < 0`

Parameters

type	The element type
size	The number of elements
data	Pointer to device memory containing the column elements
null_mask	Pointer to device memory containing the null indicator bitmask
null_count	The number of null elements.
offset	Optional, index of the first element
children	Optional, depending on the element type, child columns may contain additional data

Member Function Documentation

◆ begin()

template<typename T , CUDF_ENABLE_IF(is_rep_layout_compatible< T >()) >

T* cudf::mutable_column_view::begin ( ) const

inlinenoexcept

Return first element (accounting for offset) after underlying data is casted to the specified type.

This function does not participate in overload resolution if is_rep_layout_compatible<T> is false.

Template Parameters

T	The desired type

Returns: Pointer to the first element after casting

Definition at line 605 of file column_view.hpp.

◆ child()

mutable_column_view cudf::mutable_column_view::child ( size_type child_index ) const

inlinenoexcept

Returns a reference to the specified child.

Parameters

child_index The index of the desired child

Returns: The requested child mutable_column_view

Definition at line 655 of file column_view.hpp.

◆ child_begin()

auto cudf::mutable_column_view::child_begin ( ) const

inlinenoexcept

Returns iterator to the beginning of the ordered sequence of child column-views.

Returns: An iterator to a mutable_column_view referencing the first child column

Definition at line 672 of file column_view.hpp.

◆ child_end()

auto cudf::mutable_column_view::child_end ( ) const

inlinenoexcept

Returns iterator to the end of the ordered sequence of child column-views.

Returns: An iterator to a mutable_column_view to the element following the last child column

Definition at line 679 of file column_view.hpp.

◆ data()

template<typename T , CUDF_ENABLE_IF(is_rep_layout_compatible< T >()) >

T* cudf::mutable_column_view::data ( ) const

inlinenoexcept

Returns the underlying data casted to the specified type, plus the offset.

This function does not participate in overload resolution if is_rep_layout_compatible<T> is false.

Note: If offset() == 0, then head<T>() == data<T>()

Template Parameters

T	The type to cast to

Returns: Typed pointer to underlying data, including the offset

Definition at line 589 of file column_view.hpp.

◆ end()

template<typename T , CUDF_ENABLE_IF(is_rep_layout_compatible< T >()) >

T* cudf::mutable_column_view::end ( ) const

inlinenoexcept

Return one past the last element after underlying data is casted to the specified type.

This function does not participate in overload resolution if is_rep_layout_compatible<T> is false.

Template Parameters

T	The desired type

Returns: Pointer to one past the last element after casting

Definition at line 621 of file column_view.hpp.

◆ get_data()

void const* cudf::mutable_column_view::get_data ( ) const

overrideprotectedvirtualnoexcept

Returns pointer to the base device memory allocation.

The primary purpose of this function is to allow derived classes to override the fundamental properties of memory accesses without needing to change all of the different accessors for the underlying pointer.

Returns: Typed pointer to underlying data

Reimplemented from cudf::detail::column_view_base.

◆ head()

template<typename T = void, CUDF_ENABLE_IF(std::is_same_v< T, void > or is_rep_layout_compatible< T >()) >

T* cudf::mutable_column_view::head ( ) const

inlinenoexcept

Returns pointer to the base device memory allocation casted to the specified type.

This function will only participate in overload resolution if is_rep_layout_compatible<T>() or std::is_same_v<T,void> are true.

Note: If offset() == 0, then head<T>() == data<T>(); It should be rare to need to access the head<T>() allocation of a column, and instead, accessing the elements should be done via data<T>().

Template Parameters

The	type to cast to

Returns: Typed pointer to underlying data

Definition at line 571 of file column_view.hpp.

◆ null_mask()

bitmask_type* cudf::mutable_column_view::null_mask ( ) const

inlinenoexcept

Returns raw pointer to the underlying bitmask allocation.

Note: This function does not account for the offset().; If null_count() == 0, this may return nullptr.

Returns: Raw pointer to the underlying bitmask allocation

Definition at line 635 of file column_view.hpp.

◆ num_children()

size_type cudf::mutable_column_view::num_children ( ) const

inlinenoexcept

Returns the number of child columns.

Returns: The number of child columns

Definition at line 665 of file column_view.hpp.

◆ operator column_view()

cudf::mutable_column_view::operator column_view ( ) const

Converts a mutable view into an immutable view.

Returns: An immutable view of the mutable view's elements

◆ operator=() [1/2]

mutable_column_view& cudf::mutable_column_view::operator= ( mutable_column_view && )

default

Move assignment operator.

Returns: Reference to this object (after transferring ownership)

◆ operator=() [2/2]

mutable_column_view& cudf::mutable_column_view::operator= ( mutable_column_view const & )

default

Copy assignment operator.

Returns: Reference to this object

◆ set_null_count()

void cudf::mutable_column_view::set_null_count ( size_type new_null_count )

Set the null count.

Exceptions

cudf::logic_error if new_null_count > 0 and nullable() == false

Parameters

new_null_count The new null count

Friends And Related Function Documentation

◆ bit_cast

mutable_column_view bit_cast	(	mutable_column_view const &	input,
		data_type	type
	)

friend

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().

Exceptions

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

The documentation for this class was generated from the following file:

column_view.hpp

Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ mutable_column_view()

Member Function Documentation

◆ begin()

◆ child()

◆ child_begin()

◆ child_end()

◆ data()

◆ end()

◆ get_data()

◆ head()

◆ null_mask()

◆ num_children()

◆ operator column_view()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ set_null_count()

Friends And Related Function Documentation

◆ bit_cast