Google Cloud C++ Client  1.32.1
C++ Client Library for Google Cloud Platform
Public Types | Public Member Functions | List of all members
google::cloud::v1::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 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
 
StatusOroperator= (StatusOr const &)=default
 
 StatusOr (StatusOr &&)=default
 
StatusOroperator= (StatusOr &&)=default
 
 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...
 
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::v1::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 89 of file status_or.h.

Member Typedef Documentation

◆ value_type

template<typename T >
using google::cloud::v1::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::v1::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::v1::StatusOr< T >::StatusOr ( StatusOr< T > const &  )
default

◆ StatusOr() [3/6]

template<typename T >
google::cloud::v1::StatusOr< T >::StatusOr ( StatusOr< T > &&  )
default

◆ StatusOr() [4/6]

template<typename T >
google::cloud::v1::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 121 of file status_or.h.

◆ StatusOr() [5/6]

template<typename T >
google::cloud::v1::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 165 of file status_or.h.

◆ StatusOr() [6/6]

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

Definition at line 168 of file status_or.h.

Member Function Documentation

◆ ok()

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

Definition at line 170 of file status_or.h.

◆ operator bool()

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

Definition at line 171 of file status_or.h.

◆ operator*() [1/4]

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

Definition at line 183 of file status_or.h.

◆ operator*() [2/4]

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

Definition at line 187 of file status_or.h.

◆ operator*() [3/4]

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

Definition at line 185 of file status_or.h.

◆ operator*() [4/4]

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

Definition at line 189 of file status_or.h.

◆ operator->() [1/2]

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

Definition at line 202 of file status_or.h.

◆ operator->() [2/2]

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

Definition at line 204 of file status_or.h.

◆ operator=() [1/4]

template<typename T >
StatusOr& google::cloud::v1::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 133 of file status_or.h.

◆ operator=() [2/4]

template<typename T >
StatusOr& google::cloud::v1::StatusOr< T >::operator= ( StatusOr< T > &&  )
default

◆ operator=() [3/4]

template<typename T >
StatusOr& google::cloud::v1::StatusOr< T >::operator= ( StatusOr< T > const &  )
default

◆ 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::v1::StatusOr< T >::operator= ( U &&  rhs)
inline

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

Definition at line 148 of file status_or.h.

◆ status() [1/2]

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

Definition at line 245 of file status_or.h.

◆ status() [2/2]

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

Definition at line 244 of file status_or.h.

◆ value() [1/4]

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

Definition at line 217 of file status_or.h.

◆ value() [2/4]

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

Definition at line 227 of file status_or.h.

◆ value() [3/4]

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

Definition at line 222 of file status_or.h.

◆ value() [4/4]

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

Definition at line 232 of file status_or.h.