C API 参考#

group Nanoarrow C 库

除非另有说明，否则对象不是线程安全的，客户端应注意序列化对方法的访问。

因为该库旨在被集成（vendored），所以它提供了完整的类型定义，并鼓励客户端在方便时进行栈分配或静态分配。

创建 Schema#

group 创建 Schema

这些函数用于分配、复制和销毁 ArrowSchema 结构体。

函数

NANOARROW_DLL void ArrowSchemaInit (struct ArrowSchema *schema)

初始化一个 ArrowSchema。

初始化 schema_out 的字段和 release 回调。如果返回 NANOARROW_OK，调用者负责调用 schema->release 回调。

NANOARROW_DLL ArrowErrorCode ArrowSchemaInitFromType (struct ArrowSchema *schema, enum ArrowType type)

从一个 ArrowType 初始化 ArrowSchema。

一个方便的构造函数，用于在构建无参数类型这种常见情况下调用 ArrowSchemaInit() 和 ArrowSchemaSetType()。如果返回 NANOARROW_OK，调用者负责调用 schema->release 回调。

NANOARROW_DLL int64_t ArrowSchemaToString (const struct ArrowSchema *schema, char *out, int64_t n, char recursive)

获取 Schema 的人类可读摘要。

将 ArrowSchema 的摘要写入 out（最多 n - 1 个字符），并返回在 n 足够大时输出所需的字符数。如果 recursive 非零，则结果还将包括子级。

NANOARROW_DLL ArrowErrorCode ArrowSchemaSetType (struct ArrowSchema *schema, enum ArrowType type)

从 ArrowType 设置 schema 的 format 字段。

初始化 schema_out 的字段和 release 回调。对于 NANOARROW_TYPE_LIST、NANOARROW_TYPE_LARGE_LIST 和 NANOARROW_TYPE_MAP，会分配、初始化并命名适当数量的子级；但是，调用者必须在预初始化的子级上调用 ArrowSchemaSetType()。Schema 必须已经使用 ArrowSchemaInit() 或 ArrowSchemaDeepCopy() 进行初始化。

NANOARROW_DLL ArrowErrorCode ArrowSchemaSetTypeStruct (struct ArrowSchema *schema, int64_t n_children)

设置结构体 schema 的 format 字段并初始化其子级。

指定数量的子级会被初始化；但是，调用者负责在每个子级上调用 ArrowSchemaSetType() 和 ArrowSchemaSetName()。Schema 必须已经使用 ArrowSchemaInit() 或 ArrowSchemaDeepCopy() 进行初始化。

NANOARROW_DLL ArrowErrorCode ArrowSchemaSetTypeFixedSize (struct ArrowSchema *schema, enum ArrowType type, int32_t fixed_size)

设置固定大小 schema 的 format 字段。

如果 fixed_size <= 0 或 type 不是 NANOARROW_TYPE_FIXED_SIZE_BINARY 或 NANOARROW_TYPE_FIXED_SIZE_LIST，则返回 EINVAL。对于 NANOARROW_TYPE_FIXED_SIZE_LIST，会分配、初始化并命名适当数量的子级；但是，调用者必须在第一个子级上调用 ArrowSchemaSetType()。Schema 必须已经使用 ArrowSchemaInit() 或 ArrowSchemaDeepCopy() 进行初始化。

NANOARROW_DLL ArrowErrorCode ArrowSchemaSetTypeDecimal (struct ArrowSchema *schema, enum ArrowType type, int32_t decimal_precision, int32_t decimal_scale)

设置十进制（decimal） schema 的 format 字段。

如果 scale <= 0 或 type 不是 NANOARROW_TYPE_DECIMAL32、NANOARROW_TYPE_DECIMAL64、NANOARROW_TYPE_DECIMAL128 或 NANOARROW_TYPE_DECIMAL256，则返回 EINVAL。Schema 必须已经使用 ArrowSchemaInit() 或 ArrowSchemaDeepCopy() 进行初始化。

NANOARROW_DLL ArrowErrorCode ArrowSchemaSetTypeRunEndEncoded (struct ArrowSchema *schema, enum ArrowType run_end_type)

设置行程末端编码（run-end encoded）schema 的 format 字段。

如果 run_end_type 不是 NANOARROW_TYPE_INT16、NANOARROW_TYPE_INT32 或 NANOARROW_TYPE_INT64，则返回 EINVAL。Schema 必须已经使用 ArrowSchemaInit() 或 ArrowSchemaDeepCopy() 进行初始化。调用者必须调用 ArrowSchemaSetTypeXXX(schema->children[1]) 来设置值类型。请注意，当使用 ArrowArrayAppendXXX() 函数构建数组时，必须手动更新行程末端编码数组的逻辑长度。

NANOARROW_DLL ArrowErrorCode ArrowSchemaSetTypeDateTime (struct ArrowSchema *schema, enum ArrowType type, enum ArrowTimeUnit time_unit, const char *timezone)

设置时间、时间戳或时长 schema 的 format 字段。

如果 type 不是 NANOARROW_TYPE_TIME32、NANOARROW_TYPE_TIME64、NANOARROW_TYPE_TIMESTAMP 或 NANOARROW_TYPE_DURATION，则返回 EINVAL。对于非时间戳类型，timezone 参数必须为 NULL。Schema 必须已经使用 ArrowSchemaInit() 或 ArrowSchemaDeepCopy() 进行初始化。

NANOARROW_DLL ArrowErrorCode ArrowSchemaSetTypeUnion (struct ArrowSchema *schema, enum ArrowType type, int64_t n_children)

设置联合体（union） schema 的 format 字段。

如果 type 不是 NANOARROW_TYPE_DENSE_UNION 或 NANOARROW_TYPE_SPARSE_UNION，则返回 EINVAL。指定数量的子级会被分配和初始化。

NANOARROW_DLL ArrowErrorCode ArrowSchemaDeepCopy (const struct ArrowSchema *schema, struct ArrowSchema *schema_out)

对 schema 进行（递归）复制。

分配并将 schema 的字段复制到 schema_out 中。

NANOARROW_DLL ArrowErrorCode ArrowSchemaSetFormat (struct ArrowSchema *schema, const char *format)

将 format 复制到 schema->format 中。

schema 必须已经使用 ArrowSchemaInitFromType() 或 ArrowSchemaDeepCopy() 进行分配。

NANOARROW_DLL ArrowErrorCode ArrowSchemaSetName (struct ArrowSchema *schema, const char *name)

将 name 复制到 schema->name 中。

schema 必须已经使用 ArrowSchemaInitFromType() 或 ArrowSchemaDeepCopy() 进行分配。

NANOARROW_DLL ArrowErrorCode ArrowSchemaSetMetadata (struct ArrowSchema *schema, const char *metadata)

将元数据（metadata）复制到 schema->metadata 中。

schema 必须已经使用 ArrowSchemaInitFromType() 或 ArrowSchemaDeepCopy 进行分配。

NANOARROW_DLL ArrowErrorCode ArrowSchemaAllocateChildren (struct ArrowSchema *schema, int64_t n_children)

分配 schema->children 数组。

包括每个子 struct ArrowSchema 的内存。schema 必须已经使用 ArrowSchemaInitFromType() 或 ArrowSchemaDeepCopy() 进行分配。

NANOARROW_DLL ArrowErrorCode ArrowSchemaAllocateDictionary (struct ArrowSchema *schema)

分配 schema->dictionary 成员。

schema 必须已经使用 ArrowSchemaInitFromType() 或 ArrowSchemaDeepCopy() 进行分配。

读取 Schema#

group 读取 Schema

宏定义

NANOARROW_FLAG_ALL_SUPPORTED#: ArrowSchemaViewInit() 支持的标志。

函数

NANOARROW_DLL ArrowErrorCode ArrowSchemaViewInit (struct ArrowSchemaView *schema_view, const struct ArrowSchema *schema, struct ArrowError *error): 初始化一个 ArrowSchemaView。

struct ArrowSchemaView#

#include <nanoarrow.h>

已解析的 ArrowSchema 的一个非拥有视图。

与原始的 ArrowSchema 相比，包含更易于提取的值。客户端可以对该结构体进行栈分配或静态分配，但建议使用提供的 getters 以确保向前兼容性。

公共成员

const struct ArrowSchema *schema#: 一个指向此视图所表示的 schema 的指针。

enum ArrowType type#

schema 所表示的数据类型。

如果 schema 有一个非空的 dictionary 成员，该值可以是 NANOARROW_TYPE_DICTIONARY；日期时间类型是有效值。该值永远不会是 NANOARROW_TYPE_EXTENSION（请参阅 extension_name 和/或 extension_metadata 来检查扩展类型）。

enum ArrowType storage_type#

schema 所表示的存储数据类型。

该值永远不会是 NANOARROW_TYPE_DICTIONARY、NANOARROW_TYPE_EXTENSION 或任何日期时间类型。该值仅表示解释数组中缓冲区所需的类型。

struct ArrowLayout layout#: schema 所表示的存储布局。

struct ArrowStringView extension_name#

扩展类型名称，如果存在的话。

如果 schema.metadata 中存在 ARROW:extension:name 键，则 extension_name.data 将不为 NULL。

struct ArrowStringView extension_metadata#

扩展类型元数据，如果存在的话。

如果 schema.metadata 中存在 ARROW:extension:metadata 键，则 extension_metadata.data 将不为 NULL。

int32_t fixed_size#

格式化固定大小参数。

解析固定大小二进制或固定大小列表 schema 时会设置此值；对于其他类型，此值为未定义。对于固定大小二进制 schema，此值的单位是字节；对于固定大小列表 schema，此值指的是父级每个元素的子元素数量。

int32_t decimal_bitwidth#

十进制（Decimal）位宽。

解析十进制类型 schema 时会设置此值；对于其他类型，此值为未定义。

int32_t decimal_precision#

十进制（Decimal）精度。

解析十进制类型 schema 时会设置此值；对于其他类型，此值为未定义。

int32_t decimal_scale#

十进制（Decimal）小数位数。

解析十进制类型 schema 时会设置此值；对于其他类型，此值为未定义。

enum ArrowTimeUnit time_unit#

格式化时间单位参数。

解析日期/时间类型时会设置此值。对于其他类型，该值是未定义的。

const char *timezone#

格式化时区参数。

解析时间戳类型时会设置此值，并表示时区格式参数。此值指向 schema 内部的数据，对于其他类型是未定义的。

const char *union_type_ids#

联合体（Union）类型 ID 参数。

解析联合体类型时会设置此值，并表示类型 ID 参数。此值指向 schema 内部的数据，对于其他类型是未定义的。

创建数组#

group 创建数组

这些函数用于分配、复制和销毁 ArrowArray 结构体。一旦 ArrowArray 通过 ArrowArrayInitFromType() 或 ArrowArrayInitFromSchema() 初始化后，调用者有责任使用其内嵌的 release 回调来释放它。

枚举

enum ArrowValidationLevel#

验证级别枚举器。

值

enumerator NANOARROW_VALIDATION_LEVEL_NONE#: 不验证缓冲区大小或内容。

enumerator NANOARROW_VALIDATION_LEVEL_MINIMAL#: 验证依赖于数组长度的缓冲区大小，但不验证依赖于缓冲区数据访问的缓冲区大小。

enumerator NANOARROW_VALIDATION_LEVEL_DEFAULT#: 验证所有缓冲区大小，包括那些需要访问缓冲区数据的，但不执行任何在缓冲区长度上为 O(1) 的检查。

enumerator NANOARROW_VALIDATION_LEVEL_FULL#: 验证所有缓冲区大小和所有缓冲区内容。这在处理不受信任的输入或可能在传输中损坏的输入时非常有用。

函数

NANOARROW_DLL ArrowErrorCode ArrowArrayInitFromType (struct ArrowArray *array, enum ArrowType storage_type)

初始化数组的字段。

初始化 array 的字段和 release 回调。如果返回 NANOARROW_OK，调用者负责调用 array->release 回调。

NANOARROW_DLL ArrowErrorCode ArrowArrayInitFromSchema (struct ArrowArray *array, const struct ArrowSchema *schema, struct ArrowError *error)

从 ArrowSchema 初始化 ArrowArray 的内容。

如果返回 NANOARROW_OK，调用者负责调用 array->release 回调。

NANOARROW_DLL ArrowErrorCode ArrowArrayInitFromArrayView (struct ArrowArray *array, const struct ArrowArrayView *array_view, struct ArrowError *error)

从 ArrowArrayView 初始化 ArrowArray 的内容。

如果返回 NANOARROW_OK，调用者负责调用 array->release 回调。

NANOARROW_DLL ArrowErrorCode ArrowArrayAllocateChildren (struct ArrowArray *array, int64_t n_children)

分配 array->children 数组。

包括每个子 struct ArrowArray 的内存，其成员被标记为已释放，并可以随后用 ArrowArrayInitFromType() 初始化或从现有的 ArrowArray 移动而来。schema 必须已经使用 ArrowArrayInitFromType() 进行分配。

NANOARROW_DLL ArrowErrorCode ArrowArrayAllocateDictionary (struct ArrowArray *array)

分配 array->dictionary 成员。

包括 struct ArrowArray 的内存，其内容被标记为已释放，并可以随后用 ArrowArrayInitFromType() 初始化或从现有的 ArrowArray 移动而来。array 必须已经使用 ArrowArrayInitFromType() 进行分配。

NANOARROW_DLL void ArrowArraySetValidityBitmap (struct ArrowArray *array, struct ArrowBitmap *bitmap)

设置 ArrowArray 的有效性位图。

array 必须已经使用 ArrowArrayInitFromType() 进行分配。

NANOARROW_DLL ArrowErrorCode ArrowArraySetBuffer (struct ArrowArray *array, int64_t i, struct ArrowBuffer *buffer)

设置 ArrowArray 的一个缓冲区。

array 必须已经使用 ArrowArrayInitFromType() 进行分配。

static inline struct ArrowBitmap *ArrowArrayValidityBitmap(struct ArrowArray *array)#

获取 ArrowArray 的有效性位图。

array 必须已经使用 ArrowArrayInitFromType() 进行分配。

static inline struct ArrowBuffer *ArrowArrayBuffer(struct ArrowArray *array, int64_t i)#

获取 ArrowArray 的一个缓冲区。

array 必须已经使用 ArrowArrayInitFromType() 进行分配。

static inline ArrowErrorCode ArrowArrayStartAppending(struct ArrowArray *array)#

开始向 ArrowArray 逐元素追加。

初始化使用 ArrowArrayAppend*() 函数所需的任何值。所有逐元素追加器都按值追加，如果底层存储类型无法精确表示该值，则返回 EINVAL。array 必须已经使用 ArrowArrayInitFromType() 进行分配。

NANOARROW_DLL ArrowErrorCode ArrowArrayReserve (struct ArrowArray *array, int64_t additional_size_elements)

为未来的追加操作预留空间。

对于可以计算的缓冲区大小（即，非字符串数据缓冲区或非固定大小数组的子数组大小），递归地为额外的元素预留空间。这对于减少使用逐项追加器时发生的重分配次数很有用。

static inline ArrowErrorCode ArrowArrayAppendNull(struct ArrowArray *array, int64_t n)#: 向数组追加一个空值。

static inline ArrowErrorCode ArrowArrayAppendEmpty(struct ArrowArray *array, int64_t n)#: 向数组追加一个空的、非空值。

static inline ArrowErrorCode ArrowArrayAppendInt(struct ArrowArray *array, int64_t value)#

向数组追加一个有符号整数值。

如果 value 可以被底层存储类型精确表示，则返回 NANOARROW_OK；否则返回 EINVAL（例如，value 超出数组的有效范围）。

static inline ArrowErrorCode ArrowArrayAppendUInt(struct ArrowArray *array, uint64_t value)#

向数组追加一个无符号整数值。

如果 value 可以被底层存储类型精确表示，则返回 NANOARROW_OK；否则返回 EINVAL（例如，value 超出数组的有效范围）。

static inline ArrowErrorCode ArrowArrayAppendDouble(struct ArrowArray *array, double value)#

向数组追加一个双精度浮点数值。

如果 value 可以被底层存储类型精确表示，则返回 NANOARROW_OK；否则返回 EINVAL（例如，value 超出数组的有效范围，或试图向具有整数存储类型的数组追加非整数值）。

static inline ArrowErrorCode ArrowArrayAppendBytes(struct ArrowArray *array, struct ArrowBufferView value)#

向数组追加一个字节串。

如果 value 可以被底层存储类型精确表示，则返回 NANOARROW_OK；如果追加 value 会导致偏移类型溢出（例如，对于非大字符串类型，数据缓冲区将大于 2 GB），则返回 EOVERFLOW；否则返回 EINVAL（例如，底层数组不是二进制、字符串、大二进制、大字符串或固定大小二进制数组，或者 value 的大小对于固定大小二进制数组不正确）。

static inline ArrowErrorCode ArrowArrayAppendString(struct ArrowArray *array, struct ArrowStringView value)#

向数组追加一个字符串值。

如果 value 可以被底层存储类型精确表示，则返回 NANOARROW_OK；如果追加 value 会导致偏移类型溢出（例如，对于非大字符串类型，数据缓冲区将大于 2 GB），则返回 EOVERFLOW；否则返回 EINVAL（例如，底层数组不是字符串或大字符串数组）。

static inline ArrowErrorCode ArrowArrayAppendInterval(struct ArrowArray *array, const struct ArrowInterval *value)#

向数组追加一个 Interval（区间）。

如果 value 可以被底层存储类型精确表示，则返回 NANOARROW_OK；否则返回 EINVAL。

static inline ArrowErrorCode ArrowArrayAppendDecimal(struct ArrowArray *array, const struct ArrowDecimal *value)#

向数组追加一个十进制（decimal）值。

如果 array 是具有适当位宽的十进制数组，则返回 NANOARROW_OK；否则返回 EINVAL。

static inline ArrowErrorCode ArrowArrayFinishElement(struct ArrowArray *array)#

完成一个嵌套数组元素。

根据第一个子级的当前长度，向数组追加一个非空元素。如果项成功添加，则返回 NANOARROW_OK；如果列表或映射数组的子级将超过 INT_MAX 个元素，则返回 EOVERFLOW；如果底层存储类型不是结构体、列表、大列表或固定大小列表，或者尝试添加的结构体或固定大小列表元素的子数组长度与预期长度不匹配，则返回 EINVAL。

static inline ArrowErrorCode ArrowArrayFinishUnionElement(struct ArrowArray *array, int8_t type_id)#

完成一个联合体（union）数组元素。

向联合体类型 ID 缓冲区追加一个元素，并递增 array->length。对于稀疏联合体，最多向非类型 ID 子级添加一个元素。如果底层存储类型不是联合体，如果 type_id 无效，或者如果追加后的子级大小不一致，则返回 EINVAL。

static inline ArrowErrorCode ArrowArrayShrinkToFit(struct ArrowArray *array)#

将缓冲区容量缩减至所需大小。

此操作也适用于任何子数组。array 必须已使用 ArrowArrayInitFromType 进行分配。

NANOARROW_DLL ArrowErrorCode ArrowArrayFinishBuildingDefault (struct ArrowArray *array, struct ArrowError *error)

完成 ArrowArray 的构建。

将可能已重新分配的内部缓冲区中的任何指针刷新到 array->buffers 中，并根据最终长度检查缓冲区的实际大小与预期大小是否一致。array 必须已使用 ArrowArrayInitFromType() 进行分配。

NANOARROW_DLL ArrowErrorCode ArrowArrayFinishBuilding (struct ArrowArray *array, enum ArrowValidationLevel validation_level, struct ArrowError *error)

使用显式验证完成 ArrowArray 的构建。

使用显式验证级别完成构建。如果无法访问 CPU 缓冲区数据，可以执行较少的验证（即 NANOARROW_VALIDATION_LEVEL_NONE 或 NANOARROW_VALIDATION_LEVEL_MINIMAL）；如果缓冲区内容来自不受信任或可能损坏的来源，则可以执行更多的验证（即 NANOARROW_VALIDATION_LEVEL_FULL）。

读取数组#

group 读取数组

这些函数用于读取和验证 ArrowArray 结构体的内容。

宏定义

NANOARROW_MAX_FIXED_BUFFERS#: ArrowArrayView 或 ArrowLayout 中固定缓冲区的最大数量。

枚举

enum ArrowBufferType#

Arrow 列式规范中描述的缓冲区功能类型。

值

enumerator NANOARROW_BUFFER_TYPE_NONE#

enumerator NANOARROW_BUFFER_TYPE_VALIDITY#

enumerator NANOARROW_BUFFER_TYPE_TYPE_ID#

enumerator NANOARROW_BUFFER_TYPE_UNION_OFFSET#

enumerator NANOARROW_BUFFER_TYPE_DATA_OFFSET#

enumerator NANOARROW_BUFFER_TYPE_DATA#

enumerator NANOARROW_BUFFER_TYPE_VARIADIC_DATA#

enumerator NANOARROW_BUFFER_TYPE_VARIADIC_SIZE#

enumerator NANOARROW_BUFFER_TYPE_VIEW_OFFSET#

enumerator NANOARROW_BUFFER_TYPE_SIZE#

函数

NANOARROW_DLL void ArrowArrayViewInitFromType (struct ArrowArrayView *array_view, enum ArrowType storage_type): 初始化 ArrowArrayView 的内容。

static inline void ArrowArrayViewMove(struct ArrowArrayView *src, struct ArrowArrayView *dst)#

移动 ArrowArrayView。

将 ArrowArrayView 的数据和生命周期管理转移到另一个地址，并重置 src 的内容。

NANOARROW_DLL ArrowErrorCode ArrowArrayViewInitFromSchema (struct ArrowArrayView *array_view, const struct ArrowSchema *schema, struct ArrowError *error): 从 ArrowSchema 初始化 ArrowArrayView 的内容。

NANOARROW_DLL ArrowErrorCode ArrowArrayViewAllocateChildren (struct ArrowArrayView *array_view, int64_t n_children)

分配 array_view->children 数组。

包括每个子 struct ArrowArrayView 的内存。

NANOARROW_DLL ArrowErrorCode ArrowArrayViewAllocateDictionary (struct ArrowArrayView *array_view): 分配 array_view->dictionary。

NANOARROW_DLL void ArrowArrayViewSetLength (struct ArrowArrayView *array_view, int64_t length): 根据长度设置与数据无关的缓冲区大小。

NANOARROW_DLL ArrowErrorCode ArrowArrayViewSetArray (struct ArrowArrayView *array_view, const struct ArrowArray *array, struct ArrowError *error): 从 ArrowArray 中设置缓冲区大小和数据指针。

NANOARROW_DLL ArrowErrorCode ArrowArrayViewSetArrayMinimal (struct ArrowArrayView *array_view, const struct ArrowArray *array, struct ArrowError *error): 从 ArrowArray 中设置缓冲区大小和数据指针，但不包括那些需要解引用缓冲区内容的部分。

static inline int64_t ArrowArrayViewGetNumBuffers(struct ArrowArrayView *array_view)#

获取缓冲区的数量。

此 ArrowArrayView 引用的缓冲区数量。在许多情况下，这也可以从 ArrowArrayView 或 ArrowSchemaView 的 ArrowLayout 成员计算得出；然而，对于二进制视图和字符串视图类型，总缓冲区数量取决于可变参数缓冲区的数量。

static inline struct ArrowBufferView ArrowArrayViewGetBufferView(struct ArrowArrayView *array_view, int64_t i)#

从 ArrowArrayView 获取特定缓冲区的视图。

这是 ArrowArrayView 中与 ArrowArray::buffers[i] 等效的部分，包含了大小信息（如果已知）。

static inline enum ArrowBufferType ArrowArrayViewGetBufferType(struct ArrowArrayView *array_view, int64_t i)#

获取 ArrowArrayView 中特定缓冲区的功能。

在许多情况下，这也可以从 ArrowArrayView 或 ArrowSchemaView 的 ArrowLayout 成员获取；然而，对于二进制视图和字符串视图类型，每个缓冲区的功能在两个相同类型的数组之间可能会有所不同，具体取决于可变参数缓冲区的数量。

static inline enum ArrowType ArrowArrayViewGetBufferDataType(struct ArrowArrayView *array_view, int64_t i)#

获取 ArrowArrayView 中特定缓冲区的数据类型。

在许多情况下，这也可以从 ArrowArrayView 或 ArrowSchemaView 的 ArrowLayout 成员获取；然而，对于二进制视图和字符串视图类型，每个缓冲区的数据类型在两个相同类型的数组之间可能会有所不同，具体取决于可变参数缓冲区的数量。

static inline int64_t ArrowArrayViewGetBufferElementSizeBits(struct ArrowArrayView *array_view, int64_t i)#

获取 ArrowArrayView 中特定缓冲区的元素大小（以位为单位）。

在许多情况下，这也可以从 ArrowArrayView 或 ArrowSchemaView 的 ArrowLayout 成员获取；然而，对于二进制视图和字符串视图类型，每个缓冲区的元素宽度在两个相同类型的数组之间可能会有所不同，具体取决于可变参数缓冲区的数量。

NANOARROW_DLL ArrowErrorCode ArrowArrayViewValidate (struct ArrowArrayView *array_view, enum ArrowValidationLevel validation_level, struct ArrowError *error)

对 ArrowArrayView 的内容执行检查。

如果使用 ArrowArrayViewSetArray() 将 array_view 与 ArrowArray 关联，则缓冲区大小和某些内容（第一个和最后一个偏移量）已在“默认”级别进行了验证。如果以其他方式设置缓冲区指针和大小，您可能希望在不同级别执行检查。有关每个级别执行的检查的详细信息，请参阅 ArrowValidationLevel 的文档。

NANOARROW_DLL ArrowErrorCode ArrowArrayViewCompare (const struct ArrowArrayView *actual, const struct ArrowArrayView *expected, enum ArrowCompareLevel level, int *out, struct ArrowError *reason)

比较两个 ArrowArrayView 对象是否相等。

给定两个 ArrowArrayView 实例，将 0（不相等）或 1（相等）放置在 out 指向的地址。如果比较确定 actual 和 expected 不相等，将通过 error（如果 error 非空）传达原因。

如果比较成功完成，则返回 NANOARROW_OK。

NANOARROW_DLL void ArrowArrayViewReset (struct ArrowArrayView *array_view): 重置 ArrowArrayView 的内容并释放资源。

static inline int8_t ArrowArrayViewIsNull(const struct ArrowArrayView *array_view, int64_t i)#: 检查 ArrowArrayView 中的空元素。

static inline int64_t ArrowArrayViewComputeNullCount(const struct ArrowArrayView *array_view)#: 计算 ArrowArrayView 的空值计数。

static inline int8_t ArrowArrayViewUnionTypeId(const struct ArrowArrayView *array_view, int64_t i)#: 获取联合体数组成员的类型 ID。

static inline int8_t ArrowArrayViewUnionChildIndex(const struct ArrowArrayView *array_view, int64_t i)#: 获取联合体数组成员的子索引。

static inline int64_t ArrowArrayViewUnionChildOffset(const struct ArrowArrayView *array_view, int64_t i)#: 获取要在相关联合体子数组中使用的索引。

static inline int64_t ArrowArrayViewGetIntUnsafe(const struct ArrowArrayView *array_view, int64_t i)#

将 ArrowArrayView 中的一个元素作为整数获取。

此函数不检查空值、值是否确实是整数，或者值是否在 int64 的有效范围内。

static inline uint64_t ArrowArrayViewGetUIntUnsafe(const struct ArrowArrayView *array_view, int64_t i)#

将 ArrowArrayView 中的一个元素作为无符号整数获取。

此函数不检查空值、值是否确实是整数，或者值是否在 uint64 的有效范围内。

static inline double ArrowArrayViewGetDoubleUnsafe(const struct ArrowArrayView *array_view, int64_t i)#

将 ArrowArrayView 中的一个元素作为 double 获取。

此函数不检查空值，或者值是否在 double 的有效范围内。

static inline struct ArrowStringView ArrowArrayViewGetStringUnsafe(const struct ArrowArrayView *array_view, int64_t i)#

将 ArrowArrayView 中的一个元素作为 ArrowStringView 获取。

此函数不检查空值。

static inline struct ArrowBufferView ArrowArrayViewGetBytesUnsafe(const struct ArrowArrayView *array_view, int64_t i)#

将 ArrowArrayView 中的一个元素作为 ArrowBufferView 获取。

此函数不检查空值。

static inline void ArrowArrayViewGetDecimalUnsafe(const struct ArrowArrayView *array_view, int64_t i, struct ArrowDecimal *out)#

将 ArrowArrayView 中的一个元素作为 ArrowDecimal 获取。

此函数不检查空值。在首次调用此函数之前，必须使用适合此类型的参数通过 ArrowDecimalInit() 初始化 out 参数。

struct ArrowArrayView#

#include <inline_types.h>

一个 ArrowArray 的非所有权视图。

此数据结构提供了对 ArrowArray 中包含的值的访问，其字段以更易于提取的形式提供。您可以为一个具有相同存储类型的多个 ArrowArray 重用一个 ArrowArrayView，用它来表示一个尚不存在的假设的 ArrowArray，或者用它来验证未来 ArrowArray 的缓冲区。

公共成员

const struct ArrowArray *array#: 底层的 ArrowArray，如果尚未设置，或者此 ArrowArrayView 中的缓冲区不是由 ArrowArray 支持的，则为 NULL。

int64_t offset#: 从缓冲区的物理起始位置开始的元素数量。

int64_t length#: 此视图中的元素数量。

int64_t null_count#: 缓存的空值计数，如果此值未知，则为 -1。

enum ArrowType storage_type#

用于在此数组中存储值的类型。

此类型仅表示从数组缓冲区中提取值所需的最小信息（例如，对于 Date32 数组，此值为 NANOARROW_TYPE_INT32）。对于字典编码的数组，这将是索引类型。

struct ArrowLayout layout#: 此数组缓冲区的缓冲区类型、步长和大小。

struct ArrowBufferView buffer_views[NANOARROW_MAX_FIXED_BUFFERS]#: 此数组的缓冲区，作为 ArrowBufferView 对象。

int64_t n_children#: 此视图的子视图数量。

struct ArrowArrayView **children#: 指向此数组子视图的指针。

struct ArrowArrayView *dictionary#: 指向此数组字典视图的指针。

int8_t *union_type_id_map#

联合体类型 ID 到子索引的映射。

如果 storage_type 是联合体类型，则为一个 256 字节的 ArrowMalloc() 分配的缓冲区，使得 child_index == union_type_id_map[type_id] 并且 type_id == union_type_id_map[128 + child_index]。在 child_id == type_id 的情况下，此值可能为 NULL。

int32_t n_variadic_buffers#: 可变参数缓冲区的数量。

const void **variadic_buffers#: 指向二进制/字符串视图数组的可变参数缓冲区的指针。

int64_t *variadic_buffer_sizes#: 每个可变参数缓冲区的大小。

拥有所有权的可增长缓冲区#

group Owning, growable buffers

函数

static inline void ArrowBufferInit(struct ArrowBuffer *buffer)#

初始化一个 ArrowBuffer。

使用默认的缓冲区分配器，初始化一个具有 NULL、零大小缓冲区的缓冲区。

static inline ArrowErrorCode ArrowBufferSetAllocator(struct ArrowBuffer *buffer, struct ArrowBufferAllocator allocator)#

为一个新初始化的缓冲区设置分配器。

如果缓冲区已被分配，则返回 EINVAL。

static inline void ArrowBufferReset(struct ArrowBuffer *buffer)#

重置一个 ArrowBuffer。

如果缓冲区的 data 成员不为 null，则使用分配器的 free 方法释放缓冲区，将 data 成员设置为 NULL，并将缓冲区的大小和容量设置为 0。

static inline void ArrowBufferMove(struct ArrowBuffer *src, struct ArrowBuffer *dst)#

移动一个 ArrowBuffer。

将缓冲区数据和生命周期管理转移到另一个地址并重置缓冲区。

static inline ArrowErrorCode ArrowBufferResize(struct ArrowBuffer *buffer, int64_t new_size_bytes, char shrink_to_fit)#

将缓冲区增长或缩小到给定大小。

当缩小缓冲区大小时，仅当 shrink_to_fit 非零时才重新分配缓冲区。

static inline ArrowErrorCode ArrowBufferReserve(struct ArrowBuffer *buffer, int64_t additional_size_bytes)#

确保缓冲区至少具有给定的额外容量。

确保缓冲区有空间追加至少 additional_size_bytes 的数据，并在需要时进行超额分配。

static inline void ArrowBufferAppendUnsafe(struct ArrowBuffer *buffer, const void *data, int64_t size_bytes)#

将数据写入缓冲区并增加缓冲区大小。

此函数不检查缓冲区是否具有所需容量。

static inline ArrowErrorCode ArrowBufferAppend(struct ArrowBuffer *buffer, const void *data, int64_t size_bytes)#

将数据写入缓冲区并增加缓冲区大小。

此函数写入数据并确保缓冲区具有所需容量，可能通过重新分配缓冲区来实现。与 ArrowBufferReserve 类似，当需要重新分配时，此函数会进行超额分配。

static inline ArrowErrorCode ArrowBufferAppendFill(struct ArrowBuffer *buffer, uint8_t value, int64_t size_bytes)#

将填充数据写入缓冲区并增加缓冲区大小。

此函数写入指定数量的填充字节，并确保缓冲区具有所需容量。

static inline ArrowErrorCode ArrowBufferAppendInt8(struct ArrowBuffer *buffer, int8_t value)#: 向缓冲区写入一个 8 位整数。

static inline ArrowErrorCode ArrowBufferAppendUInt8(struct ArrowBuffer *buffer, uint8_t value)#: 向缓冲区写入一个无符号 8 位整数。

static inline ArrowErrorCode ArrowBufferAppendInt16(struct ArrowBuffer *buffer, int16_t value)#: 向缓冲区写入一个 16 位整数。

static inline ArrowErrorCode ArrowBufferAppendUInt16(struct ArrowBuffer *buffer, uint16_t value)#: 向缓冲区写入一个无符号 16 位整数。

static inline ArrowErrorCode ArrowBufferAppendInt32(struct ArrowBuffer *buffer, int32_t value)#: 向缓冲区写入一个 32 位整数。

static inline ArrowErrorCode ArrowBufferAppendUInt32(struct ArrowBuffer *buffer, uint32_t value)#: 向缓冲区写入一个无符号 32 位整数。

static inline ArrowErrorCode ArrowBufferAppendInt64(struct ArrowBuffer *buffer, int64_t value)#: 向缓冲区写入一个 64 位整数。

static inline ArrowErrorCode ArrowBufferAppendUInt64(struct ArrowBuffer *buffer, uint64_t value)#: 向缓冲区写入一个无符号 64 位整数。

static inline ArrowErrorCode ArrowBufferAppendDouble(struct ArrowBuffer *buffer, double value)#: 向缓冲区写入一个 double。

static inline ArrowErrorCode ArrowBufferAppendFloat(struct ArrowBuffer *buffer, float value)#: 向缓冲区写入一个 float。

static inline ArrowErrorCode ArrowBufferAppendStringView(struct ArrowBuffer *buffer, struct ArrowStringView value)#: 向缓冲区写入一个 ArrowStringView。

static inline ArrowErrorCode ArrowBufferAppendBufferView(struct ArrowBuffer *buffer, struct ArrowBufferView value)#: 向缓冲区写入一个 ArrowBufferView。

struct ArrowBufferAllocator#

#include <inline_types.h>

数组缓冲区的分配和释放。

包含 allocate、reallocate 和 free 方法的容器，可用于在构造 ArrowArray 时自定义缓冲区的分配和释放。

公共成员

uint8_t *(*reallocate)(struct ArrowBufferAllocator *allocator, uint8_t *ptr, int64_t old_size, int64_t new_size)#: 重新分配缓冲区，如果无法重新分配，则返回 NULL。

void (*free)(struct ArrowBufferAllocator *allocator, uint8_t *ptr, int64_t size)#: 释放由此分配器分配的缓冲区。

void *private_data#: 分配器特定的不透明数据。

struct ArrowBuffer#

#include <inline_types.h>

缓冲区的拥有所有权的可变视图。

公共成员

uint8_t *data#

指向缓冲区起始位置的指针。

如果 capacity_bytes 为 0，此值可能为 NULL。

int64_t size_bytes#: 缓冲区的大小（以字节为单位）。

int64_t capacity_bytes#: 缓冲区的容量（以字节为单位）。

struct ArrowBufferAllocator allocator#: 将用于重新分配和/或释放缓冲区的分配器。

位图工具#

group Bitmap utilities

函数

static inline int8_t ArrowBitGet(const uint8_t *bits, int64_t i)#: 从位图中提取一个布尔值。

static inline void ArrowBitSet(uint8_t *bits, int64_t i)#: 将位图中的一个布尔值设置为 true。

static inline void ArrowBitClear(uint8_t *bits, int64_t i)#: 将位图中的一个布尔值设置为 false。

static inline void ArrowBitSetTo(uint8_t *bits, int64_t i, uint8_t value)#: 将位图中的一个布尔值设置为指定值。

static inline void ArrowBitsSetTo(uint8_t *bits, int64_t start_offset, int64_t length, uint8_t bits_are_set)#: 将位图中的一个范围设置为指定的布尔值。

static inline int64_t ArrowBitCountSet(const uint8_t *bits, int64_t i_from, int64_t i_to)#: 计算位图中 true 值的数量。

static inline void ArrowBitsUnpackInt8(const uint8_t *bits, int64_t start_offset, int64_t length, int8_t *out)#: 从位图中的一个范围提取 int8 类型的布尔值。

static inline void ArrowBitsUnpackInt32(const uint8_t *bits, int64_t start_offset, int64_t length, int32_t *out)#: 从位图中的一个范围提取 int32 布尔值。

static inline void ArrowBitmapInit(struct ArrowBitmap *bitmap)#

初始化一个 ArrowBitmap。

初始化构建器的缓冲区，清空其缓存，并将大小重置为零。

static inline void ArrowBitmapMove(struct ArrowBitmap *src, struct ArrowBitmap *dst)#

移动一个 ArrowBitmap。

将底层的缓冲区数据和生命周期管理转移到另一个地址，并重置位图。

static inline ArrowErrorCode ArrowBitmapReserve(struct ArrowBitmap *bitmap, int64_t additional_size_bits)#

确保位图构建器至少具有给定的额外容量。

确保缓冲区有足够的空间来附加至少 additional_size_bits 的数据，并在需要时进行超额分配。

static inline ArrowErrorCode ArrowBitmapResize(struct ArrowBitmap *bitmap, int64_t new_size_bits, char shrink_to_fit)#

将位图扩大或缩小到给定的大小。

当缩小位图大小时，仅当 shrink_to_fit 非零时，才会重新分配位图。

static inline ArrowErrorCode ArrowBitmapAppend(struct ArrowBitmap *bitmap, uint8_t bits_are_set, int64_t length)#: 为一个位图保留空间并附加零个或多个相同的布尔值。

static inline void ArrowBitmapAppendUnsafe(struct ArrowBitmap *bitmap, uint8_t bits_are_set, int64_t length)#: 向位图附加零个或多个相同的布尔值。

static inline void ArrowBitmapAppendInt8Unsafe(struct ArrowBitmap *bitmap, const int8_t *values, int64_t n_values)#

将编码为 int8_t 的布尔值附加到_位图中。

这些值必须全部为 0 或 1。

static inline void ArrowBitmapAppendInt32Unsafe(struct ArrowBitmap *bitmap, const int32_t *values, int64_t n_values)#

将编码为 int32_t 的布尔值附加到_位图中。

这些值必须全部为 0 或 1。

static inline void ArrowBitmapReset(struct ArrowBitmap *bitmap)#

重置位图构建器。

释放缓冲区持有的任何内存，清空缓存，并将大小重置为零。

struct ArrowBitmap#

#include <inline_types.h>

一个位图的自有可变视图。

公共成员

struct ArrowBuffer buffer#: 一个用于保存已分配内存的 ArrowBuffer。

int64_t size_bits#: 已附加到该位图的位数。

创建、读取和修改模式元数据#

group 创建、读取和修改模式元数据

函数

NANOARROW_DLL ArrowErrorCode ArrowMetadataReaderInit (struct ArrowMetadataReader *reader, const char *metadata): 初始化一个 ArrowMetadataReader。

NANOARROW_DLL ArrowErrorCode ArrowMetadataReaderRead (struct ArrowMetadataReader *reader, struct ArrowStringView *key_out, struct ArrowStringView *value_out): 从 ArrowMetadataReader 中读取下一个键/值对。

NANOARROW_DLL int64_t ArrowMetadataSizeOf (const char *metadata): 键/值元数据字符串中的字节数。

NANOARROW_DLL char ArrowMetadataHasKey (const char *metadata, struct ArrowStringView key): 检查模式元数据中是否存在某个键。

NANOARROW_DLL ArrowErrorCode ArrowMetadataGetValue (const char *metadata, struct ArrowStringView key, struct ArrowStringView *value_out)

从模式元数据中提取一个值。

如果键在元数据中不存在，则 value_out 不会被修改。

NANOARROW_DLL ArrowErrorCode ArrowMetadataBuilderInit (struct ArrowBuffer *buffer, const char *metadata)

根据键/值对初始化模式元数据的构建器。

metadata 可以是现有的元数据字符串，也可以是 NULL 以初始化一个空的元数据字符串。

NANOARROW_DLL ArrowErrorCode ArrowMetadataBuilderAppend (struct ArrowBuffer *buffer, struct ArrowStringView key, struct ArrowStringView value): 向包含序列化元数据的缓冲区追加一个键/值对。

NANOARROW_DLL ArrowErrorCode ArrowMetadataBuilderSet (struct ArrowBuffer *buffer, struct ArrowStringView key, struct ArrowStringView value)

向包含序列化元数据的缓冲区设置一个键/值对。

确保元数据中键的唯一条目被设置为 value。如果键存在于数据中，此函数将保留该键（第一个实例）的现有位置。

NANOARROW_DLL ArrowErrorCode ArrowMetadataBuilderRemove (struct ArrowBuffer *buffer, struct ArrowStringView key): 从包含序列化元数据的缓冲区中删除一个键。

struct ArrowMetadataReader#

#include <nanoarrow.h>

用于读取模式元数据中键/值对的读取器。

ArrowMetadataReader 不拥有任何数据，并且仅在底层元数据指针的生命周期内有效。

公共成员

const char *metadata#: 来自 schema->metadata 字段的元数据字符串。

int64_t offset#: 在元数据字符串中的当前偏移量。

int32_t remaining_keys#: 剩余键的数量。

内存管理#

group 内存管理

对于在此处分配的模式和数组，struct ArrowSchema 和 struct ArrowArray 的非缓冲区成员必须使用 ArrowMalloc() 或 ArrowRealloc() 进行分配，并使用 ArrowFree() 进行释放。缓冲区成员使用 ArrowBufferAllocator 进行分配。

函数

NANOARROW_DLL void * ArrowMalloc (int64_t size): 类似于 malloc() 进行分配。

NANOARROW_DLL void * ArrowRealloc (void *ptr, int64_t size): 类似于 realloc() 进行重新分配。

NANOARROW_DLL void ArrowFree (void *ptr): 释放使用 ArrowMalloc() 或 ArrowRealloc() 分配的指针。

NANOARROW_DLL struct ArrowBufferAllocator ArrowBufferAllocatorDefault (void)

返回默认的分配器。

默认分配器使用 ArrowMalloc()、ArrowRealloc() 和 ArrowFree()。

NANOARROW_DLL struct ArrowBufferAllocator ArrowBufferDeallocator (ArrowBufferDeallocatorCallback, void *private_data)

创建一个自定义的释放器。

创建一个只带有释放方法的缓冲区分配器，可用于将自定义的释放器附加到 ArrowBuffer 上。这可以用来避免复制那些不是使用此处提供的基础设施分配的现有缓冲区（例如，由 R 或 Python 对象分配的）。

错误处理#

group 错误处理

函数通常返回一个与 errno 兼容的错误代码；需要传达更详细错误信息的函数接受一个指向 ArrowError 的指针。这可以是堆栈分配或静态分配的。除非已返回错误代码，否则消息的内容是未定义的。如果一个 nanoarrow 函数被传递一个非空的 ArrowError 指针，该参数指向的 ArrowError 将会带有一个以 null 结尾的错误消息进行传播。在 nanoarrow API 的任何地方传递一个 NULL ArrowError 都是安全的。

除非另有说明，否则在函数返回非零 ArrowErrorCode 后继续执行通常是不安全的。NANOARROW_RETURN_NOT_OK 和 NANOARROW_ASSERT_OK 宏用于帮助传播错误。C++ 客户端可以使用 nanoarrow.hpp 头文件中提供的帮助程序，以方便使用 C++ 的内存管理和错误传播习惯用法。

宏定义

NANOARROW_OK#: 表示成功的返回码。

NANOARROW_RETURN_NOT_OK(EXPR)#: 检查表达式的结果，如果不是 NANOARROW_OK，则返回该结果。

NANOARROW_RETURN_NOT_OK_WITH_ERROR(EXPR, ERROR_EXPR)#

检查表达式的结果，如果不是 NANOARROW_OK，则返回它，并向 ArrowError 添加一条自动生成的消息。

此宏用于确保接受 ArrowError 作为输入的函数在返回错误代码时总是设置其消息（例如，当调用一个不接受 ArrowError 的 nanoarrow 函数时）。

类型定义

typedef int ArrowErrorCode#: 表示一个与 errno 兼容的错误代码。

函数

static inline void ArrowErrorInit(struct ArrowError *error)#

通过将第一个字符置零来确保 ArrowError 以 null 结尾。

如果 error 为 NULL，此函数不执行任何操作。

static inline const char *ArrowErrorMessage(struct ArrowError *error)#

获取错误的内容。

如果 error 为 NULL，则返回 ""，否则返回错误消息的内容。

static inline void ArrowErrorSetString(struct ArrowError *error, const char *src)#

从一个现有的以 null 结尾的字符串设置错误的内容。

如果 error 为 NULL，此函数不执行任何操作。

NANOARROW_DLL NANOARROW_CHECK_PRINTF_ATTRIBUTE int ArrowErrorSet (struct ArrowError *error, const char *fmt,...)

使用 printf 语法设置错误的内容。

如果 error 为 NULL，此函数不执行任何操作并返回 NANOARROW_OK。

struct ArrowError#

#include <inline_types.h>

包含 UTF-8 编码消息的错误类型。

公共成员

char message[1024]#: 一个有空间存放错误消息的字符缓冲区。

实用数据结构#

group 实用数据结构

枚举

enum ArrowType#

Arrow 类型枚举器。

这些名称旨在映射到相应的 arrow::Type::type 枚举器；但是，数值明确不相等（即，不要依赖数值比较）。

值

enumerator NANOARROW_TYPE_UNINITIALIZED#

enumerator NANOARROW_TYPE_NA#

enumerator NANOARROW_TYPE_BOOL#

enumerator NANOARROW_TYPE_UINT8#

enumerator NANOARROW_TYPE_INT8#

enumerator NANOARROW_TYPE_UINT16#

enumerator NANOARROW_TYPE_INT16#

enumerator NANOARROW_TYPE_UINT32#

enumerator NANOARROW_TYPE_INT32#

enumerator NANOARROW_TYPE_UINT64#

enumerator NANOARROW_TYPE_INT64#

enumerator NANOARROW_TYPE_HALF_FLOAT#

enumerator NANOARROW_TYPE_FLOAT#

enumerator NANOARROW_TYPE_DOUBLE#

enumerator NANOARROW_TYPE_STRING#

enumerator NANOARROW_TYPE_BINARY#

enumerator NANOARROW_TYPE_FIXED_SIZE_BINARY#

enumerator NANOARROW_TYPE_DATE32#

enumerator NANOARROW_TYPE_DATE64#

enumerator NANOARROW_TYPE_TIMESTAMP#

enumerator NANOARROW_TYPE_TIME32#

enumerator NANOARROW_TYPE_TIME64#

enumerator NANOARROW_TYPE_INTERVAL_MONTHS#

enumerator NANOARROW_TYPE_INTERVAL_DAY_TIME#

enumerator NANOARROW_TYPE_DECIMAL128#

enumerator NANOARROW_TYPE_DECIMAL256#

enumerator NANOARROW_TYPE_LIST#

enumerator NANOARROW_TYPE_STRUCT#

enumerator NANOARROW_TYPE_SPARSE_UNION#

enumerator NANOARROW_TYPE_DENSE_UNION#

enumerator NANOARROW_TYPE_DICTIONARY#

enumerator NANOARROW_TYPE_MAP#

enumerator NANOARROW_TYPE_EXTENSION#

enumerator NANOARROW_TYPE_FIXED_SIZE_LIST#

enumerator NANOARROW_TYPE_DURATION#

enumerator NANOARROW_TYPE_LARGE_STRING#

enumerator NANOARROW_TYPE_LARGE_BINARY#

enumerator NANOARROW_TYPE_LARGE_LIST#

enumerator NANOARROW_TYPE_INTERVAL_MONTH_DAY_NANO#

enumerator NANOARROW_TYPE_RUN_END_ENCODED#

enumerator NANOARROW_TYPE_BINARY_VIEW#

enumerator NANOARROW_TYPE_STRING_VIEW#

enumerator NANOARROW_TYPE_DECIMAL32#

enumerator NANOARROW_TYPE_DECIMAL64#

enumerator NANOARROW_TYPE_LIST_VIEW#

enumerator NANOARROW_TYPE_LARGE_LIST_VIEW#

enum ArrowTimeUnit#

Arrow 时间单位枚举器。

这些名称和值映射到相应的 arrow::TimeUnit::type 枚举器。

值

enumerator NANOARROW_TIME_UNIT_SECOND#

enumerator NANOARROW_TIME_UNIT_MILLI#

enumerator NANOARROW_TIME_UNIT_MICRO#

enumerator NANOARROW_TIME_UNIT_NANO#

enum ArrowCompareLevel#

比较级别枚举器。

值

enumerator NANOARROW_COMPARE_IDENTICAL#: 如果缓冲区的内内容相同，且具有相同的偏移量、空值计数和长度，则认为数组相等。请注意，这比逻辑相等性检查要严格得多，逻辑相等性会考虑空槽中可能不同的内容、非零偏移量的数组以及其他因素。

函数

static inline const char *ArrowTypeString(enum ArrowType type)#

获取 enum ArrowType 值的字符串表示。

对于无效的 type 值返回 NULL

static inline const char *ArrowTimeUnitString(enum ArrowTimeUnit time_unit)#

获取 enum ArrowTimeUnit 值的字符串表示。

对于无效的 time_unit 值返回 NULL

static inline struct ArrowStringView ArrowCharView(const char *value)#: 返回一个 const C 字符串的视图。

static inline void ArrowIntervalInit(struct ArrowInterval *interval, enum ArrowType type)#: 使用给定单位零初始化一个 Interval。

static inline void ArrowDecimalInit(struct ArrowDecimal *decimal, int32_t bitwidth, int32_t precision, int32_t scale)#: 使用给定的一组类型参数初始化一个十进制数。

static inline void ArrowDecimalGetBytes(const struct ArrowDecimal *decimal, uint8_t *out)#: 将此十进制数的字节复制到一个足够大的缓冲区中。

static inline int64_t ArrowDecimalSign(const struct ArrowDecimal *decimal)#: 如果 decimal 表示的值 >= 0，则返回 1，否则返回 -1。

static inline void ArrowDecimalSetInt(struct ArrowDecimal *decimal, int64_t value)#: 设置此十进制数的整数值。

static inline void ArrowDecimalNegate(struct ArrowDecimal *decimal)#: 就地取反此十进制数的值。

static inline void ArrowDecimalSetBytes(struct ArrowDecimal *decimal, const uint8_t *value)#: 从缓冲区复制字节到此十进制数。

NANOARROW_DLL const char * ArrowNanoarrowVersion (void): 返回一个格式为“major.minor.patch”的版本字符串。

NANOARROW_DLL int ArrowNanoarrowVersionInt (void): 返回一个可用于顺序比较版本的整数。

NANOARROW_DLL void ArrowLayoutInit (struct ArrowLayout *layout, enum ArrowType storage_type): 根据存储类型初始化缓冲区布局的描述。

NANOARROW_DLL ArrowErrorCode ArrowDecimalSetDigits (struct ArrowDecimal *decimal, struct ArrowStringView value): 从字符串设置 ArrowDecimal 的整数值。

NANOARROW_DLL ArrowErrorCode ArrowDecimalAppendDigitsToBuffer (const struct ArrowDecimal *decimal, struct ArrowBuffer *buffer): 以字符串形式获取 ArrowDecimal 的整数值。

NANOARROW_DLL ArrowErrorCode ArrowDecimalAppendStringToBuffer (const struct ArrowDecimal *decimal, struct ArrowBuffer *buffer): 以字符串形式获取 ArrowDecimal 的十进制值。

static inline uint16_t ArrowFloatToHalfFloat(float value)#: 获取一个浮点数的半精度浮点值。

static inline float ArrowHalfFloatToFloat(uint16_t value)#: 获取一个半精度浮点数的浮点值。

static inline int64_t ArrowResolveChunk64(int64_t index, const int64_t *offsets, int64_t lo, int64_t hi)#

从递增的 int64_t 偏移量中解析块索引。

给定一个以 0 开头的递增 int64_t 偏移量缓冲区（例如，大类型的偏移量缓冲区，分块数组实现的运行结束位置），解析一个值 v，其中 lo <= v < hi，使得 offsets[v] <= index < offsets[v + 1]。

struct ArrowStringView#

#include <inline_types.h>

一个字符串的非自有视图。

公共成员

const char *data#

指向字符串起始位置的指针。

如果 size_bytes 为 0，此值可以为 NULL。

int64_t size_bytes#

字符串的大小（以字节为单位）。

（不包括空终止符。）

struct ArrowBufferView#

#include <inline_types.h>

一个缓冲区的非自有视图。

公共成员

union ArrowBufferViewData data#

指向缓冲区起始位置的指针。

如果 size_bytes 为 0，此值可以为 NULL。

int64_t size_bytes#: 缓冲区的大小（以字节为单位）。

struct ArrowLayout#

#include <inline_types.h>

缓冲区布局的描述。

包含在仅知道数组长度和偏移量的情况下，计算 ArrowArray 中每个缓冲区大小所需的最小信息。

公共成员

enum ArrowBufferType buffer_type[NANOARROW_MAX_FIXED_BUFFERS]#: 每个缓冲区的功能。

enum ArrowType buffer_data_type[NANOARROW_MAX_FIXED_BUFFERS]#: 每个缓冲区的数据类型。

int64_t element_size_bits[NANOARROW_MAX_FIXED_BUFFERS]#: 每个缓冲区中元素的大小（以位为单位），如果此大小是可变的或未知的，则为 0。

int64_t child_size_elements#: 对于固定大小列表，此数组中每个元素对应的子数组中的元素数量。

struct ArrowInterval#

#include <inline_types.h>

一个区间的表示。

公共成员

enum ArrowType type#: 正在使用的区间类型。

int32_t months#: 区间所代表的月数。

int32_t days#: 区间所代表的天数。

int32_t ms#: 区间所代表的毫秒数。

int64_t ns#: 区间所代表的纳秒数。

struct ArrowDecimal#

#include <inline_types.h>

定点精度小数的表示。

此结构应使用 ArrowDecimalInit() 初始化一次，并使用 ArrowDecimalSetInt()、ArrowDecimalSetBytes128() 或 ArrowDecimalSetBytes256() 设置值。

公共成员

uint64_t words[4]#: 一个由 n_words 个 64 位整数组成的数组，以本地字节序定义。对于 32 位小数值，索引 0 将是一个 32 位整数值。

int32_t precision#: 此小数值可以表示的有效数字位数。

int32_t scale#: 小数点后的位数。此值可以为负数。

int n_words#: words 数组中 64 位字的数目。对于 32 位小数值的特殊情况，此值为 0。

int high_word_index#: 由实现使用的缓存值。

int low_word_index#: 由实现使用的缓存值。

Arrow C 数据接口#

组 Arrow C 数据接口

Arrow C 数据（https://arrow.apache.org/docs/format/CDataInterface.html）和 Arrow C 流（https://arrow.apache.org/docs/format/CStreamInterface.html）接口是 Arrow 列式格式规范（https://arrow.apache.org/docs/format/Columnar.html）的一部分。有关这些结构的文档，请参阅 Arrow 文档。

宏定义

ARROW_C_DATA_INTERFACE#

ARROW_FLAG_DICTIONARY_ORDERED#

ARROW_FLAG_NULLABLE#

ARROW_FLAG_MAP_KEYS_SORTED#

ARROW_C_STREAM_INTERFACE#

函数

static inline void ArrowSchemaMove(struct ArrowSchema *src, struct ArrowSchema *dst)#: 将源 ArrowSchema 的内容移动到目标 dst 中，并将 src->release 设置为 NULL。

static inline void ArrowSchemaRelease(struct ArrowSchema *schema)#: 调用 ArrowSchema 的 release 回调。

static inline void ArrowArrayMove(struct ArrowArray *src, struct ArrowArray *dst)#: 将源 ArrowArray 的内容移动到目标 dst 中，并将 src->release 设置为 NULL。

static inline void ArrowArrayStreamMove(struct ArrowArrayStream *src, struct ArrowArrayStream *dst)#: 将源 ArrowArrayStream 的内容移动到目标 dst 中，并将 src->release 设置为 NULL。

static inline ArrowErrorCode ArrowArrayStreamGetSchema(struct ArrowArrayStream *array_stream, struct ArrowSchema *out, struct ArrowError *error)#

调用 ArrowArrayStream 的 get_schema 回调。

与 get_schema 回调不同，此包装器会检查返回码并将 get_last_error 报告的错误传播到 error 中。这使得使用 NANOARROW_RETURN_NOT_OK() 风格的错误处理来迭代数组流变得不那么冗长。

static inline ArrowErrorCode ArrowArrayStreamGetNext(struct ArrowArrayStream *array_stream, struct ArrowArray *out, struct ArrowError *error)#

调用 ArrowArrayStream 的 get_schema 回调。

与 get_next 回调不同，此包装器会检查返回码并将 get_last_error 报告的错误传播到 error 中。这使得使用 NANOARROW_RETURN_NOT_OK() 风格的错误处理来迭代数组流变得不那么冗长。

static inline const char *ArrowArrayStreamGetLastError(struct ArrowArrayStream *array_stream)#

调用 ArrowArrayStream 的 get_next 回调。

与 get_next 回调不同，此函数从不返回 NULL（即，其结果在 printf 风格的错误格式化器中是安全的）。来自原始回调的空值将被报告为“<get_last_error() returned NULL>”。

struct ArrowSchema#

公共成员

const char *format#

const char *name#

const char *metadata#

int64_t flags#

int64_t n_children#

struct ArrowSchema **children#

struct ArrowSchema *dictionary#

void (*release)(struct ArrowSchema*)#

void *private_data#

struct ArrowArray#

公共成员

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#

void (*release)(struct ArrowArray*)#

void *private_data#

struct ArrowArrayStream#

公共成员

int (*get_schema)(struct ArrowArrayStream*, struct ArrowSchema *out)#

int (*get_next)(struct ArrowArrayStream*, struct ArrowArray *out)#

const char *(*get_last_error)(struct ArrowArrayStream*)#

void (*release)(struct ArrowArrayStream*)#

void *private_data#

C API 参考#

创建 Schema#

读取 Schema#

创建数组#

读取数组#

拥有所有权的可增长缓冲区#

位图工具#

创建、读取和修改模式元数据#

内存管理#

错误处理#

实用数据结构#

Arrow C 数据接口#

本页