checkedint.flags

Thomas Stuart Bockman

$(BIG $(B `IntFlagPolicy.throws`))
When the throws policy is set, errors are signalled by simply throwing a new CheckedIntException. This is the recommended policy because:

• The API user is not required to explicitly handle errors.
• Printing a precise stack trace is very helpful for debugging.

However, this approach is not suitable in all cases. In particular:

• Obviously, it will not work in nothrow code.
• As of D 2.071, exceptions are still not safe to use in @nogc code.
• Exceptions are too slow for code that is expected to signal many integer math errors in normal operation.

$(BIG $(B `IntFlagPolicy.asserts`))
When the asserts policy is set, errors trigger an assertion failure. The result depends upon whether assertions were enabled at compiler time:

• With version(assert) - enabled by default in debug and unittest builds - a core.exception.AssertError will be thrown. Its msg property will be set to the description of an IntFlag that was raised.
• Otherwise (in release mode), assert(0); will be used to halt the program immediately. Unfortunately, no message or stack trace can be provided in this case. Use one of the other two error signalling policies if you need detailed information in release mode.

The asserts policy is the only one that is compatible with pure nothrow @nogc code.

$(BIG $(B `IntFlagPolicy.noex`))
An alternative error signalling method may be selected using the noex policy:

1. Whenever an integer math error occurs, a bit flag is raised in IntFlags.local, which is a TLS variable.
2. The integer math operations in checkedint only set bit flags; they never clear them. Thus, any flag that is raised because of an error will remain set until handled by the API user.
3. The API user periodically checks whether any flags have been raised like so: if (IntFlags.local)
4. IntFlags.local may be inspected to determine the general type of the error - for example, "divide by zero".
5. Once the API user has handled the error somehow, IntFlags.clear() can be used to unset all bit flags before continuing the program.

The IntFlags.pushPop mixin can be used to prevent a function from handling or clearing flags that were set by the caller.

Care must be taken when using the noex policy to insert sufficient if (IntFlags.local) checks; otherwise checkedint will not provide much protection from integer math related bugs.