You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by "paleolimbot (via GitHub)" <gi...@apache.org> on 2023/05/09 19:55:42 UTC
[GitHub] [arrow-nanoarrow] paleolimbot opened a new pull request, #190: docs: Add "getting started with nanoarrow" tutorial
paleolimbot opened a new pull request, #190:
URL: https://github.com/apache/arrow-nanoarrow/pull/190
(no comment)
--
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.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow-nanoarrow] paleolimbot merged pull request #190: docs: Add "getting started with nanoarrow" tutorial
Posted by "paleolimbot (via GitHub)" <gi...@apache.org>.
paleolimbot merged PR #190:
URL: https://github.com/apache/arrow-nanoarrow/pull/190
--
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.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow-nanoarrow] lidavidm commented on a diff in pull request #190: docs: Add "getting started with nanoarrow" tutorial
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #190:
URL: https://github.com/apache/arrow-nanoarrow/pull/190#discussion_r1191536067
##########
docs/source/getting-started.md:
##########
@@ -0,0 +1,393 @@
+<!---
+ 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.
+-->
+
+# Getting started with nanoarrow
+
+This tutorial provides a short example of writing a C++ library that exposes
+an Arrow-based API and uses nanoarrow to implement a simple text file reader/writer.
+In general, nanoarrow can help you write a library or application that:
+
+- exposes an Arrow-based API to read from a data source or format,
+- exposes an Arrow-based API to write to a data source or format,
+- exposes one or more compute functions that operates on and produces data
+ in the form of Arrow arrays, and/or
+- exposes an extension type implementation.
+
+Becauase Arrow has bindings in many languages, it means that you or others can easily
+bind or use your tool in higher-level runtimes like R, Java, C++, Python, Rust, Julia,
+Go, or Ruby, among others.
+
+The nanoarrow library is not the only way that an Arrow-based API can be implemented:
+Arrow C++, Rust, and Go are all excellent choices and can compile into
+static libraries that are C-linkable from other languages; however, existing Arrow
+implementations produce relatively large static libraries and can present complex build-time
+or run-time linking requirements depending on the implementation and features used. If
+the set of libraries you're working with already provide the conveniences you need,
+nanoarrow may provide all the functionality you need.
+
+Now that we've talked about why you might want to build a library with nanoarrow...let's
+build one!
+
+Note:
+This tutorial also goes over some of the basic structure of writing a C++ library.
+If you already know how to do this, feel free to scroll to the code examples provided
+below or take a look at the
+[complete example source](https://github.com/apache/arrow-nanoarrow/tree/main/examples/linesplitter).
+
+## The library
+
+The library we'll write in this tutorial is a simple text processing library that splits
+and reassembles lines of text. It will be able to:
+
+- Read text from a buffer into an `ArrowArray` as one element per line,
+- Write elements of an `ArrowArray` into a buffer, inserting line breaks
+ after every element, and
+
+For the sake of argument, we'll call it `linesplitter`.
+
+## The development environment
+
+There are many excellent IDEs that can be used to develop C and C++ libraries. For
+this tutorial, we will use [VSCode](https://code.visualstudio.com/) and
+[CMake](https://cmake.org/). You'll need both installed to follow along:
+VSCode can be downloaded from the official site for most platforms;
+CMake is typically installed via your favourite package manager
+(e.g., `brew install cmake`, `apt-get install cmake` `dnf install cmake`,
+etc.). You will also need a C and C++ compiler: on MacOS these can be installed
+using `xcode-select --install`; on Linux you will need the packages that provice
+`gcc`, `g++`, and `make`; on Windows you will need to install
Review Comment:
Often this is called `build-essential` (on Debian and Ubuntu at least)
##########
docs/source/getting-started.md:
##########
@@ -0,0 +1,393 @@
+<!---
+ 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.
+-->
+
+# Getting started with nanoarrow
+
+This tutorial provides a short example of writing a C++ library that exposes
+an Arrow-based API and uses nanoarrow to implement a simple text file reader/writer.
+In general, nanoarrow can help you write a library or application that:
+
+- exposes an Arrow-based API to read from a data source or format,
+- exposes an Arrow-based API to write to a data source or format,
+- exposes one or more compute functions that operates on and produces data
+ in the form of Arrow arrays, and/or
+- exposes an extension type implementation.
+
+Becauase Arrow has bindings in many languages, it means that you or others can easily
+bind or use your tool in higher-level runtimes like R, Java, C++, Python, Rust, Julia,
+Go, or Ruby, among others.
+
+The nanoarrow library is not the only way that an Arrow-based API can be implemented:
+Arrow C++, Rust, and Go are all excellent choices and can compile into
+static libraries that are C-linkable from other languages; however, existing Arrow
+implementations produce relatively large static libraries and can present complex build-time
+or run-time linking requirements depending on the implementation and features used. If
+the set of libraries you're working with already provide the conveniences you need,
+nanoarrow may provide all the functionality you need.
+
+Now that we've talked about why you might want to build a library with nanoarrow...let's
+build one!
+
+Note:
+This tutorial also goes over some of the basic structure of writing a C++ library.
+If you already know how to do this, feel free to scroll to the code examples provided
+below or take a look at the
+[complete example source](https://github.com/apache/arrow-nanoarrow/tree/main/examples/linesplitter).
+
+## The library
+
+The library we'll write in this tutorial is a simple text processing library that splits
+and reassembles lines of text. It will be able to:
+
+- Read text from a buffer into an `ArrowArray` as one element per line,
+- Write elements of an `ArrowArray` into a buffer, inserting line breaks
+ after every element, and
Review Comment:
cut off sentence?
##########
docs/source/getting-started.md:
##########
@@ -0,0 +1,393 @@
+<!---
+ 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.
+-->
+
+# Getting started with nanoarrow
+
+This tutorial provides a short example of writing a C++ library that exposes
+an Arrow-based API and uses nanoarrow to implement a simple text file reader/writer.
+In general, nanoarrow can help you write a library or application that:
+
+- exposes an Arrow-based API to read from a data source or format,
+- exposes an Arrow-based API to write to a data source or format,
+- exposes one or more compute functions that operates on and produces data
+ in the form of Arrow arrays, and/or
+- exposes an extension type implementation.
+
+Becauase Arrow has bindings in many languages, it means that you or others can easily
+bind or use your tool in higher-level runtimes like R, Java, C++, Python, Rust, Julia,
+Go, or Ruby, among others.
+
+The nanoarrow library is not the only way that an Arrow-based API can be implemented:
+Arrow C++, Rust, and Go are all excellent choices and can compile into
+static libraries that are C-linkable from other languages; however, existing Arrow
+implementations produce relatively large static libraries and can present complex build-time
+or run-time linking requirements depending on the implementation and features used. If
+the set of libraries you're working with already provide the conveniences you need,
+nanoarrow may provide all the functionality you need.
+
+Now that we've talked about why you might want to build a library with nanoarrow...let's
+build one!
+
+Note:
+This tutorial also goes over some of the basic structure of writing a C++ library.
+If you already know how to do this, feel free to scroll to the code examples provided
+below or take a look at the
+[complete example source](https://github.com/apache/arrow-nanoarrow/tree/main/examples/linesplitter).
+
+## The library
+
+The library we'll write in this tutorial is a simple text processing library that splits
+and reassembles lines of text. It will be able to:
+
+- Read text from a buffer into an `ArrowArray` as one element per line,
+- Write elements of an `ArrowArray` into a buffer, inserting line breaks
+ after every element, and
+
+For the sake of argument, we'll call it `linesplitter`.
+
+## The development environment
+
+There are many excellent IDEs that can be used to develop C and C++ libraries. For
+this tutorial, we will use [VSCode](https://code.visualstudio.com/) and
+[CMake](https://cmake.org/). You'll need both installed to follow along:
+VSCode can be downloaded from the official site for most platforms;
+CMake is typically installed via your favourite package manager
+(e.g., `brew install cmake`, `apt-get install cmake` `dnf install cmake`,
+etc.). You will also need a C and C++ compiler: on MacOS these can be installed
+using `xcode-select --install`; on Linux you will need the packages that provice
+`gcc`, `g++`, and `make`; on Windows you will need to install
+[Visual Studio](https://visualstudio.microsoft.com/downloads/) and
+CMake from the official download pages.
+
+After installing the required dependencies, create a folder called `linesplitter`
+and open it.
+
+## The interface
+
+We'll expose the interface to our library as a header called `linesplitter.h`.
+To ensure the definitions are only included once in any given source file, we'll
+add the following line at the top:
+
+```cpp
+#pragma once
+```
+
+Then, we need the
+[Arrow C Data interface](https://arrow.apache.org/docs/format/CDataInterface.html#structure-definitions)
+itself, since it provides the type definitions that are recognized by other Arrow
+implementations on which our API will be built. It's designed to be copy and
+pasted in this way - there's no need to put it in another file include
+something from another project.
+
+```cpp
+#include <stdint.h>
+
+#ifndef ARROW_C_DATA_INTERFACE
+#define ARROW_C_DATA_INTERFACE
+
+#define ARROW_FLAG_DICTIONARY_ORDERED 1
+#define ARROW_FLAG_NULLABLE 2
+#define ARROW_FLAG_MAP_KEYS_SORTED 4
+
+struct ArrowSchema {
+ // Array type description
+ const char* format;
+ const char* name;
+ const char* metadata;
+ int64_t flags;
+ int64_t n_children;
+ struct ArrowSchema** children;
+ struct ArrowSchema* dictionary;
+
+ // Release callback
+ void (*release)(struct ArrowSchema*);
+ // Opaque producer-specific data
+ void* private_data;
+};
+
+struct ArrowArray {
+ // Array data description
+ int64_t length;
+ int64_t null_count;
+ int64_t offset;
+ int64_t n_buffers;
+ int64_t n_children;
+ const void** buffers;
+ struct ArrowArray** children;
+ struct ArrowArray* dictionary;
+
+ // Release callback
+ void (*release)(struct ArrowArray*);
+ // Opaque producer-specific data
+ void* private_data;
+};
+
+#endif // ARROW_C_DATA_INTERFACE
+```
+
+Next, we'll provide definitions for the functions we'll implement below:
+
+```c
+std::pair<int, std::string> linesplitter_read(const std::string& src,
+ struct ArrowArray* out);
+std::pair<int, std::string> linesplitter_write(struct ArrowArray* input);
+```
+
+## Arrow C data/nanoarrow interface basics
+
+Now that we've seen the functions we need to implement and the Arrow types exposed
+in the C data interface, let's unpack a few basics about using the Arrow C data
+interface and a few conventions used in the nanoarrow implementation.
+
+First, let's discuss the `ArrowSchema` and the `ArrowArray`. You can think of an
+`ArrowSchema` as an expression of a data type, whereas an `ArrowArray` is the
+data itself. These structures accomodate nested types: columns are encoded in
+the `children` member of each. You always need to know the data type of an
+`ArrowArray` before accessing its contents. In our case we only operate on arrays
+of one type ("string") and document that in our interface; for functions that
+operate on more than one type of array you will need to accept an `ArrowSchema`
+and inspect it (e.g., using nanoarrow's helper functions).
+
+Second, let's discuss error handling. You may have noticed in the function definitions
+above that we return `int`, which is an errno-compatible error code or `0` to
+indicate success. Functions in nanoarrow that need to communicate more detailed
+error information accept an `ArrowError*` argument (which can be `NULL` if
+the caller does care about the extra information). Any nanoarrow function that
+might fail communicates errors in this way. To avoid verbose code like the
+following:
+
+```c
+int init_string_non_null(struct ArrowSchema* schema) {
+ int code = ArrowSchemaInitFromType(&schema, NANOARROW_TYPE_STRING);
+ if (code != NANOARROW_OK) {
+ return code;
+ }
+
+ schema->flags &= ~ARROW_FLAG_NULLABLE;
+ return NANOARROW_OK;
+}
+```
+
+...you can use the `NANOARROW_RETURN_NOT_OK()` macro:
+
+```c
+int init_string_non_null(struct ArrowSchema* schema) {
+ NANOARROW_RETURN_NOT_OK(ArrowSchemaInitFromType(&schema, NANOARROW_TYPE_STRING));
+ schema->flags &= ~ARROW_FLAG_NULLABLE;
+ return NANOARROW_OK;
+}
+```
+
+This works as long as your internal functions that use nanoarrow also return
+`int` and/or an `ArrowError*` argument. This usually means that there is
+an outer function that presents a more idiomatic interface (e.g., returning
+`std::optional<>` or throwing an exception) and an inner function that uses
+nanoarrow-style error handling. Embracing `NANOARROW_RETURN_NOT_OK()` is key
+to hapiness when using the nanoarrow library.
+
+Third, let's discuss memory management. Because nanoarrow is implemented in C
+and provides a C interface, the library by default uses C-style memory management
+(i.e., if you allocate it, you clean it up). This is unnecessary when you have
+C++ at your disposal, so nanoarrow also provides a C++ header (`nanoarrow.hpp`) with
+`std::unique_ptr<>`-like wrappers around anything that requires explicit clean up.
+Whereas in C you might have to write code like this:
+
+```c
+struct ArrowSchema schema;
+struct ArrowArray array;
+
+// Ok: if this returns, array was not initialized
+NANOARROW_RETURN_NOT_OK(ArrowSchemaInitFromType(&schema, NANOARROW_TYPE_STRING));
+
+// Verbose: if this fails, we need to release schema before returning
+// or it will leak.
+int code = ArrowArrayInitFromSchema(&array, &schema, NULL);
+if (code != NANOARROW_OK) {
+ schema.release(&schema);
+ return code;
+}
+```
+
+...using the `nanoarrow.hpp` types we can do:
+
+```cpp
+// These objects have C++ deleters that clean up the underlying
+nanoarrow::UniqueSchema schema;
+nanoarrow::UniqueArray array;
+
+NANOARROW_RETURN_NOT_OK(ArrowSchemaInitFromType(schema.get(), NANOARROW_TYPE_STRING));
+NANOARROW_RETURN_NOT_OK(ArrowArrayInitFromSchema(array.get(), schema.get(), NULL));
+```
+
+## Building the library
+
+Our library implementation will live in `linesplitter.cc`. Before writing the
+actual implementations, let's add just enough to our project that we can
+build it using VSCode's C/C++/CMake integration:
+
+```cpp
+
Review Comment:
(maybe a `// this file intentionally left blank`? Or include our header here?)
##########
docs/source/getting-started.md:
##########
@@ -0,0 +1,393 @@
+<!---
+ 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.
+-->
+
+# Getting started with nanoarrow
+
+This tutorial provides a short example of writing a C++ library that exposes
+an Arrow-based API and uses nanoarrow to implement a simple text file reader/writer.
+In general, nanoarrow can help you write a library or application that:
+
+- exposes an Arrow-based API to read from a data source or format,
+- exposes an Arrow-based API to write to a data source or format,
+- exposes one or more compute functions that operates on and produces data
+ in the form of Arrow arrays, and/or
+- exposes an extension type implementation.
+
+Becauase Arrow has bindings in many languages, it means that you or others can easily
+bind or use your tool in higher-level runtimes like R, Java, C++, Python, Rust, Julia,
+Go, or Ruby, among others.
+
+The nanoarrow library is not the only way that an Arrow-based API can be implemented:
+Arrow C++, Rust, and Go are all excellent choices and can compile into
+static libraries that are C-linkable from other languages; however, existing Arrow
+implementations produce relatively large static libraries and can present complex build-time
+or run-time linking requirements depending on the implementation and features used. If
+the set of libraries you're working with already provide the conveniences you need,
+nanoarrow may provide all the functionality you need.
+
+Now that we've talked about why you might want to build a library with nanoarrow...let's
+build one!
+
+Note:
+This tutorial also goes over some of the basic structure of writing a C++ library.
+If you already know how to do this, feel free to scroll to the code examples provided
+below or take a look at the
+[complete example source](https://github.com/apache/arrow-nanoarrow/tree/main/examples/linesplitter).
+
+## The library
+
+The library we'll write in this tutorial is a simple text processing library that splits
+and reassembles lines of text. It will be able to:
+
+- Read text from a buffer into an `ArrowArray` as one element per line,
+- Write elements of an `ArrowArray` into a buffer, inserting line breaks
+ after every element, and
+
+For the sake of argument, we'll call it `linesplitter`.
+
+## The development environment
+
+There are many excellent IDEs that can be used to develop C and C++ libraries. For
+this tutorial, we will use [VSCode](https://code.visualstudio.com/) and
+[CMake](https://cmake.org/). You'll need both installed to follow along:
+VSCode can be downloaded from the official site for most platforms;
+CMake is typically installed via your favourite package manager
+(e.g., `brew install cmake`, `apt-get install cmake` `dnf install cmake`,
+etc.). You will also need a C and C++ compiler: on MacOS these can be installed
+using `xcode-select --install`; on Linux you will need the packages that provice
+`gcc`, `g++`, and `make`; on Windows you will need to install
+[Visual Studio](https://visualstudio.microsoft.com/downloads/) and
+CMake from the official download pages.
+
+After installing the required dependencies, create a folder called `linesplitter`
+and open it.
+
+## The interface
+
+We'll expose the interface to our library as a header called `linesplitter.h`.
+To ensure the definitions are only included once in any given source file, we'll
+add the following line at the top:
+
+```cpp
+#pragma once
+```
+
+Then, we need the
+[Arrow C Data interface](https://arrow.apache.org/docs/format/CDataInterface.html#structure-definitions)
+itself, since it provides the type definitions that are recognized by other Arrow
+implementations on which our API will be built. It's designed to be copy and
+pasted in this way - there's no need to put it in another file include
+something from another project.
+
+```cpp
+#include <stdint.h>
+
+#ifndef ARROW_C_DATA_INTERFACE
+#define ARROW_C_DATA_INTERFACE
+
+#define ARROW_FLAG_DICTIONARY_ORDERED 1
+#define ARROW_FLAG_NULLABLE 2
+#define ARROW_FLAG_MAP_KEYS_SORTED 4
+
+struct ArrowSchema {
+ // Array type description
+ const char* format;
+ const char* name;
+ const char* metadata;
+ int64_t flags;
+ int64_t n_children;
+ struct ArrowSchema** children;
+ struct ArrowSchema* dictionary;
+
+ // Release callback
+ void (*release)(struct ArrowSchema*);
+ // Opaque producer-specific data
+ void* private_data;
+};
+
+struct ArrowArray {
+ // Array data description
+ int64_t length;
+ int64_t null_count;
+ int64_t offset;
+ int64_t n_buffers;
+ int64_t n_children;
+ const void** buffers;
+ struct ArrowArray** children;
+ struct ArrowArray* dictionary;
+
+ // Release callback
+ void (*release)(struct ArrowArray*);
+ // Opaque producer-specific data
+ void* private_data;
+};
+
+#endif // ARROW_C_DATA_INTERFACE
+```
+
+Next, we'll provide definitions for the functions we'll implement below:
+
+```c
+std::pair<int, std::string> linesplitter_read(const std::string& src,
+ struct ArrowArray* out);
+std::pair<int, std::string> linesplitter_write(struct ArrowArray* input);
+```
+
+## Arrow C data/nanoarrow interface basics
+
+Now that we've seen the functions we need to implement and the Arrow types exposed
+in the C data interface, let's unpack a few basics about using the Arrow C data
+interface and a few conventions used in the nanoarrow implementation.
+
+First, let's discuss the `ArrowSchema` and the `ArrowArray`. You can think of an
+`ArrowSchema` as an expression of a data type, whereas an `ArrowArray` is the
+data itself. These structures accomodate nested types: columns are encoded in
+the `children` member of each. You always need to know the data type of an
+`ArrowArray` before accessing its contents. In our case we only operate on arrays
+of one type ("string") and document that in our interface; for functions that
+operate on more than one type of array you will need to accept an `ArrowSchema`
+and inspect it (e.g., using nanoarrow's helper functions).
+
+Second, let's discuss error handling. You may have noticed in the function definitions
+above that we return `int`, which is an errno-compatible error code or `0` to
+indicate success. Functions in nanoarrow that need to communicate more detailed
+error information accept an `ArrowError*` argument (which can be `NULL` if
+the caller does care about the extra information). Any nanoarrow function that
+might fail communicates errors in this way. To avoid verbose code like the
+following:
+
+```c
+int init_string_non_null(struct ArrowSchema* schema) {
+ int code = ArrowSchemaInitFromType(&schema, NANOARROW_TYPE_STRING);
+ if (code != NANOARROW_OK) {
+ return code;
+ }
+
+ schema->flags &= ~ARROW_FLAG_NULLABLE;
+ return NANOARROW_OK;
+}
+```
+
+...you can use the `NANOARROW_RETURN_NOT_OK()` macro:
+
+```c
+int init_string_non_null(struct ArrowSchema* schema) {
+ NANOARROW_RETURN_NOT_OK(ArrowSchemaInitFromType(&schema, NANOARROW_TYPE_STRING));
+ schema->flags &= ~ARROW_FLAG_NULLABLE;
+ return NANOARROW_OK;
+}
+```
+
+This works as long as your internal functions that use nanoarrow also return
+`int` and/or an `ArrowError*` argument. This usually means that there is
+an outer function that presents a more idiomatic interface (e.g., returning
+`std::optional<>` or throwing an exception) and an inner function that uses
+nanoarrow-style error handling. Embracing `NANOARROW_RETURN_NOT_OK()` is key
+to hapiness when using the nanoarrow library.
+
+Third, let's discuss memory management. Because nanoarrow is implemented in C
+and provides a C interface, the library by default uses C-style memory management
+(i.e., if you allocate it, you clean it up). This is unnecessary when you have
+C++ at your disposal, so nanoarrow also provides a C++ header (`nanoarrow.hpp`) with
+`std::unique_ptr<>`-like wrappers around anything that requires explicit clean up.
+Whereas in C you might have to write code like this:
+
+```c
+struct ArrowSchema schema;
+struct ArrowArray array;
+
+// Ok: if this returns, array was not initialized
+NANOARROW_RETURN_NOT_OK(ArrowSchemaInitFromType(&schema, NANOARROW_TYPE_STRING));
+
+// Verbose: if this fails, we need to release schema before returning
+// or it will leak.
+int code = ArrowArrayInitFromSchema(&array, &schema, NULL);
+if (code != NANOARROW_OK) {
+ schema.release(&schema);
+ return code;
+}
+```
+
+...using the `nanoarrow.hpp` types we can do:
+
+```cpp
+// These objects have C++ deleters that clean up the underlying
Review Comment:
also cut off?
--
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.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org