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

#include <google/cloud/status_or.h>

Public Types
using	value_type = T
	A `value_type` member for use in generic programming. More...

Public Member Functions

StatusOr ()

Initializes with an error status (UNKNOWN). More...

StatusOr (StatusOr const &)=default

StatusOr & operator= (StatusOr const &)=default

StatusOr (StatusOr &&other)

StatusOr & operator= (StatusOr &&other)

StatusOr (Status rhs)

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

StatusOr & operator= (Status status)

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

template<typename U = T>

std::enable_if< !std::is_same< StatusOr, typename std::decay< U >::type >::value, StatusOr >::type & operator= (U &&rhs)

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

StatusOr (T &&rhs)

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

StatusOr (T const &rhs)

bool ok () const

operator bool () const

Deference operators.

Warning: Using these operators when ok() == false results in undefined behavior.

Returns: All these return a (properly ref and const-qualified) reference to the underlying value.

T & operator* () &

T const & operator* () const &

T && operator* () &&

T const && operator* () const &&

Member access operators.

Warning: Using these operators when ok() == false results in undefined behavior.

Returns: All these return a (properly ref and const-qualified) pointer to the underlying value.

T * operator-> () &

T const * operator-> () const &

Value accessors.

Returns: All these member functions return a (properly ref and const-qualified) reference to the underlying value.

Exceptions

<tt>RuntimeStatusError</tt> with the contents of status() if the object does not contain a value, i.e., if ok() == false.

T & value () &

T const & value () const &

T && value () &&

T const && value () const &&

Status accessors.
Returns A reference to the contained `Status`.
Status const &	status () const &

Status &&	status () &&

Detailed Description

template<typename T>
class google::cloud::StatusOr< T >

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 throw an exception if there is no T value, or 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 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.

TODO(...) - the current implementation is fairly naive with respect to T, it is unlikely to work correctly for reference types, types without default constructors, arrays.

Template Parameters

T	the type of the value.

Definition at line 89 of file status_or.h.

Member Typedef Documentation

◆ value_type

template<typename T >

using google::cloud::StatusOr< T >::value_type = T

A value_type member for use in generic programming.

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

Definition at line 96 of file status_or.h.

Constructor & Destructor Documentation

◆ StatusOr() [1/6]

template<typename T >

google::cloud::StatusOr< T >::StatusOr ( )

inline

Initializes with an error status (UNKNOWN).

Definition at line 101 of file status_or.h.

◆ StatusOr() [2/6]

template<typename T >

google::cloud::StatusOr< T >::StatusOr ( StatusOr< T > const & )

default

◆ StatusOr() [3/6]

template<typename T >

google::cloud::StatusOr< T >::StatusOr ( StatusOr< T > && other )

inline

Definition at line 106 of file status_or.h.

◆ StatusOr() [4/6]

template<typename T >

google::cloud::StatusOr< T >::StatusOr ( Status rhs )

inline

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

Post-conditions: ok() == false and status() == rhs.

Parameters

rhs	the status to initialize the object.

Exceptions

std::invalid_argument if rhs.ok(). If exceptions are disabled the program terminates via google::cloud::Terminate()

Definition at line 129 of file status_or.h.

◆ StatusOr() [5/6]

template<typename T >

google::cloud::StatusOr< T >::StatusOr ( T && rhs )

inline

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

Post-conditions: ok() == true and value() == rhs.

Parameters

rhs	the value used to initialize the object.

Exceptions

only	if `T`'s move constructor throws.

Definition at line 173 of file status_or.h.

◆ StatusOr() [6/6]

template<typename T >

template<typename T >

StatusOr& google::cloud::StatusOr< T >::operator= ( Status status )

inline

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

Exceptions

std::invalid_argument if status.ok(). If exceptions are disabled the program terminates via google::cloud::Terminate()

Definition at line 141 of file status_or.h.

◆ operator=() [2/4]

template<typename T >

StatusOr& google::cloud::StatusOr< T >::operator= ( StatusOr< T > && other )

inline

Definition at line 111 of file status_or.h.

◆ operator=() [3/4]

template<typename T >

StatusOr& google::cloud::StatusOr< T >::operator= ( StatusOr< T > const & )

default

◆ operator=() [4/4]

template<typename T >

template<typename U = T>

template<typename T >

T const&& google::cloud::StatusOr< T >::value ( ) const &&

inline

Definition at line 240 of file status_or.h.

Public Types

Public Member Functions

Status accessors.

Detailed Description

template<typename T> class google::cloud::StatusOr< T >

Member Typedef Documentation

◆ value_type

Constructor & Destructor Documentation

◆ StatusOr() [1/6]

◆ StatusOr() [2/6]

◆ StatusOr() [3/6]

◆ StatusOr() [4/6]

◆ StatusOr() [5/6]

◆ StatusOr() [6/6]

Member Function Documentation

◆ ok()

◆ operator bool()

◆ operator*() [1/4]

◆ operator*() [2/4]

◆ operator*() [3/4]

◆ operator*() [4/4]

◆ operator->() [1/2]

◆ operator->() [2/2]

◆ operator=() [1/4]

◆ operator=() [2/4]

◆ operator=() [3/4]

◆ operator=() [4/4]

◆ status() [1/2]

◆ status() [2/2]

◆ value() [1/4]

◆ value() [2/4]

◆ value() [3/4]

◆ value() [4/4]

template<typename T>
class google::cloud::StatusOr< T >