Files | Functions

Files

file  copying.hpp
 Column APIs for gather, scatter, split, slice, etc.
 

Functions

std::unique_ptr< tablecudf::scatter (table_view const &source, column_view const &scatter_map, table_view const &target, bool check_bounds=false, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
 Scatters the rows of the source table into a copy of the target table according to a scatter map. More...
 
std::unique_ptr< tablecudf::scatter (std::vector< std::reference_wrapper< const scalar >> const &source, column_view const &indices, table_view const &target, bool check_bounds=false, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
 Scatters a row of scalar values into a copy of the target table according to a scatter map. More...
 
std::unique_ptr< tablecudf::boolean_mask_scatter (table_view const &input, table_view const &target, column_view const &boolean_mask, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
 Scatters rows from the input table to rows of the output corresponding to true values in a boolean mask. More...
 
std::unique_ptr< tablecudf::boolean_mask_scatter (std::vector< std::reference_wrapper< const scalar >> const &input, table_view const &target, column_view const &boolean_mask, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
 Scatters scalar values to rows of the output corresponding to true values in a boolean mask. More...
 

Detailed Description

Function Documentation

◆ boolean_mask_scatter() [1/2]

std::unique_ptr<table> cudf::boolean_mask_scatter ( std::vector< std::reference_wrapper< const scalar >> const &  input,
table_view const &  target,
column_view const &  boolean_mask,
rmm::mr::device_memory_resource mr = rmm::mr::get_current_device_resource() 
)

Scatters scalar values to rows of the output corresponding to true values in a boolean mask.

The ith scalar in input will be written to all columns of the output table at the location of the ith true value in boolean_mask. All other rows in the output will equal the same row in target.

Example:
input: {11}
boolean_mask: {true, false, false, false, true, true, false, true, true, false}
target: {{ 2, 2, 3, 4, 4, 7, 7, 7, 8, 10}}
output: {{ 11, 2, 3, 4, 11, 11, 7, 11, 11, 10}}
Exceptions
cudf::logic_errorif input.size() != target.num_columns()
cudf::logic_errorif any ith input_scalar type != ith target_column type
cudf::logic_errorif boolean_mask.type() != bool
cudf::logic_errorif boolean_mask.size() != target.size()
Parameters
[in]inputscalars to scatter
[in]targettable_view to modify with scattered values from input
[in]boolean_maskcolumn_view which acts as boolean mask.
[in]mrDevice memory resource used to allocate device memory of the returned table.
Returns
Returns a table by scattering input into target as per boolean_mask.

◆ boolean_mask_scatter() [2/2]

std::unique_ptr<table> cudf::boolean_mask_scatter ( table_view const &  input,
table_view const &  target,
column_view const &  boolean_mask,
rmm::mr::device_memory_resource mr = rmm::mr::get_current_device_resource() 
)

Scatters rows from the input table to rows of the output corresponding to true values in a boolean mask.

The ith row of input will be written to the output table at the location of the ith true value in boolean_mask. All other rows in the output will equal the same row in target.

boolean_mask should have number of trues <= number of rows in input. If boolean mask is true, corresponding value in target is updated with value from corresponding input column, else it is left untouched.

Example:
input: {{1, 5, 6, 8, 9}}
boolean_mask: {true, false, false, false, true, true, false, true, true, false}
target: {{ 2, 2, 3, 4, 4, 7, 7, 7, 8, 10}}
output: {{ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}}
Exceptions
cudf::logic_errorif input.num_columns() != target.num_columns()
cudf::logic_errorif any ith input_column type != ith target_column type
cudf::logic_errorif boolean_mask.type() != bool
cudf::logic_errorif boolean_mask.size() != target.num_rows()
cudf::logic_errorif number of true in boolean_mask > input.num_rows()
Parameters
[in]inputtable_view (set of dense columns) to scatter
[in]targettable_view to modify with scattered values from input
[in]boolean_maskcolumn_view which acts as boolean mask.
[in]mrDevice memory resource used to allocate device memory of the returned table.
Returns
Returns a table by scattering input into target as per boolean_mask.

◆ scatter() [1/2]

std::unique_ptr<table> cudf::scatter ( std::vector< std::reference_wrapper< const scalar >> const &  source,
column_view const &  indices,
table_view const &  target,
bool  check_bounds = false,
rmm::mr::device_memory_resource mr = rmm::mr::get_current_device_resource() 
)

Scatters a row of scalar values into a copy of the target table according to a scatter map.

Scatters values from the source row into the target table out-of-place, returning a "destination table". The scatter is performed according to a scatter map such that row scatter_map[i] of the destination table is replaced by the source row. All other rows of the destination table equal corresponding rows of the target table.

The number of elements in source must match the number of columns in target and their corresponding datatypes must be the same.

If the same index appears more than once in the scatter map, the result is undefined.

Exceptions
cudf::logic_errorif check_bounds == true and an index exists in scatter_map outside the range [-n, n), where n is the number of rows in the target table. If check_bounds == false, the behavior is undefined.
Parameters
sourceThe input scalars containing values to be scattered into the target columns
indicesA non-nullable column of integral indices that indicate the rows in the target table to be replaced by source.
targetThe set of columns into which values from the source_table are to be scattered
check_boundsOptionally perform bounds checking on the values of scatter_map and throw an error if any of its values are out of bounds.
mrDevice memory resource used to allocate the returned table's device memory.
Returns
Result of scattering values from source to target

◆ scatter() [2/2]

std::unique_ptr<table> cudf::scatter ( table_view const &  source,
column_view const &  scatter_map,
table_view const &  target,
bool  check_bounds = false,
rmm::mr::device_memory_resource mr = rmm::mr::get_current_device_resource() 
)

Scatters the rows of the source table into a copy of the target table according to a scatter map.

Scatters values from the source table into the target table out-of-place, returning a "destination table". The scatter is performed according to a scatter map such that row scatter_map[i] of the destination table gets row i of the source table. All other rows of the destination table equal corresponding rows of the target table.

The number of columns in source must match the number of columns in target and their corresponding datatypes must be the same.

If the same index appears more than once in the scatter map, the result is undefined.

A negative value i in the scatter_map is interpreted as i+n, where n is the number of rows in the target table.

Exceptions
cudf::logic_errorif check_bounds == true and an index exists in scatter_map outside the range [-n, n), where n is the number of rows in the target table. If check_bounds == false, the behavior is undefined.
Parameters
sourceThe input columns containing values to be scattered into the target columns
scatter_mapA non-nullable column of integral indices that maps the rows in the source table to rows in the target table. The size must be equal to or less than the number of elements in the source columns.
targetThe set of columns into which values from the source_table are to be scattered
check_boundsOptionally perform bounds checking on the values of scatter_map and throw an error if any of its values are out of bounds.
mrDevice memory resource used to allocate the returned table's device memory.
Returns
Result of scattering values from source to target