Skip to main content
Pigweed's logo Pigweed
code_xml
  1. Home
  2. Reference
  3. C/C++
  4. Data structures & utilities
  5. pw_status
  6. pw::StatusBase< Derived, kOkCode, kMessages > Class Template Reference
pw::StatusBase< Derived, kOkCode, kMessages > Class Template Reference

Overview

template<typename Derived, auto kOkCode, StatusMessages kMessages = StatusMessages::kDefault>
class pw::StatusBase< Derived, kOkCode, kMessages >

Base class providing standard status operations for status types using CRTP.

StatusBase provides common functionality for status types that wrap an enum or integer status code, including checking for success (ok()), retrieving the code (code()), optional error messages (has_message(), message()), string formatting (str()), updating, and equality comparisons.

Custom status types should derive from StatusBase<Derived, kOkCode> or alias StatusOf<kOkCode>. Derived classes should be declared [[nodiscard]] unless using StatusOf (which is declared [[nodiscard]]).

Equality comparisons consider only the status code; messages are ignored.

Users should not interact directly with StatusBase, except to instantiate a custom status class. Do not use StatusBase for variables or function parameters.

A status type supports messages if its code is an enum registered with PW_ENUM whose values are all from 0 to 65535. Passing a PW_STATUS_MSG to any other status type, or to one that uses StatusMessages::kDisabled, does not compile.

Warning
Status codes must be valid enumerators. They are not range checked, and when messages are stored as tokens, the code shares a 32-bit word with the message token. A value that needs more bits than the code's enumerators do (pw::EnumTraits<Code>::kBitWidth) corrupts both the code and the message. Check integers from outside the program, such as with pw::IsValidEnum, before casting them to the code type.
Template Parameters
DerivedThe derived status class (CRTP parameter).
kOkCodeCode value that represents success (ok() == true).
kMessagesPass StatusMessages::kDisabled for a status that never carries a message.
Inheritance diagram for pw::StatusBase< Derived, kOkCode, kMessages >:
pw::StatusOf< kOkCode, kMessages >

Classes

class  Message
 

Public Types

using Code = decltype(kOkCode)
 The underlying status code type.
 

Public Member Functions

constexpr bool ok () const noexcept
 Returns true if the status is the OK code.
 
constexpr Code code () const noexcept
 Returns the underlying status code.
 
constexpr bool has_message () const noexcept
 
constexpr Message message () const noexcept
 
constexpr void Update (Derived other) noexcept
 
constexpr void IgnoreError () const noexcept
 Ignores any errors, suppressing unused-result warnings.
 
constexpr const char * str () const
 

Protected Member Functions

constexpr StatusBase () noexcept=default
 Defaults to kOkCode (ok() == true).
 
constexpr StatusBase (Code code) noexcept
 Explicitly construct from the underlying code.
 
constexpr StatusBase (Code code, Message message) noexcept
 
constexpr StatusBase (const StatusBase &)=default
 
constexpr StatusBase & operator= (const StatusBase &)=default
 
constexpr StatusBase (StatusBase &&)=default
 
constexpr StatusBase & operator= (StatusBase &&)=default
 

Friends

constexpr bool operator== (Derived lhs, Derived rhs) noexcept
 Compares two statuses by code only; error messages are ignored.
 
constexpr bool operator!= (Derived lhs, Derived rhs) noexcept
 Compares two statuses by code only; error messages are ignored.
 
constexpr bool operator== (Derived lhs, Code rhs) noexcept
 Compares a status with a status code; error messages are ignored.
 
constexpr bool operator== (Code lhs, Derived rhs) noexcept
 Compares two statuses by code only; error messages are ignored.
 
constexpr bool operator!= (Derived lhs, Code rhs) noexcept
 Compares two statuses by code only; error messages are ignored.
 
constexpr bool operator!= (Code lhs, Derived rhs) noexcept
 Compares two statuses by code only; error messages are ignored.
 

Constructor & Destructor Documentation

◆ StatusBase()

template<typename Derived , auto kOkCode, StatusMessages kMessages = StatusMessages::kDefault>
constexpr pw::StatusBase< Derived, kOkCode, kMessages >::StatusBase ( Code  code,
Message  message 
)
inlineconstexprprotectednoexcept

Constructs from a status code and a PW_STATUS_MSG. The message is dropped if code is the OK code.

Member Function Documentation

◆ has_message()

template<typename Derived , auto kOkCode, StatusMessages kMessages = StatusMessages::kDefault>
constexpr bool pw::StatusBase< Derived, kOkCode, kMessages >::has_message ( ) const
inlineconstexprnoexcept

Returns true if this status carries an error message.

Always false for OK statuses and when messages are disabled.

◆ message()

template<typename Derived , auto kOkCode, StatusMessages kMessages = StatusMessages::kDefault>
constexpr Message pw::StatusBase< Derived, kOkCode, kMessages >::message ( ) const
inlineconstexprnoexcept

Returns the error message, which is empty if !has_message(). Pass it to a constructor to create a status with a different code and the same message.

◆ str()

template<typename Derived , auto kOkCode, StatusMessages kMessages = StatusMessages::kDefault>
constexpr const char * pw::StatusBase< Derived, kOkCode, kMessages >::str ( ) const
inlineconstexpr

Returns a string representation of the status code. Only supported for status types with enum codes.

◆ Update()

template<typename Derived , auto kOkCode, StatusMessages kMessages = StatusMessages::kDefault>
constexpr void pw::StatusBase< Derived, kOkCode, kMessages >::Update ( Derived  other)
inlineconstexprnoexcept

Updates this status to other if this status is currently ok().

This is useful for tracking the first encountered error, as calls to this helper will not change one error status to another error status.

Friends And Related Function Documentation

◆ operator!= [1/3]

template<typename Derived , auto kOkCode, StatusMessages kMessages = StatusMessages::kDefault>
constexpr bool operator!= ( Code  lhs,
Derived  rhs 
)
friend

Compares two statuses by code only; error messages are ignored.

◆ operator!= [2/3]

template<typename Derived , auto kOkCode, StatusMessages kMessages = StatusMessages::kDefault>
constexpr bool operator!= ( Derived  lhs,
Code  rhs 
)
friend

Compares two statuses by code only; error messages are ignored.

◆ operator!= [3/3]

template<typename Derived , auto kOkCode, StatusMessages kMessages = StatusMessages::kDefault>
constexpr bool operator!= ( Derived  lhs,
Derived  rhs 
)
friend

Compares two statuses by code only; error messages are ignored.

◆ operator==

template<typename Derived , auto kOkCode, StatusMessages kMessages = StatusMessages::kDefault>
constexpr bool operator== ( Code  lhs,
Derived  rhs 
)
friend

Compares two statuses by code only; error messages are ignored.


The documentation for this class was generated from the following file: