Asylo
Classes | Public Member Functions | Friends | List of all members
asylo::StatusOr< T > Class Template Reference

A class for representing either a usable value, or an error. More...

#include <statusor.h>

Public Member Functions

 StatusOr ()
 Constructs a StatusOr object that contains a non-OK status. More...
 
 ~StatusOr ()
 
 StatusOr (const Status &status)
 Constructs a StatusOr object with the given non-OK Status object. More...
 
template<typename U , typename E = typename std::enable_if< is_implicitly_constructible<T, U>::value>::type>
 StatusOr (U &&value)
 Constructs a StatusOr object that contains value. More...
 
 StatusOr (const StatusOr &other)
 Copy constructor. More...
 
template<typename U , typename E = typename std::enable_if< is_implicitly_constructible<T, const U &>::value>::type>
 StatusOr (const StatusOr< U > &other)
 Templatized constructor that constructs a StatusOr<T> from a const reference to a StatusOr<U>. More...
 
StatusOroperator= (const StatusOr &other)
 Copy-assignment operator. More...
 
template<typename U , typename E = typename std::enable_if< is_implicitly_constructible<T, U &&>::value>::type>
 StatusOr (StatusOr< U > &&other)
 Templatized constructor which constructs a StatusOr<T> by moving the contents of a StatusOr<U>. More...
 
StatusOroperator= (StatusOr &&other)
 Move-assignment operator. More...
 
bool ok () const
 Indicates whether the object contains a T value. More...
 
Status status () const
 Gets the stored status object, or an OK status if a T value is stored. More...
 
const T & ValueOrDie () const &
 Gets the stored T value. More...
 
T & ValueOrDie () &
 Gets a mutable reference to the stored T value. More...
 
ValueOrDie () &&
 Moves and returns the internally-stored T value. More...
 

Friends

template<typename U >
class StatusOr
 

Detailed Description

template<class T>
class asylo::StatusOr< T >

A class for representing either a usable value, or an error.

A StatusOr object either contains a value of type T or a Status object explaining why such a value is not present. The type T must be copy-constructible and/or move-constructible.

The state of a StatusOr object may be determined by calling ok() or status(). The ok() method returns true if the object contains a valid value. The status() method returns the internal Status object. A StatusOr object that contains a valid value will return an OK Status for a call to status().

A value of type T may be extracted from a StatusOr object through a call to ValueOrDie(). This function should only be called if a call to ok() returns true. Sample usage:

asylo::StatusOr<Foo> result = CalculateFoo();
if (result.ok()) {
Foo foo = result.ValueOrDie();
foo->DoSomethingCool();
} else {
LOG(ERROR) << result.status();
}

If T is a move-only type, like std::unique_ptr<>, then the value should only be extracted after invoking std::move() on the StatusOr object. Sample usage:

if (result.ok()) {
std::unique_ptr<Foo> foo = std::move(result).ValueOrDie();
foo->DoSomethingCool();
} else {
LOG(ERROR) << result.status();
}

StatusOr is provided for the convenience of implementing functions that return some value but may fail during execution. For instance, consider a function with the following signature:

asylo::Status CalculateFoo(int *output);

This function may instead be written as:

asylo::StatusOr<int> CalculateFoo();

Constructor & Destructor Documentation

◆ StatusOr() [1/6]

template<class T>
asylo::StatusOr< T >::StatusOr ( )
inlineexplicit

Constructs a StatusOr object that contains a non-OK status.

The non-OK status has an error code of -1. This is a non-standard POSIX error code and is used in this context to indicate an unknown error.

This constructor is marked explicit to prevent attempts to return {} from a function with a return type of, for example, StatusOr<std::vector<int>>. While return {} seems like it would return an empty vector, it will actually invoke the default constructor of StatusOr.

◆ ~StatusOr()

template<class T>
asylo::StatusOr< T >::~StatusOr ( )
inline

◆ StatusOr() [2/6]

template<class T>
asylo::StatusOr< T >::StatusOr ( const Status status)
inline

Constructs a StatusOr object with the given non-OK Status object.

All calls to ValueOrDie() on this object will abort. The given status must not be an OK status, otherwise this constructor will abort.

This constructor is not declared explicit so that a function with a return type of StatusOr<T> can return a Status object, and the status will be implicitly converted to the appropriate return type as a matter of convenience.

Parameters
statusThe non-OK Status object to initalize to.

◆ StatusOr() [3/6]

template<class T>
template<typename U , typename E = typename std::enable_if< is_implicitly_constructible<T, U>::value>::type>
asylo::StatusOr< T >::StatusOr ( U &&  value)
inline

Constructs a StatusOr object that contains value.

The resulting object is considered to have an OK status. The wrapped element can be accessed with ValueOrDie().

This constructor is made implicit so that a function with a return type of StatusOr<T> can return an object of type U &&, implicitly converting it to a StatusOr<T> object.

Note that T must be implicitly constructible from U. Due to C++ reference-collapsing rules and perfect-forwarding semantics, this constructor matches invocations that pass value either as a const reference or as an rvalue reference. See http://thbecker.net/articles/rvalue_references/section_08.html for additional details.

Parameters
valueThe value to initialize to.

◆ StatusOr() [4/6]

template<class T>
asylo::StatusOr< T >::StatusOr ( const StatusOr< T > &  other)
inline

Copy constructor.

This constructor needs to be explicitly defined because the presence of the move-assignment operator deletes the default copy constructor. In such a scenario, since the deleted copy constructor has stricter binding rules than the templated copy constructor, the templated constructor cannot act as a copy constructor, and any attempt to copy-construct a StatusOr object results in a compilation error.

Parameters
otherThe value to copy from.

◆ StatusOr() [5/6]

template<class T>
template<typename U , typename E = typename std::enable_if< is_implicitly_constructible<T, const U &>::value>::type>
asylo::StatusOr< T >::StatusOr ( const StatusOr< U > &  other)
inline

Templatized constructor that constructs a StatusOr<T> from a const reference to a StatusOr<U>.

T must be implicitly constructible from const U &.

Parameters
otherThe value to copy from.

◆ StatusOr() [6/6]

template<class T>
template<typename U , typename E = typename std::enable_if< is_implicitly_constructible<T, U &&>::value>::type>
asylo::StatusOr< T >::StatusOr ( StatusOr< U > &&  other)
inline

Templatized constructor which constructs a StatusOr<T> by moving the contents of a StatusOr<U>.

T must be implicitly constructible from U &&.

Sets other to contain a non-OK status with aStatusError::MOVED error code.

Parameters
otherThe StatusOr object to move from and set to a non-OK status.

Member Function Documentation

◆ ok()

template<class T>
bool asylo::StatusOr< T >::ok ( ) const
inline

Indicates whether the object contains a T value.

Returns
True if this StatusOr object's status is OK (i.e. a call to ok() returns true). If this function returns true, then it is safe to access the wrapped element through a call to ValueOrDie().

◆ operator=() [1/2]

template<class T>
StatusOr& asylo::StatusOr< T >::operator= ( const StatusOr< T > &  other)
inline

Copy-assignment operator.

Parameters
otherThe StatusOr object to copy.

◆ operator=() [2/2]

template<class T>
StatusOr& asylo::StatusOr< T >::operator= ( StatusOr< T > &&  other)
inline

Move-assignment operator.

Sets other to contain a non-OK status with a StatusError::MOVED error code.

Parameters
otherThe StatusOr object to assign from and set to a non-OK status.

◆ status()

template<class T>
Status asylo::StatusOr< T >::status ( ) const
inline

Gets the stored status object, or an OK status if a T value is stored.

Returns
The stored non-OK status object, or an OK status if this object has a value.

◆ ValueOrDie() [1/3]

template<class T>
const T& asylo::StatusOr< T >::ValueOrDie ( ) const &
inline

Gets the stored T value.

This method should only be called if this StatusOr object's status is OK (i.e. a call to ok() returns true), otherwise this call will abort.

Returns
The stored T value.

◆ ValueOrDie() [2/3]

template<class T>
T& asylo::StatusOr< T >::ValueOrDie ( ) &
inline

Gets a mutable reference to the stored T value.

This method should only be called if this StatusOr object's status is OK (i.e. a call to ok() returns true), otherwise this call will abort.

Returns
The stored T value.

◆ ValueOrDie() [3/3]

template<class T>
T asylo::StatusOr< T >::ValueOrDie ( ) &&
inline

Moves and returns the internally-stored T value.

This method should only be called if this StatusOr object's status is OK (i.e. a call to ok() returns true), otherwise this call will abort. The StatusOr object is invalidated after this call and will be updated to contain a non-OK status with a StatusError::MOVED error code.

Returns
The stored T value.

Friends And Related Function Documentation

◆ StatusOr

template<class T>
template<typename U >
friend class StatusOr
friend

The documentation for this class was generated from the following file: