约定

Arrow C++ API 遵循一些简单的准则。 与许多规则一样，可能存在例外。

语言版本

从 10.0 版开始，Arrow C++ 兼容 C++17。

命名空间

所有 Arrow API（宏除外）都在 arrow 命名空间及其嵌套命名空间内。

安全指针

Arrow 对象通常使用安全指针传递和存储 – 大多数时候是 std::shared_ptr，但有时也是 std::unique_ptr。

不可变性

许多 Arrow 对象是不可变的：一旦构建，它们的逻辑属性就无法再更改。 这使得可以在多线程场景中使用它们，而无需繁琐且容易出错的同步。

对此存在明显的例外，例如 IO 对象或可变数据缓冲区。

错误报告

大多数 API 通过返回一个 arrow::Status 实例来指示成功或错误的执行结果。 Arrow 不会抛出自己的异常，但第三方异常可能会传播，尤其是 std::bad_alloc（但 Arrow 不会将标准分配器用于大型数据）。

当 API 可以返回错误代码或成功值时，它通常通过返回模板类 arrow::Result 来实现。 但是，某些 API（通常已弃用）返回 arrow::Status 并将结果值作为 out-pointer 参数传递。

这是一个检查操作结果的示例

const int64_t buffer_size = 4096;

auto maybe_buffer = arrow::AllocateBuffer(buffer_size, &buffer);
if (!maybe_buffer.ok()) {
   // ... handle error
} else {
   std::shared_ptr<arrow::Buffer> buffer = *maybe_buffer;
   // ... use allocated buffer
}

如果调用者函数本身返回一个 arrow::Result 或 arrow::Status 并且想要传播任何不成功的结果，则可以使用两个便捷的宏

• ARROW_RETURN_NOT_OK 接受一个 arrow::Status 参数，如果该参数不成功，则返回该参数。

• ARROW_ASSIGN_OR_RAISE 接受一个 arrow::Result 参数，如果成功，则将其结果分配给一个 *lvalue*，否则返回相应的 arrow::Status（如果发生错误）。

例如

arrow::Status DoSomething() {
   const int64_t buffer_size = 4096;
   std::shared_ptr<arrow::Buffer> buffer;
   ARROW_ASSIGN_OR_RAISE(buffer, arrow::AllocateBuffer(buffer_size));
   // ... allocation successful, do something with buffer below

   // return success at the end
   return Status::OK();
}

另请参阅

错误报告的 API 参考