Conventions#

The Arrow C++ API follows a few simple guidelines. As with many rules, there may be exceptions.

Language version#

Starting with version 23.0, Arrow C++ requires C++20 or later.

Namespacing#

All the Arrow API (except macros) is namespaced inside a arrow namespace, and nested namespaces thereof.

Safe pointers#

Arrow objects are usually passed and stored using safe pointers most of the time std::shared_ptr but sometimes also std::unique_ptr.

Non-owning alternatives exist for the rare situations where the overhead of a safe pointer is considered unacceptable: ArraySpan and BufferSpan. Their usage in third-party code is not recommended.

Immutability#

Many Arrow objects are immutable: once constructed, their logical properties cannot change anymore. This makes it possible to use them in multi-threaded scenarios without requiring tedious and error-prone synchronization.

There are obvious exceptions to this, such as IO objects or mutable data buffers.

Error reporting#

Most APIs indicate a successful or erroneous outcome by returning a arrow::Status instance. Arrow doesnt throw exceptions of its own, but third-party exceptions might propagate through, especially std::bad_alloc (but Arrow doesnt use the standard allocators for large data).

When an API can return either an error code or a successful value, it usually does so by returning the template class arrow::Result. However, some APIs (usually deprecated) return arrow::Status and pass the result value as an out-pointer parameter.

Here is an example of checking the outcome of an operation:

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
}

If the caller function itself returns a arrow::Result or arrow::Status and wants to propagate any non-successful outcome, two convenience macros are available:

• ARROW_RETURN_NOT_OK takes a arrow::Status parameter and returns it if not successful.

• ARROW_ASSIGN_OR_RAISE takes a arrow::Result parameter, assigns its result to a lvalue if successful, or returns the corresponding arrow::Status on error.

For example:

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();
}