absl::StatusOr

Description

The absl::StatusOr<T> class template is a union of an absl::Status object and an object of type T. The absl::StatusOr<T> models an object that is either a usable object, or an error (of type absl::Status) explaining why such an object is not present. An absl::StatusOr<T> is typically the return value of a function which may fail.

An absl::StatusOr<T> can never hold an "OK" status (an absl::StatusCode::kOk value); instead, the presence of an object of type T indicates success. Instead of checking for a kOk value, use the absl::StatusOr<T>::ok() member function. (It is for this reason, and code readability, that using the ok() function is preferred for absl::Status as well.)

Example:

StatusOr<Foo> result = DoBigCalculationThatCouldFail(); if (result.ok()) { result->DoSomethingCool(); } else { LOG(ERROR) << result.status(); }

Accessing the object held by an absl::StatusOr<T> should be performed via operator* or operator->, after a call to ok() confirms that the absl::StatusOr<T> holds an object of type T:

Example:

absl::StatusOr<int> i = GetCount(); if (i.ok()) { updated_total += *i; }

NOTE: using absl::StatusOr<T>::value() when no valid value is present will throw an exception if exceptions are enabled or terminate the process when exceptions are not enabled.

Example:

StatusOr<Foo> result = DoBigCalculationThatCouldFail(); const Foo& foo = result.value(); // Crash/exception if no value present foo.DoSomethingCool();

A absl::StatusOr<T*> can be constructed from a null pointer like any other pointer value, and the result will be that ok() returns true and value() returns nullptr. Checking the value of pointer in an absl::StatusOr<T*> generally requires a bit more care, to ensure both that a value is present and that value is not null:

StatusOr<std::unique_ptr<Foo>> result = FooFactory::MakeNewFoo(arg); if (!result.ok()) { LOG(ERROR) << result.status(); } else if (*result == nullptr) { LOG(ERROR) << "Unexpected null pointer"; } else { (*result)->DoSomethingCool(); }

Example factory implementation returning StatusOr<T>:

StatusOr<Foo> FooFactory::MakeFoo(int arg) { if (arg <= 0) { return absl::Status(absl::StatusCode::kInvalidArgument, "Arg must be positive"); } return Foo(arg); }