Extracting

Files
file	lists/extract.hpp

Functions
std::unique_ptr< column >	cudf::lists::extract_list_element (lists_column_view const &lists_column, size_type index, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	Create a column where each row is the element at position index from the corresponding sublist in the input lists_column. More...
std::unique_ptr< column >	cudf::lists::extract_list_element (lists_column_view const &lists_column, column_view const &indices, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	Create a column where each row is a single element from the corresponding sublist in the input lists_column, selected using indices from the indices column. More...

Detailed Description

Function Documentation

extract_list_element() [1/2]

std::unique_ptr<column> cudf::lists::extract_list_element	(	lists_column_view const &	lists_column,
		column_view const &	indices,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

Create a column where each row is a single element from the corresponding sublist in the input lists_column, selected using indices from the indices column.

Output column[i] is set from element lists_column[i][indices[i]]. If indices[i] is larger than the size of the sublist at lists_column[i] then output column[i] = null. Similarly, if indices[i] is null, then column[i] = null.

l = { {1, 2, 3}, {4}, {5, 6} }
r = extract_list_element(l, {0, null, 2})
r is now {1, null, null}

indices[i] may also be negative, in which case the row retrieved is offset from the end of each sublist.

l = { {"a"}, {"b", "c"}, {"d", "e", "f"} }
r = extract_list_element(l, {-1, -2, -4})
r is now {"a", "b", null}

Any input where lists_column[i] == null produces output column[i] = null. Any input where lists_column[i][indices[i]] == null produces output column[i] = null.

Parameters

lists_column	Column to extract elements from.
indices	The column whose rows indicate the element index to be retrieved from each list row.
stream	CUDA stream used for device memory operations and kernel launches.
mr	Device memory resource used to allocate the returned column's device memory.

Returns

Column of extracted elements.

Exceptions

cudf::logic_error

If the sizes of lists_column and indices do not match.

extract_list_element() [2/2]

std::unique_ptr<column> cudf::lists::extract_list_element	(	lists_column_view const &	lists_column,
		size_type	index,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

Create a column where each row is the element at position index from the corresponding sublist in the input lists_column.

Output column[i] is set from element lists_column[i][index]. If index is larger than the size of the sublist at lists_column[i] then output column[i] = null.

l = { {1, 2, 3}, {4}, {5, 6} }
r = extract_list_element(l, 1)
r is now {2, null, 6}

The index may also be negative in which case the row retrieved is offset from the end of each sublist.

l = { {"a"}, {"b", "c"}, {"d", "e", "f"} }
r = extract_list_element(l, -1)
r is now {"a", "c", "f"}

Any input where lists_column[i] == null will produce output column[i] = null. Also, any element where lists_column[i][index] == null will produce output column[i] = null.

Parameters

lists_column	Column to extract elements from.
index	The row within each sublist to retrieve.
stream	CUDA stream used for device memory operations and kernel launches.
mr	Device memory resource used to allocate the returned column's device memory.

Returns

Column of extracted elements.