【PaddlePaddle Hackathon 3】16 新增 API paddle.take

docs/api/api_label

@@ -246,6 +246,7 @@ paddle.subtract	.. _api_paddle_subtract:
 paddle.Tensor.subtract_	.. _api_paddle_Tensor_subtract_:
 paddle.sum	.. _api_paddle_sum:
 paddle.t	.. _api_paddle_t:
+paddle.take	.. _api_paddle_take:
 paddle.tanh	.. _api_paddle_tanh:
 paddle.tanh_	.. _api_paddle_tanh_:
 paddle.tile	.. _api_paddle_tile:

docs/api/paddle/Overview_cn.rst

@@ -136,6 +136,7 @@ tensor 数学操作
     " :ref:`paddle.acosh <cn_api_fluid_layers_acosh>` ", "反双曲余弦函数"
     " :ref:`paddle.asinh <cn_api_fluid_layers_asinh>` ", "反双曲正弦函数"
     " :ref:`paddle.atanh <cn_api_fluid_layers_atanh>` ", "反双曲正切函数"
+    " :ref:`paddle.take <cn_api_tensor_take>` ", "输出给定索引处的输入元素，结果与 index 的形状相同"
 
 
 .. _tensor_logic:

docs/api/paddle/Tensor/Overview_en.rst

@@ -246,6 +246,7 @@ Methods
     subtract_
     sum
     t
+    take
     tanh
     tanh_
     tile

docs/api/paddle/Tensor_cn.rst

@@ -2412,3 +2412,12 @@ erfinv(x, name=None)
 对输入 x 进行逆误差函数计算
 
 请参考 :ref:`cn_api_paddle_tensor_erfinv`
+
+take(index, mode='raise', name=None)
+:::::::::
+
+返回：一个新的 Tensor，其中包含给定索引处的输入元素。结果与 :attr:`index` 的形状相同
+
+返回类型：Tensor
+
+请参考 :ref:`cn_api_tensor_take`

docs/api/paddle/take_cn.rst

@@ -0,0 +1,32 @@
+.. _cn_api_paddle_tensor_take:
+
+take
+-------------------------------
+
+.. py:function:: paddle.take(x, index, mode='raise', name=None)
+
+返回一个新的 Tensor，其中包含给定索引处的输入元素。
+将输入 Tensor 视为一维 Tensor，返回指定索引上的元素集合，返回结果与 :attr:`index` 的形状相同。
+
+参数
+:::::::::
+
+- **x**  (Tensor) - 输入的 Tensor，支持 int32、int64、float32、float64 数据类型。
+- **index**  (Tensor) - 索引矩阵，支持 int32、int64 数据类型。
+- **mode**  (str，可选) - 索引越界处理，可选 ``'raise'``，``'wrap'``，``'clip'``，默认为 ``'raise'``。
+
+    - ``raise``：直接抛出错误；
+    - ``wrap``：通过取余数来约束超出范围的索引；
+    - ``clip``：将超出范围的索引剪裁到允许的最小（大）范围。此模式意味着所有超出范围的索引都将被最后一个元素的索引替换，而且将禁用负值索引。
+
+- **name**  (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+返回
+:::::::::
+
+Tensor，其中包含给定索引处的输入元素。与 index 的形状相同。
+
+代码示例
+:::::::::
+
+COPY-FROM: paddle.take