约定

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` 并将结果值作为输出指针参数传递。

以下是检查操作结果的示例

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` 参数，如果成功，则将其结果赋给左值，否则返回相应的 `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 参考