Programming Support¶

General information¶

const BuildInfo &arrow::GetBuildInfo()¶

Get runtime build info.

The returned values correspond to exact loaded version of the Arrow library, rather than the values frozen at application compile-time through the ARROW_* preprocessor definitions.

struct BuildInfo¶

Public Members

int version¶: The packed version number, e.g. 1002003 (decimal) for Arrow 1.2.3.

int version_major¶: The “major” version number, e.g. 1 for Arrow 1.2.3.

int version_minor¶: The “minor” version number, e.g. 2 for Arrow 1.2.3.

int version_patch¶: The “patch” version number, e.g. 3 for Arrow 1.2.3.

std::string version_string¶: The version string, e.g. “1.2.3”.

std::string compiler_id¶: The CMake compiler identifier, e.g. “GNU”.

std::string git_id¶: The git changeset id, if available.

std::string git_description¶: The git changeset description, if available.

std::string build_type¶: The uppercase build type, e.g. “DEBUG” or “RELEASE”.

RuntimeInfo arrow::GetRuntimeInfo()¶: Get runtime info.

struct RuntimeInfo¶

Public Members

std::string simd_level¶

The enabled SIMD level.

This can be less than detected_simd_level if the ARROW_USER_SIMD_LEVEL environment variable is set to another value.

std::string detected_simd_level¶: The SIMD level available on the OS and CPU.

bool using_os_timezone_db¶: Whether using the OS-based timezone database This is set at compile-time.

std::optional<std::string> timezone_db_path¶: The path to the timezone database; by default None.

Macro definitions¶

These can be useful if you need to decide between different blocks of code at compile time (for example to conditionally take advantage of a recently introduced API).

ARROW_VERSION_MAJOR¶: The Arrow major version number, for example 7 for Arrow 7.0.1.

ARROW_VERSION_MINOR¶: The Arrow minor version number, for example 0 for Arrow 7.0.1.

ARROW_VERSION_PATCH¶: The Arrow patch version number, for example 1 for Arrow 7.0.1.

ARROW_VERSION¶

A consolidated integer representing the full Arrow version in an easily comparable form, computed with the formula: ((ARROW_VERSION_MAJOR * 1000) + ARROW_VERSION_MINOR) * 1000 + ARROW_VERSION_PATCH.

For example, this would choose a different block of code if the code is being compiled against a Arrow version equal to or greater than 7.0.1:

#if ARROW_VERSION >= 7000001
// Arrow 7.0.1 or later...
#endif

ARROW_VERSION_STRING¶: A human-readable string representation of the Arrow version, such as "7.0.1".

Runtime Configuration¶

struct GlobalOptions¶

Public Members

std::optional<std::string> timezone_db_path¶

Path to text timezone database.

This is only configurable on Windows, which does not have a compatible OS timezone database.

Status arrow::Initialize(const GlobalOptions &options) noexcept¶

Error return and reporting¶

class Status : public arrow::util::EqualityComparable<Status>, public arrow::util::ToStringOstreamable<Status>¶

Status outcome object (success or error)

The Status object is an object holding the outcome of an operation. The outcome is represented as a StatusCode, either success (StatusCode::OK) or an error (any other of the StatusCode enumeration values).

Additionally, if an error occurred, a specific error message is generally attached.

Public Functions

Status(StatusCode code, std::string msg, std::shared_ptr<StatusDetail> detail)¶: Pluggable constructor for use by sub-systems. detail cannot be null.

inline constexpr bool ok() const¶: Return true iff the status indicates success.

inline constexpr bool IsOutOfMemory() const¶: Return true iff the status indicates an out-of-memory error.

inline constexpr bool IsKeyError() const¶: Return true iff the status indicates a key lookup error.

inline constexpr bool IsInvalid() const¶: Return true iff the status indicates invalid data.

inline constexpr bool IsCancelled() const¶: Return true iff the status indicates a cancelled operation.

inline constexpr bool IsIOError() const¶: Return true iff the status indicates an IO-related failure.

inline constexpr bool IsCapacityError() const¶: Return true iff the status indicates a container reaching capacity limits.

inline constexpr bool IsIndexError() const¶: Return true iff the status indicates an out of bounds index.

inline constexpr bool IsTypeError() const¶: Return true iff the status indicates a type error.

inline constexpr bool IsUnknownError() const¶: Return true iff the status indicates an unknown error.

inline constexpr bool IsNotImplemented() const¶: Return true iff the status indicates an unimplemented operation.

inline constexpr bool IsSerializationError() const¶: Return true iff the status indicates a (de)serialization failure.

inline constexpr bool IsRError() const¶: Return true iff the status indicates a R-originated error.

std::string ToString() const¶

Return a string representation of this status suitable for printing.

The string “OK” is returned for success.

std::string ToStringWithoutContextLines() const¶

Return a string representation of this status without context lines suitable for printing.

The string “OK” is returned for success.

std::string CodeAsString() const¶: Return a string representation of the status code, without the message text or POSIX code information.

inline constexpr StatusCode code() const¶: Return the StatusCode value attached to this status.

inline const std::string &message() const¶: Return the specific error message attached to this status.

inline const std::shared_ptr<StatusDetail> &detail() const¶: Return the status detail attached to this message.

inline Status WithDetail(std::shared_ptr<StatusDetail> new_detail) const¶: Return a new Status copying the existing status, but updating with the existing detail.

template<typename ...Args> inline Status WithMessage(Args&&... args) const¶: Return a new Status with changed message, copying the existing status code and detail.

Public Static Functions

static inline Status OK()¶: Return a success status.

template<typename ...Args> static inline Status OutOfMemory(Args&&... args)¶: Return an error status for out-of-memory conditions.

template<typename ...Args> static inline Status KeyError(Args&&... args)¶: Return an error status for failed key lookups (e.g. column name in a table)

template<typename ...Args> static inline Status TypeError(Args&&... args)¶: Return an error status for type errors (such as mismatching data types)

template<typename ...Args> static inline Status UnknownError(Args&&... args)¶: Return an error status for unknown errors.

template<typename ...Args> static inline Status NotImplemented(Args&&... args)¶: Return an error status when an operation or a combination of operation and data types is unimplemented.

template<typename ...Args> static inline Status Invalid(Args&&... args)¶: Return an error status for invalid data (for example a string that fails parsing)

template<typename ...Args> static inline Status Cancelled(Args&&... args)¶: Return an error status for cancelled operation.

template<typename ...Args> static inline Status IndexError(Args&&... args)¶: Return an error status when an index is out of bounds.

template<typename ...Args> static inline Status CapacityError(Args&&... args)¶: Return an error status when a container’s capacity would exceed its limits.

template<typename ...Args> static inline Status IOError(Args&&... args)¶: Return an error status when some IO-related operation failed.

template<typename ...Args> static inline Status SerializationError(Args&&... args)¶: Return an error status when some (de)serialization operation failed.

class StatusDetail¶

An opaque class that allows subsystems to retain additional information inside the Status.

Subclassed by arrow::flight::FlightStatusDetail, arrow::flight::FlightWriteSizeStatusDetail

Public Functions

virtual const char *type_id() const = 0¶: Return a unique id for the type of the StatusDetail (effectively a poor man’s substitute for RTTI).

virtual std::string ToString() const = 0¶: Produce a human-readable description of this status.

template<class T> class Result : public arrow::util::EqualityComparable<Result<T>>¶

A class for representing either a usable value, or an error.

A Result object either contains a value of type T or a Status object explaining why such a value is not present. The type T must be copy-constructible and/or move-constructible.

The state of a Result object may be determined by calling ok() or status(). The ok() method returns true if the object contains a valid value. The status() method returns the internal Status object. A Result object that contains a valid value will return an OK Status for a call to status().

A value of type T may be extracted from a Result object through a call to ValueOrDie(). This function should only be called if a call to ok() returns true. Sample usage:

 arrow::Result<Foo> result = CalculateFoo();
 if (result.ok()) {
   Foo foo = result.ValueOrDie();
   foo.DoSomethingCool();
 } else {
   ARROW_LOG(ERROR) << result.status();
}

If T is a move-only type, like std::unique_ptr<>, then the value should only be extracted after invoking std::move() on the Result object. Sample usage:

arrow::Result<std::unique_ptr<Foo>> result = CalculateFoo();
if (result.ok()) {
  std::unique_ptr<Foo> foo = std::move(result).ValueOrDie();
  foo->DoSomethingCool();
} else {
  ARROW_LOG(ERROR) << result.status();
}

Result is provided for the convenience of implementing functions that return some value but may fail during execution. For instance, consider a function with the following signature:

arrow::Status CalculateFoo(int *output);

This function may instead be written as:

arrow::Result<int> CalculateFoo();

Public Functions

inline explicit Result() noexcept¶

Constructs a Result object that contains a non-OK status.

This constructor is marked explicit to prevent attempts to return {} from a function with a return type of, for example, Result<std::vector<int>>. While return {} seems like it would return an empty vector, it will actually invoke the default constructor of Result.

inline Result(const Status &status) noexcept¶

Constructs a Result object with the given non-OK Status object.

All calls to ValueOrDie() on this object will abort. The given status must not be an OK status, otherwise this constructor will abort.

This constructor is not declared explicit so that a function with a return type of Result<T> can return a Status object, and the status will be implicitly converted to the appropriate return type as a matter of convenience.

Parameters:: status – The non-OK Status object to initialize to.

template<typename U, typename E = typename std::enable_if<std::is_constructible<T, U>::value && std::is_convertible<U, T>::value && !std::is_same<typename std::remove_reference<typename std::remove_cv::type>::type, Status>::value>::type> inline Result(U &&value) noexcept¶

Constructs a Result object that contains value.

The resulting object is considered to have an OK status. The wrapped element can be accessed with ValueOrDie().

This constructor is made implicit so that a function with a return type of Result<T> can return an object of type U &&, implicitly converting it to a Result<T> object.

Note that T must be implicitly constructible from U, and U must not be a (cv-qualified) Status or Status-reference type. Due to C++ reference-collapsing rules and perfect-forwarding semantics, this constructor matches invocations that pass value either as a const reference or as an rvalue reference. Since Result needs to work for both reference and rvalue-reference types, the constructor uses perfect forwarding to avoid invalidating arguments that were passed by reference. See http://thbecker.net/articles/rvalue_references/section_08.html for additional details.

Parameters:: value – The value to initialize to.

inline Result(T &&value) noexcept¶

Constructs a Result object that contains value.

The resulting object is considered to have an OK status. The wrapped element can be accessed with ValueOrDie().

This constructor is made implicit so that a function with a return type of Result<T> can return an object of type T, implicitly converting it to a Result<T> object.

Parameters:: value – The value to initialize to.

inline Result(const Result &other) noexcept¶

Copy constructor.

This constructor needs to be explicitly defined because the presence of the move-assignment operator deletes the default copy constructor. In such a scenario, since the deleted copy constructor has stricter binding rules than the templated copy constructor, the templated constructor cannot act as a copy constructor, and any attempt to copy-construct a Result object results in a compilation error.

Parameters:: other – The value to copy from.

template<typename U, typename E = typename std::enable_if<std::is_constructible<T, const U&>::value && std::is_convertible<U, T>::value>::type> inline Result(const Result &other) noexcept¶

Templatized constructor that constructs a Result<T> from a const reference to a Result.

T must be implicitly constructible from const U &.

Parameters:: other – The value to copy from.

inline Result &operator=(const Result &other) noexcept¶

Copy-assignment operator.

Parameters:: other – The Result object to copy.

template<typename U, typename E = typename std::enable_if<std::is_constructible<T, U&&>::value && std::is_convertible<U, T>::value>::type> inline Result(Result &&other) noexcept¶

Templatized constructor which constructs a Result<T> by moving the contents of a Result.

T must be implicitly constructible from U &&.

Sets other to contain a non-OK status with aStatusError::Invalid error code.

Parameters:: other – The Result object to move from and set to a non-OK status.

inline Result &operator=(Result &&other) noexcept¶

Move-assignment operator.

Sets other to an invalid state..

Parameters:: other – The Result object to assign from and set to a non-OK status.

inline bool Equals(const Result &other) const¶: Compare to another Result.

inline constexpr bool ok() const¶

Indicates whether the object contains a T value.

Generally instead of accessing this directly you will want to use ASSIGN_OR_RAISE defined below.

Returns:: True if this Result object’s status is OK (i.e. a call to ok() returns true). If this function returns true, then it is safe to access the wrapped element through a call to ValueOrDie().

inline constexpr const Status &status() const¶

Equivalent to ok().

Gets the stored status object, or an OK status if a T value is stored.

Returns:: The stored non-OK status object, or an OK status if this object has a value.

inline const T &ValueOrDie() const &¶

Gets the stored T value.

This method should only be called if this Result object’s status is OK (i.e. a call to ok() returns true), otherwise this call will abort.

Returns:: The stored T value.

inline T &ValueOrDie() &¶

Gets a mutable reference to the stored T value.

This method should only be called if this Result object’s status is OK (i.e. a call to ok() returns true), otherwise this call will abort.

Returns:: The stored T value.

inline T ValueOrDie() &&¶

Moves and returns the internally-stored T value.

This method should only be called if this Result object’s status is OK (i.e. a call to ok() returns true), otherwise this call will abort. The Result object is invalidated after this call and will be updated to contain a non-OK status.

Returns:: The stored T value.

template<typename U, typename E = typename std::enable_if<std::is_constructible<U, T>::value>::type> inline Status Value(U *out) &&¶

Helper method for implementing Status returning functions in terms of semantically equivalent Result returning functions.

For example:

Status GetInt(int *out) { return GetInt().Value(out); }

inline T ValueOr(T alternative) &&¶: Move and return the internally stored value or alternative if an error is stored.

template<typename G> inline T ValueOrElse(G &&generate_alternative) &&¶: Retrieve the value if ok(), falling back to an alternative generated by the provided factory.

template<typename M> inline EnsureResult< decltype(std::declval< M && >)(std::declval< T && >)))>::type Map (M &&m) &&: Apply a function to the internally stored value to produce a new result or propagate the stored error.

template<typename M> inline EnsureResult< decltype(std::declval< M && >)(std::declval< const T & >)))>::type Map (M &&m) const &: Apply a function to the internally stored value to produce a new result or propagate the stored error.

template<typename U, typename E = typename std::enable_if<std::is_constructible<U, T>::value>::type> inline Result As() &&¶: Cast the internally stored value to produce a new result or propagate the stored error.

template<typename U, typename E = typename std::enable_if<std::is_constructible<U, const T&>::value>::type> inline Result As() const &¶: Cast the internally stored value to produce a new result or propagate the stored error.

class ParquetException : public exception¶: Subclassed by parquet::HiddenColumnException, parquet::KeyAccessDeniedException, parquet::ParquetStatusException

Functional macros for error-based control flow¶

ARROW_RETURN_NOT_OK(status)¶: Propagate any non-successful Status to the caller.

ARROW_ASSIGN_OR_RAISE(lhs, rexpr)¶

Execute an expression that returns a Result, extracting its value into the variable defined by lhs (or returning a Status on error).

Example: Assigning to a new value: ARROW_ASSIGN_OR_RAISE(auto value, MaybeGetValue(arg));

Example: Assigning to an existing value: ValueType value; ARROW_ASSIGN_OR_RAISE(value, MaybeGetValue(arg));

WARNING: ARROW_ASSIGN_OR_RAISE expands into multiple statements; it cannot be used in a single statement (e.g. as the body of an if statement without {})!

WARNING: ARROW_ASSIGN_OR_RAISE std::moves its right operand. If you have an lvalue Result which you don’t want to move out of cast appropriately.

WARNING: ARROW_ASSIGN_OR_RAISE is not a single expression; it will not maintain lifetimes of all temporaries in rexpr (e.g. ARROW_ASSIGN_OR_RAISE(auto x, MakeTemp().GetResultRef()); will most likely segfault)!

PARQUET_THROW_NOT_OK(s)¶

PARQUET_ASSIGN_OR_THROW(lhs, rexpr)¶

API Reference

Memory (management)