diff --git a/developer-handbook.md b/developer-handbook.md index 58ebe616..2a63ba91 100644 --- a/developer-handbook.md +++ b/developer-handbook.md @@ -162,18 +162,10 @@ classes in question. ### Error Handling -Exceptions are clean and nice in userland code running in environments with -expansive system resources, but they are a bit of a pain in small bare metal -environments. -The GBA build has them disabled. -Exceptions cause also the compiler to generate a great deal of extra code that -inflates the size of the binary. -The binary size bloat is often cited as one of the main reasons why many -embedded developers prefer C to C++. - -Instead of throwing exceptions, all engine code must return Ox error codes. -For the sake of consistency, try to stick to Ox error codes in non-engine code -as well. +The GBA build has exceptions disabled. +Instead of throwing exceptions, all engine code must return ```ox::Error```s. +For the sake of consistency, try to stick to ```ox::Error``` in non-engine code +as well, but non-engine code is free to use exceptions when they make sense. Nostalgia and Ox both use ```ox::Error``` to report errors. ```ox::Error``` is a struct that has overloaded operators to behave like an integer error code, plus some extra fields to enhance debuggability. @@ -219,6 +211,22 @@ int caller2() { std::cout << val << '\n'; return 0; } + +ox::Error caller3(int &i) { + return foo(i).moveTo(i); +} + +ox::Error caller4(int &i) { + return foo(i).copyTo(i); +} + +int caller5(int i) { + return foo(i).unwrap(); // unwrap will kill the program if there is an error +} + +int caller6(int i) { + return foo(i).unwrapThrow(); // unwrap will throw if there is an error +} ``` Lastly, there are a few macros available to help in passing ```ox::Error```s @@ -275,6 +283,7 @@ ox::Error engineCode() noexcept { return OxError(0); } ``` + Ox also has the ```oxRequire``` macro, which will initialize a value if there is no error, and return if there is. It aims to somewhat emulate the ```?``` operator in Rust and Swift. @@ -309,6 +318,9 @@ ox::Result f2() noexcept { * ```oxRequireT``` - oxRequire Throw * ```oxRequireMT``` - oxRequire Mutable Throw +The throw variants of ```oxRequire``` are generally legacy code. +```ox::Result::unwrapThrow``` is generally preferred now. + ### Logging and Output Ox provides for logging and debug prints via the ```oxTrace```, ```oxDebug```, and ```oxError``` macros.