MaxMatrix
Drive chained 8x8 LED dot matrix modules with MAX7219.
Loading...
Searching...
No Matches
MaxMatrixError.h
Go to the documentation of this file.
1// Copyright 2026 Andreas Burnickl
2// SPDX-License-Identifier: GPL-3.0-or-later
3
12
13#ifndef MAXMATRIX_SRC_MAXMATRIXERROR_H_
14#define MAXMATRIX_SRC_MAXMATRIXERROR_H_
15
16#include "Arduino.h"
17#include "MaxMatrixAttributes.h"
18#include "MaxMatrixConfig.h"
19
20namespace max_matrix {
21
34#if (MAXMATRIX_DEV_ERROR_DETECT == STD_ON)
35// NOLINTNEXTLINE(cppcoreguidelines-macro-usage): T-6, F() needs a literal
36#define MAXMATRIX_REPORT_ERROR(Api, Call) \
37 ::max_matrix::internal::ReportIfError(F(Api), Call)
38#else
39// NOLINTNEXTLINE(cppcoreguidelines-macro-usage): T-6, a build without reports
40#define MAXMATRIX_REPORT_ERROR(Api, Call) (Call)
41#endif
42
60
73class Status {
74 private:
75 // A sketch reaches the error only through this class, so that it could carry
76 // more than the enum one day without a sketch changing.
77 Error error_;
78
79 public:
87 Status(Error error = Error::kOk) // NOLINT(runtime/explicit): returns Error
88 : error_{error} {}
89
91 MAXMATRIX_NODISCARD Error GetError() const { return error_; }
92
103 MAXMATRIX_NODISCARD __FlashStringHelper const* GetErrorText() const;
104
106 MAXMATRIX_NODISCARD bool IsOk() const { return error_ == Error::kOk; }
107
114 friend bool operator==(Status status, Error error) {
115 return status.error_ == error;
116 }
117
124 friend bool operator!=(Status status, Error error) {
125 return !(status == error);
126 }
127};
128
140template <typename ValueType>
141class Result {
142 private:
143 // Side by side rather than in a union: a byte and its error still return in
144 // registers on the AVR, and the value is never left undefined.
145 ValueType value_;
146 Error error_;
147
148 public:
156 Result(ValueType value) // NOLINT(runtime/explicit): returns the value
157 : value_{value}, error_{Error::kOk} {}
158
166 Result(Error error) // NOLINT(runtime/explicit): returns Error
167 : value_{}, error_{error} {}
168
170 MAXMATRIX_NODISCARD ValueType GetValue() const { return value_; }
171
173 MAXMATRIX_NODISCARD Error GetError() const { return error_; }
174
176 MAXMATRIX_NODISCARD __FlashStringHelper const* GetErrorText() const {
177 return Status(error_).GetErrorText();
178 }
179
181 MAXMATRIX_NODISCARD bool IsOk() const { return error_ == Error::kOk; }
182
189 friend bool operator==(Result const& result, Error error) {
190 return result.error_ == error;
191 }
192
199 friend bool operator!=(Result const& result, Error error) {
200 return !(result == error);
201 }
202};
203
204#if (MAXMATRIX_DEV_ERROR_DETECT == STD_ON)
219void ReportError(__FlashStringHelper const* api, Error error);
220
231void PrintError(__FlashStringHelper const* api, Error error);
232
234namespace internal {
235
236// Passes a Status or Result<T> on, after reporting its error,
237// if it has one; what MAXMATRIX_REPORT_ERROR() calls.
238template <typename ResultType>
239ResultType ReportIfError(__FlashStringHelper const* api, ResultType result) {
240 if (!result.IsOk()) {
241 ReportError(api, result.GetError());
242 }
243 return result;
244}
245
246} // namespace internal
248#endif
249
250} // namespace max_matrix
251
252#endif // MAXMATRIX_SRC_MAXMATRIXERROR_H_
The attributes of a later standard, as macros, where the compiler has them.
#define MAXMATRIX_NODISCARD
Marks a function whose result must not be dropped: the compiler warns where it is.
Definition MaxMatrixAttributes.h:37
Configuration of the MaxMatrix library.
Error
Why a call did not do what it was asked; one byte, so that it returns in a register.
Definition MaxMatrixError.h:45
@ kUnknownCommand
Definition MaxMatrixError.h:53
@ kUnknownChar
Definition MaxMatrixError.h:49
@ kLineTooLong
Definition MaxMatrixError.h:55
@ kNotANumber
Definition MaxMatrixError.h:52
@ kNoText
Definition MaxMatrixError.h:50
@ kOk
Definition MaxMatrixError.h:46
@ kOutOfRange
Definition MaxMatrixError.h:48
@ kNotAFont
Definition MaxMatrixError.h:58
friend bool operator!=(Result const &result, Error error)
Returns whether there is a value, or none for another reason.
Definition MaxMatrixError.h:199
Result(ValueType value)
Makes a result that holds value.
Definition MaxMatrixError.h:156
Result(Error error)
Makes a result that holds why there is no value.
Definition MaxMatrixError.h:166
MAXMATRIX_NODISCARD __FlashStringHelper const * GetErrorText() const
Returns the error in a few words, in flash, for Serial.print().
Definition MaxMatrixError.h:176
MAXMATRIX_NODISCARD ValueType GetValue() const
Returns the value; 0, or what ValueType() is, after an error.
Definition MaxMatrixError.h:170
MAXMATRIX_NODISCARD bool IsOk() const
Returns whether there is a value.
Definition MaxMatrixError.h:181
friend bool operator==(Result const &result, Error error)
Returns whether there is no value for this reason.
Definition MaxMatrixError.h:189
MAXMATRIX_NODISCARD Error GetError() const
Returns why there is no value, or Error::kOk.
Definition MaxMatrixError.h:173
What a function that can fail returns when it has no value to return.
Definition MaxMatrixError.h:73
Status(Error error=Error::kOk)
Makes a status of error, ok when none is given.
Definition MaxMatrixError.h:87
friend bool operator!=(Status status, Error error)
Returns whether the call did not fail for this reason.
Definition MaxMatrixError.h:124
MAXMATRIX_NODISCARD Error GetError() const
Returns why the call failed, or Error::kOk.
Definition MaxMatrixError.h:91
friend bool operator==(Status status, Error error)
Returns whether the call failed for this reason.
Definition MaxMatrixError.h:114
MAXMATRIX_NODISCARD bool IsOk() const
Returns whether the call did what it was asked.
Definition MaxMatrixError.h:106
MAXMATRIX_NODISCARD __FlashStringHelper const * GetErrorText() const
Returns the error in a few words, in flash, for Serial.print().