You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by GitBox <gi...@apache.org> on 2020/07/10 20:15:24 UTC
[GitHub] [arrow] bkietz commented on a change in pull request #7695: ARROW-8989: [C++][Doc] Document available compute functions
bkietz commented on a change in pull request #7695:
URL: https://github.com/apache/arrow/pull/7695#discussion_r453046448
##########
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.
Review comment:
```suggestion
inputs is null, similar to the way any operation involving ``NaN`` devolves to ``NaN``.
```
##########
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`
+ is a substring of the corresponding input element.
+
+* \(2) Output is true iff the corresponding input element is equal to one
+ of the elements in :member:`SetLookupOptions::value_set`.
+
+* \(3) Output is the index of the corresponding input element in
+ :member:`SetLookupOptions::value_set`, if found there. Otherwise,
+ output is null.
+
+Structural transforms
+~~~~~~~~~~~~~~~~~~~~~
+
++--------------------------+------------+--------------------+---------------------+---------+
+| Function name | Arity | Input types | Output type | Notes |
++==========================+============+====================+=====================+=========+
+| is_null | Unary | Any | Boolean | \(1) |
++--------------------------+------------+--------------------+---------------------+---------+
+| is_valid | Unary | Any | Boolean | \(2) |
++--------------------------+------------+--------------------+---------------------+---------+
+| list_value_lengths | Unary | List-like | Int32 or Int64 | \(3) |
++--------------------------+------------+--------------------+---------------------+---------+
+
+* \(1) Output is true iff the corresponding input element is non-null.
+
+* \(2) Output is true iff the corresponding input element is null.
+
+* \(3) Each output element is the length of the corresponding input element
+ (null if input is null).
Review comment:
```suggestion
(null if input is null). The output type is Int32 for List, Int64 for LargeList
```
##########
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``.
Review comment:
If we made a recommendation for general use it'd probably be `_checked` so that users become aware of overflow sooner and can be intentional about handling it
##########
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
Review comment:
```suggestion
The inputs and outputs of compute functions are of type :class:`arrow::Datum`, which are
a discriminated union of several shapes of data, including :class:`arrow::Scalar`,
:class:`arrow::Array`, and :class:`arrow::ChunkedArray`.
Compute functions can be invoked by name using the :func:`arrow::compute::CallFunction`
or via dedicated c++ convenience functions.
.. code-block:: cpp
std::shared_ptr<arrow::Int32Array> ints = ...;
std::shared_ptr<arrow::Int32Scalar> increment = ...;
ARROW_ASSIGN_OR_RAISE(arrow::Datum incremented, arrow::compute::CallFunction("add_checked",
{arrow::Datum(ints), arrow::Datum(increment)}));
arrow::ArithmeticOptions options;
options.check_overflow = true;
ARROW_ASSIGN_OR_RAISE(arrow::Datum equivalent, arrow::compute::Add(
{arrow::Datum(ints), arrow::Datum(increment)}, arithmetic_options));
```
##########
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`
+ is a substring of the corresponding input element.
+
+* \(2) Output is true iff the corresponding input element is equal to one
+ of the elements in :member:`SetLookupOptions::value_set`.
+
+* \(3) Output is the index of the corresponding input element in
+ :member:`SetLookupOptions::value_set`, if found there. Otherwise,
+ output is null.
+
+Structural transforms
+~~~~~~~~~~~~~~~~~~~~~
+
++--------------------------+------------+--------------------+---------------------+---------+
+| Function name | Arity | Input types | Output type | Notes |
++==========================+============+====================+=====================+=========+
+| is_null | Unary | Any | Boolean | \(1) |
++--------------------------+------------+--------------------+---------------------+---------+
+| is_valid | Unary | Any | Boolean | \(2) |
++--------------------------+------------+--------------------+---------------------+---------+
+| list_value_lengths | Unary | List-like | Int32 or Int64 | \(3) |
++--------------------------+------------+--------------------+---------------------+---------+
+
+* \(1) Output is true iff the corresponding input element is non-null.
+
+* \(2) Output is true iff the corresponding input element is null.
+
+* \(3) Each output element is the length of the corresponding input element
+ (null if input is null).
+
+Conversions
+~~~~~~~~~~~
+
+A general conversion function named ``cast`` is provided which accepts a large
+number of input and output types. The type to cast to can be passed in a
+:struct:`CastOptions` instance.
+
++--------------------------+------------+--------------------+-----------------------+--------------------------------------------+
+| Function name | Arity | Input types | Output type | Options class |
++==========================+============+====================+=======================+============================================+
+| cast | Unary | Many | Variable | :struct:`CastOptions` |
++--------------------------+------------+--------------------+-----------------------+--------------------------------------------+
+| strptime | Unary | String-like | Timestamp | :struct:`StrptimeOptions` |
++--------------------------+------------+--------------------+-----------------------+--------------------------------------------+
+
+The conversions available with ``cast`` are listed below. In all cases, a
+null input value is converted into a null output value.
+
+**Truth value extraction**
+
++-----------------------------+------------------------------------+--------------+
+| Input type | Output type | Notes |
++=============================+====================================+==============+
+| Binary- and String-like | Boolean | \(1) |
++-----------------------------+------------------------------------+--------------+
+| Numeric | Boolean | \(2) |
++-----------------------------+------------------------------------+--------------+
+
+* \(1) Output is true iff the corresponding input value has non-zero length.
+
+* \(2) Output is true iff the corresponding input value is non-zero.
+
+**Same-kind conversion**
+
++-----------------------------+------------------------------------+--------------+
+| Input type | Output type | Notes |
++=============================+====================================+==============+
+| Int32 | 32-bit Temporal | \(1) |
++-----------------------------+------------------------------------+--------------+
+| Int64 | 64-bit Temporal | \(1) |
++-----------------------------+------------------------------------+--------------+
+| (Large)Binary | (Large)String | \(2) |
++-----------------------------+------------------------------------+--------------+
+| (Large)String | (Large)Binary | \(3) |
++-----------------------------+------------------------------------+--------------+
+| Numeric | Numeric | \(4) \(5) |
++-----------------------------+------------------------------------+--------------+
+| 32-bit Temporal | Int32 | \(1) |
++-----------------------------+------------------------------------+--------------+
+| 64-bit Temporal | Int64 | \(1) |
++-----------------------------+------------------------------------+--------------+
+| Temporal | Temporal | \(4) \(5) |
++-----------------------------+------------------------------------+--------------+
+
+* \(1) No-operation cast: the raw values are kept identical, only
+ the type is changed.
+
+* \(2) Validates the contents if :member:`CastOptions::allow_invalid_utf8`
+ is false.
+
+* \(3) No-operation cast: only the type is changed.
+
+* \(4) Overflow and truncation checks are enabled depending on
+ the given :struct:`CastOptions`.
+
+* \(5) Not all such casts have been implemented.
+
+**String representations**
+
++-----------------------------+------------------------------------+---------+
+| Input type | Output type | Notes |
++=============================+====================================+=========+
+| Boolean | String-like | |
++-----------------------------+------------------------------------+---------+
+| Numeric | String-like | |
++-----------------------------+------------------------------------+---------+
+
+**Generic conversions**
+
++-----------------------------+------------------------------------+---------+
+| Input type | Output type | Notes |
++=============================+====================================+=========+
+| Dictionary | Dictionary value type | |
++-----------------------------+------------------------------------+---------+
+| Extension | Extension storage type | |
++-----------------------------+------------------------------------+---------+
+| List-like | List-like | \(1) |
++-----------------------------+------------------------------------+---------+
+| Null | Any | |
++-----------------------------+------------------------------------+---------+
+
+* \(1) The list offsets are unchanged, the list values are cast from the
+ input value type to the output value type (if a conversion is
+ available).
+
+
+.. TODO: add C++ cast example
Review comment:
```suggestion
C++ cast example::
std::shared_ptr<arrow::StringArray> inputs = ...;
ARROW_ASSIGN_OR_RAISE(arrow::Datum converted, arrow::compute::Cast(inputs, arrow::int32()));
auto inputs32 = std::static_pointer_cast<arrow::Int32Array>(converted.make_array());
for (int64_t i = 0; i < inputs32.length(); ++i) {
ReportInput(inputs32.Value(i));
}
```
##########
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
Review comment:
```suggestion
``_kleene``) where null is taken to mean "undefined". (This is the interpretation of null
used in ``R`` and ``SQL``, for example.) For those variants
```
##########
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``.
Review comment:
```suggestion
operation to each pair of elements gathered from the inputs. Integer overflow is
handled by wrapping; the sum of ``1`` and the maximum value will evaluate to the
minimum value for any integer type. Each function is also available in an overflow-
checking variant which raises an error if overflow would occur, suffixed ``_checked``.
```
##########
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`
+ is a substring of the corresponding input element.
+
+* \(2) Output is true iff the corresponding input element is equal to one
+ of the elements in :member:`SetLookupOptions::value_set`.
+
+* \(3) Output is the index of the corresponding input element in
+ :member:`SetLookupOptions::value_set`, if found there. Otherwise,
+ output is null.
+
+Structural transforms
+~~~~~~~~~~~~~~~~~~~~~
+
++--------------------------+------------+--------------------+---------------------+---------+
+| Function name | Arity | Input types | Output type | Notes |
++==========================+============+====================+=====================+=========+
+| is_null | Unary | Any | Boolean | \(1) |
++--------------------------+------------+--------------------+---------------------+---------+
+| is_valid | Unary | Any | Boolean | \(2) |
++--------------------------+------------+--------------------+---------------------+---------+
+| list_value_lengths | Unary | List-like | Int32 or Int64 | \(3) |
++--------------------------+------------+--------------------+---------------------+---------+
+
+* \(1) Output is true iff the corresponding input element is non-null.
+
+* \(2) Output is true iff the corresponding input element is null.
+
+* \(3) Each output element is the length of the corresponding input element
+ (null if input is null).
+
+Conversions
+~~~~~~~~~~~
+
+A general conversion function named ``cast`` is provided which accepts a large
+number of input and output types. The type to cast to can be passed in a
+:struct:`CastOptions` instance.
+
++--------------------------+------------+--------------------+-----------------------+--------------------------------------------+
+| Function name | Arity | Input types | Output type | Options class |
++==========================+============+====================+=======================+============================================+
+| cast | Unary | Many | Variable | :struct:`CastOptions` |
++--------------------------+------------+--------------------+-----------------------+--------------------------------------------+
+| strptime | Unary | String-like | Timestamp | :struct:`StrptimeOptions` |
++--------------------------+------------+--------------------+-----------------------+--------------------------------------------+
+
+The conversions available with ``cast`` are listed below. In all cases, a
+null input value is converted into a null output value.
+
+**Truth value extraction**
+
++-----------------------------+------------------------------------+--------------+
+| Input type | Output type | Notes |
++=============================+====================================+==============+
+| Binary- and String-like | Boolean | \(1) |
++-----------------------------+------------------------------------+--------------+
+| Numeric | Boolean | \(2) |
++-----------------------------+------------------------------------+--------------+
+
+* \(1) Output is true iff the corresponding input value has non-zero length.
+
+* \(2) Output is true iff the corresponding input value is non-zero.
+
+**Same-kind conversion**
+
++-----------------------------+------------------------------------+--------------+
+| Input type | Output type | Notes |
++=============================+====================================+==============+
+| Int32 | 32-bit Temporal | \(1) |
++-----------------------------+------------------------------------+--------------+
+| Int64 | 64-bit Temporal | \(1) |
++-----------------------------+------------------------------------+--------------+
+| (Large)Binary | (Large)String | \(2) |
++-----------------------------+------------------------------------+--------------+
+| (Large)String | (Large)Binary | \(3) |
++-----------------------------+------------------------------------+--------------+
+| Numeric | Numeric | \(4) \(5) |
++-----------------------------+------------------------------------+--------------+
+| 32-bit Temporal | Int32 | \(1) |
++-----------------------------+------------------------------------+--------------+
+| 64-bit Temporal | Int64 | \(1) |
++-----------------------------+------------------------------------+--------------+
+| Temporal | Temporal | \(4) \(5) |
++-----------------------------+------------------------------------+--------------+
+
+* \(1) No-operation cast: the raw values are kept identical, only
+ the type is changed.
+
+* \(2) Validates the contents if :member:`CastOptions::allow_invalid_utf8`
+ is false.
+
+* \(3) No-operation cast: only the type is changed.
+
+* \(4) Overflow and truncation checks are enabled depending on
+ the given :struct:`CastOptions`.
+
+* \(5) Not all such casts have been implemented.
+
+**String representations**
+
++-----------------------------+------------------------------------+---------+
+| Input type | Output type | Notes |
++=============================+====================================+=========+
+| Boolean | String-like | |
++-----------------------------+------------------------------------+---------+
+| Numeric | String-like | |
++-----------------------------+------------------------------------+---------+
+
+**Generic conversions**
+
++-----------------------------+------------------------------------+---------+
+| Input type | Output type | Notes |
++=============================+====================================+=========+
+| Dictionary | Dictionary value type | |
++-----------------------------+------------------------------------+---------+
+| Extension | Extension storage type | |
++-----------------------------+------------------------------------+---------+
+| List-like | List-like | \(1) |
++-----------------------------+------------------------------------+---------+
+| Null | Any | |
++-----------------------------+------------------------------------+---------+
+
+* \(1) The list offsets are unchanged, the list values are cast from the
+ input value type to the output value type (if a conversion is
+ available).
+
+
+.. TODO: add C++ cast example
+
+Array-wise ("vector") functions
+-------------------------------
+
+Associative transforms
+~~~~~~~~~~~~~~~~~~~~~~
+
++--------------------------+------------+----------------------------+----------------------------+
+| Function name | Arity | Input types | Output type |
++==========================+============+============================+============================+
+| dictionary_encode | Unary | Binary- and String-like | Dictionary (1) |
Review comment:
dictionary_encode infers the dictionary's type from the argument and always uses int32 indices. Cast requires that you specify the destination type
----------------------------------------------------------------
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:
users@infra.apache.org