pitrou commented on a change in pull request #7695: URL: https://github.com/apache/arrow/pull/7695#discussion_r453001192
########## File path: docs/source/cpp/compute.rst ########## @@ -0,0 +1,419 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + +.. default-domain:: cpp +.. highlight:: cpp +.. cpp:namespace:: arrow::compute + +================= +Compute Functions +================= + +.. TODO: describe API and how to invoke compute functions + +Available functions +=================== + +Aggregations +------------ + ++--------------------------+------------+--------------------+-----------------------+--------------------------------------------+ +| Function name | Arity | Input types | Output type | Options class | ++==========================+============+====================+=======================+============================================+ +| count | Unary | Any | Scalar Int64 | :struct:`CountOptions` | ++--------------------------+------------+--------------------+-----------------------+--------------------------------------------+ +| mean | Unary | Numeric | Scalar Float64 | | ++--------------------------+------------+--------------------+-----------------------+--------------------------------------------+ +| minmax | Unary | Numeric | Scalar Struct (1) | :struct:`MinMaxOptions` | ++--------------------------+------------+--------------------+-----------------------+--------------------------------------------+ +| sum | Unary | Numeric | Scalar Numeric (2) | | ++--------------------------+------------+--------------------+-----------------------+--------------------------------------------+ + +Notes: + +* \(1) Output is a ``{"min": input type, "max": input type}`` Struct + +* \(2) Output is Int64, UInt64 or Float64, depending on the input type + + +Element-wise ("scalar") functions +--------------------------------- + +Arithmetic functions +~~~~~~~~~~~~~~~~~~~~ + +Those functions expect two inputs of the same type and apply a given binary +operation to each pair of elements gathered from the inputs. Each function +is also available in an overflow-checking variant, suffixed ``_checked``. + +If any of the input elements in a pair is null, the corresponding output +element is null. + ++--------------------------+------------+--------------------+---------------------+ +| Function name | Arity | Input types | Output type | ++==========================+============+====================+=====================+ +| add | Binary | Numeric | Numeric | ++--------------------------+------------+--------------------+---------------------+ +| add_checked | Binary | Numeric | Numeric | ++--------------------------+------------+--------------------+---------------------+ +| multiply | Binary | Numeric | Numeric | ++--------------------------+------------+--------------------+---------------------+ +| multiply_checked | Binary | Numeric | Numeric | ++--------------------------+------------+--------------------+---------------------+ +| subtract | Binary | Numeric | Numeric | ++--------------------------+------------+--------------------+---------------------+ +| subtract_checked | Binary | Numeric | Numeric | ++--------------------------+------------+--------------------+---------------------+ + +Comparisons +~~~~~~~~~~~ + +Those functions expect two inputs of the same type and apply a given +comparison operator. If any of the input elements in a pair is null, +the corresponding output element is null. + ++--------------------------+------------+---------------------------------+---------------------+ +| Function names | Arity | Input types | Output type | ++==========================+============+=================================+=====================+ +| equal, not_equal | Binary | Numeric | Boolean | ++--------------------------+------------+---------------------------------+---------------------+ +| equal, not_equal | Binary | Binary- and String-like | Boolean | ++--------------------------+------------+---------------------------------+---------------------+ +| equal, not_equal | Binary | Temporal | Boolean | ++--------------------------+------------+---------------------------------+---------------------+ +| greater, greater_equal, | Binary | Numeric | Boolean | +| less, less_equal | | | | ++--------------------------+------------+---------------------------------+---------------------+ +| greater, greater_equal, | Binary | Binary- and String-like | Boolean | +| less, less_equal | | | | ++--------------------------+------------+---------------------------------+---------------------+ +| greater, greater_equal, | Binary | Temporal | Boolean | +| less, less_equal | | | | ++--------------------------+------------+---------------------------------+---------------------+ + +Logical functions +~~~~~~~~~~~~~~~~~~ + +The normal behaviour for these functions is to emit a null if any of the +inputs is null. + +Some of them are also available in a "`Kleene logic`_" variant (suffixed +``_kleene``) where null is taken to mean "undefined". For those variants +therefore: + +* "true AND null", "null AND true" give "null" (the result is undefined) +* "true OR null", "null OR true" give "true" +* "false AND null", "null AND false" give "false" +* "false OR null", "null OR false" give "null" (the result is undefined) + ++--------------------------+------------+--------------------+---------------------+ +| Function name | Arity | Input types | Output type | ++==========================+============+====================+=====================+ +| and | Binary | Boolean | Boolean | ++--------------------------+------------+--------------------+---------------------+ +| and_kleene | Binary | Boolean | Boolean | ++--------------------------+------------+--------------------+---------------------+ +| invert | Unary | Boolean | Boolean | ++--------------------------+------------+--------------------+---------------------+ +| or | Binary | Boolean | Boolean | ++--------------------------+------------+--------------------+---------------------+ +| or_kleene | Binary | Boolean | Boolean | ++--------------------------+------------+--------------------+---------------------+ +| xor | Binary | Boolean | Boolean | ++--------------------------+------------+--------------------+---------------------+ + +.. _Kleene logic: https://en.wikipedia.org/wiki/Three-valued_logic#Kleene_and_Priest_logics + +String functions +~~~~~~~~~~~~~~~~ + ++--------------------------+------------+--------------------+---------------------+---------+ +| Function name | Arity | Input types | Output type | Notes | ++==========================+============+====================+=====================+=========+ +| ascii_length | Unary | String-like | Int32 or Int64 | \(1) | ++--------------------------+------------+--------------------+---------------------+---------+ +| ascii_lower | Unary | String-like | String-like | \(2) | ++--------------------------+------------+--------------------+---------------------+---------+ +| ascii_upper | Unary | String-like | String-like | \(2) | ++--------------------------+------------+--------------------+---------------------+---------+ +| utf8_lower | Unary | String-like | String-like | \(3) | ++--------------------------+------------+--------------------+---------------------+---------+ +| utf8_upper | Unary | String-like | String-like | \(3) | ++--------------------------+------------+--------------------+---------------------+---------+ + +* \(1) Output is the physical length in bytes of each input element. + +* \(2) Each ASCII character in the input is converted to lowercase or + uppercase. Non-ASCII characters are left untouched. + +* \(3) Each UTF8-encoded character in the input is converted to lowercase or + uppercase. + +Containment tests +~~~~~~~~~~~~~~~~~ + ++--------------------------+------------+----------------------------------+-----------------------+--------------------------------------------+ +| Function name | Arity | Input types | Output type | Options class | ++==========================+============+==================================+=======================+============================================+ +| binary_contains_exact | Unary | String-like | Boolean (1) | :struct:`BinaryContainsExactOptions` | ++--------------------------+------------+----------------------------------+-----------------------+--------------------------------------------+ +| isin | Unary | Binary- and String-like | Boolean (2) | :struct:`SetLookupOptions` | ++--------------------------+------------+----------------------------------+-----------------------+--------------------------------------------+ +| isin | Unary | Null | Boolean (2) | :struct:`SetLookupOptions` | ++--------------------------+------------+----------------------------------+-----------------------+--------------------------------------------+ +| isin | Unary | Boolean,Numeric, Temporal | Boolean (2) | :struct:`SetLookupOptions` | ++--------------------------+------------+----------------------------------+-----------------------+--------------------------------------------+ +| match | Unary | Binary- and String-like | Int32 (3) | :struct:`SetLookupOptions` | ++--------------------------+------------+----------------------------------+-----------------------+--------------------------------------------+ +| match | Unary | Null | Int32 (3) | :struct:`SetLookupOptions` | ++--------------------------+------------+----------------------------------+-----------------------+--------------------------------------------+ +| match | Unary | Boolean,Numeric, Temporal | Int32 (3) | :struct:`SetLookupOptions` | ++--------------------------+------------+----------------------------------+-----------------------+--------------------------------------------+ + +* \(1) Output is true iff :member:`BinaryContainsExactOptions::pattern` Review comment: You get the detailed API docs by clicking on the `BinaryContainsExactOptions` hyperlink (in the rendered docs only, though :-)). ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
