[#absl-StatusOr]
= xref:absl.adoc[absl]::StatusOr
:relfileprefix: ../
:mrdocs:

A union of an object of type `T` and an `absl::Status`.

== Synopsis

Declared in `<absl/status/statusor.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<typename T>
class [[nodiscard]] StatusOr;
----

== Description

The `absl::StatusOr<T>` class template is a union of an `absl::Status` object and an object of type `T`. The `absl::StatusOr<T>` models an object that is either a usable object, or an error (of type `absl::Status`) explaining why such an object is not present. An `absl::StatusOr<T>` is typically the return value of a function which may fail.

An `absl::StatusOr<T>` can never hold an "OK" status (an `absl::StatusCode::kOk` value); instead, the presence of an object of type `T` indicates success. Instead of checking for a `kOk` value, use the `absl::StatusOr<T>::ok()` member function. (It is for this reason, and code readability, that using the `ok()` function is preferred for `absl::Status` as well.)

Example:

StatusOr<Foo> result = DoBigCalculationThatCouldFail(); if (result.ok()) { result‐>DoSomethingCool(); } else { LOG(ERROR) << result.status(); }

Accessing the object held by an `absl::StatusOr<T>` should be performed via `operator*` or `operator‐>`, after a call to `ok()` confirms that the `absl::StatusOr<T>` holds an object of type `T`:

Example:

absl::StatusOr<int> i = GetCount(); if (i.ok()) { updated_total += *i; }

NOTE: using `absl::StatusOr<T>::value()` when no valid value is present will throw an exception if exceptions are enabled or terminate the process when exceptions are not enabled.

Example:

StatusOr<Foo> result = DoBigCalculationThatCouldFail(); const Foo& foo = result.value(); // Crash/exception if no value present foo.DoSomethingCool();

A `absl::StatusOr<T*>` can be constructed from a null pointer like any other pointer value, and the result will be that `ok()` returns `true` and `value()` returns `nullptr`. Checking the value of pointer in an `absl::StatusOr<T*>` generally requires a bit more care, to ensure both that a value is present and that value is not null:

StatusOr<std::unique_ptr<Foo>> result = FooFactory::MakeNewFoo(arg); if (!result.ok()) { LOG(ERROR) << result.status(); } else if (*result == nullptr) { LOG(ERROR) << "Unexpected null pointer"; } else { (*result)‐>DoSomethingCool(); }

Example factory implementation returning StatusOr<T>:

StatusOr<Foo> FooFactory::MakeFoo(int arg) { if (arg <= 0) { return absl::Status(absl::StatusCode::kInvalidArgument, "Arg must be positive"); } return Foo(arg); }

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:absl/StatusOr/value_type.adoc[`value_type`] 
| Generic value type alias for the held type `T`.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:absl/StatusOr/2constructor-087.adoc[`StatusOr`]         [.small]#[constructor]#
| Constructors
| xref:absl/StatusOr/operator_assign-0b.adoc[`operator=`] 
| Assignment operators
| xref:absl/StatusOr/AddSourceLocation.adoc[`AddSourceLocation`] 
| Appends a source location to the status location chain.
| xref:absl/StatusOr/GetSourceLocations.adoc[`GetSourceLocations`] 
| Returns the chain of source locations recorded in the status.
| xref:absl/StatusOr/IgnoreError.adoc[`IgnoreError`] 
| Ignores any error held by this object.
| xref:absl/StatusOr/WithSourceLocation.adoc[`WithSourceLocation`] 
| Appends a source location and returns an rvalue reference to `*this`.
| xref:absl/StatusOr/emplace-08.adoc[`emplace`] 
| `emplace` overloads
| xref:absl/StatusOr/ok.adoc[`ok`] 
| Returns whether this `StatusOr<T>` holds a value.
| xref:absl/StatusOr/status-0ec.adoc[`status`] 
| `status` overloads
| xref:absl/StatusOr/value_or-06.adoc[`value_or`] 
| `value_or` overloads
|===


== Using Declarations

[cols="1"]
|===
| Name
| xref:absl/StatusOr/AssignStatus.adoc[`AssignStatus`] 
| xref:absl/StatusOr/operator*.adoc[`operator*`] 
| xref:absl/StatusOr/operator->.adoc[`operator‐>`] 
| xref:absl/StatusOr/value.adoc[`value`] 
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `absl::internal_statusor::OperatorBase`
| 
| `absl::StatusOr`
| A union of an object of type `T` and an `absl::Status`.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:absl/MarshalHashtableProfile.adoc[`MarshalHashtableProfile`]
| Serialize the current hash table profile into a string.
| xref:absl/operator_not_eq-048f.adoc[`operator!=`]
| Checks the inequality of two `absl::StatusOr<T>` objects.
| xref:absl/operator_eq-036.adoc[`operator==`]
| Checks the equality of two `absl::StatusOr<T>` objects.
|===

== Return Value

[NOTE]
====
The return value https://en.cppreference.com/cpp/language/attributes/nodiscard[should not be discarded^].
====
== Template Parameters

[cols="1,4"]
|===
| Name| Description
| *T*
| The type of the value held on success.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#