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.
Constructors
StatusOr
Initializes with an error status (StatusCode::kUnknown
).
StatusOr
Parameter | |
---|---|
Name | Description |
|
StatusOr const &
|
StatusOr
Parameter | |
---|---|
Name | Description |
other |
StatusOr &&
|
StatusOr
Creates a new StatusOr
<T>
holding the error condition rhs
.
Parameter | |
---|---|
Name | Description |
rhs |
Status
the status to initialize the object. |
StatusOr
Creates a new StatusOr
<T>
holding the value rhs
.
Parameter | |
---|---|
Name | Description |
rhs |
T &&
the value used to initialize the object. |
StatusOr
Parameter | |
---|---|
Name | Description |
rhs |
T const &
|
Operators
operator*
Returns | |
---|---|
Type | Description |
T & |
operator*
Returns | |
---|---|
Type | Description |
T const & |
operator*
Returns | |
---|---|
Type | Description |
T && |
operator*
Returns | |
---|---|
Type | Description |
T const && |
operator->
Returns | |
---|---|
Type | Description |
T * |
operator->
Returns | |
---|---|
Type | Description |
T const * |
operator=
Parameter | |
---|---|
Name | Description |
|
StatusOr const &
|
Returns | |
---|---|
Type | Description |
StatusOr & |
operator=
Parameter | |
---|---|
Name | Description |
other |
StatusOr &&
|
Returns | |
---|---|
Type | Description |
StatusOr & |
operator=
Parameter | |
---|---|
Name | Description |
status |
Status
|
Returns | |
---|---|
Type | Description |
StatusOr & |
operator=
Assign a T
(or anything convertible to T
) into the StatusOr
.
Parameters | |
---|---|
Name | Description |
rhs |
U &&
|
typename U |
|
Returns | |
---|---|
Type | Description |
std::enable_if<!std::is_same< StatusOr, typenamestd::decay< U >::type >::value, StatusOr >::type & |
operator bool
Returns true
when this
holds a value.
Functions
value
Returns | |
---|---|
Type | Description |
T & |
value
Returns | |
---|---|
Type | Description |
T const & |
value
Returns | |
---|---|
Type | Description |
T && |
value
Returns | |
---|---|
Type | Description |
T const && |
status
Returns | |
---|---|
Type | Description |
Status const & |
status
Returns | |
---|---|
Type | Description |
Status && |
ok
Returns true
when this
holds a value.
Returns | |
---|---|
Type | Description |
bool |