This is an automated email from the ASF dual-hosted git repository.
paleolimbot pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-nanoarrow.git
The following commit(s) were added to refs/heads/main by this push:
new 4a42e11 Add example usage to examples/ directory (#40)
4a42e11 is described below
commit 4a42e11a8807a47db69b3c139510098c702a338e
Author: Dewey Dunnington <[email protected]>
AuthorDate: Fri Sep 2 22:03:45 2022 -0300
Add example usage to examples/ directory (#40)
* start on examples
* maybe fix target include dirs for fetch content build
* with working app
* maybe github action to check example
* maybe fix repo name
* maybe the right repo
* actually use tag
* maybe correct sha
* try by reference
* maybe simpler cmake setup
* annotate CMakeLists.txt
* build out example a little bit
* better example
* let example error
* add license to readme
* sketch vendored example
* document and maybe test vendored example
* fix typo in action
* simplify example
* rewrite README, fix vendored example
* remove references to previous example
---
.github/workflows/examples.yaml | 66 ++++++++++++++++
CMakeLists.txt | 7 +-
README.md | 122 ++++++++++++++++--------------
examples/cmake-minimal/CMakeLists.txt | 55 ++++++++++++++
examples/cmake-minimal/README.md | 54 +++++++++++++
examples/cmake-minimal/src/app.c | 40 ++++++++++
examples/cmake-minimal/src/library.c | 69 +++++++++++++++++
examples/cmake-minimal/src/library.h | 120 +++++++++++++++++++++++++++++
examples/vendored-minimal/README.md | 74 ++++++++++++++++++
examples/vendored-minimal/src/.gitignore | 20 +++++
examples/vendored-minimal/src/app.c | 40 ++++++++++
examples/vendored-minimal/src/library.c | 69 +++++++++++++++++
examples/vendored-minimal/src/library.h | 120 +++++++++++++++++++++++++++++
examples/vendored-minimal/src/nanoarrow.c | 18 +++++
examples/vendored-minimal/src/nanoarrow.h | 18 +++++
15 files changed, 835 insertions(+), 57 deletions(-)
diff --git a/.github/workflows/examples.yaml b/.github/workflows/examples.yaml
new file mode 100644
index 0000000..eb5d480
--- /dev/null
+++ b/.github/workflows/examples.yaml
@@ -0,0 +1,66 @@
+# 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.
+
+name: Build and run examples
+
+on:
+ push:
+ branches:
+ - main
+ pull_request:
+ branches:
+ - main
+
+jobs:
+ examples:
+
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout repo
+ uses: actions/checkout@v3
+ with:
+ fetch-depth: 0
+
+ - name: Install dependencies
+ run: |
+ sudo apt-get install -y cmake
+
+ - name: Minimal CMake Example
+ run: |
+ cd examples/cmake-minimal
+ mkdir build && cd build
+ cmake ..
+ cmake --build .
+
+ ./example_cmake_minimal_app
+
+ - name: Minimal Vendored Example
+ run: |
+ cd examples/vendored-minimal
+ mkdir build && cd build
+ cmake ../../.. -DNANOARROW_BUNDLE=ON
-DNANOARROW_NAMESPACE=ExampleVendored
+ cmake --build .
+ cmake --install . --prefix=../src
+
+ cd ../src
+
+ gcc -c library.c nanoarrow.c
+ ar rcs libexample_vendored_minimal_library.a library.o nanoarrow.o
+ gcc -o example_vendored_minimal_app app.c
libexample_vendored_minimal_library.a
+
+ ./example_vendored_minimal_app
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 492cb5d..6ba5a49 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -79,14 +79,17 @@ if(NANOARROW_BUNDLE)
# Install the amalgamated header and source
install(FILES ${NANOARROW_H_TEMP} ${NANOARROW_C_TEMP} DESTINATION ".")
else()
- include_directories(src)
- include_directories(${CMAKE_CURRENT_BINARY_DIR}/generated)
add_library(
nanoarrow
src/nanoarrow/array.c
src/nanoarrow/schema.c
src/nanoarrow/utils.c)
+ target_include_directories(nanoarrow PUBLIC
+ $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
+ $<INSTALL_INTERFACE:include>)
+ target_include_directories(nanoarrow PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>)
+
install(TARGETS nanoarrow DESTINATION lib)
install(DIRECTORY src/ DESTINATION include FILES_MATCHING PATTERN "*.h")
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/generated/build_id.h DESTINATION
include/nanoarrow)
diff --git a/README.md b/README.md
index 92ce687..5cc909e 100644
--- a/README.md
+++ b/README.md
@@ -17,67 +17,79 @@
under the License.
-->
-# nanoarrow
+# arrow-nanoarrow
[](https://app.codecov.io/gh/apache/arrow-nanoarrow?branch=main)
The nanoarrow library is a set of helper functions to interpret and generate
[Arrow C Data
Interface](https://arrow.apache.org/docs/format/CDataInterface.html)
and [Arrow C Stream
Interface](https://arrow.apache.org/docs/format/CStreamInterface.html)
-structures. The library is in active development and should currently be used
only
-for entertainment purposes. Everything from the name of the project to the
variable
-names are up for grabs (i.e., suggest/pull request literally any ideas you may
-have!).
+structures. The library is in active early development and users should update
regularly
+from the main branch of this repository.
Whereas the current suite of Arrow implementations provide the basis for a
comprehensive data analysis toolkit, this library is intended to support
clients
-that wish to produce or interpret Arrow C Data and/or Arrow C Stream
structures.
-The library will:
-
-- Create, copy, parse, and validate struct ArrowSchema objects (all types
mentioned
- in the C Data interface specification)
-- Create and validate struct ArrowArray/struct ArrowSchema pairs for (all types
- mentioned in the C Data interface specification)
-- Iterate over struct ArrowArrays element-wise (non-nested types) (i.e., is the
- ith element null; get the ith element).
-- Build Arrays element-wise (non-nested types) (i.e., basic Array Builder
logic).
-
-While it will not provide full support for nested types, it should provide
enough
-infrastructure that an extension library with a similar format could implement
such
-support.
-
-## Usage
-
-You can use nanoarrow in your project in two ways:
-
-1. Copy contents of the `src/nanoarrow/` into your favourite include directory
and
- `#include <nanoarrow/nanoarrow.c>` somewhere in your project exactly once.
-2. Clone and use `cmake`, `cmake --build`, and `cmake --install` to
build/install
- the static library and add `-L/path/to/nanoarrow/lib -lnanoarrow` to your
favourite
- linker flag configuration.
-
-All public functions and types are declared in `nanoarrow/nanoarrow.h`.
-
-In all cases you will want to copy this project or pin your build to a
specific commit
-since it will change rapidly and regularly. The nanoarrow library does not and
will
-not provide ABI stability (i.e., you must vendor or link to a private version
of
-the static library).
-
-## Background
-
-The design of nanoarrow reflects the needs of a few previous
libraries/prototypes
-requiring a library with a similar scope:
-
-- DuckDB’s Arrow wrappers, the details of which are in a few places
- (e.g.,
[here](https://github.com/duckdb/duckdb/blob/master/src/common/arrow_wrapper.cpp),
-
[here](https://github.com/duckdb/duckdb/blob/master/src/main/query_result.cpp),
- and a few other places)
-- An [R wrapper around the C Data
interface](https://github.com/paleolimbot/narrow),
- along which a [C-only
library](https://github.com/paleolimbot/narrow/tree/master/src/narrow)
- was prototyped.
-- An [R implementation of the draft GeoArrow
specification](https://github.com/paleolimbot/geoarrow),
- along which a [mostly header-only C++
library](https://github.com/paleolimbot/geonanoarrowpp/tree/main/src/geoarrow/internal/arrow-hpp)
- was prototyped.
-- The [Arrow Database Connectivity](https://github.com/apache/arrow-adbc) C
API, for which drivers
- in theory can be written in C (which is currently difficult in practice
because there
- are few if any tools to help do this properly).
+that wish to produce or interpret Arrow C Data and/or Arrow C Stream structures
+where linking to a higher level Arrow binding is difficult or impossible.
+
+## Using the C library
+
+The nanoarrow C library is intended to be copied and vendored. This can be
done using
+CMake or by using the bundled nanoarrow.h/nanorrow.c distribution available in
the
+dist/ directory in this repository. Examples of both can be found in the
examples/
+directory in this repository.
+
+A simple producer example:
+
+```c
+#include "nanoarrow.h"
+
+int make_simple_array(struct ArrowArray* array_out, struct ArrowSchema*
schema_out) {
+ struct ArrowError error;
+ array_out->release = NULL;
+ schema_out->release = NULL;
+
+ NANOARROW_RETURN_NOT_OK(ArrowArrayInit(array_out, NANOARROW_TYPE_INT32));
+
+ NANOARROW_RETURN_NOT_OK(ArrowArrayStartAppending(array_out));
+ NANOARROW_RETURN_NOT_OK(ArrowArrayAppendInt(array_out, 1));
+ NANOARROW_RETURN_NOT_OK(ArrowArrayAppendInt(array_out, 2));
+ NANOARROW_RETURN_NOT_OK(ArrowArrayAppendInt(array_out, 3));
+ NANOARROW_RETURN_NOT_OK(ArrowArrayFinishBuilding(array_out, &error));
+
+ NANOARROW_RETURN_NOT_OK(ArrowSchemaInit(schema_out, NANOARROW_TYPE_INT32));
+
+ return NANOARROW_OK;
+}
+```
+
+A simple consumer example:
+
+```c
+#include <stdio.h>
+
+#include "nanoarrow.h"
+
+int print_simple_array(struct ArrowArray* array, struct ArrowSchema* schema) {
+ struct ArrowError error;
+ struct ArrowArrayView array_view;
+ NANOARROW_RETURN_NOT_OK(ArrowArrayViewInitFromSchema(&array_view, schema,
&error));
+
+ if (array_view.storage_type != NANOARROW_TYPE_INT32) {
+ printf("Array has storage that is not int32\n");
+ }
+
+ int result = ArrowArrayViewSetArray(&array_view, array, &error);
+ if (result != NANOARROW_OK) {
+ ArrowArrayViewReset(&array_view);
+ return result;
+ }
+
+ for (int64_t i = 0; i < array->length; i++) {
+ printf("%d\n", (int)ArrowArrayViewGetIntUnsafe(&array_view, i));
+ }
+
+ ArrowArrayViewReset(&array_view);
+ return NANOARROW_OK;
+}
+```
diff --git a/examples/cmake-minimal/CMakeLists.txt
b/examples/cmake-minimal/CMakeLists.txt
new file mode 100644
index 0000000..4cd26e8
--- /dev/null
+++ b/examples/cmake-minimal/CMakeLists.txt
@@ -0,0 +1,55 @@
+# 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.
+
+message(STATUS "Building using CMake version: ${CMAKE_VERSION}")
+cmake_minimum_required(VERSION 3.11)
+include(FetchContent)
+
+project(NanoArrowExampleCMakeMinimal)
+
+# When adding nanoarrow's CMake directory to a CMake project that contains a
library
+# intended for use by others, set NANOARROW_NAMESPACE to rename symbols in the
+# nanoarrow library such that they do not collide with other libraries that
may also
+# link to their own copy of nanoarrow. You may wish to include the namespace
only
+# on release builds, since the namespace implementation obscures inline help
+# available in many text editors.
+set(NANOARROW_NAMESPACE "ExampleCmakeMinimal")
+
+FetchContent_Declare(
+ nanoarrow_example_cmake_minimal
+
+ # We use SOURCE_DIR here to point to the version of nanoarrow represented
+ # by this checkout of the repo; however, you can use any of the methods
+ # supported by FetchContent_Declare, e.g.:
+ # GIT_REPOSITORY https://github.com/apache/arrow-nanoarrow.git
+ # GIT_TAG some_commit_hash
+ # GIT_SHALLOW TRUE
+ SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR}/../..)
+
+FetchContent_MakeAvailable(nanoarrow_example_cmake_minimal)
+
+# Add the library and link it against nanoarrow
+include_directories(src)
+add_library(example_cmake_minimal_library src/library.c)
+
+# Always use PRIVATE when linking to nanoarrow to hide nanoarrow's headers
from a
+# target that in turn uses your library.
+target_link_libraries(example_cmake_minimal_library PRIVATE nanoarrow)
+
+# Add the executable and link it against the library
+add_executable(example_cmake_minimal_app src/app.c)
+target_link_libraries(example_cmake_minimal_app example_cmake_minimal_library)
diff --git a/examples/cmake-minimal/README.md b/examples/cmake-minimal/README.md
new file mode 100644
index 0000000..6d64706
--- /dev/null
+++ b/examples/cmake-minimal/README.md
@@ -0,0 +1,54 @@
+<!---
+ 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.
+-->
+
+# Minimal CMake Example
+
+This folder contains a CMake project that links to its own copy of
+nanoarrow using CMake's `FetchContent` module. Whether vendoring or
+using CMake, nanoarrow is intended to be vendored or statically
+linked in a way that does not expose its headers or symbols to other
+projects. To illustrate this, a small library is included (library.h
+and library.c) and built in this way, linked to by a program (app.c)
+that does not use nanoarrow (but does make use of the Arrow C Data
+interface header, since this is ABI stable and intended to be used
+in this way).
+
+To build the project:
+
+```bash
+git clone https://github.com/apache/arrow-nanoarrow.git
+cd arrow-nanoarrow/examples/cmake-minimal
+mkdir build && cd build
+cmake ..
+cmake --build .
+```
+
+You can also open the cmake-minimal folder in VSCode and configure/build
+the project using VSCode's CMake integration.
+
+After building, you can run the app from the build directory. The app
+parses command line arguments into an int32 array and prints out the
+resulting length (or any error encountered whilst building the array).
+
+```bash
+./example_cmake_minimal_app
+# 1
+# 2
+# 3
+```
diff --git a/examples/cmake-minimal/src/app.c b/examples/cmake-minimal/src/app.c
new file mode 100644
index 0000000..5d23a34
--- /dev/null
+++ b/examples/cmake-minimal/src/app.c
@@ -0,0 +1,40 @@
+// 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.
+
+#include "library.h"
+
+#include <stdio.h>
+
+int main(int argc, char* argv[]) {
+ struct ArrowArray array;
+ struct ArrowSchema schema;
+ array.release = NULL;
+ schema.release = NULL;
+
+ int result = make_simple_array(&array, &schema);
+ if (result != 0) {
+ if (array.release) array.release(&array);
+ if (schema.release) schema.release(&schema);
+ return result;
+ }
+
+ result = print_simple_array(&array, &schema);
+ if (array.release) array.release(&array);
+ if (schema.release) schema.release(&schema);
+
+ return result;
+}
diff --git a/examples/cmake-minimal/src/library.c
b/examples/cmake-minimal/src/library.c
new file mode 100644
index 0000000..ba23507
--- /dev/null
+++ b/examples/cmake-minimal/src/library.c
@@ -0,0 +1,69 @@
+// 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.
+
+#include <errno.h>
+#include <stdlib.h>
+
+#include <stdio.h>
+
+#include "nanoarrow/nanoarrow.h"
+
+#include "library.h"
+
+static struct ArrowError global_error;
+
+const char* my_library_last_error() { return ArrowErrorMessage(&global_error);
}
+
+int make_simple_array(struct ArrowArray* array_out, struct ArrowSchema*
schema_out) {
+ ArrowErrorSet(&global_error, "");
+ array_out->release = NULL;
+ schema_out->release = NULL;
+
+ NANOARROW_RETURN_NOT_OK(ArrowArrayInit(array_out, NANOARROW_TYPE_INT32));
+
+ NANOARROW_RETURN_NOT_OK(ArrowArrayStartAppending(array_out));
+ NANOARROW_RETURN_NOT_OK(ArrowArrayAppendInt(array_out, 1));
+ NANOARROW_RETURN_NOT_OK(ArrowArrayAppendInt(array_out, 2));
+ NANOARROW_RETURN_NOT_OK(ArrowArrayAppendInt(array_out, 3));
+ NANOARROW_RETURN_NOT_OK(ArrowArrayFinishBuilding(array_out, &global_error));
+
+ NANOARROW_RETURN_NOT_OK(ArrowSchemaInit(schema_out, NANOARROW_TYPE_INT32));
+
+ return NANOARROW_OK;
+}
+
+int print_simple_array(struct ArrowArray* array, struct ArrowSchema* schema) {
+ struct ArrowArrayView array_view;
+ NANOARROW_RETURN_NOT_OK(ArrowArrayViewInitFromSchema(&array_view, schema,
&global_error));
+
+ if (array_view.storage_type != NANOARROW_TYPE_INT32) {
+ printf("Array has storage that is not int32\n");
+ }
+
+ int result = ArrowArrayViewSetArray(&array_view, array, &global_error);
+ if (result != NANOARROW_OK) {
+ ArrowArrayViewReset(&array_view);
+ return result;
+ }
+
+ for (int64_t i = 0; i < array->length; i++) {
+ printf("%d\n", (int)ArrowArrayViewGetIntUnsafe(&array_view, i));
+ }
+
+ ArrowArrayViewReset(&array_view);
+ return NANOARROW_OK;
+}
diff --git a/examples/cmake-minimal/src/library.h
b/examples/cmake-minimal/src/library.h
new file mode 100644
index 0000000..c93f1ab
--- /dev/null
+++ b/examples/cmake-minimal/src/library.h
@@ -0,0 +1,120 @@
+// 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.
+
+#pragma once
+
+#include <stdint.h>
+
+// You can and should use the Arrow C Data interface types in headers
+// that will be included by others; however, you should not include
+// any other parts of the nanoarrow.h header in one of your own that
+// might be accessed by others.
+
+// Extra guard for versions of Arrow without the canonical guard
+#ifndef ARROW_FLAG_DICTIONARY_ORDERED
+
+#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
+
+#ifndef ARROW_C_STREAM_INTERFACE
+#define ARROW_C_STREAM_INTERFACE
+
+struct ArrowArrayStream {
+ // Callback to get the stream type
+ // (will be the same for all arrays in the stream).
+ //
+ // Return value: 0 if successful, an `errno`-compatible error code otherwise.
+ //
+ // If successful, the ArrowSchema must be released independently from the
stream.
+ int (*get_schema)(struct ArrowArrayStream*, struct ArrowSchema* out);
+
+ // Callback to get the next array
+ // (if no error and the array is released, the stream has ended)
+ //
+ // Return value: 0 if successful, an `errno`-compatible error code otherwise.
+ //
+ // If successful, the ArrowArray must be released independently from the
stream.
+ int (*get_next)(struct ArrowArrayStream*, struct ArrowArray* out);
+
+ // Callback to get optional detailed error information.
+ // This must only be called if the last stream operation failed
+ // with a non-0 return code.
+ //
+ // Return value: pointer to a null-terminated character array describing
+ // the last error, or NULL if no description is available.
+ //
+ // The returned pointer is only valid until the next operation on this stream
+ // (including release).
+ const char* (*get_last_error)(struct ArrowArrayStream*);
+
+ // Release callback: release the stream's own resources.
+ // Note that arrays returned by `get_next` must be individually released.
+ void (*release)(struct ArrowArrayStream*);
+
+ // Opaque producer-specific data
+ void* private_data;
+};
+
+#endif // ARROW_C_STREAM_INTERFACE
+#endif // ARROW_FLAG_DICTIONARY_ORDERED
+
+const char* my_library_last_error();
+
+// Creates the integer array [1, 2, 3]
+int make_simple_array(struct ArrowArray* array_out, struct ArrowSchema*
schema_out);
+
+// Prints the array created by make_simple_array to the stdout
+int print_simple_array(struct ArrowArray* array, struct ArrowSchema* schema);
diff --git a/examples/vendored-minimal/README.md
b/examples/vendored-minimal/README.md
new file mode 100644
index 0000000..58c6757
--- /dev/null
+++ b/examples/vendored-minimal/README.md
@@ -0,0 +1,74 @@
+<!---
+ 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.
+-->
+
+# Minimal Vendored Example
+
+This folder contains a project that uses the bundled nanarrow.c and nanoarrow.h
+files included in the dist/ directory of this repository (or that can be
generated
+using `cmake -DNANOARROW_BUNDLE=ON` from the root CMake project). Like the
CMake
+example, you must be careful to not expose nanoarrow's header outside your
project
+and make use of `#define NANOARROW_NAMESPACE MyProject` to prefix nanoarrow's
symbol
+names to ensure they do not collide with another copy of nanoarrow potentially
+linked to by another project.
+
+The nanoarrow.c and nanoarrow.h files included in this example are stubs to
illustrate
+how these files could fit in to a library and/or command-line application
project.
+The easiest way is to use the pre-generated versions in the dist/ folder of
this
+repository:
+
+```bash
+git clone https://github.com/apache/arrow-nanoarrow.git
+cd arrow-nanoarrow/examples/vendored-minimal
+cp ../../dist/nanoarrow.h src/nanoarrow.h
+cp ../../dist/nanoarrow.c src/nanoarrow.c
+```
+
+If you use these, you will have to manually `#define NANOARROW_NAMESPACE
MyProject`
+manually next to `#define NANOARROW_BUILD_ID` in the header.
+
+You can also generate the bundled versions with the namespace defined using
`cmake`:
+
+```bash
+git clone https://github.com/apache/arrow-nanoarrow.git
+cd arrow-nanoarrow
+mkdir build && cd build
+cmake .. -DNANOARROW_BUNDLE=ON -DNANOARROW_NAMESPACE=ExampleVendored
+cmake --build .
+cmake --install . --prefix=../examples/vendored-minimal/src
+```
+
+Then you can build/link the application/library using the build tool of your
choosing:
+
+```bash
+cd src
+cc -c library.c nanoarrow.c
+ar rcs libexample_vendored_minimal_library.a library.o nanoarrow.o
+cc -o example_vendored_minimal_app app.c libexample_vendored_minimal_library.a
+```
+
+After building, you can run the app. The app
+parses command line arguments into an int32 array and prints out the
+resulting length (or any error encountered whilst building the array).
+
+```bash
+./example_vendored_minimal_app
+# 1
+# 2
+# 3
+```
diff --git a/examples/vendored-minimal/src/.gitignore
b/examples/vendored-minimal/src/.gitignore
new file mode 100644
index 0000000..3fe5595
--- /dev/null
+++ b/examples/vendored-minimal/src/.gitignore
@@ -0,0 +1,20 @@
+# 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.
+
+*.o
+*.a
+example_vendored_minimal_app
diff --git a/examples/vendored-minimal/src/app.c
b/examples/vendored-minimal/src/app.c
new file mode 100644
index 0000000..5d23a34
--- /dev/null
+++ b/examples/vendored-minimal/src/app.c
@@ -0,0 +1,40 @@
+// 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.
+
+#include "library.h"
+
+#include <stdio.h>
+
+int main(int argc, char* argv[]) {
+ struct ArrowArray array;
+ struct ArrowSchema schema;
+ array.release = NULL;
+ schema.release = NULL;
+
+ int result = make_simple_array(&array, &schema);
+ if (result != 0) {
+ if (array.release) array.release(&array);
+ if (schema.release) schema.release(&schema);
+ return result;
+ }
+
+ result = print_simple_array(&array, &schema);
+ if (array.release) array.release(&array);
+ if (schema.release) schema.release(&schema);
+
+ return result;
+}
diff --git a/examples/vendored-minimal/src/library.c
b/examples/vendored-minimal/src/library.c
new file mode 100644
index 0000000..9ddf7ad
--- /dev/null
+++ b/examples/vendored-minimal/src/library.c
@@ -0,0 +1,69 @@
+// 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.
+
+#include <errno.h>
+#include <stdlib.h>
+
+#include <stdio.h>
+
+#include "nanoarrow.h"
+
+#include "library.h"
+
+static struct ArrowError global_error;
+
+const char* my_library_last_error() { return ArrowErrorMessage(&global_error);
}
+
+int make_simple_array(struct ArrowArray* array_out, struct ArrowSchema*
schema_out) {
+ ArrowErrorSet(&global_error, "");
+ array_out->release = NULL;
+ schema_out->release = NULL;
+
+ NANOARROW_RETURN_NOT_OK(ArrowArrayInit(array_out, NANOARROW_TYPE_INT32));
+
+ NANOARROW_RETURN_NOT_OK(ArrowArrayStartAppending(array_out));
+ NANOARROW_RETURN_NOT_OK(ArrowArrayAppendInt(array_out, 1));
+ NANOARROW_RETURN_NOT_OK(ArrowArrayAppendInt(array_out, 2));
+ NANOARROW_RETURN_NOT_OK(ArrowArrayAppendInt(array_out, 3));
+ NANOARROW_RETURN_NOT_OK(ArrowArrayFinishBuilding(array_out, &global_error));
+
+ NANOARROW_RETURN_NOT_OK(ArrowSchemaInit(schema_out, NANOARROW_TYPE_INT32));
+
+ return NANOARROW_OK;
+}
+
+int print_simple_array(struct ArrowArray* array, struct ArrowSchema* schema) {
+ struct ArrowArrayView array_view;
+ NANOARROW_RETURN_NOT_OK(ArrowArrayViewInitFromSchema(&array_view, schema,
&global_error));
+
+ if (array_view.storage_type != NANOARROW_TYPE_INT32) {
+ printf("Array has storage that is not int32\n");
+ }
+
+ int result = ArrowArrayViewSetArray(&array_view, array, &global_error);
+ if (result != NANOARROW_OK) {
+ ArrowArrayViewReset(&array_view);
+ return result;
+ }
+
+ for (int64_t i = 0; i < array->length; i++) {
+ printf("%d\n", (int)ArrowArrayViewGetIntUnsafe(&array_view, i));
+ }
+
+ ArrowArrayViewReset(&array_view);
+ return NANOARROW_OK;
+}
diff --git a/examples/vendored-minimal/src/library.h
b/examples/vendored-minimal/src/library.h
new file mode 100644
index 0000000..c93f1ab
--- /dev/null
+++ b/examples/vendored-minimal/src/library.h
@@ -0,0 +1,120 @@
+// 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.
+
+#pragma once
+
+#include <stdint.h>
+
+// You can and should use the Arrow C Data interface types in headers
+// that will be included by others; however, you should not include
+// any other parts of the nanoarrow.h header in one of your own that
+// might be accessed by others.
+
+// Extra guard for versions of Arrow without the canonical guard
+#ifndef ARROW_FLAG_DICTIONARY_ORDERED
+
+#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
+
+#ifndef ARROW_C_STREAM_INTERFACE
+#define ARROW_C_STREAM_INTERFACE
+
+struct ArrowArrayStream {
+ // Callback to get the stream type
+ // (will be the same for all arrays in the stream).
+ //
+ // Return value: 0 if successful, an `errno`-compatible error code otherwise.
+ //
+ // If successful, the ArrowSchema must be released independently from the
stream.
+ int (*get_schema)(struct ArrowArrayStream*, struct ArrowSchema* out);
+
+ // Callback to get the next array
+ // (if no error and the array is released, the stream has ended)
+ //
+ // Return value: 0 if successful, an `errno`-compatible error code otherwise.
+ //
+ // If successful, the ArrowArray must be released independently from the
stream.
+ int (*get_next)(struct ArrowArrayStream*, struct ArrowArray* out);
+
+ // Callback to get optional detailed error information.
+ // This must only be called if the last stream operation failed
+ // with a non-0 return code.
+ //
+ // Return value: pointer to a null-terminated character array describing
+ // the last error, or NULL if no description is available.
+ //
+ // The returned pointer is only valid until the next operation on this stream
+ // (including release).
+ const char* (*get_last_error)(struct ArrowArrayStream*);
+
+ // Release callback: release the stream's own resources.
+ // Note that arrays returned by `get_next` must be individually released.
+ void (*release)(struct ArrowArrayStream*);
+
+ // Opaque producer-specific data
+ void* private_data;
+};
+
+#endif // ARROW_C_STREAM_INTERFACE
+#endif // ARROW_FLAG_DICTIONARY_ORDERED
+
+const char* my_library_last_error();
+
+// Creates the integer array [1, 2, 3]
+int make_simple_array(struct ArrowArray* array_out, struct ArrowSchema*
schema_out);
+
+// Prints the array created by make_simple_array to the stdout
+int print_simple_array(struct ArrowArray* array, struct ArrowSchema* schema);
diff --git a/examples/vendored-minimal/src/nanoarrow.c
b/examples/vendored-minimal/src/nanoarrow.c
new file mode 100644
index 0000000..9bd0367
--- /dev/null
+++ b/examples/vendored-minimal/src/nanoarrow.c
@@ -0,0 +1,18 @@
+// 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.
+
+// See the README in this directory for how to generate this file
diff --git a/examples/vendored-minimal/src/nanoarrow.h
b/examples/vendored-minimal/src/nanoarrow.h
new file mode 100644
index 0000000..9bd0367
--- /dev/null
+++ b/examples/vendored-minimal/src/nanoarrow.h
@@ -0,0 +1,18 @@
+// 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.
+
+// See the README in this directory for how to generate this file
