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 (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, 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
	operator bool () const
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 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.

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

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

operator bool()

template<typename T >

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

inlineexplicit

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