C++ API 参考#

group Nanoarrow C++ 帮助程序: 此文件中提供的实用程序旨在为 nanoarrow C 库的 C++ 用户提供支持，以便 C++ 风格的资源分配和错误处理能够与 nanoarrow 数据结构一起使用。这些实用程序并不旨在镜像 nanoarrow C API。

错误处理#

group 错误处理帮助程序

C API 中的大多数函数返回 ArrowErrorCode 以传达可能的失败。除非另有说明，否则在返回非零值后继续操作通常是不安全的。虽然 nanoarrow C++ 帮助程序本身不抛出任何异常，但提供这些帮助程序是为了方便在 C++ 框架中使用 nanoarrow C++ 帮助程序，在这些框架中，异常是一种有用的错误处理方式。

宏定义

_NANOARROW_THROW_NOT_OK_IMPL(NAME, EXPR, EXPR_STR)#

NANOARROW_THROW_NOT_OK(EXPR)#

class Exception : public std::exception#

所属权对象包装器#

group 唯一对象包装器

Arrow C 数据接口、Arrow C 流接口以及 nanoarrow C 库都使用可在栈上分配的对象，其中一些需要初始化或清理。

类型定义

using UniqueSchema = internal::Unique<struct ArrowSchema>#: 用于包装唯一 ArrowSchema 结构体的类。

using UniqueArray = internal::Unique<struct ArrowArray>#: 用于包装唯一 ArrowArray 结构体的类。

using UniqueArrayStream = internal::Unique<struct ArrowArrayStream>#: 用于包装唯一 ArrowArrayStream 结构体的类。

using UniqueBuffer = internal::Unique<struct ArrowBuffer>#: 用于包装唯一 ArrowBuffer 结构体的类。

using UniqueBitmap = internal::Unique<struct ArrowBitmap>#: 用于包装唯一 ArrowBitmap 结构体的类。

using UniqueArrayView = internal::Unique<struct ArrowArrayView>#: 用于包装唯一 ArrowArrayView 结构体的类。

数组流实用程序#

group ArrayStream 帮助程序

这些类提供了简单的 ArrowArrayStream 实现，可以对其进行扩展以帮助简化创建有效 ArrowArrayStream 实现的过程，或直接用于测试。

template<typename T> class ArrayStreamFactory#

#include <array_stream.hpp>

从一个标准 C++ 类导出 ArrowArrayStream。

该类通过将 C 回调调用映射到对象的实例方法调用，允许将标准 C++ 类导出到通用的 ArrowArrayStream 消费者。该对象的生命周期由 ArrowArrayStream 管理。关于此模式的最小有用示例，请参阅 VectorArrayStream。

这些方法必须能被 ArrayStreamFactory 访问，可以是公共方法，也可以通过将 ArrayStreamFactory<ImplClass> 声明为友元。鼓励（但不强制）实现者实现一个 ToArrayStream(ArrowArrayStream*) 方法，该方法创建一个由 ArrowArrayStream 拥有生命周期的新实例，并将相关数据移动到该实例中。

一个实现示例可能如下

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; }
};

一个使用示例可能如下

// 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());

模板参数：: T – 一个包含方法 int GetSchema(ArrowSchema*)、int GetNext(ArrowArray*) 和 const char* GetLastError() 的类。

公共静态函数

static inline void InitArrayStream(T *instance, struct ArrowArrayStream *out)#: 获取 instance 的所有权并填充 out 的回调。

class EmptyArrayStream#

#include <array_stream.hpp>

一个空的数组流。

这个类可以从一个 ArrowSchema 结构体构造，并实现一个默认的 get_next() 方法，该方法总是将输出的 ArrowArray 标记为已释放。

公共函数

inline EmptyArrayStream(struct ArrowSchema *schema)#

从一个 ArrowSchema 创建一个 EmptyArrayStream。

获取 schema 的所有权。

inline void ToArrayStream(struct ArrowArrayStream *out)#: 导出到 ArrowArrayStream。

class VectorArrayStream#

#include <array_stream.hpp>

一个由 UniqueArray 对象向量支持的 ArrowArrayStream 实现。

公共函数

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

从一个 ArrowSchema 和一个 UniqueArray 的向量创建一个 VectorArrayStream。

获取 schema 的所有权，并尽可能移动 arrays。

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

从一个 ArrowSchema 和一个 ArrowArray 创建一个一次性的 VectorArrayStream。

获取 schema 和 array 的所有权。

inline void ToArrayStream(struct ArrowArrayStream *out)#: 导出到 ArrowArrayStream。

缓冲区实用程序#

group Buffer 帮助程序

用于将类似缓冲区的 C++ 对象包装为 ArrowBuffer 对象的帮助程序，这些对象可用于构建 ArrowArray 对象。

函数

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

初始化一个包装任意 C++ 对象的缓冲区。

使用一个释放回调来初始化缓冲区，该回调在 ArrowBufferReset 被调用时删除被移动的 obj。此版本适用于包装其 .data() 成员缺失或与 ArrowArray 缓冲区目标值无关的对象。T 必须是可移动的。

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

初始化一个包装 C++ 序列的缓冲区。

具体来说，这使用 obj.data() 来设置缓冲区地址，并使用 obj.size() * sizeof(T::value_type) 来设置缓冲区大小。这适用于像 std::vector、std::array 和 std::string 这样的 STL 容器。此函数会移动 obj，并确保在调用 ArrowBufferReset 时将其删除。

范围-for 实用程序#

group 范围-for 帮助程序

Arrow C 数据接口和 Arrow C 流接口表示的数据可以使用 C++ 的范围-for 语句进行迭代。

变量

constexpr internal::Nothing NA = {}#: 一个可转换为任何空 optional 的对象。

template<typename T> class ViewArrayAs#

#include <view.hpp>

一个用于固定大小类型 ArrowArray 的、兼容范围-for 的包装器。

提供一个 optional<T> 序列，从被包装数组的每个非空槽位复制而来（空槽位导致空的 optional）。

template<int OffsetSize> class ViewArrayAsBytes#

#include <view.hpp>

一个用于二进制或 utf8 类型 ArrowArray 的、兼容范围-for 的包装器。

提供一个 optional<ArrowStringView> 序列，引用被包装数组的每个非空槽位（空槽位导致空的 optional）。可以通过为模板参数指定 64 而不是 32 来包装大型二进制和 utf8 数组。

class ViewBinaryViewArrayAsBytes#

class ViewArrayAsFixedSizeBytes#

#include <view.hpp>

一个用于固定大小二进制类型 ArrowArray 的、兼容范围-for 的包装器。

提供一个 optional<ArrowStringView> 序列，引用被包装数组的每个非空槽位（空槽位导致空的 optional）。

class ViewArrayStream#

#include <view.hpp>

一个用于 ArrowArrayStream 的、兼容范围-for 的包装器。

提供一个 ArrowArray& 序列，引用从被包装流中提取的最新数组。（每个数组如有必要可以被移动。）当流因错误而终止时，可以通过 code() 和 error() 成员函数分别检查错误码和错误消息。如果不检查错误码将导致断言失败。从流中提取的数组数量也可以通过 count() 成员函数获取。

公共函数

inline ArrowErrorCode code()#: 导致此流终止的错误码（如果有）。

inline ArrowError *error()#: 导致此流终止的错误消息（如果有）。

inline int count() const#: 到目前为止流式传输的数组数量。

C++ API 参考#

错误处理#

所属权对象包装器#

数组流实用程序#

缓冲区实用程序#

范围-for 实用程序#

本页