Class StatusOr<T> (2.24.0)

Holds a value or a Status indicating why there is no value.

StatusOr<T> represents either a usable T value or a Status object explaining why a T value is not present. Typical usage of StatusOr<T> looks like usage of a smart pointer, or even a std::optional<T>, in that you first check its validity using a conversion to bool (or by calling StatusOr::ok()), then you may dereference the object to access the contained value.

It is undefined behavior (UB) to dereference a StatusOr<T> that is not "ok". For example:

StatusOr<Foo> foo = FetchFoo();
if (!foo) {  // Same as !foo.ok()
  // handle error and probably look at foo.status()
} else {
  foo->DoSomethingFooey();  // UB if !foo
}

Alternatively, you may call the StatusOr::value() member function, which is defined to: (1) throw an exception if there is no T value, or (2) crash the program if exceptions are disabled. It is never UB to call value().

StatusOr<Foo> foo = FetchFoo();
foo.value().DoSomethingFooey();  // May throw/crash if there is no value

Functions that can fail will often return a StatusOr<T> instead of returning an error code and taking a T out-param, or rather than directly returning the T and throwing an exception on error. StatusOr<T> is used so that callers can choose whether they want to explicitly check for errors, crash the program, or throw exceptions.

Since constructors do not have a return value, they should be designed in such a way that they cannot fail by moving the object's complex initialization logic into a separate factory function that itself can return a StatusOr<T>. For example:

class Bar {
 public:
  Bar(Arg arg);
  ...
};
StatusOr<Bar> MakeBar() {
  ... complicated logic that might fail
  return Bar(std::move(arg));
}

StatusOr<T> supports equality comparisons if the underlying type T does.

Constructors

StatusOr()

Initializes with an error status (StatusCode::kUnknown).

StatusOr(StatusOr const &)

Parameter
Name	Description
	`StatusOr const &`

StatusOr(StatusOr &&)

Parameter
Name	Description
`other`	`StatusOr &&`

StatusOr(Status)

Creates a new StatusOr<T> holding the error condition rhs.

Post-conditions

ok()== false and status()== rhs.

Parameter
Name	Description
`rhs`	`Status` the status to initialize the object.

Exceptions
Type	Description
`std::invalid_argument`	if `rhs.ok()`. If exceptions are disabled the program terminates via [`google::cloud::Terminate()`](xref:group__terminate_1gac5d2d48b27f2cd1de9075a1c9522f0cf)

StatusOr(T &&)

Creates a new StatusOr<T> holding the value rhs.

Post-conditions

ok()== true and value()== rhs.

Parameter
Name	Description
`rhs`	`T &&` the value used to initialize the object.

Exceptions
Type	Description
`...`	If `T`'s move constructor throws.

StatusOr(T const &)

Creates a new StatusOr<T> holding the value rhs.

Post-conditions

ok()== true and value()== rhs.

Parameter
Name	Description
`rhs`	`T const &` the value used to initialize the object.

Exceptions
Type	Description
`...`	If `T` copy constructor throws.

Operators

operator*() &

Dereference operators.

Returns
Type	Description
`T &`

operator*() const &

Dereference operators.

Returns
Type	Description
`T const &`

operator*() &&

Dereference operators.

Returns
Type	Description
`T &&`

operator*() const &&

Dereference operators.

Returns
Type	Description
`T const &&`

operator->() &

Member access operators.

Returns
Type	Description
`T *`

operator->() const &

Member access operators.

Returns
Type	Description
`T const *`

operator=(StatusOr const &)

Parameter
Name	Description
	`StatusOr const &`

Returns
Type	Description
`StatusOr &`

operator=(StatusOr &&)

Parameter
Name	Description
`other`	`StatusOr &&`

Returns
Type	Description
`StatusOr &`

operator=(Status)

Assigns the given non-OK Status to this StatusOr<T>.

Parameter
Name	Description
`status`	`Status`

Exceptions
Type	Description
`std::invalid_argument`	if `status.ok()`. If exceptions are disabled the program terminates via [`google::cloud::Terminate()`](xref:group__terminate_1gac5d2d48b27f2cd1de9075a1c9522f0cf)

Returns
Type	Description
`StatusOr &`

operator=(U &&)

Assign a T (or anything convertible to T) into the StatusOr.

This function does not participate in overload resolution if U is equal to StatusOr<T> (or to a cv-ref-qualified StatusOr<T>).

Parameters
Name	Description
`rhs`	`U &&`
`typename U`	a type convertible to `T`.

Returns
Type	Description
`StatusOr &`	a reference to this object.

operator bool() const

Returns true when this holds a value.

Functions

value() &

Value accessors.

Returns
Type	Description
`T &`

value() const &

Value accessors.

Returns
Type	Description
`T const &`

value() &&

Value accessors.

Returns
Type	Description
`T &&`

value() const &&

Value accessors.

Returns
Type	Description
`T const &&`

status() const &

Status accessors.

Returns
Type	Description
`Status const &`

status() &&

Status accessors.

Returns
Type	Description
`Status &&`

ok() const

Returns true when this holds a value.

Returns
Type	Description
`bool`

Type Aliases

value_type

Alias Of: T

A value_type member for use in generic programming.

This is analogous to that of std::optional::value_type.