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.

Base classes and utilities#

group nanoarrow_hpp-unique_base

Functions

template<typename T> static inline void init_pointer(T *data)#

template<typename T> static inline void move_pointer(T *src, T *dst)#

template<typename T> static inline void release_pointer(T *data)#

template<> inline void init_pointer(struct ArrowSchema *data)#

template<> inline void move_pointer(struct ArrowSchema *src, struct ArrowSchema *dst)#

template<> inline void release_pointer(struct ArrowSchema *data)#

template<> inline void init_pointer(struct ArrowArray *data)#

template<> inline void move_pointer(struct ArrowArray *src, struct ArrowArray *dst)#

template<> inline void release_pointer(struct ArrowArray *data)#

template<> inline void init_pointer(struct ArrowArrayStream *data)#

template<> inline void move_pointer(struct ArrowArrayStream *src, struct ArrowArrayStream *dst)#

template<> inline void release_pointer(ArrowArrayStream *data)#

template<> inline void init_pointer(struct ArrowBuffer *data)#

template<> inline void move_pointer(struct ArrowBuffer *src, struct ArrowBuffer *dst)#

template<> inline void release_pointer(struct ArrowBuffer *data)#

template<> inline void init_pointer(struct ArrowBitmap *data)#

template<> inline void move_pointer(struct ArrowBitmap *src, struct ArrowBitmap *dst)#

template<> inline void release_pointer(struct ArrowBitmap *data)#

template<> inline void init_pointer(struct ArrowArrayView *data)#

template<> inline void move_pointer(struct ArrowArrayView *src, struct ArrowArrayView *dst)#

template<> inline void release_pointer(struct ArrowArrayView *data)#

template<typename T> class Unique#

#include <nanoarrow.hpp>

A unique_ptr-like base class for stack-allocatable objects.

Template Parameters:: T – The object type

Public Functions

inline Unique()#: Construct an invalid instance of T holding no resources.

inline Unique(T *data)#: Move and take ownership of data.

inline Unique(Unique &&rhs)#: Move and take ownership of data wrapped by rhs.

inline T *get() noexcept#: Get a pointer to the data owned by this object.

inline T *operator->() noexcept#: Use the pointer operator to access fields of this object.

inline void reset()#: Call data’s release callback if valid.

inline void reset(T *data)#: Call data’s release callback if valid and move ownership of the data pointed to by data.

inline void move(T *out)#: Move ownership of this object to the data pointed to by out.