Google Cloud C++ Client  0.10.0
C++ Client Library for Google Cloud Platform
Public Member Functions | List of all members
google::cloud::v0::StatusOr< T > Class Template Referencefinal

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...
 
StatusOroperator= (Status status)
 Assigns the given non-OK Status to this StatusOr<T>. More...
 
 StatusOr (StatusOr &&rhs)
 
StatusOroperator= (StatusOr &&rhs)
 
 StatusOr (StatusOr const &rhs)
 
StatusOroperator= (StatusOr const &rhs)
 
 ~StatusOr ()
 
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.
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.
Statusstatus () &
 
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));
}

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
Tthe type of the value.

Definition at line 86 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 95 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
rhsthe status to initialize the object.
Exceptions
std::invalid_argumentif rhs.ok(). If exceptions are disabled the program terminates via google::cloud::Terminate()

Definition at line 108 of file status_or.h.

◆ StatusOr() [3/6]

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

Definition at line 124 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 153 of file status_or.h.

◆ ~StatusOr()

template<typename T >
google::cloud::v0::StatusOr< T >::~StatusOr ( )
inline

Definition at line 182 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
rhsthe value used to initialize the object.
Exceptions
onlyif T's move constructor throws.

Definition at line 223 of file status_or.h.

◆ StatusOr() [6/6]

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

Definition at line 226 of file status_or.h.

Member Function Documentation

◆ ok()

template<typename T >
bool google::cloud::v0::StatusOr< T >::ok ( ) const
inline

Definition at line 228 of file status_or.h.

◆ operator bool()

template<typename T >
google::cloud::v0::StatusOr< T >::operator bool ( ) const
inlineexplicit

Definition at line 229 of file status_or.h.

◆ operator*() [1/3]

template<typename T >
T& google::cloud::v0::StatusOr< T >::operator* ( ) &
inline

Definition at line 241 of file status_or.h.

◆ operator*() [2/3]

template<typename T >
T const& google::cloud::v0::StatusOr< T >::operator* ( ) const &
inline

Definition at line 243 of file status_or.h.

◆ operator*() [3/3]

template<typename T >
T&& google::cloud::v0::StatusOr< T >::operator* ( ) &&
inline

Definition at line 245 of file status_or.h.

◆ operator->() [1/2]

template<typename T >
T* google::cloud::v0::StatusOr< T >::operator-> ( ) &
inline

Definition at line 262 of file status_or.h.

◆ operator->() [2/2]

template<typename T >
T const* google::cloud::v0::StatusOr< T >::operator-> ( ) const &
inline

Definition at line 264 of file status_or.h.

◆ operator=() [1/4]

template<typename T >
StatusOr& google::cloud::v0::StatusOr< T >::operator= ( Status  status)
inline

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

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

Definition at line 120 of file status_or.h.

◆ operator=() [2/4]

template<typename T >
StatusOr& google::cloud::v0::StatusOr< T >::operator= ( StatusOr< T > &&  rhs)
inline

Definition at line 130 of file status_or.h.

◆ operator=() [3/4]

template<typename T >
StatusOr& google::cloud::v0::StatusOr< T >::operator= ( StatusOr< T > const &  rhs)
inline

Definition at line 159 of file status_or.h.

◆ operator=() [4/4]

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

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

Definition at line 198 of file status_or.h.

◆ status() [1/3]

template<typename T >
Status& google::cloud::v0::StatusOr< T >::status ( ) &
inline

Definition at line 308 of file status_or.h.

◆ status() [2/3]

template<typename T >
Status const& google::cloud::v0::StatusOr< T >::status ( ) const &
inline

Definition at line 309 of file status_or.h.

◆ status() [3/3]

template<typename T >
Status&& google::cloud::v0::StatusOr< T >::status ( ) &&
inline

Definition at line 310 of file status_or.h.

◆ value() [1/3]

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

Definition at line 277 of file status_or.h.

◆ value() [2/3]

template<typename T >
T const& google::cloud::v0::StatusOr< T >::value ( ) const &
inline

Definition at line 282 of file status_or.h.

◆ value() [3/3]

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

Definition at line 287 of file status_or.h.

Member Data Documentation

◆ value_

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

Definition at line 332 of file status_or.h.