google::cloud::StatusOr< T > Class Template Reference

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 (StatusCode::kUnknown). 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, typenamestd::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
	Returns true when this holds a value. More...
	operator bool () const
	Returns true when this holds a value. More...
Deference operators.
T &	operator* () &
T const &	operator* () const &
T &&	operator* () &&
T const &&	operator* () const &&
Member access operators.
T *	operator-> () &
T const *	operator-> () const &
Value accessors.
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: (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.

Template Parameters

T	the type of the value.

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.

Constructor & Destructor Documentation

StatusOr() [1/6]

template<typename T >

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

inline

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

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

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()

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.

StatusOr() [6/6]

template<typename T >

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

inline

Member Function Documentation

ok()

template<typename T >

bool google::cloud::StatusOr< T >::ok ( ) const

inline

Returns true when this holds a value.

operator bool()

template<typename T >

google::cloud::StatusOr< T >::operator bool ( ) const

inlineexplicit

Returns true when this holds a value.

operator*() [1/4]

template<typename T >

T & google::cloud::StatusOr< T >::operator* ( ) &

inline

operator*() [2/4]

template<typename T >

T && google::cloud::StatusOr< T >::operator* ( ) &&

inline

operator*() [3/4]

template<typename T >

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

inline

operator*() [4/4]

template<typename T >

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

inline

operator->() [1/2]

template<typename T >

T * google::cloud::StatusOr< T >::operator-> ( ) &

inline

operator->() [2/2]

template<typename T >

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

inline

operator=() [1/4]

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()

operator=() [2/4]

template<typename T >

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

inline

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>

std::enable_if<!std::is_same< StatusOr, typenamestd::decay< U >::type >::value, StatusOr >::type & google::cloud::StatusOr< T >::operator= ( U &&  rhs )

inline

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

status() [1/2]

template<typename T >

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

inline

status() [2/2]

template<typename T >

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

inline

value() [1/4]

template<typename T >

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

inline

value() [2/4]

template<typename T >

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

inline

value() [3/4]

template<typename T >

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

inline

value() [4/4]

template<typename T >

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

inline