散点 (Scattering)

文件
文件	copying.hpp
	列API，用于 gather（聚集）、scatter（散点）、split（分割）、slice（切片）等操作。

函数
std::unique_ptr< table >	cudf::scatter (table_view const &source, column_view const &scatter_map, table_view const &target, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	根据散点映射将源表的行散布到目标表的副本中。更多...
std::unique_ptr< table >	cudf::scatter (std::vector< std::reference_wrapper< scalar const >> const &source, column_view const &indices, table_view const &target, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	根据散点映射将一行标量值散布到目标表的副本中。更多...
std::unique_ptr< table >	cudf::boolean_mask_scatter (table_view const &input, table_view const &target, column_view const &boolean_mask, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	根据布尔掩码中的真值，将输入表的行散布到输出表的相应行中。更多...
std::unique_ptr< table >	cudf::boolean_mask_scatter (std::vector< std::reference_wrapper< scalar const >> const &input, table_view const &target, column_view const &boolean_mask, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	根据布尔掩码中的真值，将标量值散布到输出表的相应行中。更多...

详细描述

函数文档

boolean_mask_scatter() [1/2]

std::unique_ptr<table> cudf::boolean_mask_scatter	(	std::vector< std::reference_wrapper< scalar const >> const &	input,
		table_view const &	target,
		column_view const &	boolean_mask,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

根据布尔掩码中的真值，将标量值散布到输出表的相应行中。

input 中的第i个标量将被写入输出表的第 i 列中，写入位置对应于boolean_mask中的每个真值。输出表中的所有其他行将等于target表中的相应行。

示例
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}}

异常

std::invalid_argument	如果 input 的大小不等于 target 的列数
cudf::data_type_error	如果任何第i个 input 列的类型不等于第i个 target 列的类型
cudf::data_type_error	如果 boolean_mask 的类型不是 bool
std::invalid_argument	如果 boolean_mask 的大小不等于 target 的行数

参数

input	要散布的标量
target	table_view 用来自 input 的散布值修改
boolean_mask	column_view 用作布尔掩码
stream	用于设备内存操作和内核启动的 CUDA 流
mr	用于分配返回表的设备内存的设备内存资源

返回值

根据 boolean_mask 将 input 散布到 target 中，返回一个表

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::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

根据布尔掩码中的真值，将输入表的行散布到输出表的相应行中。

input 的第i行将被写入输出表中，写入位置对应于 boolean_mask 中的第i个真值。输出表中的所有其他行将等于 target 表中的相应行。

boolean_mask 中 true 的数量应小于等于 input 的行数。如果布尔掩码为 true，则 target 中的相应值将使用相应 input 列中的值进行更新，否则保持不变。

示例
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}}

异常

std::invalid_argument	如果 input 的列数不等于 target 的列数
cudf::data_type_error	如果任何第i个 input 列的类型不等于第i个 target 列的类型
cudf::data_type_error	如果 boolean_mask 的类型不是 bool
std::invalid_argument	如果 boolean_mask 的大小不等于 target 的行数
std::invalid_argument	如果 boolean_mask 中 true 的数量大于 input 的行数

参数

input	table_view (一组稠密列) 要散布
target	table_view 用来自 input 的散布值修改
boolean_mask	column_view 用作布尔掩码
stream	用于设备内存操作和内核启动的 CUDA 流
mr	用于分配返回表的设备内存的设备内存资源

返回值

根据 boolean_mask 将 input 散布到 target 中，返回一个表

scatter() [1/2]

std::unique_ptr<table> cudf::scatter	(	std::vector< std::reference_wrapper< scalar const >> const &	source,
		column_view const &	indices,
		table_view const &	target,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

根据散点映射将一行标量值散布到目标表的副本中。

将源行的值非原地 (out-of-place) 散布到目标表中，返回一个“目标表”。散布根据散点映射进行，使得目标表的行 scatter_map[i] 被源行替换。目标表中的所有其他行等于目标表的相应行。

源中的元素数量必须与 target 中的列数匹配，并且它们的相应数据类型必须相同。

如果散点映射中同一索引出现多次，则结果未定义。

如果 scatter_map 中的任何值超出区间 [-n, n) 范围（其中 n 是 target 表中的行数），则行为未定义。

异常

std::invalid_argument	如果标量数量与 target 的列数不匹配
std::invalid_argument	如果 indices 包含空值
cudf::data_type_error	如果标量和 target 列的数据类型不匹配

参数

source	包含要散布到 target 列中的值的输入标量
indices	一个非空的整数索引列，指示 target 表中要由 source 替换的行。
target	要将来自 source_table 的值散布到其中的列集
stream	用于设备内存操作和内核启动的 CUDA 流
mr	用于分配返回表的设备内存的设备内存资源

返回值

将 source 中的值散布到 target 的结果

scatter() [2/2]

std::unique_ptr<table> cudf::scatter	(	table_view const &	source,
		column_view const &	scatter_map,
		table_view const &	target,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

根据散点映射将源表的行散布到目标表的副本中。

将源表的值非原地 (out-of-place) 散布到目标表中，返回一个“目标表”。散布根据散点映射进行，使得目标表的行 scatter_map[i] 获得源表的第 i 行。目标表中的所有其他行等于目标表的相应行。

source 中的列数必须与 target 中的列数匹配，并且它们的相应数据类型必须相同。

如果散点映射中同一索引出现多次，则结果未定义。

如果 scatter_map 中的任何值超出区间 [-n, n) 范围（其中 n 是 target 表中的行数），则行为未定义。

scatter_map 中的负值 i 被解释为 i+n，其中 n 是 target 表中的行数。

异常

std::invalid_argument	如果 source 的列数与 target 的列数不匹配
std::invalid_argument	如果 source 的行数与 scatter_map 中的元素数量不匹配
cudf::data_type_error	如果 source 和 target 列的数据类型不匹配
std::invalid_argument	如果 scatter_map 包含空值

参数

source	包含要散布到 target 列中的值的输入列
scatter_map	一个非空的整数索引列，将 source 表中的行映射到 target 表中的行。其大小必须等于或小于 source 列中的元素数量。
target	要将来自 source_table 的值散布到其中的列集
stream	用于设备内存操作和内核启动的 CUDA 流
mr	用于分配返回表的设备内存的设备内存资源

返回值

将 source 中的值散布到 target 的结果