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

A type used to gracefully handle errors across API boundaries.

== Synopsis

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

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

== Description

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

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

Example:

absl::Status myFunction(absl::string_view fname, ...) { ... // encounter error if (error condition) { // Construct an absl::StatusCode::kInvalidArgument error return absl::InvalidArgumentError("bad mode"); } // else, return OK return absl::OkStatus(); }

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

Example:

absl::Status result = DoSomething(); if (!result.ok()) { LOG(ERROR) << result; }

// Provide a default if switching on multiple error codes switch (result.code()) { // The user hasn't authenticated. Ask them to reauth case absl::StatusCode::kUnauthenticated: DoReAuth(); break; // The user does not have permission. Log an error. case absl::StatusCode::kPermissionDenied: LOG(ERROR) << result; break; // Propagate the error otherwise. default: return true; }

An `absl::Status` can optionally include a payload with more information about the error. Typically, this payload serves one of several purposes:

* It may provide more fine‐grained semantic information about the error to facilitate actionable remedies. * It may provide human‐readable contextual information that is more appropriate to display to an end user.

Example:

absl::Status result = DoSomething(); // Inform user to retry after 30 seconds // See more error details in googleapis/google/rpc/error_details.proto if (absl::IsResourceExhausted(result)) { google::rpc::RetryInfo info; info.retry_delay().seconds() = 30; // Payloads require a unique key (a URL to ensure no collisions with // other payloads), and an `absl::Cord` to hold the encoded data. absl::string_view url = "type.googleapis.com/google.rpc.RetryInfo"; result.SetPayload(url, info.SerializeAsCord()); return result; }

For documentation see https://abseil.io/docs/cpp/guides/status.

Returned Status objects may not be ignored. status_internal.h has a forward declaration of the form class ABSL_MUST_USE_RESULT Status;

== Member Functions

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


== Friends

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

== Non-Member Functions

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

== 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]#