Adding upstream version 18.2.2.upstream/18.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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));
+      }
+    };
+
+    }}
+