C++ API Reference#

group nanoarrow_hpp: The utilities provided in this file are intended to support C++ users of the nanoarrow C library such that C++-style resource allocation and error handling can be used with nanoarrow data structures. These utilities are not intended to mirror the nanoarrow C API.

Error handling#

group nanoarrow_hpp-errors

Most functions in the C API return an ArrowErrorCode to communicate possible failure. Except where documented, it is usually not safe to continue after a non-zero value has been returned. While the nanoarrow C++ helpers do not throw any exceptions of their own, these helpers are provided to facilitate using the nanoarrow C++ helpers in frameworks where this is a useful error handling idiom.

Defines

_NANOARROW_THROW_NOT_OK_IMPL(NAME, EXPR, EXPR_STR)#

NANOARROW_THROW_NOT_OK(EXPR)#

class Exception : public std::exception#

Owning object wrappers#

group nanoarrow_hpp-unique

The Arrow C Data interface, the Arrow C Stream interface, and the nanoarrow C library use stack-allocatable objects, some of which require initialization or cleanup.

Typedefs

using UniqueSchema = internal::Unique<struct ArrowSchema>#: Class wrapping a unique struct ArrowSchema.

using UniqueArray = internal::Unique<struct ArrowArray>#: Class wrapping a unique struct ArrowArray.

using UniqueArrayStream = internal::Unique<struct ArrowArrayStream>#: Class wrapping a unique struct ArrowArrayStream.

using UniqueBuffer = internal::Unique<struct ArrowBuffer>#: Class wrapping a unique struct ArrowBuffer.

using UniqueBitmap = internal::Unique<struct ArrowBitmap>#: Class wrapping a unique struct ArrowBitmap.

using UniqueArrayView = internal::Unique<struct ArrowArrayView>#: Class wrapping a unique struct ArrowArrayView.

Array Stream utilities#

group nanoarrow_hpp-array-stream

These classes provide simple ArrowArrayStream implementations that can be extended to help simplify the process of creating a valid ArrowArrayStream implementation or used as-is for testing.

template<typename T> class ArrayStreamFactory#

#include <nanoarrow.hpp>

Export an ArrowArrayStream from a standard C++ class.

This class allows a standard C++ class to be exported to a generic ArrowArrayStream consumer by mapping C callback invocations to method calls on an instance of the object whose lifecycle is owned by the ArrowArrayStream. See VectorArrayStream for minimal useful example of this pattern.

The methods must be accessible to the ArrayStreamFactory, either as public methods or by declaring ArrayStreamFactory<ImplClass> a friend. Implementors are encouraged (but not required) to implement a ToArrayStream(ArrowArrayStream*) that creates a new instance owned by the ArrowArrayStream and moves the relevant data to that instance.

An example implementation might be:

class StreamImpl {
 public:
  // Public methods (e.g., constructor) used from C++ to initialize relevant data

  // Idiomatic exporter to move data + lifecycle responsibility to an instance
  // managed by the ArrowArrayStream callbacks
  void ToArrayStream(struct ArrowArrayStream* out) {
    ArrayStreamFactory<StreamImpl>::InitArrayStream(new StreamImpl(...), out);
  }

 private:
  // Make relevant methods available to the ArrayStreamFactory
  friend class ArrayStreamFactory<StreamImpl>;

  // Method implementations (called from C, not normally interacted with from C++)
  int GetSchema(struct ArrowSchema* schema) { return ENOTSUP; }
  int GetNext(struct ArrowArray* array) { return ENOTSUP; }
  const char* GetLastError() { nullptr; }
};

An example usage might be:

// Call constructor and/or public methods to initialize relevant data
StreamImpl impl;

// Export to ArrowArrayStream after data are finalized
UniqueArrayStream stream;
impl.ToArrayStream(stream.get());

Template Parameters:: T – A class with methods int GetSchema(ArrowSchema*), int GetNext(ArrowArray*), and const char* GetLastError()

Public Static Functions

static inline void InitArrayStream(T *instance, struct ArrowArrayStream *out)#: Take ownership of instance and populate callbacks of out.

class EmptyArrayStream#

#include <nanoarrow.hpp>

An empty array stream.

This class can be constructed from an struct ArrowSchema and implements a default get_next() method that always marks the output ArrowArray as released.

DEPRECATED (0.4.0): Early versions of nanoarrow allowed subclasses to override get_schema(), get_next(), and get_last_error(). This functionality will be removed in a future release: use the pattern documented in ArrayStreamFactory to create custom ArrowArrayStream implementations.

Public Functions

inline EmptyArrayStream(struct ArrowSchema *schema)#

Create an EmptyArrayStream from an ArrowSchema.

Takes ownership of schema.

inline void ToArrayStream(struct ArrowArrayStream *out)#: Export to ArrowArrayStream.

Public Static Functions

static inline UniqueArrayStream MakeUnique(struct ArrowSchema *schema)#

Create an empty UniqueArrayStream from a struct ArrowSchema.

DEPRECATED (0.4.0): Use the constructor + ToArrayStream() to export an EmptyArrayStream to an ArrowArrayStream consumer.

class VectorArrayStream#

#include <nanoarrow.hpp>

Implementation of an ArrowArrayStream backed by a vector of UniqueArray objects.

Public Functions

inline VectorArrayStream(struct ArrowSchema *schema, std::vector<UniqueArray> arrays)#

Create a VectorArrayStream from an ArrowSchema + vector of UniqueArray.

Takes ownership of schema and moves arrays if possible.

inline VectorArrayStream(struct ArrowSchema *schema, struct ArrowArray *array)#

Create a one-shot VectorArrayStream from an ArrowSchema + ArrowArray.

Takes ownership of schema and array.

inline void ToArrayStream(struct ArrowArrayStream *out)#: Export to ArrowArrayStream.

Public Static Functions

static inline UniqueArrayStream MakeUnique(struct ArrowSchema *schema, struct ArrowArray *array)#

Create a UniqueArrowArrayStream from an existing array.

DEPRECATED (0.4.0): Use the constructors + ToArrayStream() to export a VectorArrayStream to an ArrowArrayStream consumer.

static inline UniqueArrayStream MakeUnique(struct ArrowSchema *schema, std::vector<UniqueArray> arrays)#

Create a UniqueArrowArrayStream from existing arrays.

DEPRECATED (0.4.0): Use the constructor + ToArrayStream() to export a VectorArrayStream to an ArrowArrayStream consumer.

Buffer utilities#

group nanoarrow_hpp-buffer

Helpers to wrap buffer-like C++ objects as ArrowBuffer objects that can be used to build ArrowArray objects.

Functions

template<typename T> static inline void BufferInitWrapped(struct ArrowBuffer *buffer, T obj, const uint8_t *data, int64_t size_bytes)#

Initialize a buffer wrapping an arbitrary C++ object.

Initializes a buffer with a release callback that deletes the moved obj when ArrowBufferReset is called. This version is useful for wrapping an object whose .data() member is missing or unrelated to the buffer value that is destined for a the buffer of an ArrowArray. T must be movable.

template<typename T> void BufferInitSequence(struct ArrowBuffer *buffer, T obj)#

Initialize a buffer wrapping a C++ sequence.

Specifically, this uses obj.data() to set the buffer address and obj.size() * sizeof(T::value_type) to set the buffer size. This works for STL containers like std::vector, std::array, and std::string. This function moves obj and ensures it is deleted when ArrowBufferReset is called.

Range-for utilities#

group nanoarrow_hpp-range_for

The Arrow C Data interface and the Arrow C Stream interface represent data which can be iterated through using C++’s range-for statement.

Variables

constexpr internal::Nothing NA = {}#: An object convertible to any empty optional.

template<typename T> class ViewArrayAs#

#include <nanoarrow.hpp>

A range-for compatible wrapper for ArrowArray of fixed size type.

Provides a sequence of optional<T> copied from each non-null slot of the wrapped array (null slots result in empty optionals).

template<int OffsetSize> class ViewArrayAsBytes#

#include <nanoarrow.hpp>

A range-for compatible wrapper for ArrowArray of binary or utf8.

Provides a sequence of optional<ArrowStringView> referencing each non-null slot of the wrapped array (null slots result in empty optionals). Large binary and utf8 arrays can be wrapped by specifying 64 instead of 32 for the template argument.

class ViewArrayAsFixedSizeBytes#

#include <nanoarrow.hpp>

A range-for compatible wrapper for ArrowArray of fixed size binary.

Provides a sequence of optional<ArrowStringView> referencing each non-null slot of the wrapped array (null slots result in empty optionals).

class ViewArrayStream#

#include <nanoarrow.hpp>

A range-for compatible wrapper for ArrowArrayStream.

Provides a sequence of ArrowArray& referencing the most recent array drawn from the wrapped stream. (Each array may be moved from if necessary.) When streams terminate due to an error, the error code and message are available for inspection through the code() and error() member functions respectively. Failure to inspect the error code will result in an assertion failure. The number of arrays drawn from the stream is also available through the count() member function.

Public Functions

inline ArrowErrorCode code()#: The error code which caused this stream to terminate, if any.

inline ArrowError *error()#: The error message which caused this stream to terminate, if any.

inline int count() const#: The number of arrays streamed so far.