C API 参考#

group nanoarrow

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

由于此库旨在作为供应商库，因此它提供了完整的类型定义，并鼓励客户端在方便的情况下使用堆栈或静态分配。

创建模式#

group nanoarrow-schema

这些函数分配、复制和销毁 ArrowSchema 结构

函数

void ArrowSchemaInit(struct ArrowSchema *schema)#

初始化一个 ArrowSchema。

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

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

从 ArrowType 初始化一个 ArrowSchema。

一个便利的构造函数，它调用 ArrowSchemaInit() 和 ArrowSchemaSetType() 用于构造非参数化类型的常见情况。如果返回 NANOARROW_OK，则调用方负责调用 schema->release 回调。

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

获取模式的人类可读摘要。

将 ArrowSchema 的摘要写入 out（最多 n - 1 个字符），如果 n 足够大，则返回输出所需的字符数。如果 recursive 不为零，则结果还将包含子项。

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

从 ArrowType 设置模式的格式字段。

初始化 schema_out 的字段和释放回调。对于 NANOARROW_TYPE_LIST、NANOARROW_TYPE_LARGE_LIST 和 NANOARROW_TYPE_MAP，将分配、初始化和命名适当数量的子项；但是，调用方必须对预初始化的子项调用 ArrowSchemaSetType()。模式必须使用 ArrowSchemaInit() 或 ArrowSchemaDeepCopy() 进行初始化。

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

设置结构模式的格式字段并初始化子项。

初始化指定数量的子项；但是，调用方负责对每个子项调用 ArrowSchemaSetType() 和 ArrowSchemaSetName()。模式必须使用 ArrowSchemaInit() 或 ArrowSchemaDeepCopy() 进行初始化。

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

设置固定大小模式的格式字段。

对于 fixed_size <= 0 或类型不是 NANOARROW_TYPE_FIXED_SIZE_BINARY 或 NANOARROW_TYPE_FIXED_SIZE_LIST 返回 EINVAL。对于 NANOARROW_TYPE_FIXED_SIZE_LIST，将分配、初始化和命名适当数量的子项；但是，调用方必须对第一个子项调用 ArrowSchemaSetType()。模式必须使用 ArrowSchemaInit() 或 ArrowSchemaDeepCopy() 进行初始化。

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

设置十进制模式的格式字段。

对于 scale <= 0 或类型不是 NANOARROW_TYPE_DECIMAL128 或 NANOARROW_TYPE_DECIMAL256 返回 EINVAL。模式必须使用 ArrowSchemaInit() 或 ArrowSchemaDeepCopy() 进行初始化。

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

设置运行结束编码模式下的 Schema 的格式字段。

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

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

设置时间、时间戳或持续时间 Schema 的格式字段。

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

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

设置联合 Schema 的格式字段。

如果 type 不是 NANOARROW_TYPE_DENSE_UNION 或 NANOARROW_TYPE_SPARSE_UNION，则返回 EINVAL。将分配并初始化指定数量的子节点。

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

创建 Schema 的（递归）副本。

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

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

将 format 复制到 schema->format 中。

schema 必须使用 ArrowSchemaInitFromType() 或 ArrowSchemaDeepCopy() 分配。

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

将 name 复制到 schema->name 中。

schema 必须使用 ArrowSchemaInitFromType() 或 ArrowSchemaDeepCopy() 分配。

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

将 metadata 复制到 schema->metadata 中。

schema 必须使用 ArrowSchemaInitFromType() 或 ArrowSchemaDeepCopy 分配。

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

分配 schema->children 数组。

包括每个子结构体 ArrowSchema 的内存。schema 必须使用 ArrowSchemaInitFromType() 或 ArrowSchemaDeepCopy() 分配。

ArrowErrorCode ArrowSchemaAllocateDictionary(struct ArrowSchema *schema)#

分配 schema->dictionary 成员。

schema 必须使用 ArrowSchemaInitFromType() 或 ArrowSchemaDeepCopy() 分配。

读取 Schema#

group nanoarrow-schema-view

函数

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

struct ArrowSchemaView#

#include <nanoarrow.h>

解析后的 ArrowSchema 的非拥有视图。

包含比原始 ArrowSchema 更易于提取的值。客户端可以堆叠或静态分配此结构，但建议使用提供的 getter 以确保向前兼容。

公共成员

const struct ArrowSchema *schema#: 指向此视图表示的架构的指针。

enum ArrowType type#

架构表示的数据类型。

如果架构具有非空字典成员，则此值可能为 NANOARROW_TYPE_DICTIONARY；日期时间类型是有效值。此值永远不会是 NANOARROW_TYPE_EXTENSION（请参阅 extension_name 和/或 extension_metadata 以检查扩展类型）。

enum ArrowType storage_type#

架构表示的存储数据类型。

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

struct ArrowLayout layout#: 架构表示的存储布局。

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#

格式固定大小参数。

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

int32_t decimal_bitwidth#

十进制位宽。

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

int32_t decimal_precision#

十进制精度。

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

int32_t decimal_scale#

十进制刻度。

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

enum ArrowTimeUnit time_unit#

格式时间单位参数。

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

const char *timezone#

格式时区参数。

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

const char *union_type_ids#

联合类型 ID 参数。

解析联合类型时设置此值，并表示类型 ID 参数。此值指向架构中的数据，对于其他类型未定义。

创建数组#

group nanoarrow-array

这些函数分配、复制和销毁 ArrowArray 结构。一旦通过 ArrowArrayInitFromType() 或 ArrowArrayInitFromSchema() 初始化了 ArrowArray，则调用方负责使用嵌入的释放回调来释放它。

函数

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

初始化数组的字段。

初始化数组的字段和释放回调。如果返回 NANOARROW_OK，则调用方负责调用 array->release 回调。

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

从 ArrowSchema 初始化 ArrowArray 的内容。

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

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

从 ArrowArrayView 初始化 ArrowArray 的内容。

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

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

分配 array->children 数组。

包含每个子结构体 ArrowArray 的内存，其成员被标记为已释放，并且可以随后使用 ArrowArrayInitFromType() 初始化或从现有的 ArrowArray 移动。schema 必须使用 ArrowArrayInitFromType() 分配。

ArrowErrorCode ArrowArrayAllocateDictionary(struct ArrowArray *array)#

分配 array->dictionary 成员。

包含结构体 ArrowArray 的内存，其内容被标记为已释放，并且可以随后使用 ArrowArrayInitFromType() 初始化或从现有的 ArrowArray 移动。array 必须使用 ArrowArrayInitFromType() 分配。

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

设置 ArrowArray 的有效性位图。

array 必须使用 ArrowArrayInitFromType() 分配。

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() 分配。

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)#

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

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

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

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

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

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

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

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

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

将一段字节字符串追加到数组中。

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

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

将一个字符串值追加到数组中。

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

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

将一个时间间隔值追加到数组中。

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

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

将一个小数值追加到数组中。

如果数组是一个具有适当位宽的小数数组，则返回 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)#

完成一个联合数组元素。

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

static inline ArrowErrorCode ArrowArrayShrinkToFit(struct ArrowArray *array)#

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

还将缩减应用于任何子数组。数组必须使用 ArrowArrayInitFromType 进行分配。

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

完成 ArrowArray 的构建。

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

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 nanoarrow-array-view

这些函数读取并验证 ArrowArray 结构的内容。

函数

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

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

移动 ArrowArrayView。

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

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

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

分配 array_view->children 数组。

包括每个子结构体 ArrowArrayView 的内存。

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

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

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

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 的 ArrowLayout 成员或ArrowSchemaView计算得出；但是，对于二进制视图和字符串视图类型，缓冲区的总数取决于可变参数缓冲区的数量。

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 的 ArrowLayout 成员或 ArrowSchemaView 获取；但是，对于二进制视图和字符串视图类型，每个缓冲区的函数在两个相同类型的数组之间可能不同，具体取决于可变缓冲区的数量。

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

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

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

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

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

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

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

对 ArrowArrayView 的内容进行检查。

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

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 非 NULL，则将通过 error 传达原因。

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

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中的元素作为双精度浮点数获取。

此函数不检查空值或值是否在双精度浮点数的有效范围内。

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参数。

拥有、可增长的缓冲区#

group nanoarrow-buffer

函数

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 成员不为空，则使用分配器的 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)#: 将一个双精度浮点数写入缓冲区。

static inline ArrowErrorCode ArrowBufferAppendFloat(struct ArrowBuffer *buffer, float value)#: 将一个单精度浮点数写入缓冲区。

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

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

位图工具函数#

group nanoarrow-bitmap

函数

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)#: 计算位图中真值的数量。

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)#

重置位图构建器。

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

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

group nanoarrow-metadata

函数

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

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

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

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

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

从模式元数据中提取值。

如果元数据中不存在键，则 value_out 保持不变。

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

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

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

ArrowErrorCode ArrowMetadataBuilderAppend(struct ArrowBuffer *buffer, struct ArrowStringView key, struct ArrowStringView value)#: 将键值对追加到包含序列化元数据的缓冲区。

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

将键值对设置为包含序列化元数据的缓冲区。

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

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

struct ArrowMetadataReader#

#include <nanoarrow.h>

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

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

公共成员

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

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

int32_t remaining_keys#: 剩余键的数量。

内存管理#

group nanoarrow-malloc

结构体 ArrowSchema 和结构体 ArrowArray 的非缓冲区成员必须使用 ArrowMalloc() 或 ArrowRealloc() 分配，并使用 ArrowFree() 释放此处分配的模式和数组。缓冲区成员使用 ArrowBufferAllocator 分配。

函数

void *ArrowMalloc(int64_t size)#: 像 malloc() 一样分配内存。

void *ArrowRealloc(void *ptr, int64_t size)#: 像 realloc() 一样重新分配内存。

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

struct ArrowBufferAllocator ArrowBufferAllocatorDefault(void)#

返回默认分配器。

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

struct ArrowBufferAllocator ArrowBufferDeallocator(ArrowBufferDeallocatorCallback, void *private_data)#

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

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

错误处理#

group nanoarrow-errors

函数通常返回一个与 errno 兼容的错误代码；需要传达更详细的错误信息的函数接受指向 ArrowError 的指针。这可以是栈分配或静态分配。除非返回了错误代码，否则消息的内容未定义。如果 nanoarrow 函数传递了一个非空 ArrowError 指针，则将使用空终止的错误消息传播该参数指向的 ArrowError。在 nanoarrow API 中传递 NULL ArrowError 是安全的。

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

函数

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

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

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

实用程序数据结构#

group nanoarrow-utils

函数

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

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

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

static inline struct ArrowStringView ArrowCharView(const char *value)#: 从空终止字符串创建字符串视图。

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

ArrowErrorCode ArrowDecimalAppendDigitsToBuffer(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]。

Arrow C 数据接口#

警告

doxygengroup：在来自目录 ../../src/apidoc/xml 的项目“nanoarrow_c”的 doxygen xml 输出中找不到组“nanoarrow-arrow-cdata”。