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

A type used to gracefully handle errors across API boundaries&period;

== Synopsis

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

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class &lsqb;&lsqb;nodiscard&rsqb;&rsqb; Status final
----

== Description

The `absl&colon;&colon;Status` class is generally used to gracefully handle errors across API boundaries (and in particular across RPC boundaries)&period; Some of these errors may be recoverable, but others may not&period; Most functions which can produce a recoverable error should be designed to return either an `absl&colon;&colon;Status` (or the similar `absl&colon;&colon;StatusOr&lt;T&gt;`, which holds either an object of type `T` or an error)&period;

API developers should construct their functions to return `absl&colon;&colon;OkStatus()` upon success, or an `absl&colon;&colon;StatusCode` upon another type of error (e&period;g an `absl&colon;&colon;StatusCode&colon;&colon;kInvalidArgument` error)&period; The API provides convenience functions to construct each status code&period;

Example&colon;

absl&colon;&colon;Status myFunction(absl&colon;&colon;string&lowbar;view fname, &period;&period;&period;) &lcub; &period;&period;&period; &sol;&sol; encounter error if (error condition) &lcub; &sol;&sol; Construct an absl&colon;&colon;StatusCode&colon;&colon;kInvalidArgument error return absl&colon;&colon;InvalidArgumentError(&quot;bad mode&quot;)&semi; &rcub; &sol;&sol; else, return OK return absl&colon;&colon;OkStatus()&semi; &rcub;

Users handling status error codes should prefer checking for an OK status using the `ok()` member function&period; Handling multiple error codes may justify use of switch statement, but only check for error codes you know how to handle&semi; do not try to exhaustively match against all canonical error codes&period; Errors that cannot be handled should be logged and&sol;or propagated for higher levels to deal with&period; If you do use a switch statement, make sure that you also provide a `default&colon;` switch case, so that code does not break as other canonical codes are added to the API&period;

Example&colon;

absl&colon;&colon;Status result &equals; DoSomething()&semi; if (!result&period;ok()) &lcub; LOG(ERROR) &lt;&lt; result&semi; &rcub;

&sol;&sol; Provide a default if switching on multiple error codes switch (result&period;code()) &lcub; &sol;&sol; The user hasn&apos;t authenticated&period; Ask them to reauth case absl&colon;&colon;StatusCode&colon;&colon;kUnauthenticated&colon; DoReAuth()&semi; break&semi; &sol;&sol; The user does not have permission&period; Log an error&period; case absl&colon;&colon;StatusCode&colon;&colon;kPermissionDenied&colon; LOG(ERROR) &lt;&lt; result&semi; break&semi; &sol;&sol; Propagate the error otherwise&period; default&colon; return true&semi; &rcub;

An `absl&colon;&colon;Status` can optionally include a payload with more information about the error&period; Typically, this payload serves one of several purposes&colon;

&ast; It may provide more fine&hyphen;grained semantic information about the error to facilitate actionable remedies&period; &ast; It may provide human&hyphen;readable contextual information that is more appropriate to display to an end user&period;

Example&colon;

absl&colon;&colon;Status result &equals; DoSomething()&semi; &sol;&sol; Inform user to retry after 30 seconds &sol;&sol; See more error details in googleapis&sol;google&sol;rpc&sol;error&lowbar;details&period;proto if (absl&colon;&colon;IsResourceExhausted(result)) &lcub; google&colon;&colon;rpc&colon;&colon;RetryInfo info&semi; info&period;retry&lowbar;delay()&period;seconds() &equals; 30&semi; &sol;&sol; Payloads require a unique key (a URL to ensure no collisions with &sol;&sol; other payloads), and an `absl&colon;&colon;Cord` to hold the encoded data&period; absl&colon;&colon;string&lowbar;view url &equals; &quot;type&period;googleapis&period;com&sol;google&period;rpc&period;RetryInfo&quot;&semi; result&period;SetPayload(url, info&period;SerializeAsCord())&semi; return result&semi; &rcub;

For documentation see https&colon;&sol;&sol;abseil&period;io&sol;docs&sol;cpp&sol;guides&sol;status&period;

Returned Status objects may not be ignored&period; status&lowbar;internal&period;h has a forward declaration of the form class ABSL&lowbar;MUST&lowbar;USE&lowbar;RESULT Status&semi;

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:absl/Status/2constructor-08b.adoc[`Status`]         [.small]#[constructor]#
| Constructors
| xref:absl/Status/2destructor.adoc[`&#126;Status`] [.small]#[destructor]#
| Destroys the status and releases any owned resources&period;
| xref:absl/Status/operator_assign-06.adoc[`operator&equals;`] 
| Assignment operators
| xref:absl/Status/AddSourceLocation.adoc[`AddSourceLocation`] 
| Appends the `loc` to the current location chain inside the status, iff the status is non&hyphen;ok and contains a non&hyphen;empty message&period;
| xref:absl/Status/ErasePayload.adoc[`ErasePayload`] 
| Erases the payload corresponding to the `type&lowbar;url` key&period;
| xref:absl/Status/ForEachPayload.adoc[`ForEachPayload`] 
| Iterates over the stored payloads and calls the `visitor(type&lowbar;key, payload)` callable for each one&period;
| xref:absl/Status/GetPayload.adoc[`GetPayload`] 
| Gets the payload of a status given its unique `type&lowbar;url` key, if present&period;
| xref:absl/Status/GetSourceLocations.adoc[`GetSourceLocations`] 
| Returns the source locations attached to this status&period;
| xref:absl/Status/IgnoreError.adoc[`IgnoreError`] 
| Ignores any errors&period;
| xref:absl/Status/SetPayload.adoc[`SetPayload`] 
| Sets the payload for a non&hyphen;ok status using a `type&lowbar;url` key, overwriting any existing payload for that `type&lowbar;url`&period;
| xref:absl/Status/ToString.adoc[`ToString`] 
| Returns a string based on the `mode`&period;
| xref:absl/Status/Update-06.adoc[`Update`] 
| `Update` overloads
| xref:absl/Status/WithSourceLocation-0c.adoc[`WithSourceLocation`] 
| `WithSourceLocation` overloads
| xref:absl/Status/code.adoc[`code`] 
| Returns the canonical error code of type `absl&colon;&colon;StatusCode` of this status&period;
| xref:absl/Status/message.adoc[`message`] 
| Returns the error message associated with this error code, if available&period;
| xref:absl/Status/ok.adoc[`ok`] 
| Returns `true` if `this&hyphen;&gt;code()` &equals;&equals; `absl&colon;&colon;StatusCode&colon;&colon;kOk`, indicating the absence of an error&period;
| xref:absl/Status/raw_code.adoc[`raw&lowbar;code`] 
| Returns a raw (canonical) error code corresponding to the enum value of `google&period;rpc&period;Code` definitions within https&colon;&sol;&sol;github&period;com&sol;googleapis&sol;googleapis&sol;blob&sol;master&sol;google&sol;rpc&sol;code&period;proto&period; These values could be out of the range of canonical `absl&colon;&colon;StatusCode` enum values&period;
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `absl::status&lowbar;internal::StatusRep`
| 
| `xref:absl/MakeStatusRepImpl.adoc[absl::MakeStatusRepImpl]`
| Builds a status representation from an inlined rep and a message&period;
| `xref:absl/StatusOr.adoc[absl::StatusOr]`
| A union of an object of type `T` and an `absl&colon;&colon;Status`&period;
| `absl::status&lowbar;internal::StatusPrivateAccessorForStatusBuilder`
| 
| `absl::status&lowbar;internal::StatusPrivateAccessor`
| 
| `xref:absl/CancelledError-0a.adoc[absl::CancelledError]`
| Creates a `Status` object with the `absl&colon;&colon;StatusCode&colon;&colon;kCancelled` error code and an empty message&period;
| `xref:absl/swap-028.adoc[absl::swap]`
| Swaps the contents of one status with another&period;
| `xref:absl/AbslStringify-01d.adoc[absl::AbslStringify]`
| Support `absl&colon;&colon;StrCat`, `absl&colon;&colon;StrFormat`, etc&period;
| `xref:absl/operator_not_eq-0988.adoc[absl::operator!&equals;]`
| Compares two statuses for inequality&period;
| `xref:absl/operator_eq-0b3.adoc[absl::operator&equals;&equals;]`
| Compares two statuses for equality&period;
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:absl/AbortedError-02.adoc[`AbortedError`]
| Creates a status with the `kAborted` error code and `message`&period;
| xref:absl/AbortedError-0c.adoc[`AbortedError`]
| Creates a status with the `kAborted` error code and `message`&period;
| xref:absl/AlreadyExistsError-02.adoc[`AlreadyExistsError`]
| Creates a status with the `kAlreadyExists` error code and `message`&period;
| xref:absl/AlreadyExistsError-0e.adoc[`AlreadyExistsError`]
| Creates a status with the `kAlreadyExists` error code and `message`&period;
| xref:absl/CancelledError-001.adoc[`CancelledError`]
| Creates a status with the `kCancelled` error code and `message`&period;
| xref:absl/CancelledError-06.adoc[`CancelledError`]
| Creates a status with the `kCancelled` error code and `message`&period;
| xref:absl/DataLossError-09.adoc[`DataLossError`]
| Creates a status with the `kDataLoss` error code and `message`&period;
| xref:absl/DataLossError-0a.adoc[`DataLossError`]
| Creates a status with the `kDataLoss` error code and `message`&period;
| xref:absl/DeadlineExceededError-073.adoc[`DeadlineExceededError`]
| Creates a status with the `kDeadlineExceeded` error code and `message`&period;
| xref:absl/DeadlineExceededError-075.adoc[`DeadlineExceededError`]
| Creates a status with the `kDeadlineExceeded` error code and `message`&period;
| xref:absl/ErrnoToStatus.adoc[`ErrnoToStatus`]
| Convenience function that creates a `absl&colon;&colon;Status` using an `error&lowbar;number`, which should be an `errno` value&period;
| xref:absl/FailedPreconditionError-00.adoc[`FailedPreconditionError`]
| Creates a status with the `kFailedPrecondition` error code and `message`&period;
| xref:absl/FailedPreconditionError-0f.adoc[`FailedPreconditionError`]
| Creates a status with the `kFailedPrecondition` error code and `message`&period;
| xref:absl/InternalError-0c.adoc[`InternalError`]
| Creates a status with the `kInternal` error code and `message`&period;
| xref:absl/InternalError-0f.adoc[`InternalError`]
| Creates a status with the `kInternal` error code and `message`&period;
| xref:absl/InvalidArgumentError-06.adoc[`InvalidArgumentError`]
| Creates a status with the `kInvalidArgument` error code and `message`&period;
| xref:absl/InvalidArgumentError-07.adoc[`InvalidArgumentError`]
| Creates a status with the `kInvalidArgument` error code and `message`&period;
| xref:absl/IsAborted.adoc[`IsAborted`]
| Returns `true` if `status` has the `kAborted` error code&period;
| xref:absl/IsAlreadyExists.adoc[`IsAlreadyExists`]
| Returns `true` if `status` has the `kAlreadyExists` error code&period;
| xref:absl/IsCancelled.adoc[`IsCancelled`]
| Returns `true` if `status` has the `kCancelled` error code&period;
| xref:absl/IsDataLoss.adoc[`IsDataLoss`]
| Returns `true` if `status` has the `kDataLoss` error code&period;
| xref:absl/IsDeadlineExceeded.adoc[`IsDeadlineExceeded`]
| Returns `true` if `status` has the `kDeadlineExceeded` error code&period;
| xref:absl/IsFailedPrecondition.adoc[`IsFailedPrecondition`]
| Returns `true` if `status` has the `kFailedPrecondition` error code&period;
| xref:absl/IsInternal.adoc[`IsInternal`]
| Returns `true` if `status` has the `kInternal` error code&period;
| xref:absl/IsInvalidArgument.adoc[`IsInvalidArgument`]
| Returns `true` if `status` has the `kInvalidArgument` error code&period;
| xref:absl/IsNotFound.adoc[`IsNotFound`]
| Returns `true` if `status` has the `kNotFound` error code&period;
| xref:absl/IsOutOfRange.adoc[`IsOutOfRange`]
| Returns `true` if `status` has the `kOutOfRange` error code&period;
| xref:absl/IsPermissionDenied.adoc[`IsPermissionDenied`]
| Returns `true` if `status` has the `kPermissionDenied` error code&period;
| xref:absl/IsResourceExhausted.adoc[`IsResourceExhausted`]
| Returns `true` if `status` has the `kResourceExhausted` error code&period;
| xref:absl/IsUnauthenticated.adoc[`IsUnauthenticated`]
| Returns `true` if `status` has the `kUnauthenticated` error code&period;
| xref:absl/IsUnavailable.adoc[`IsUnavailable`]
| Returns `true` if `status` has the `kUnavailable` error code&period;
| xref:absl/IsUnimplemented.adoc[`IsUnimplemented`]
| Returns `true` if `status` has the `kUnimplemented` error code&period;
| xref:absl/IsUnknown.adoc[`IsUnknown`]
| Returns `true` if `status` has the `kUnknown` error code&period;
| xref:absl/NotFoundError-0b.adoc[`NotFoundError`]
| Creates a status with the `kNotFound` error code and `message`&period;
| xref:absl/NotFoundError-0c.adoc[`NotFoundError`]
| Creates a status with the `kNotFound` error code and `message`&period;
| xref:absl/OkStatus.adoc[`OkStatus`]
| Returns an OK status, equivalent to a default constructed instance&period;
| xref:absl/OutOfRangeError-06.adoc[`OutOfRangeError`]
| Creates a status with the `kOutOfRange` error code and `message`&period;
| xref:absl/OutOfRangeError-0e.adoc[`OutOfRangeError`]
| Creates a status with the `kOutOfRange` error code and `message`&period;
| xref:absl/PermissionDeniedError-06.adoc[`PermissionDeniedError`]
| Creates a status with the `kPermissionDenied` error code and `message`&period;
| xref:absl/PermissionDeniedError-07.adoc[`PermissionDeniedError`]
| Creates a status with the `kPermissionDenied` error code and `message`&period;
| xref:absl/ResourceExhaustedError-04.adoc[`ResourceExhaustedError`]
| Creates a status with the `kResourceExhausted` error code and `message`&period;
| xref:absl/ResourceExhaustedError-097.adoc[`ResourceExhaustedError`]
| Creates a status with the `kResourceExhausted` error code and `message`&period;
| xref:absl/StatusMessageAsCStr.adoc[`StatusMessageAsCStr`]
| Retrieves a message&apos;s status as a null terminated C string&period;
| xref:absl/UnauthenticatedError-04.adoc[`UnauthenticatedError`]
| Creates a status with the `kUnauthenticated` error code and `message`&period;
| xref:absl/UnauthenticatedError-0f.adoc[`UnauthenticatedError`]
| Creates a status with the `kUnauthenticated` error code and `message`&period;
| xref:absl/UnavailableError-0a.adoc[`UnavailableError`]
| Creates a status with the `kUnavailable` error code and `message`&period;
| xref:absl/UnavailableError-0c.adoc[`UnavailableError`]
| Creates a status with the `kUnavailable` error code and `message`&period;
| xref:absl/UnimplementedError-0d.adoc[`UnimplementedError`]
| Creates a status with the `kUnimplemented` error code and `message`&period;
| xref:absl/UnimplementedError-0f.adoc[`UnimplementedError`]
| Creates a status with the `kUnimplemented` error code and `message`&period;
| xref:absl/UnknownError-0d3.adoc[`UnknownError`]
| Creates a status with the `kUnknown` error code and `message`&period;
| xref:absl/UnknownError-0dd.adoc[`UnknownError`]
| Creates a status with the `kUnknown` error code and `message`&period;
|===

== Return Value

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

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