From 55d4d8bfa2a97bfaf43f75582042b5cf6b7c0e45 Mon Sep 17 00:00:00 2001 From: Bryce Mecum Date: Sat, 10 Feb 2024 04:15:41 -0800 Subject: [PATCH] MINOR: [Docs] Use ' and remove trailing spaces in basic_arrow.rst (#39989) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ### Rationale for this change basic_arrow.rst had two minor issues: - It used `’` (U+2019) instead of `'` - While editing, I found it wasn't whitespace normalized ### What changes are included in this PR? - `’` replaced with `'` - Whitespace has been normalized ### Are these changes tested? No ### Are there any user-facing changes? Just docs. Authored-by: Bryce Mecum Signed-off-by: Sutou Kouhei --- docs/source/cpp/tutorials/basic_arrow.rst | 72 +++++++++++------------ 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/source/cpp/tutorials/basic_arrow.rst b/docs/source/cpp/tutorials/basic_arrow.rst index 409dfcc40d28f..355976d02a072 100644 --- a/docs/source/cpp/tutorials/basic_arrow.rst +++ b/docs/source/cpp/tutorials/basic_arrow.rst @@ -25,15 +25,15 @@ Basic Arrow Data Structures =========================== Apache Arrow provides fundamental data structures for representing data: -:class:`Array`, :class:`ChunkedArray`, :class:`RecordBatch`, and :class:`Table`. -This article shows how to construct these data structures from primitive -data types; specifically, we will work with integers of varying size +:class:`Array`, :class:`ChunkedArray`, :class:`RecordBatch`, and :class:`Table`. +This article shows how to construct these data structures from primitive +data types; specifically, we will work with integers of varying size representing days, months, and years. We will use them to create the following data structures: #. Arrow :class:`Arrays ` -#. :class:`ChunkedArrays` +#. :class:`ChunkedArrays` #. :class:`RecordBatch`, from :class:`Arrays ` -#. :class:`Table`, from :class:`ChunkedArrays` +#. :class:`Table`, from :class:`ChunkedArrays` Pre-requisites -------------- @@ -50,14 +50,14 @@ Setup Before trying out Arrow, we need to fill in a couple gaps: 1. We need to include necessary headers. - + 2. ``A main()`` is needed to glue things together. Includes ^^^^^^^^ First, as ever, we need some includes. We'll get ``iostream`` for output, then import Arrow's basic -functionality from ``api.h``, like so: +functionality from ``api.h``, like so: .. literalinclude:: ../../../../cpp/examples/tutorial_examples/arrow_example.cc :language: cpp @@ -75,14 +75,14 @@ following: :start-after: (Doc section: Main) :end-before: (Doc section: Main) -This allows us to easily use Arrow’s error-handling macros, which will +This allows us to easily use Arrow's error-handling macros, which will return back to ``main()`` with a :class:`arrow::Status` object if a failure occurs – and this ``main()`` will report the error. Note that this means Arrow never raises exceptions, instead relying upon returning :class:`Status`. For more on that, read here: :doc:`/cpp/conventions`. To accompany this ``main()``, we have a ``RunMain()`` from which any :class:`Status` -objects can return – this is where we’ll write the rest of the program: +objects can return – this is where we'll write the rest of the program: .. literalinclude:: ../../../../cpp/examples/tutorial_examples/arrow_example.cc :language: cpp @@ -97,14 +97,14 @@ Building int8 Arrays ^^^^^^^^^^^^^^^^^^^^ Given that we have some data in standard C++ arrays, and want to use Arrow, we need to move -the data from said arrays into Arrow arrays. We still guarantee contiguity of memory in an +the data from said arrays into Arrow arrays. We still guarantee contiguity of memory in an :class:`Array`, so no worries about a performance loss when using :class:`Array` vs C++ arrays. -The easiest way to construct an :class:`Array` uses an :class:`ArrayBuilder`. +The easiest way to construct an :class:`Array` uses an :class:`ArrayBuilder`. .. seealso:: :doc:`/cpp/arrays` for more technical details on :class:`Array` The following code initializes an :class:`ArrayBuilder` for an :class:`Array` that will hold 8 bit -integers. Specifically, it uses the ``AppendValues()`` method, present in concrete +integers. Specifically, it uses the ``AppendValues()`` method, present in concrete :class:`arrow::ArrayBuilder` subclasses, to fill the :class:`ArrayBuilder` with the contents of a standard C++ array. Note the use of :c:macro:`ARROW_RETURN_NOT_OK`. If ``AppendValues()`` fails, this macro will return to ``main()``, which will @@ -115,10 +115,10 @@ print out the meaning of the failure. :start-after: (Doc section: int8builder 1 Append) :end-before: (Doc section: int8builder 1 Append) -Given an :class:`ArrayBuilder` has the values we want in our :class:`Array`, we can use -:func:`ArrayBuilder::Finish` to output the final structure to an :class:`Array` – specifically, +Given an :class:`ArrayBuilder` has the values we want in our :class:`Array`, we can use +:func:`ArrayBuilder::Finish` to output the final structure to an :class:`Array` – specifically, we output to a ``std::shared_ptr``. Note the use of :c:macro:`ARROW_ASSIGN_OR_RAISE` -in the following code. :func:`~ArrayBuilder::Finish` outputs a :class:`arrow::Result` object, which :c:macro:`ARROW_ASSIGN_OR_RAISE` +in the following code. :func:`~ArrayBuilder::Finish` outputs a :class:`arrow::Result` object, which :c:macro:`ARROW_ASSIGN_OR_RAISE` can process. If the method fails, it will return to ``main()`` with a :class:`Status` that will explain what went wrong. If it succeeds, then it will assign the final output to the left-hand variable. @@ -141,7 +141,7 @@ Building int16 Arrays An :class:`ArrayBuilder` has its type specified at the time of declaration. Once this is done, it cannot have its type changed. We have to make a new one when we switch to year data, which -requires a 16-bit integer at the minimum. Of course, there’s an :class:`ArrayBuilder` for that. +requires a 16-bit integer at the minimum. Of course, there's an :class:`ArrayBuilder` for that. It uses the exact same methods, but with the new data type: .. literalinclude:: ../../../../cpp/examples/tutorial_examples/arrow_example.cc @@ -154,16 +154,16 @@ Now, we have three Arrow :class:`Arrays `, with some variance in t Making a RecordBatch -------------------- -A columnar data format only really comes into play when you have a table. -So, let’s make one. The first kind we’ll make is the :class:`RecordBatch` – this -uses :class:`Arrays ` internally, which means all data will be contiguous within each +A columnar data format only really comes into play when you have a table. +So, let's make one. The first kind we'll make is the :class:`RecordBatch` – this +uses :class:`Arrays ` internally, which means all data will be contiguous within each column, but any appending or concatenating will require copying. Making a :class:`RecordBatch` has two steps, given existing :class:`Arrays `: #. Defining a :class:`Schema` #. Loading the :class:`Schema` and Arrays into the constructor -Defining a Schema +Defining a Schema ^^^^^^^^^^^^^^^^^ To get started making a :class:`RecordBatch`, we first need to define @@ -180,8 +180,8 @@ so: Building a RecordBatch ^^^^^^^^^^^^^^^^^^^^^^ -With data in :class:`Arrays ` from the previous section, and column descriptions in our -:class:`Schema` from the previous step, we can make the :class:`RecordBatch`. Note that the +With data in :class:`Arrays ` from the previous section, and column descriptions in our +:class:`Schema` from the previous step, we can make the :class:`RecordBatch`. Note that the length of the columns is necessary, and the length is shared by all columns. .. literalinclude:: ../../../../cpp/examples/tutorial_examples/arrow_example.cc @@ -190,18 +190,18 @@ length of the columns is necessary, and the length is shared by all columns. :end-before: (Doc section: RBatch) Now, we have our data in a nice tabular form, safely within the :class:`RecordBatch`. -What we can do with this will be discussed in the later tutorials. +What we can do with this will be discussed in the later tutorials. Making a ChunkedArray --------------------- -Let’s say that we want an array made up of sub-arrays, because it +Let's say that we want an array made up of sub-arrays, because it can be useful for avoiding data copies when concatenating, for parallelizing work, for fitting each chunk cutely into cache, or for exceeding the 2,147,483,647 row limit in a standard Arrow :class:`Array`. For this, Arrow offers :class:`ChunkedArray`, which can be made up of individual Arrow :class:`Arrays `. In this example, we can reuse the arrays we made earlier in part of our chunked array, allowing us to extend them without having to copy -data. So, let’s build a few more :class:`Arrays `, +data. So, let's build a few more :class:`Arrays `, using the same builders for ease of use: .. literalinclude:: ../../../../cpp/examples/tutorial_examples/arrow_example.cc @@ -209,7 +209,7 @@ using the same builders for ease of use: :start-after: (Doc section: More Arrays) :end-before: (Doc section: More Arrays) -In order to support an arbitrary amount of :class:`Arrays ` in the construction of the +In order to support an arbitrary amount of :class:`Arrays ` in the construction of the :class:`ChunkedArray`, Arrow supplies :class:`ArrayVector`. This provides a vector for :class:`Arrays `, and we'll use it here to prepare to make a :class:`ChunkedArray`: @@ -233,18 +233,18 @@ for the month and year data: :start-after: (Doc section: ChunkedArray Month Year) :end-before: (Doc section: ChunkedArray Month Year) -With that, we are left with three :class:`ChunkedArrays `, varying in type. +With that, we are left with three :class:`ChunkedArrays `, varying in type. Making a Table -------------- -One particularly useful thing we can do with the :class:`ChunkedArrays ` from the previous section is creating -:class:`Tables `. Much like a :class:`RecordBatch`, a :class:`Table` stores tabular data. However, a +One particularly useful thing we can do with the :class:`ChunkedArrays ` from the previous section is creating +:class:`Tables
`. Much like a :class:`RecordBatch`, a :class:`Table` stores tabular data. However, a :class:`Table` does not guarantee contiguity, due to being made up of :class:`ChunkedArrays `. This can be useful for logic, parallelizing work, for fitting chunks into cache, or exceeding the 2,147,483,647 row limit present in :class:`Array` and, thus, :class:`RecordBatch`. -If you read up to :class:`RecordBatch`, you may note that the :class:`Table` constructor in the following code is +If you read up to :class:`RecordBatch`, you may note that the :class:`Table` constructor in the following code is effectively identical, it just happens to put the length of the columns in position 3, and makes a :class:`Table`. We re-use the :class:`Schema` from before, and make our :class:`Table`: @@ -255,23 +255,23 @@ make our :class:`Table`: :end-before: (Doc section: Table) Now, we have our data in a nice tabular form, safely within the :class:`Table`. -What we can do with this will be discussed in the later tutorials. +What we can do with this will be discussed in the later tutorials. -Ending Program +Ending Program -------------- At the end, we just return :func:`Status::OK()`, so the ``main()`` knows that -we’re done, and that everything’s okay. +we're done, and that everything's okay. .. literalinclude:: ../../../../cpp/examples/tutorial_examples/arrow_example.cc :language: cpp :start-after: (Doc section: Ret) :end-before: (Doc section: Ret) -Wrapping Up +Wrapping Up ----------- -With that, you’ve created the fundamental data structures in Arrow, and +With that, you've created the fundamental data structures in Arrow, and can proceed to getting them in and out of a program with file I/O in the next article. Refer to the below for a copy of the complete code: @@ -281,4 +281,4 @@ Refer to the below for a copy of the complete code: :start-after: (Doc section: Basic Example) :end-before: (Doc section: Basic Example) :linenos: - :lineno-match: \ No newline at end of file + :lineno-match: