Status(T) – Zero Means Okay (Must-Use, No Truth Value)
A great deal of C returns a status code: 0 when things went fine, and something else when they didn’t. POSIX calls, ODBC’s SQLRETURN, and a thousand in-house #define OK 0 / #define ERR -1 conventions all work this way.
Status(T) marks such a return value:
Status(int) Flush_Buffer(Buffer* b) {
if (b->broken)
return E_IO;
/* ... */
return okay;
}
In a plain C build it is just a T (with a must-use annotation where the compiler offers one). In the checked build it enforces three things.
What It Enforces
It can’t be ignored. Like Fallible(T), calling a function that returns a Status(T) and dropping the result is a diagnostic.
It has no truth value. This is the reason the type exists:
if (Flush_Buffer(b)) /* reads as "if it worked"... */
Report_Success(); /* ...runs when it FAILED */
Zero-is-okay is backwards from how C’s if reads, and everyone has written that bug. So in the checked build if (status), ! status, status && x and status ? a : b do not compile. You have to say which you mean:
if (is_okay(Flush_Buffer(b)))
Report_Success();
It doesn’t mix with Option(T) or Fallible(T). Those also single out zero, but with the opposite meaning: for them zero is none, the bad state. A Status(T) function can’t return none;, an Option(T) function can’t return okay;, and each family’s macros refuse the other’s values.
What Counts as a Status
Deliberately little: zero is okay, and anything else is a signal the caller must look at. It is not called “failed”, because it might not be:
#define C_OK 0
#define C_ERR -1
#define C_RETRY -2
C_RETRY isn’t a failure. It’s just not okay. That is why the vocabulary below says not_okay and never failed.
The Vocabulary
Status(T) | The return type. |
StatusVar(T) | The same thing for locals, parameters and struct members (see why two spellings). |
okay | The zero value: return okay;, rc = okay;. |
is_okay(expr) | True if the status is zero. The only way to test one. |
status_code(expr) | The raw T, for a switch, a log message, or <. |
return_if_not_okay (T, expr); | If expr isn’t okay, return its code. T is the code’s type. |
abort_if_not_okay (expr); | Crash if not okay. |
assert_okay (expr); | Assert okay in debug builds (expr still runs under NDEBUG). |
tolerate_not_okay (expr); | Deliberately ignore it, and say so. |
Comparing against a particular code needs nothing special:
StatusVar(int) rc = Try_Lock(m);
if (rc == C_RETRY)
Wait_A_Bit();
Why return_if_not_okay takes a type
return_if_none can simply return none. Propagating a status means returning the code that came back, so the macro has to hold it in a temporary, and plain C has no auto to declare one with. So you say what type the code is:
Status(int) Save_All(Document* doc) {
return_if_not_okay (int, Write_Header(doc));
return_if_not_okay (int, Write_Body(doc));
return okay;
}
The function’s own return type has to be able to hold the code. If you need to translate one kind of code into another, or want the code in a variable to inspect before deciding, write it out:
StatusVar(int) rc = Write_Header(doc);
if (rc == C_RETRY)
/* ... */
How the Three Families Line Up
Each type has exactly one state that it defines precisely, and that state gets the name. The other side is just “not that”.
Option / Fallible | Status | Result | |
|---|---|---|---|
| The named state | none (zero) | okay (zero) | failed |
| Returning it | return none; | return okay; | return_fail (...) |
| Testing | is_none(x) | is_okay(x) | catch_if_failed |
| Propagate | return_if_none | return_if_not_okay | return_if_failed |
| Die on it | abort_if_none | abort_if_not_okay | panic_if_failed |
| Assert | assert_not_none | assert_okay | assert_not_failed |
| Ignore | tolerate_none | tolerate_not_okay | extract_failure |
Option and Status are mirror images, which is exactly why the Status macros carry a not_ where the Option ones don’t.
Unannotated APIs
is_okay() and status_code() also accept a raw integer or enum, so you can use them on functions you haven’t (or can’t) annotate:
if (! is_okay(SQLFetch(stmt)))
/* ... */
and return_if_not_okay (SQLRETURN, SQLFetch(stmt)); works for the same reason: a raw code converts to a Status(T). What they don’t accept is a bool, a pointer, or an Option(T). Returning true from a Status(T) function is likewise an error.
Limits
- A plain C build checks only the must-use part, and only where the compiler has an annotation for it. There
okayandnoneare both0. The checked build is what catchesif (status). See which builds enforce must-use; the same table applies here. - Below C++17 the checked build can’t enforce must-use either, since
[[nodiscard]]on a class doesn’t exist. The truth-value and mixing checks work from C++11. Statusis a common name. X11 and GDI+ both define one. If it collides, leaveNEEDFUL_STATUS_SHORTHANDSoff for those files and writeNeedfulStatus(T).
Related
Fallible(T)– the must-use type where zero is the failureResult(T)– when a failure needs to carry information- Setup –
NEEDFUL_STATUS_USES_WRAPPER,NEEDFUL_STATUS_SHORTHANDS
Compile-Time Tests
Basic usage
#include <assert.h>
#ifdef __cplusplus
#define NEEDFUL_CPP_ENHANCED 1
#endif
#define NEEDFUL_STATUS_SHORTHANDS 1
#include "needful.h"
#define C_OK 0
#define C_ERR -1
#define C_RETRY -2
typedef enum { E_NONE = 0, E_IO = 1, E_FULL = 2 } DiskError;
static int Raw_Api(int n) { return n; } // an API nobody annotated
static Status(int) Step(int n) {
if (n < 0)
return C_ERR;
if (n == 0)
return C_RETRY;
return okay;
}
static Status(DiskError) Write_Block(int n) {
if (n > 100)
return E_FULL;
return okay;
}
static Status(int) Run(int n) {
return_if_not_okay (int, Step(n));
return_if_not_okay (int, Raw_Api(0)); // raw codes work too
return okay;
}
static Status(DiskError) Save(int n) {
return_if_not_okay (DiskError, Write_Block(n));
return okay;
}
int main() {
StatusVar(int) rc = Run(1);
assert(is_okay(rc));
rc = Run(-1); // the code is propagated, not flattened
assert(! is_okay(rc));
assert(rc == C_ERR);
assert(rc != C_OK);
assert(Run(0) == C_RETRY); // not okay, and not a failure either
switch (status_code(Run(0))) { // the raw code, for a switch
case C_RETRY:
break;
default:
assert(0);
}
assert(status_code(rc) < 0);
StatusVar(DiskError) e = Save(500); // enum codes
assert(e == E_FULL);
assert(is_okay(Save(5)));
assert(is_okay(Raw_Api(0))); // unannotated API
assert_okay (Run(5));
assert_okay (rc = Run(5)); // the assignment happens even under NDEBUG
assert(is_okay(rc));
abort_if_not_okay (Run(5));
tolerate_not_okay (Run(-1));
rc = okay;
assert(rc == okay);
return 0;
}
A Status(T) has no truth value
// MATCH-ERROR-TEXT: has no truth value
#ifdef __cplusplus
#define NEEDFUL_CPP_ENHANCED 1
#endif
#define NEEDFUL_STATUS_SHORTHANDS 1
#include "needful.h"
static Status(int) Step(void) { return okay; }
int main() {
if (Step()) // ERROR: reads as "if it worked", means "if it didn't"
return 1;
return 0;
}
Negating a Status(T) is a compile error too
// MATCH-ERROR-TEXT: has no truth value
#ifdef __cplusplus
#define NEEDFUL_CPP_ENHANCED 1
#endif
#define NEEDFUL_STATUS_SHORTHANDS 1
#include "needful.h"
static Status(int) Step(void) { return okay; }
int main() {
StatusVar(int) rc = Step();
if (! rc) // ERROR: say is_okay(rc)
return 0;
return 1;
}
Discarding a Status(T) is a compile error
// REQUIRES-STD: c++17
//
// MATCH-ERROR-TEXT: nodiscard <- all three
// MATCH-ERROR-TEXT: ignoring return value <- GCC, Clang
// MATCH-ERROR-TEXT: discarding return value <- MSVC (C4834)
#ifdef __cplusplus
#define NEEDFUL_CPP_ENHANCED 1
#endif
#define NEEDFUL_STATUS_SHORTHANDS 1
#include "needful.h"
static Status(int) Step(void) { return okay; }
int main() {
Step(); // ERROR: the status must be looked at
return 0;
}
return none; from a Status(T) function is a compile error
// MATCH-ERROR-TEXT: deleted
#ifdef __cplusplus
#define NEEDFUL_CPP_ENHANCED 1
#endif
#define NEEDFUL_STATUS_SHORTHANDS 1
#define NEEDFUL_OPTION_SHORTHANDS 1
#include "needful.h"
static Status(int) Step(void) {
return none; // ERROR: `none` is Option(T)'s word; this is `okay`
}
int main() {
return is_okay(Step()) ? 0 : 1;
}
return okay; from an Option(T) function is a compile error
// MATCH-ERROR-TEXT: could not convert <- GCC
// MATCH-ERROR-TEXT: no viable conversion <- Clang
// MATCH-ERROR-TEXT: cannot convert <- MSVC
#ifdef __cplusplus
#define NEEDFUL_CPP_ENHANCED 1
#endif
#define NEEDFUL_STATUS_SHORTHANDS 1
#define NEEDFUL_OPTION_SHORTHANDS 1
#include "needful.h"
static Option(int*) Find(void) {
return okay; // ERROR: an Option(T)'s zero state is `none`
}
int main() {
return Find() ? 1 : 0;
}
return true; from a Status(T) function is a compile error
// MATCH-ERROR-TEXT: could not convert <- GCC
// MATCH-ERROR-TEXT: no viable conversion <- Clang
// MATCH-ERROR-TEXT: cannot convert <- MSVC
#ifdef __cplusplus
#define NEEDFUL_CPP_ENHANCED 1
#endif
#define NEEDFUL_STATUS_SHORTHANDS 1
#include "needful.h"
static Status(int) Step(void) {
return true; // ERROR: true is 1, which is "not okay"
}
int main() {
return is_okay(Step()) ? 0 : 1;
}