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

#include <google/cloud/status_or.h>

Public Member Functions
	StatusOr ()
	Initializes with an error status (UNKNOWN). More...

	StatusOr (Status rhs)
	Creates a new `StatusOr<T>` holding the error condition `rhs`. More...

	StatusOr (StatusOr &&rhs)

StatusOr &	operator= (StatusOr &&rhs)

	StatusOr (StatusOr const &rhs)

StatusOr &	operator= (StatusOr const &rhs)

	~StatusOr ()

template<typename U = T>
std::enable_if< not 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.
T &	operator* () &

T const &	operator* () const &

T &&	operator* () &&

Member access operators.
T *	operator-> () &

T const *	operator-> () const &

Value accessors.
T &	value () &

T const &	value () const &

T &&	value () &&

Status accessors.
Returns All these member functions return the (properly ref and const-qualified) status. If the object contains a value then `status().ok() == true`.
Status &	status () &

Status const &	status () const &

Status &&	status () &&

Detailed Description

template<typename T>
class google::cloud::v0::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));
}

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 84 of file status_or.h.

Constructor & Destructor Documentation

◆ StatusOr() [1/6]

template<typename T >

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

inline

Initializes with an error status (UNKNOWN).

TODO(#548) - currently storage::Status does not define the status codes, they are simply integers, usually HTTP status codes. We need to map to the well-defined set of status codes.

Definition at line 93 of file status_or.h.

◆ StatusOr() [2/6]

template<typename T >

google::cloud::v0::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 106 of file status_or.h.

◆ StatusOr() [3/6]

template<typename T >

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

inline

Definition at line 112 of file status_or.h.

◆ StatusOr() [4/6]

template<typename T >

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

inline

Definition at line 141 of file status_or.h.

◆ ~StatusOr()

template<typename T >

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

inline

Definition at line 170 of file status_or.h.

◆ StatusOr() [5/6]

template<typename T >

google::cloud::v0::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 211 of file status_or.h.

◆ StatusOr() [6/6]

template<typename T >

template<typename T >

template<typename U = T>

template<typename T >

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

inline

Definition at line 275 of file status_or.h.

Member Data Documentation

◆ value_

template<typename T >

T google::cloud::v0::StatusOr< T >::value_

Definition at line 320 of file status_or.h.

Public Member Functions

Detailed Description

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

Constructor & Destructor Documentation

◆ StatusOr() [1/6]

◆ StatusOr() [2/6]

◆ StatusOr() [3/6]

◆ StatusOr() [4/6]

◆ ~StatusOr()

◆ StatusOr() [5/6]

◆ StatusOr() [6/6]

Member Function Documentation

◆ ok()

◆ operator bool()

◆ operator*() [1/3]

◆ operator*() [2/3]

◆ operator*() [3/3]

◆ operator->() [1/2]

◆ operator->() [2/2]

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ status() [1/3]

◆ status() [2/3]

◆ status() [3/3]

◆ value() [1/3]

◆ value() [2/3]

◆ value() [3/3]

Member Data Documentation

◆ value_

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