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

A union of an object of type `T` and an `absl&colon;&colon;Status`&period;

== Synopsis

Declared in `&lt;absl&sol;status&sol;statusor&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;typename T&gt;
class &lsqb;&lsqb;nodiscard&rsqb;&rsqb; StatusOr;
----

== Description

The `absl&colon;&colon;StatusOr&lt;T&gt;` class template is a union of an `absl&colon;&colon;Status` object and an object of type `T`&period; The `absl&colon;&colon;StatusOr&lt;T&gt;` models an object that is either a usable object, or an error (of type `absl&colon;&colon;Status`) explaining why such an object is not present&period; An `absl&colon;&colon;StatusOr&lt;T&gt;` is typically the return value of a function which may fail&period;

An `absl&colon;&colon;StatusOr&lt;T&gt;` can never hold an &quot;OK&quot; status (an `absl&colon;&colon;StatusCode&colon;&colon;kOk` value)&semi; instead, the presence of an object of type `T` indicates success&period; Instead of checking for a `kOk` value, use the `absl&colon;&colon;StatusOr&lt;T&gt;&colon;&colon;ok()` member function&period; (It is for this reason, and code readability, that using the `ok()` function is preferred for `absl&colon;&colon;Status` as well&period;)

Example&colon;

StatusOr&lt;Foo&gt; result &equals; DoBigCalculationThatCouldFail()&semi; if (result&period;ok()) &lcub; result&hyphen;&gt;DoSomethingCool()&semi; &rcub; else &lcub; LOG(ERROR) &lt;&lt; result&period;status()&semi; &rcub;

Accessing the object held by an `absl&colon;&colon;StatusOr&lt;T&gt;` should be performed via `operator&ast;` or `operator&hyphen;&gt;`, after a call to `ok()` confirms that the `absl&colon;&colon;StatusOr&lt;T&gt;` holds an object of type `T`&colon;

Example&colon;

absl&colon;&colon;StatusOr&lt;int&gt; i &equals; GetCount()&semi; if (i&period;ok()) &lcub; updated&lowbar;total &plus;&equals; &ast;i&semi; &rcub;

NOTE&colon; using `absl&colon;&colon;StatusOr&lt;T&gt;&colon;&colon;value()` when no valid value is present will throw an exception if exceptions are enabled or terminate the process when exceptions are not enabled&period;

Example&colon;

StatusOr&lt;Foo&gt; result &equals; DoBigCalculationThatCouldFail()&semi; const Foo&amp; foo &equals; result&period;value()&semi; &sol;&sol; Crash&sol;exception if no value present foo&period;DoSomethingCool()&semi;

A `absl&colon;&colon;StatusOr&lt;T&ast;&gt;` 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`&period; Checking the value of pointer in an `absl&colon;&colon;StatusOr&lt;T&ast;&gt;` generally requires a bit more care, to ensure both that a value is present and that value is not null&colon;

StatusOr&lt;std&colon;&colon;unique&lowbar;ptr&lt;Foo&gt;&gt; result &equals; FooFactory&colon;&colon;MakeNewFoo(arg)&semi; if (!result&period;ok()) &lcub; LOG(ERROR) &lt;&lt; result&period;status()&semi; &rcub; else if (&ast;result &equals;&equals; nullptr) &lcub; LOG(ERROR) &lt;&lt; &quot;Unexpected null pointer&quot;&semi; &rcub; else &lcub; (&ast;result)&hyphen;&gt;DoSomethingCool()&semi; &rcub;

Example factory implementation returning StatusOr&lt;T&gt;&colon;

StatusOr&lt;Foo&gt; FooFactory&colon;&colon;MakeFoo(int arg) &lcub; if (arg &lt;&equals; 0) &lcub; return absl&colon;&colon;Status(absl&colon;&colon;StatusCode&colon;&colon;kInvalidArgument, &quot;Arg must be positive&quot;)&semi; &rcub; return Foo(arg)&semi; &rcub;

== Type Aliases

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


== 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&equals;`] 
| Assignment operators
| xref:absl/StatusOr/AddSourceLocation.adoc[`AddSourceLocation`] 
| Appends a source location to the status location chain&period;
| xref:absl/StatusOr/GetSourceLocations.adoc[`GetSourceLocations`] 
| Returns the chain of source locations recorded in the status&period;
| xref:absl/StatusOr/IgnoreError.adoc[`IgnoreError`] 
| Ignores any error held by this object&period;
| xref:absl/StatusOr/WithSourceLocation.adoc[`WithSourceLocation`] 
| Appends a source location and returns an rvalue reference to `&ast;this`&period;
| xref:absl/StatusOr/emplace-08.adoc[`emplace`] 
| `emplace` overloads
| xref:absl/StatusOr/ok.adoc[`ok`] 
| Returns whether this `StatusOr&lt;T&gt;` holds a value&period;
| xref:absl/StatusOr/status-0ec.adoc[`status`] 
| `status` overloads
| xref:absl/StatusOr/value_or-06.adoc[`value&lowbar;or`] 
| `value&lowbar;or` overloads
|===


== Using Declarations

[cols="1"]
|===
| Name
| xref:absl/StatusOr/AssignStatus.adoc[`AssignStatus`] 
| xref:absl/StatusOr/operator*.adoc[`operator&ast;`] 
| xref:absl/StatusOr/operator->.adoc[`operator&hyphen;&gt;`] 
| xref:absl/StatusOr/value.adoc[`value`] 
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `absl::internal&lowbar;statusor::OperatorBase`
| 
| `absl::StatusOr`
| A union of an object of type `T` and an `absl&colon;&colon;Status`&period;
|===

== Non-Member Functions

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

== 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&period;
|===


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