diff options
Diffstat (limited to 'src/arrow/docs/source/cpp/examples')
6 files changed, 244 insertions, 0 deletions
diff --git a/src/arrow/docs/source/cpp/examples/cmake_minimal_build.rst b/src/arrow/docs/source/cpp/examples/cmake_minimal_build.rst new file mode 100644 index 000000000..f135de830 --- /dev/null +++ b/src/arrow/docs/source/cpp/examples/cmake_minimal_build.rst @@ -0,0 +1,28 @@ +.. 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 + +Minimal build using CMake +========================== + +The folder ``cpp/examples/minimal_build/`` located inside the source tree +contains a Docker-based example of building and using Arrow from a +third-party project, using CMake. The +`README <https://github.com/apache/arrow/tree/master/cpp/examples/minimal_build/README.md>`_ +file in that folder has more information. diff --git a/src/arrow/docs/source/cpp/examples/compute_and_write_example.rst b/src/arrow/docs/source/cpp/examples/compute_and_write_example.rst new file mode 100644 index 000000000..096b97b83 --- /dev/null +++ b/src/arrow/docs/source/cpp/examples/compute_and_write_example.rst @@ -0,0 +1,28 @@ +.. 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 + +Compute and Write CSV Example +============================= + +The file ``cpp/examples/arrow/compute_and_write_csv_example.cc`` located inside +the source tree contains an example of creating a table of two numerical columns +and then compariong the magnitudes of the entries in the columns and wrting out to +a CSV file with the column entries and their comparisons. The code in the example +is documented. diff --git a/src/arrow/docs/source/cpp/examples/dataset_documentation_example.rst b/src/arrow/docs/source/cpp/examples/dataset_documentation_example.rst new file mode 100644 index 000000000..2bc993f24 --- /dev/null +++ b/src/arrow/docs/source/cpp/examples/dataset_documentation_example.rst @@ -0,0 +1,27 @@ +.. 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 + +Arrow Datasets example +========================= + +The file ``cpp/examples/arrow/dataset_documentation_example.cc`` +located inside the source tree contains an example of using Arrow +Datasets to read, write, select, and filter data. :doc:`../dataset` +has a full walkthrough of the example. diff --git a/src/arrow/docs/source/cpp/examples/index.rst b/src/arrow/docs/source/cpp/examples/index.rst new file mode 100644 index 000000000..bc5bd497c --- /dev/null +++ b/src/arrow/docs/source/cpp/examples/index.rst @@ -0,0 +1,28 @@ +.. 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. + +Examples +======== + +.. toctree:: + :maxdepth: 1 + + cmake_minimal_build + compute_and_write_example + dataset_documentation_example + row_columnar_conversion + std::tuple-like ranges to Arrow <tuple_range_conversion> diff --git a/src/arrow/docs/source/cpp/examples/row_columnar_conversion.rst b/src/arrow/docs/source/cpp/examples/row_columnar_conversion.rst new file mode 100644 index 000000000..3f45864c2 --- /dev/null +++ b/src/arrow/docs/source/cpp/examples/row_columnar_conversion.rst @@ -0,0 +1,27 @@ +.. 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 + +Row to columnar conversion +========================== + +The following example converts an array of structs to a :class:`arrow::Table` +instance, and then converts it back to the original array of structs. + +.. literalinclude:: ../../../../cpp/examples/arrow/row_wise_conversion_example.cc diff --git a/src/arrow/docs/source/cpp/examples/tuple_range_conversion.rst b/src/arrow/docs/source/cpp/examples/tuple_range_conversion.rst new file mode 100644 index 000000000..64ba23782 --- /dev/null +++ b/src/arrow/docs/source/cpp/examples/tuple_range_conversion.rst @@ -0,0 +1,106 @@ +.. 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 + +Conversion of range of ``std::tuple``-like to ``Table`` instances +================================================================= + +While the above example shows a quite manual approach of a row to columnar +conversion, Arrow also provides some template logic to convert ranges of +``std::tuple<..>``-like objects to tables. + +In the most simple case, you only need to provide the input data and the +type conversion is then inferred at compile time. + +.. code:: + + std::vector<std::tuple<double, std::string>> rows = .. + std::shared_ptr<Table> table; + + if (!arrow::stl::TableFromTupleRange( + arrow::default_memory_pool(), + rows, names, &table).ok() + ) { + // Error handling code should go here. + } + +In reverse, you can use ``TupleRangeFromTable`` to fill an already +pre-allocated range with the data from a ``Table`` instance. + +.. code:: + + // An important aspect here is that the table columns need to be in the + // same order as the columns will later appear in the tuple. As the tuple + // is unnamed, matching is done on positions. + std::shared_ptr<Table> table = .. + + // The range needs to be pre-allocated to the respective amount of rows. + // This allows us to pass in an arbitrary range object, not only + // `std::vector`. + std::vector<std::tuple<double, std::string>> rows(2); + if (!arrow::stl::TupleRangeFromTable(*table, &rows).ok()) { + // Error handling code should go here. + } + +Arrow itself already supports some C(++) data types for this conversion. If you +want to support additional data types, you need to implement a specialization +of ``arrow::stl::ConversionTraits<T>`` and the more general +``arrow::CTypeTraits<T>``. + + +.. code:: + + namespace arrow { + + template<> + struct CTypeTraits<boost::posix_time::ptime> { + using ArrowType = ::arrow::TimestampType; + + static std::shared_ptr<::arrow::DataType> type_singleton() { + return ::arrow::timestamp(::arrow::TimeUnit::MICRO); + } + }; + + } + + namespace arrow { namespace stl { + + template <> + struct ConversionTraits<boost::posix_time::ptime> : public CTypeTraits<boost::posix_time::ptime> { + constexpr static bool nullable = false; + + // This is the specialization to load a scalar value into an Arrow builder. + static Status AppendRow( + typename TypeTraits<TimestampType>::BuilderType& builder, + boost::posix_time::ptime cell) { + boost::posix_time::ptime const epoch({1970, 1, 1}, {0, 0, 0, 0}); + return builder.Append((cell - epoch).total_microseconds()); + } + + // Specify how we can fill the tuple from the values stored in the Arrow + // array. + static boost::posix_time::ptime GetEntry( + const TimestampArray& array, size_t j) { + return psapp::arrow::internal::timestamp_epoch + + boost::posix_time::time_duration(0, 0, 0, array.Value(j)); + } + }; + + }} + |