C++ API 参考#

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

错误处理#

group nanoarrow_hpp-errors

C API 中的大多数函数都返回一个 ArrowErrorCode 来传达可能的失败。除非有文档说明，否则在返回非零值后继续执行通常是不安全的。虽然 nanoarrow C++ 助手本身不会抛出任何异常，但提供这些助手是为了便于在将此作为有用错误处理习惯用法的框架中使用 nanoarrow C++ 助手。

定义

_NANOARROW_THROW_NOT_OK_IMPL(NAME, EXPR, EXPR_STR)#

NANOARROW_THROW_NOT_OK(EXPR)#

class Exception : public std::exception#

拥有对象包装器#

group nanoarrow_hpp-unique

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

类型定义

using UniqueSchema = internal::Unique<struct ArrowSchema>#: 包装唯一 struct ArrowSchema 的类。

using UniqueArray = internal::Unique<struct ArrowArray>#: 包装唯一 struct ArrowArray 的类。

using UniqueArrayStream = internal::Unique<struct ArrowArrayStream>#: 包装唯一 struct ArrowArrayStream 的类。

using UniqueBuffer = internal::Unique<struct ArrowBuffer>#: 包装唯一 struct ArrowBuffer 的类。

using UniqueBitmap = internal::Unique<struct ArrowBitmap>#: 包装唯一 struct ArrowBitmap 的类。

using UniqueArrayView = internal::Unique<struct ArrowArrayView>#: 包装唯一 struct ArrowArrayView 的类。

数组流实用程序#

group nanoarrow_hpp-array-stream

这些类提供简单的 ArrowArrayStream 实现，可以扩展这些实现以帮助简化创建有效 ArrowArrayStream 实现的过程，或者按原样用于测试。

template<typename T> class ArrayStreamFactory#

#include <nanoarrow.hpp>

从标准 C++ 类导出 ArrowArrayStream。

此类允许通过将 C 回调调用映射到其生命周期由 ArrowArrayStream 拥有的对象的实例上的方法调用，将标准 C++ 类导出到通用 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() 的类

class EmptyArrayStream#

#include <nanoarrow.hpp>

一个空数组流。

此类可以从 struct ArrowSchema 构造，并实现一个默认的 get_next() 方法，该方法始终将输出 ArrowArray 标记为已释放。

已弃用 (0.4.0)：nanoarrow 的早期版本允许子类覆盖 get_schema()、get_next() 和 get_last_error()。此功能将在将来的版本中删除：使用 ArrayStreamFactory 中记录的模式创建自定义 ArrowArrayStream 实现。

class VectorArrayStream#: #include <nanoarrow.hpp>

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

缓冲区实用程序#

group nanoarrow_hpp-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) 设置缓冲区大小。这适用于 STL 容器，如 std::vector、std::array 和 std::string。此函数移动 obj 并确保在调用 ArrowBufferReset 时删除它。

范围 for 实用程序#

group nanoarrow_hpp-range_for

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

变量

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

template<typename T> class ViewArrayAs#

#include <nanoarrow.hpp>

一个与范围 for 兼容的固定大小类型 ArrowArray 包装器。

提供从包装数组的每个非空槽复制的 optional<T> 序列（空槽导致空可选）。

template<int OffsetSize> class ViewArrayAsBytes#

#include <nanoarrow.hpp>

用于二进制或 utf8 类型 ArrowArray 的 range-for 兼容包装器。

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

class ViewArrayAsFixedSizeBytes#

#include <nanoarrow.hpp>

用于固定大小二进制类型 ArrowArray 的 range-for 兼容包装器。

提供一系列 optional<ArrowStringView>，引用包装数组中每个非空槽（空槽将导致空 optional）。

class ViewArrayStream#

#include <nanoarrow.hpp>

用于 ArrowArrayStream 的 range-for 兼容包装器。

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