慣例

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 參數，如果成功，則將其結果賦值給左值，否則傳回對應的 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 參考