| .. 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. | |
| =================================== | |
| Working with the C++ Implementation | |
| =================================== | |
| This section of the cookbook goes over basic concepts | |
| that will be needed regardless of how you intend to use | |
| the Arrow C++ implementation. | |
| .. contents:: | |
| Working with Status and Result | |
| ============================== | |
| C++ libraries often have to choose between throwing exceptions and | |
| returning error codes. Arrow chooses to return Status and Result | |
| objects as a middle ground. This makes it clear when a function | |
| can fail and is easier to use than integer arrow codes. | |
| It is important to always check the value of a returned Status object to | |
| ensure that the operation succeeded. However, this can quickly become | |
| tedious: | |
| .. recipe:: ../code/basic_arrow.cc ReturnNotOkNoMacro | |
| :caption: Checking the status of every function manually | |
| :dedent: 2 | |
| The macro :c:macro:`ARROW_RETURN_NOT_OK` will take care of some of this | |
| boilerplate for you. It will run the contained expression and check the resulting | |
| ``Status`` or ``Result`` object. If it failed then it will return the failure. | |
| .. recipe:: ../code/basic_arrow.cc ReturnNotOk | |
| :caption: Using ARROW_RETURN_NOT_OK to check the status | |
| :dedent: 2 | |
| Using the Visitor Pattern | |
| ========================= | |
| Arrow classes :cpp:class:`arrow::DataType`, :cpp:class:`arrow::Scalar`, and | |
| :cpp:class:`arrow::Array` have specialized subclasses for each Arrow type. In | |
| order to specialize logic for each subclass, you can use the visitor pattern. | |
| Arrow provides inline template functions that allow you to call visitors | |
| efficiently: | |
| * :cpp:func:`arrow::VisitTypeInline` | |
| * :cpp:func:`arrow::VisitScalarInline` | |
| * :cpp:func:`arrow::VisitArrayInline` | |
| Generate Random Data | |
| -------------------- | |
| See example at :ref:`Generate Random Data Example`. | |
| Generalize Computations Across Arrow Types | |
| ------------------------------------------ | |
| Array visitors can be useful when writing functions that can handle multiple | |
| array types. However, implementing a visitor for each type individually can be | |
| excessively verbose. Fortunately, Arrow provides type traits that allow you to | |
| write templated functions to handle subsets of types. The example below | |
| demonstrates a table sum function that can handle any integer or floating point | |
| array with only a single visitor implementation by leveraging | |
| :cpp:type:`arrow::enable_if_number`. | |
| .. literalinclude:: ../code/basic_arrow.cc | |
| :language: cpp | |
| :linenos: | |
| :start-at: class TableSummation | |
| :end-at: }; // TableSummation | |
| :caption: Using visitor pattern that can compute sum of table with any numeric type | |
| .. recipe:: ../code/basic_arrow.cc VisitorSummationExample | |
| :dedent: 2 |