Gathering

Files
file	gather.hpp

Functions
std::unique_ptr< column >	cudf::lists::segmented_gather (lists_column_view const &source_column, lists_column_view const &gather_map_list, out_of_bounds_policy bounds_policy=out_of_bounds_policy::DONT_CHECK, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Segmented gather of the elements within a list element in each row of a list column. More...

Detailed Description

Function Documentation

segmented_gather()

std::unique_ptr<column> cudf::lists::segmented_gather	(	lists_column_view const &	source_column,
		lists_column_view const &	gather_map_list,
		out_of_bounds_policy	bounds_policy = out_of_bounds_policy::DONT_CHECK,
		rmm::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Segmented gather of the elements within a list element in each row of a list column.

source_column with any depth and gather_map_list with depth 1 are only supported.

source_column   : [{"a", "b", "c", "d"}, {"1", "2", "3", "4"}, {"x", "y", "z"}]
gather_map_list : [{0, 1, 3, 2}, {1, 3, 2}, {}]
 
result          : [{"a", "b", "d", "c"}, {"2", "4", "3"}, {}]

Exceptions

cudf::logic_error	if gather_map_list size is not same as source_column size.
cudf::logic_error	if gather_map contains null values.
cudf::logic_error	if gather_map is not list column of an index type.

If indices in gather_map_list are outside the range [-n, n), where n is the number of elements in corresponding row of the source column, the behavior is as follows:

1. If bounds_policy is set to DONT_CHECK, the behavior is undefined.
2. If bounds_policy is set to NULLIFY, the corresponding element in the list row is set to null in the output column.

source_column       : [{"a", "b", "c", "d"}, {"1", "2", "3", "4"}, {"x", "y", "z"}]
gather_map_list     : [{0, -1, 4, -5}, {1, 3, 5}, {}]
 
result_with_nullify : [{"a", "d", null, null}, {"2", "4", null}, {}]

Parameters

source_column	View into the list column to gather from
gather_map_list	View into a non-nullable list column of integral indices that maps the element in list of each row in the source columns to rows of lists in the destination columns.
bounds_policy	Can be DONT_CHECK or NULLIFY. Selects whether or not to nullify the output list row's element, when the gather index falls outside the range [-n, n), where n is the number of elements in list row corresponding to the gather-map row.
mr	Device memory resource to allocate any returned objects

Returns

column with elements in list of rows gathered based on gather_map_list