General information#

constBuildInfo&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 theARROW_* preprocessor definitions.

structBuildInfo#

Public Members

intversion#

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

intversion_major#

The “major” version number, e.g. 1 for Arrow 1.2.3.

intversion_minor#

The “minor” version number, e.g. 2 for Arrow 1.2.3.

intversion_patch#

The “patch” version number, e.g. 3 for Arrow 1.2.3.

std::stringversion_string#

The version string, e.g. “1.2.3”.

std::stringcompiler_id#

The CMake compiler identifier, e.g. “GNU”.

std::stringgit_id#

The git changeset id, if available.

std::stringgit_description#

The git changeset description, if available.

std::stringbuild_type#

The uppercase build type, e.g. “DEBUG” or “RELEASE”.

RuntimeInfoarrow::GetRuntimeInfo()#

Get runtime info.

structRuntimeInfo#

Public Members

std::stringsimd_level#

The enabled SIMD level.

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

std::stringdetected_simd_level#

The SIMD level available on the OS and CPU.

boolusing_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.

Runtime Configuration#

structGlobalOptions#

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.

Statusarrow::Initialize(constGlobalOptions&options)noexcept#

Error return and reporting#

classStatus:publicarrow::util::EqualityComparable<Status>,publicarrow::util::ToStringOstreamable<Status>#

Status outcome object (success or error)

TheStatus 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(StatusCodecode,std::stringmsg,std::shared_ptr<StatusDetail>detail)#

Pluggable constructor for use by sub-systems. detail cannot be null.

inlineconstexprboolok()const#

Return true iff the status indicates success.

inlineconstexprboolIsOutOfMemory()const#

Return true iff the status indicates an out-of-memory error.

inlineconstexprboolIsKeyError()const#

Return true iff the status indicates a key lookup error.

inlineconstexprboolIsInvalid()const#

Return true iff the status indicates invalid data.

inlineconstexprboolIsCancelled()const#

Return true iff the status indicates a cancelled operation.

inlineconstexprboolIsIOError()const#

Return true iff the status indicates an IO-related failure.

inlineconstexprboolIsCapacityError()const#

Return true iff the status indicates a container reaching capacity limits.

inlineconstexprboolIsIndexError()const#

Return true iff the status indicates an out of bounds index.

inlineconstexprboolIsTypeError()const#

Return true iff the status indicates a type error.

inlineconstexprboolIsUnknownError()const#

Return true iff the status indicates an unknown error.

inlineconstexprboolIsNotImplemented()const#

Return true iff the status indicates an unimplemented operation.

inlineconstexprboolIsSerializationError()const#

Return true iff the status indicates a (de)serialization failure.

inlineconstexprboolIsRError()const#

Return true iff the status indicates a R-originated error.

std::stringToString()const#

Return a string representation of this status suitable for printing.

The string “OK” is returned for success.

std::stringToStringWithoutContextLines()const#

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

The string “OK” is returned for success.

std::stringCodeAsString()const#

Return a string representation of the status code, without the message text or POSIX code information.

inlineconstexprStatusCodecode()const#

Return the StatusCode value attached to this status.

conststd::string&message()const#

Return the specific error message attached to this status.

conststd::shared_ptr<StatusDetail>&detail()const#

Return the status detail attached to this message.

inlineStatusWithDetail(std::shared_ptr<StatusDetail>new_detail)const#

Return a newStatus copying the existing status, but updating with the existing detail.

template<typename...Args>
inlineStatusWithMessage(Args&&...args)const#

Return a newStatus with changed message, copying the existing status code and detail.

template<typenameOnError>
inlineStatusOrElse(OnError&&on_error)#

Apply a functor if the status indicates an error.

This can be used to execute fallback or cleanup actions.

If the status indicates a success, it is returned as-is.

If the status indicates an error, the given functor is called with the status as argument. If the functor returns a newStatus, it is returned. If the functor returns a Status-compatible object such as Result<T>, it is converted toStatus and returned. If the functor returns void, the originalStatus is returned.

Public Static Functions

staticinlineStatusOK()#

Return a success status.

template<typename...Args>
staticinlineStatusOutOfMemory(Args&&...args)#

Return an error status for out-of-memory conditions.

template<typename...Args>
staticinlineStatusKeyError(Args&&...args)#

Return an error status for failed key lookups (e.g. column name in a table)

template<typename...Args>
staticinlineStatusTypeError(Args&&...args)#

Return an error status for type errors (such as mismatching data types)

template<typename...Args>
staticinlineStatusUnknownError(Args&&...args)#

Return an error status for unknown errors.

template<typename...Args>
staticinlineStatusNotImplemented(Args&&...args)#

Return an error status when an operation or a combination of operation and data types is unimplemented.

template<typename...Args>
staticinlineStatusInvalid(Args&&...args)#

Return an error status for invalid data (for example a string that fails parsing)

template<typename...Args>
staticinlineStatusCancelled(Args&&...args)#

Return an error status for cancelled operation.

template<typename...Args>
staticinlineStatusIndexError(Args&&...args)#

Return an error status when an index is out of bounds.

template<typename...Args>
staticinlineStatusCapacityError(Args&&...args)#

Return an error status when a container’s capacity would exceed its limits.

template<typename...Args>
staticinlineStatusIOError(Args&&...args)#

Return an error status when some IO-related operation failed.

template<typename...Args>
staticinlineStatusSerializationError(Args&&...args)#

Return an error status when some (de)serialization operation failed.

classStatusDetail#

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

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

Public Functions

virtualconstchar*type_id()const=0#

Return a unique id for the type of theStatusDetail (effectively a poor man’s substitute for RTTI).

virtualstd::stringToString()const=0#

Produce a human-readable description of this status.

template<classT>
classResult:publicarrow::util::EqualityComparable<Result<T>>#

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

AResult object either contains a value of typeT or aStatus object explaining why such a value is not present. The typeT must be copy-constructible and/or move-constructible.

The state of aResult object may be determined by callingok() orstatus(). Theok() method returns true if the object contains a valid value. Thestatus() method returns the internalStatus object. AResult object that contains a valid value will return an OKStatus for a call tostatus().

A value of typeT may be extracted from aResult object through a call toValueOrDie(). This function should only be called if a call took() returns true. Sample usage:

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

IfT is a move-only type, likestd::unique_ptr<>, then the value should only be extracted after invokingstd::move() on theResult 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::StatusCalculateFoo(int*output);

This function may instead be written as:

arrow::Result<int>CalculateFoo();

Public Functions

inlineexplicitResult()noexcept#

Constructs aResult object that contains a non-OK status.

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

inlineResult(constStatus&status)noexcept#

Constructs aResult object with the given non-OKStatus object.

All calls toValueOrDie() on this object will abort. The givenstatus 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 ofResult<T> can return aStatus object, and the status will be implicitly converted to the appropriate return type as a matter of convenience.

Parameters:

status – The non-OKStatus object to initialize to.

template<typenameU,typenameE=typenamestd::enable_if<std::is_constructible<T,U>::value&&std::is_convertible<U,T>::value&&!std::is_same<typenamestd::remove_reference<typenamestd::remove_cv<U>::type>::type,Status>::value>::type>
inlineResult(U&&value)noexcept#

Constructs aResult object that containsvalue.

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

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

Note thatT must be implicitly constructible fromU, andU 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 passvalue either as a const reference or as an rvalue reference. SinceResult needs to work for both reference and rvalue-reference types, the constructor uses perfect forwarding to avoid invalidating arguments that were passed by reference. Seehttp://thbecker.net/articles/rvalue_references/section_08.html for additional details.

Parameters:

value – The value to initialize to.

inlineResult(T&&value)noexcept#

Constructs aResult object that containsvalue.

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

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

Parameters:

value – The value to initialize to.

inlineResult(constResult&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 aResult object results in a compilation error.

Parameters:

other – The value to copy from.

template<typenameU,typenameE=typenamestd::enable_if<std::is_constructible<T,constU&>::value&&std::is_convertible<U,T>::value>::type>
inlineResult(constResult<U>&other)noexcept#

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

T must be implicitly constructible fromconstU&.

Parameters:

other – The value to copy from.

inlineResult&operator=(constResult&other)noexcept#

Copy-assignment operator.

Parameters:

other – TheResult object to copy.

template<typenameU,typenameE=typenamestd::enable_if<std::is_constructible<T,U&&>::value&&std::is_convertible<U,T>::value>::type>
inlineResult(Result<U>&&other)noexcept#

Templatized constructor which constructs aResult<T> by moving the contents of aResult<U>.

T must be implicitly constructible fromU&&.

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

Parameters:

other – TheResult object to move from and set to a non-OK status.

inlineResult&operator=(Result&&other)noexcept#

Move-assignment operator.

Setsother to an invalid state..

Parameters:

other – TheResult object to assign from and set to a non-OK status.

inlineboolEquals(constResult&other)const#

Compare to anotherResult.

inlineconstexprboolok()const#

Indicates whether the object contains aT value.

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

Returns:

True if thisResult object’s status is OK (i.e. a call took() returns true). If this function returns true, then it is safe to access the wrapped element through a call toValueOrDie().

inlineconstexprconstStatus&status()const&#

Equivalent took().

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

Returns:

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

inlineStatusstatus()&&#

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

Returns:

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

inlineconstT&ValueOrDie()const&#

Gets the storedT value.

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

Returns:

The storedT value.

inlineT&ValueOrDie()&#

Gets a mutable reference to the storedT value.

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

Returns:

The storedT value.

inlineTValueOrDie()&&#

Moves and returns the internally-storedT value.

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

Returns:

The storedT value.

template<typenameU,typenameE=typenamestd::enable_if<std::is_constructible<U,T>::value>::type>
inlineStatusValue(U*out)&&#

Helper method for implementingStatus returning functions in terms of semantically equivalentResult returning functions.

For example:

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

inlineTValueOr(Talternative)&&#

Move and return the internally stored value or alternative if an error is stored.

inlineTValueOr(Talternative)const&#

Return a copy of the internally stored value or alternative if an error is stored.

template<typenameG>
inlineTValueOrElse(G&&generate_alternative)&&#

Retrieve the value ifok(), falling back to an alternative generated by the provided factory.

template<typenameM>
inlineEnsureResult<decltype(std::declval<M&&>()(std::declval<T&&>()))>::typeMap(M&&m)&&#

Apply a function to the internally stored value to produce a new result or propagate the stored error.

template<typenameM>
inlineEnsureResult<decltype(std::declval<M&&>()(std::declval<constT&>()))>::typeMap(M&&m)const&#

Apply a function to the internally stored value to produce a new result or propagate the stored error.

template<typenameU,typenameE=typenamestd::enable_if<std::is_constructible<U,T>::value>::type>
inlineResult<U>As()&&#

Cast the internally stored value to produce a new result or propagate the stored error.

template<typenameU,typenameE=typenamestd::enable_if<std::is_constructible<U,constT&>::value>::type>
inlineResult<U>As()const&#

Cast the internally stored value to produce a new result or propagate the stored error.

classParquetException:publicstd::exception#

Subclassed by parquet::HiddenColumnException, parquet::KeyAccessDeniedException, parquet::ParquetStatusException