This module defines facilities for efficient checking of integral operationsagainst overflow, casting with loss of precision, unexpected change of sign,etc. The checking (and possibly correction) can be done at operation level, forexample
opChecked!"+"(x, y, overflow) adds two integrals
x and
y and sets
overflow to
true if an overflow occurred. The flag
overflow(a
bool passed by reference) is not touched if the operation succeeded, so thesame flag can be reused for a sequence of operations and tested at the end.
Issuing individual checked operations is flexible and efficient but oftentedious. The
Checked facility offers encapsulated integral wrappers thatdo all checking internally and have configurable behavior upon erroneousresults. For example,
Checked!int is a type that behaves like
int but abortsexecution immediately whenever involved in an operation that produces thearithmetically wrong result. The accompanying convenience function
checked uses type deduction to convert a value
x of integral type
T to
Checked!T by means of
checked(x). For example:
void main(){import std.checkedint, std.stdio; writeln((checked(5) + 7).get);// 12 writeln((checked(10) * 1000 * 1000 * 1000).get);// Overflow}Similarly,
checked(-1) > uint(0) aborts execution (even though the built-incomparison
int(-1) > uint(0) is surprisingly true due to language'sconversion rules modeled after C). Thus,
Checked!int is a virtually drop-inreplacement for
int useable in debug builds, to be replaced by
int inrelease mode if efficiency demands it.
Checked has customizable behavior with the help of a second type parameter,
Hook. Depending on what methods
Hook defines, core operations on theunderlying integral may be verified for overflow or completely redefined. If
Hook defines no method at all and carries no state, there is no change inbehavior, i.e.
Checked!(int, void) is a wrapper around
int that adds nocustomization at all.
This module provides a few predefined hooks (below) that add useful behavior to
Checked:
| Abort | fails every incorrect operation with a message tostd.stdio. stderr followed by a call toassert(0). It is the default second parameter, i.e.Checked!short is the same asChecked!(short, Abort). |
| Throw | fails every incorrect operation by throwing an exception. |
| Warn | prints incorrect operations tostd.stdio.stderr but otherwise preserves the built-in behavior. |
| ProperCompare | fixes the comparison operators==,!=,<,<=,>, and>= to return correct results in all circumstances, at a slight cost in efficiency. For example,Checked!(uint, ProperCompare)(1) > -1 istrue, which is not the case for the built-in comparison. Also, comparing numbers for equality with floating-point numbers only passes if the integral can be converted to the floating-point number precisely, so as to preserve transitivity of equality. |
| WithNaN | reserves a special "Not a Number" (NaN) value akin to the homonym value reserved for floating-point values. Once aChecked!(X, WithNaN) gets this special value, it preserves and propagates it until reassigned.isNaN can be used to query whether the object is not a number. |
| Saturate | implements saturating arithmetic, i.e.Checked!(int, Saturate) "stops" atint.max for all operations that would cause anint to overflow toward infinity, and atint.min for all operations that would correspondingly overflow toward negative infinity. |
These policies may be used alone, e.g.
Checked!(uint, WithNaN) defines a
uint-like type that reaches a stable NaN state for all erroneous operations.They may also be "stacked" on top of each other, owing to the property that achecked integral emulates an actual integral, which means another checkedintegral can be built on top of it. Some combinations of interest include:
| Checked!(Checked!int, ProperCompare) |
| defines anint with fixedcomparison operators that will fail withassert(0) upon overflow. (Recall thatAbort is the default policy.) The order in which policies are combined isimportant because the outermost policy (ProperCompare in this case) has thefirst crack at intercepting an operator. The converse combinationChecked!(Checked!(int, ProperCompare)) is meaningless becauseAbort willintercept comparison and will fail without givingProperCompare a chance tointervene. |
|
| Checked!(Checked!(int, ProperCompare), WithNaN) |
| defines anint-liketype that supports a NaN value. For values that are not NaN, comparison worksproperly. Again the composition order is important;Checked!(Checked!(int,WithNaN), ProperCompare) does not have good semantics becauseProperCompareintercepts comparisons before the numbers involved are tested for NaN. |
The hook's members are looked up statically in a Design by Introspection mannerand are all optional. The table below illustrates the members that a hook typemay define and their influence over the behavior of the
Checked type using it.In the table,
hook is an alias for
Hook if the type
Hook does notintroduce any state, or an object of type
Hook otherwise.
| Hook member | Semantics inChecked!(T, Hook) |
|---|
| defaultValue | If defined,Hook.defaultValue!T is used as thedefault initializer of the payload. |
| min | If defined,Hook.min!T is used as the minimum value ofthe payload. |
| max | If defined,Hook.max!T is used as the maximum value ofthe payload. |
| hookOpCast | If defined,hook.hookOpCast!U(get) is forwardedto unconditionally when the payload is to be cast to typeU. |
| onBadCast | If defined andhookOpCast isnot defined,onBadCast!U(get) is forwarded to when the payload is to be cast to typeUand the cast would lose information or force a change of sign. |
| hookOpEquals | If defined,hook.hookOpEquals(get, rhs) isforwarded to unconditionally when the payload is compared for equality againstvaluerhs of integral, floating point, or Boolean type. |
| hookOpCmp | If defined,hook.hookOpCmp(get, rhs) isforwarded to unconditionally when the payload is compared for ordering againstvaluerhs of integral, floating point, or Boolean type. |
| hookOpUnary | If defined,hook.hookOpUnary!op(get) (whereopis the operator symbol) is forwarded to for unary operators- and~. Inaddition, for unary operators++ and--,hook.hookOpUnary!op(payload) iscalled, wherepayload is a reference to the value wrapped byChecked so thehook can change it. |
| hookOpBinary | If defined,hook.hookOpBinary!op(get, rhs)(whereop is the operator symbol andrhs is the right-hand side operand) isforwarded to unconditionally for binary operators+,-,*,/,%,^^,&,|,^,<<,>>, and>>>. |
| hookOpBinaryRight | If defined,hook.hookOpBinaryRight!op(lhs, get) (whereop is the operator symbol andlhs is the left-hand side operand) is forwarded to unconditionally for binaryoperators+,-,*,/,%,^^,&,|,^,<<,>>, and>>>. |
| onOverflow | If defined,hook.onOverflow!op(get) is forwardedto for unary operators that overflow but only ifhookOpUnary is not defined.Unary~ does not overflow; unary- overflows only when the most negativevalue of a signed type is negated, and the result of the hook call is returned.When the increment or decrement operators overflow, the payload is assigned theresult ofhook.onOverflow!op(get). When a binary operator overflows, theresult ofhook.onOverflow!op(get, rhs) is returned, but only ifHook doesnot definehookOpBinary. |
| hookOpOpAssign | If defined,hook.hookOpOpAssign!op(payload,rhs) (whereop is the operator symbol andrhs is the right-hand sideoperand) is forwarded to unconditionally for binary operators+=,-=,*=,/=,%=,^^=,&=,|=,^=,<<=,>>=, and>>>=. |
| onLowerBound | If defined,hook.onLowerBound(value, bound)(wherevalue is the value being assigned) is forwarded to when the result ofbinary operators+=,-=,*=,/=,%=,^^=,&=,|=,^=,<<=,>>=,and>>>= is smaller than the smallest value representable byT. |
| onUpperBound | If defined,hook.onUpperBound(value, bound)(wherevalue is the value being assigned) is forwarded to when the result ofbinary operators+=,-=,*=,/=,%=,^^=,&=,|=,^=,<<=,>>=,and>>>= is larger than the largest value representable byT. |
| hookToHash | If defined,hook.hookToHash(payload)(wherepayload is a reference to the value wrapped by Checked) is forwardedto whentoHash is called on a Checked type. Custom hashing can be implementedin aHook, otherwise the built-in hashing is used. |
struct
Checked(T, Hook = Abort) if (isIntegral!T || is(T ==
Checked!(U, H), U, H));
Checked integral type wraps an integralT and customizes its behavior with thehelp of aHook type. The type wrapped must be one of the predefined integrals(unqualified), or another instance ofChecked.
Parameters:| T | type that is wrapped in theChecked type |
| Hook | hook type that customizes the behavior of theChecked type |
Examples:// Hook that ignores all problems.staticstruct Ignore{ @nogcnothrowpure @safestatic: Dst onBadCast(Dst, Src)(Src src) {returncast(Dst) src; } Lhs onLowerBound(Rhs, T)(Rhs rhs, T bound) {returncast(T) rhs; } T onUpperBound(Rhs, T)(Rhs rhs, T bound) {returncast(T) rhs; }bool hookOpEquals(Lhs, Rhs)(Lhs lhs, Rhs rhs) {return lhs == rhs; }int hookOpCmp(Lhs, Rhs)(Lhs lhs, Rhs rhs) {return (lhs > rhs) - (lhs < rhs); }typeof(~Lhs()) onOverflow(string x, Lhs)(ref Lhs lhs) {returnmixin(x ~"lhs"); }typeof(Lhs() + Rhs()) onOverflow(string x, Lhs, Rhs)(Lhs lhs, Rhs rhs) {staticif (x =="/")returntypeof(lhs / rhs).min;elsereturnmixin("lhs" ~ x ~"rhs"); }}auto x =Checked!(int, Ignore)(5) + 7; The type of the integral subject to checking.
hook is a member variable if it has state, or an alias forHook otherwise.
Returns:A copy of the underlying value.
Examples:auto x = checked(ubyte(42));staticassert(is(typeof(x.get()) ==ubyte));writeln(x.get);// 42const y = checked(ubyte(42));staticassert(is(typeof(y.get()) ==constubyte));writeln(y.get);// 42
enum Checked!(T, Hook)
min;
enum Checked!(T, Hook)
max;
Defines the minimum and maximum. These values are hookable by definingHook.min and/orHook.max.
Examples:Defines the minimum and maximum. These values are hookable by defining
Hook.min and/or
Hook.max.
writeln(Checked!short.min);// -32768writeln(Checked!(short, WithNaN).min);// -32767writeln(Checked!(uint, WithNaN).max);// uint.max - 1
this
(U)(U
rhs)
if (valueConvertible!(U, T) || !isIntegral!T && is(typeof(T(rhs))) || is(U == Checked!(V, W), V, W) && is(typeof(Checked!(T, Hook)(rhs.get))));
Constructor taking a value properly convertible to the underlying type.U may be either an integral that can be converted toT without a loss, or anotherChecked instance whose representation may be in turn converted toT without a loss.
Examples:auto a = checked(42L);writeln(a);// 42auto b = Checked!long(4242);// convert 4242 to longwriteln(b);// 4242
ref Checked
opAssign(U)(U
rhs) return
if (is(typeof(Checked!(T, Hook)(rhs))));
Assignment operator. Has the same constraints as the constructor.
Returns:A reference tothis
Examples:Checked!long a;a = 42L;writeln(a);// 42a = 4242;writeln(a);// 4242
Examples:Checked!long a, b;a = b = 3;assert(a == 3 && b == 3);
this
(Range)(Range
str)
if (isInputRange!Range && isSomeChar!(ElementType!Range));
Construct from a decimal string. The conversion follows the same rules as
std.conv.to converting a string to the wrapped
T type.
Examples:std.conv.to can convert a string to a
Checked!T:
import std.conv : to;const a = to!long("1234");const b = to!(Checked!long)("1234");writeln(a);// b U
opCast(U, this _)()
if (isIntegral!U || isFloatingPoint!U || is(U == bool));
Casting operator to integral,bool, or floating point type.
If a cast to a floating-point type is requested and
Hook defines
onBadCast, the cast is verified by ensuring
get == cast(T) U(get). If that is not
true,
hook.onBadCast!U(get) is returned.
If a cast to an integral type is requested and
Hook defines
onBadCast, the cast is verified by ensuring
get and
cast(U) get are the same arithmetic number. (Note that
int(-1) and
uint(1) are different values arithmetically although they have the same bitwise representation and compare equal by language rules.) If the numbers are not arithmetically equal,
hook.onBadCast!U(get) is returned.
Returns:IfHook defineshookOpCast, the call immediately returnshook.hookOpCast!U(get). Otherwise, casting tobool yields get != 0 and casting to another integral that can represent all values ofT returnsget promoted toU.
Examples:writeln(cast(uint)checked(42));// 42writeln(cast(uint)checked!WithNaN(-42));// uint.max
bool
opEquals(U, this _)(U
rhs)
if (isIntegral!U || isFloatingPoint!U || is(U == bool) || is(U == Checked!(V, W), V, W) && is(typeof(this ==rhs.payload)));
Comparesthis againstrhs for equality.
IfU is also an instance ofChecked, both hooks (left- and right-hand side) are introspected for the methodhookOpEquals. If both define it, priority is given to the left-hand side.
Parameters:Urhs | Right-hand side to compare for equality |
Returns:IfHook defineshookOpEquals, the function forwards to hook.hookOpEquals(get, rhs). Otherwise, the result of the built-in operationget == rhs is returned.
Examples:import std.traits : isUnsigned;staticstruct MyHook{staticbool thereWereErrors;staticbool hookOpEquals(L, R)(L lhs, Rrhs) {if (lhs !=rhs)returnfalse;staticif (isUnsigned!L && !isUnsigned!R) {if (lhs > 0 &&rhs < 0) thereWereErrors =true; }elsestaticif (isUnsigned!R && !isUnsigned!L)if (lhs < 0 &&rhs > 0) thereWereErrors =true;// Preserve built-in behavior.returntrue; }}auto a = checked!MyHook(-42);writeln(a);// uint(-42)assert(MyHook.thereWereErrors);MyHook.thereWereErrors =false;writeln(checked!MyHook(uint(-42)));// -42assert(MyHook.thereWereErrors);staticstruct MyHook2{staticbool hookOpEquals(L, R)(L lhs, Rrhs) {return lhs ==rhs; }}MyHook.thereWereErrors =false;writeln(checked!MyHook2(uint(-42)));// a// Hook on left hand side takes precedence, so no errorsassert(!MyHook.thereWereErrors); nothrow @safe size_t
toHash() const;
nothrow @safe size_t
toHash(this _)() shared const;
Generates a hash forthis. IfHook defineshookToHash, the call immediately returnshook.hookToHash(payload). IfHook does not implementhookToHash, but it has state, a hash will be generated for theHook using the built-in function and it will be xored with the hash of thepayload.
Returns:The hash ofthis instance.
void
toString(Writer, Char)(ref scope Writer
sink, ref scope const FormatSpec!Char
fmt) const;
Writes a string representation of this to asink.
Examples:toString is rarely directly invoked; the usual way of using it is via
std.format.format:
import std.format;writeln(format("%04d", checked(15)));// "0015"writeln(format("0x%02x", checked(15)));// "0x0f" auto
opCmp(U, this _)(const U
rhs)
if (isIntegral!U || isFloatingPoint!U || is(U == bool));
auto
opCmp(U, Hook1, this _)(Checked!(U, Hook1)
rhs);
Comparesthis againstrhs for ordering. IfHook defineshookOpCmp, the function forwards tohook.hookOpCmp(get, rhs). Otherwise, the result of the built-in comparison operation is returned.
IfU is also an instance ofChecked, both hooks (left- and right-hand side) are introspected for the methodhookOpCmp. If both define it, priority is given to the left-hand side.
Parameters:Urhs | The right-hand side operand |
| U | either the type ofrhs or the underlying type ifrhs is aChecked instance |
| Hook1 | Ifrhs is aChecked instance,Hook1 represents the instance's behavior hook |
Returns:The result ofhookOpCmp ifhook defineshookOpCmp. IfU is an instance ofChecked andhook does not definehookOpCmp, result ofrhs.hook.hookOpCmp is returned. If none of the instances specify the behavior viahookOpCmp,-1 is returned iflhs is lesser thanrhs,1 iflhs is greater thanrhs and0 on equality.
Examples:import std.traits : isUnsigned;staticstruct MyHook{staticbool thereWereErrors;staticint hookOpCmp(L, R)(L lhs, Rrhs) {staticif (isUnsigned!L && !isUnsigned!R) {if (rhs < 0 &&rhs >= lhs) thereWereErrors =true; }elsestaticif (isUnsigned!R && !isUnsigned!L) {if (lhs < 0 && lhs >=rhs) thereWereErrors =true; }// Preserve built-in behavior.return lhs <rhs ? -1 : lhs >rhs; }}auto a = checked!MyHook(-42);assert(a >uint(42));assert(MyHook.thereWereErrors);staticstruct MyHook2{staticint hookOpCmp(L, R)(L lhs, Rrhs) {// Default behaviorreturn lhs <rhs ? -1 : lhs >rhs; }}MyHook.thereWereErrors =false;assert(Checked!(uint, MyHook2)(uint(-42)) <= a);//assert(Checked!(uint, MyHook2)(uint(-42)) >= a);// Hook on left hand side takes precedence, so no errorsassert(!MyHook.thereWereErrors);assert(a <= Checked!(uint, MyHook2)(uint(-42)));assert(MyHook.thereWereErrors); auto
opUnary(string op, this _)()
if (op == "+" || op == "-" || op == "~");
ref Checked
opUnary(string op)() return
if (op == "++" || op == "--");
Defines unary operators+,-,~,++, and--. Unary+ is not overridable and always has built-in behavior (returnsthis). For the others, ifHook defineshookOpUnary,opUnary forwards to Checked!(typeof(hook.hookOpUnary!op(get)), Hook)(hook.hookOpUnary!op(get)).
If
Hook does not define
hookOpUnary but defines
onOverflow,
opUnary forwards to
hook.onOverflow!op(get) in case an overflow occurs. For
++ and
--, the payload is assigned from the result of the call to
onOverflow.
Note that unary
- is considered to overflow if
T is a signed integral of 32 or 64 bits and is equal to the most negative value. This is because that value has no positive negation.
Returns:AChecked instance representing the result of the unary operation
Examples:staticstruct MyHook{staticbool thereWereErrors;static L hookOpUnary(string x, L)(L lhs) {if (x =="-" && lhs == -lhs) thereWereErrors =true;return -lhs; }}auto a = checked!MyHook(long.min);writeln(a);// -aassert(MyHook.thereWereErrors);auto b = checked!void(42);writeln(++b);// 43 auto
opBinary(string op, Rhs)(const Rhs
rhs)
if (isIntegral!Rhs || isFloatingPoint!Rhs || is(Rhs == bool));
auto
opBinary(string op, Rhs)(const Rhs
rhs) const
if (isIntegral!Rhs || isFloatingPoint!Rhs || is(Rhs == bool));
auto
opBinary(string op, U, Hook1)(Checked!(U, Hook1)
rhs);
auto
opBinary(string op, U, Hook1)(Checked!(U, Hook1)
rhs) const;
Defines binary operators+,-,*,/,%,^^,&,|,^,<<,>>, and>>>. IfHook defineshookOpBinary,opBinary forwards to Checked!(typeof(hook.hookOpBinary!op(get, rhs)), Hook)(hook.hookOpBinary!op(get, rhs)).
If
Hook does not define
hookOpBinary but defines
onOverflow,
opBinary forwards to
hook.onOverflow!op(get,rhs) in case an overflow occurs.
If two
Checked instances are involved in a binary operation and both define
hookOpBinary, the left-hand side hook has priority. If both define
onOverflow, a compile-time error occurs.
Parameters:| op | The binary operator |
Rhsrhs | The right hand side operand |
| U | Ifrhs is aChecked instance,U represents the underlying instance type |
| Hook1 | Ifrhs is aChecked instance,Hook1 represents the instance's behavior hook |
Returns:AChecked instance representing the result of the binary operation
auto
opBinaryRight(string op, Lhs)(const Lhs
lhs)
if (isIntegral!Lhs || isFloatingPoint!Lhs || is(Lhs == bool));
auto
opBinaryRight(string op, Lhs)(const Lhs
lhs) const
if (isIntegral!Lhs || isFloatingPoint!Lhs || is(Lhs == bool));
Defines binary operators+,-,*,/,%,^^,&,|,^,<<,>>, and>>> for the case when a built-in numeric or Boolean type is on the left-hand side, and aChecked instance is on the right-hand side.
Parameters:| op | The binary operator |
Lhslhs | The left hand side operand |
Returns:AChecked instance representing the result of the binary operation
ref Checked
opOpAssign(string op, Rhs)(const Rhs
rhs) return
if (isIntegral!Rhs || isFloatingPoint!Rhs || is(Rhs == bool));
ref Checked
opOpAssign(string op, Rhs)(const Rhs
rhs) return
if (is(Rhs == Checked!(RhsT, RhsHook), RhsT, RhsHook));
Defines operators+=,-=,*=,/=,%=,^^=,&=,|=,^=,<<=,>>=, and>>>=.
If
Hook defines
hookOpOpAssign,
opOpAssign forwards to
hook.hookOpOpAssign!op(payload,rhs), where
payload is a reference to the internally held data so the hook can change it.
Otherwise, the operator first evaluates
auto result = opBinary!op(payload, rhs).payload, which is subject to the hooks in
opBinary. Then, if
result is less than
Checked!(T, Hook).min and if
Hook defines
onLowerBound, the payload is assigned from
hook.onLowerBound(result, min). If
result is greater than
Checked!(T, Hook).max and if
Hook defines
onUpperBound, the payload is assigned from
hook.onUpperBound(result, min).
If the right-hand side is also a Checked but with a different hook or underlying type, the hook and underlying type of this Checked takes precedence.
In all other cases, the built-in behavior is carried out.
Parameters:| op | The operator involved (without the"=", e.g."+" for"+=" etc) |
Rhsrhs | The right-hand side of the operator (left-hand side isthis) |
Returns:A reference tothis.
Examples:staticstruct MyHook{staticbool thereWereErrors;static T onLowerBound(Rhs, T)(Rhsrhs, T bound) { thereWereErrors =true;return bound; }static T onUpperBound(Rhs, T)(Rhsrhs, T bound) { thereWereErrors =true;return bound; }}auto x = checked!MyHook(byte.min);x -= 1;assert(MyHook.thereWereErrors);MyHook.thereWereErrors =false;x =byte.max;x += 1;assert(MyHook.thereWereErrors);
Checked!(T, Hook)
checked(Hook = Abort, T)(const T
value)
if (is(typeof(Checked!(T, Hook)(value))));
Convenience function that turns an integral into the correspondingCheckedinstance by using template argument deduction. The hook type may be specified(by defaultAbort).
Parameters:| Hook | type that customizes the behavior, by defaultAbort |
| T | type represetinfg the underlying represantion of theChecked instance |
Tvalue | the actual value of the representation |
Returns:AChecked instance customized by the providedHook andvalue
Examples:staticassert(is(typeof(checked(42)) == Checked!int));writeln(checked(42));// Checked!int(42)staticassert(is(typeof(checked!WithNaN(42)) == Checked!(int, WithNaN)));writeln(checked!WithNaN(42));// Checked!(int, WithNaN)(42)
Force all integral errors to fail by printing an error message tostderr andthen abort the program.Abort is the default second argument forChecked.
Examples:void test(T)(){ Checked!(int,Abort) x; x = 42;auto x1 =cast(T) x; writeln(x1);// 42//x1 += long(int.max);}test!short;test!(constshort);test!(immutableshort); Dst
onBadCast(Dst, Src)(Src
src);
Called automatically upon a bad cast (one that loses precision or attempts to convert a negative value to an unsigned type). The source type isSrc and the destination type isDst.
Returns:Nominally the result is the desired value of the cast operation, which will be forwarded as the result of the cast. ForAbort, the function never returns because it aborts the program.
T
onLowerBound(Rhs, T)(Rhs
rhs, T
bound);
T
onUpperBound(Rhs, T)(Rhs
rhs, T
bound);
Called automatically upon a bounds error.
Parameters:Rhsrhs | The right-hand side value in the assignment, after the operator has been evaluated |
Tbound | The value of the bound being violated |
Returns:Nominally the result is the desired value of the operator, which will be forwarded as result. ForAbort, the function never returns because it aborts the program.
bool
hookOpEquals(Lhs, Rhs)(Lhs
lhs, Rhs
rhs);
Called automatically upon a comparison for equality. In case of a erroneous comparison (one that would make a signed negative value appear equal to an unsigned positive value), this hook issuesassert(0) which terminates the application.
Parameters:Lhslhs | The first argument ofChecked, e.g.int if the left-hand side of the operator isChecked!int |
Rhsrhs | The right-hand side type involved in the operator |
Returns:Upon a correct comparison, returns the result of the comparison. Otherwise, the function terminates the application so it never returns.
int
hookOpCmp(Lhs, Rhs)(Lhs
lhs, Rhs
rhs);
Called automatically upon a comparison for ordering using one of the operators<,<=,>, or>=. In case the comparison is erroneous (i.e. it would make a signed negative value appear greater than or equal to an unsigned positive value), then application is terminated withassert(0). Otherwise, the three-state result is returned (positive iflhs > rhs, negative iflhs < rhs,0 otherwise).
Parameters:Lhslhs | The first argument ofChecked, e.g.int if the left-hand side of the operator isChecked!int |
Rhsrhs | The right-hand side type involved in the operator |
Returns:For correct comparisons, returns a positive integer iflhs > rhs, a negative integer iflhs < rhs,0 if the two are equal. Upon a mistaken comparison such asint(-1) < uint(0), the function never returns because it aborts the program.
typeof(~Lhs())
onOverflow(string x, Lhs)(Lhs
lhs);
typeof(Lhs() + Rhs())
onOverflow(string x, Lhs, Rhs)(Lhs
lhs, Rhs
rhs);
Called automatically upon an overflow during a unary or binary operation.
Parameters:| x | The operator, e.g.- |
Lhslhs | The left-hand side (or sole) argument |
Rhsrhs | The right-hand side type involved in the operator |
Returns:Nominally the result is the desired value of the operator, which will be forwarded as result. ForAbort, the function never returns because it aborts the program.
Force all integral errors to fail by throwing an exception of typeThrow.CheckFailure. The message coming with the error is similar to the oneprinted byWarn.
Examples:void test(T)(){ Checked!(int,Throw) x; x = 42;auto x1 =cast(T) x; writeln(x1);// 42 x = T.max + 1;import std.exception : assertThrown, assertNotThrown; assertThrown(cast(T) x); x = x.max; assertThrown(x += 42); assertThrown(x += 42L); x = x.min; assertThrown(-x); assertThrown(x -= 42); assertThrown(x -= 42L); x = -1; assertNotThrown(x == -1); assertThrown(x ==uint(-1)); assertNotThrown(x <= -1); assertThrown(x <=uint(-1));}test!short;test!(constshort);test!(immutableshort); class
CheckFailure:
object.Exception;
Exception type thrown upon any failure.
this
(T...)(string
f, T
vals);
Parameters:stringf | format specifier |
Tvals | actual values for the format specifier |
Dst
onBadCast(Dst, Src)(Src
src);
Called automatically upon a bad cast (one that loses precision or attempts to convert a negative value to an unsigned type). The source type isSrc and the destination type isDst.
Returns:Nominally the result is the desired value of the cast operation, which will be forwarded as the result of the cast. ForThrow, the function never returns because it throws an exception.
Throws:CheckFailure on bad cast
T
onLowerBound(Rhs, T)(Rhs
rhs, T
bound);
T
onUpperBound(Rhs, T)(Rhs
rhs, T
bound);
Called automatically upon a bounds error.
Parameters:Rhsrhs | The right-hand side value in the assignment, after the operator has been evaluated |
Tbound | The value of the bound being violated |
Returns:Nominally the result is the desired value of the operator, which will be forwarded as result. ForThrow, the function never returns because it throws.
Throws:CheckFailure on overflow
bool
hookOpEquals(L, R)(L
lhs, R
rhs);
Called automatically upon a comparison for equality. Throws upon an erroneous comparison (one that would make a signed negative value appear equal to an unsigned positive value).
Parameters:Llhs | The first argument ofChecked, e.g.int if the left-hand side of the operator isChecked!int |
Rrhs | The right-hand side type involved in the operator |
Returns:The result of the comparison.
Throws:CheckFailure if the comparison is mathematically erroneous.
int
hookOpCmp(Lhs, Rhs)(Lhs
lhs, Rhs
rhs);
Called automatically upon a comparison for ordering using one of the operators<,<=,>, or>=. In case the comparison is erroneous (i.e. it would make a signed negative value appear greater than or equal to an unsigned positive value), throws aThrow.CheckFailure exception. Otherwise, the three-state result is returned (positive iflhs > rhs, negative iflhs < rhs,0 otherwise).
Parameters:Lhslhs | The first argument ofChecked, e.g.int if the left-hand side of the operator isChecked!int |
Rhsrhs | The right-hand side type involved in the operator |
Returns:For correct comparisons, returns a positive integer iflhs > rhs, a negative integer iflhs < rhs,0 if the two are equal.
Throws:Upon a mistaken comparison such asint(-1) < uint(0), the function never returns because it throws aThrow.CheckedFailure exception.
typeof(~Lhs())
onOverflow(string x, Lhs)(Lhs
lhs);
typeof(Lhs() + Rhs())
onOverflow(string x, Lhs, Rhs)(Lhs
lhs, Rhs
rhs);
Called automatically upon an overflow during a unary or binary operation.
Parameters:| x | The operator, e.g.- |
Lhslhs | The left-hand side (or sole) argument |
Rhsrhs | The right-hand side type involved in the operator |
Returns:Nominally the result is the desired value of the operator, which will be forwarded as result. ForThrow, the function never returns because it throws an exception.
Throws:CheckFailure on overflow
Hook that prints tostderr a trace of all integral errors, without affectingdefault behavior.
Examples:auto x = checked!Warn(42);short x1 =cast(short) x;//x += long(int.max);auto y = checked!Warn(cast(constint) 42);short y1 =cast(constbyte) y;
Dst
onBadCast(Dst, Src)(Src
src);
Called automatically upon a bad cast fromsrc to typeDst (one that loses precision or attempts to convert a negative value to an unsigned type).
Parameters:Srcsrc | The source of the cast |
| Dst | The target type of the cast |
T
onLowerBound(Rhs, T)(Rhs
rhs, T
bound);
T
onUpperBound(Rhs, T)(Rhs
rhs, T
bound);
Called automatically upon a badopOpAssign call (one that loses precision or attempts to convert a negative value to an unsigned type).
Parameters:Rhsrhs | The right-hand side value in the assignment, after the operator has been evaluated |
Tbound | The bound being violated |
bool
hookOpEquals(Lhs, Rhs)(Lhs
lhs, Rhs
rhs);
Called automatically upon a comparison for equality. In case of an Erroneous comparison (one that would make a signed negative value appear equal to an unsigned positive value), writes a warning message tostderr as a side effect.
Parameters:Lhslhs | The first argument ofChecked, e.g.int if the left-hand side of the operator isChecked!int |
Rhsrhs | The right-hand side type involved in the operator |
Returns:In all cases the function returns the built-in result oflhs == rhs.
Examples:auto x = checked!Warn(-42);// Passeswriteln(x);// -42// Passes but prints a warning// assert(x == uint(-42));
int
hookOpCmp(Lhs, Rhs)(Lhs
lhs, Rhs
rhs);
Called automatically upon a comparison for ordering using one of the operators<,<=,>, or>=. In case the comparison is erroneous (i.e. it would make a signed negative value appear greater than or equal to an unsigned positive value), then a warning message is printed tostderr.
Parameters:Lhslhs | The first argument ofChecked, e.g.int if the left-hand side of the operator isChecked!int |
Rhsrhs | The right-hand side type involved in the operator |
Returns:In all cases, returnslhs < rhs ? -1 : lhs > rhs. The result is not autocorrected in case of an erroneous comparison.
Examples:auto x = checked!Warn(-42);// Passesassert(x <= -42);// Passes but prints a warning// assert(x <= uint(-42));
typeof(~Lhs())
onOverflow(string x, Lhs)(ref Lhs
lhs);
typeof(Lhs() + Rhs())
onOverflow(string x, Lhs, Rhs)(Lhs
lhs, Rhs
rhs);
Called automatically upon an overflow during a unary or binary operation.
Parameters:| x | The operator involved |
| Lhs | The first argument ofChecked, e.g.int if the left-hand side of the operator isChecked!int |
| Rhs | The right-hand side type involved in the operator |
Returns:mixin(x ~ "lhs") for unary,mixin("lhs" ~ x ~ "rhs") for binary
Hook that provides arithmetically correct comparisons for equality and ordering.Comparing an object of typeChecked!(X, ProperCompare) against anotherintegral (for equality or ordering) ensures that no surprising conversions fromsigned to unsigned integral occur before the comparison. UsingChecked!(X,ProperCompare) on either side of a comparison for equality against afloating-point number makes sure the integral can be properly converted to thefloating point type, thus making sure equality is transitive.
Examples:alias opEqualsProper =ProperCompare.hookOpEquals;assert(opEqualsProper(42, 42));assert(opEqualsProper(42.0, 42.0));assert(opEqualsProper(42u, 42));assert(opEqualsProper(42, 42u));writeln(-1);// 4294967295uassert(!opEqualsProper(-1, 4294967295u));assert(!opEqualsProper(constuint(-1), -1));assert(!opEqualsProper(uint(-1), -1.0));writeln(3_000_000_000U);// -1_294_967_296assert(!opEqualsProper(3_000_000_000U, -1_294_967_296));
bool
hookOpEquals(L, R)(L
lhs, R
rhs);
Hook for== and!= that ensures comparison against integral values has the behavior expected by the usual arithmetic rules. The built-in semantics yield surprising behavior when comparing signed values against unsigned values for equality, for exampleuint.max == -1 or-1_294_967_296 == 3_000_000_000u. The callhookOpEquals(x, y) returnstrue if and only ifx andy represent the same arithmetic number.
If one of the numbers is an integral and the other is a floating-point number,hookOpEquals(x, y) returnstrue if and only if the integral can be converted exactly (without approximation) to the floating-point number. This is in order to preserve transitivity of equality: if hookOpEquals(x, y) andhookOpEquals(y, z) thenhookOpEquals(y, z), in casex,y, andz are a mix of integral and floating-point numbers.
Parameters:Llhs | The left-hand side of the comparison for equality |
Rrhs | The right-hand side of the comparison for equality |
Returns:The result of the comparison,true if the values are equal
auto
hookOpCmp(L, R)(L
lhs, R
rhs);
Hook for<,<=,>, and>= that ensures comparison against integral values has the behavior expected by the usual arithmetic rules. The built-in semantics yield surprising behavior when comparing signed values against unsigned values, for example0u < -1. The callhookOpCmp(x, y) returns-1 if and only ifx is smaller thany in abstract arithmetic sense.
If one of the numbers is an integral and the other is a floating-point number,hookOpEquals(x, y) returns a floating-point number that is-1 ifx < y,0 ifx == y,1 ifx > y, andNaN if the floating-point number isNaN.
Parameters:Llhs | The left-hand side of the comparison for ordering |
Rrhs | The right-hand side of the comparison for ordering |
Returns:The result of the comparison (negative iflhs < rhs, positive if lhs > rhs,0 if the values are equal)
Hook that reserves a special value as a "Not a Number" representative. Forsigned integrals, the reserved value isT.min. For unsigned integrals, thereserved value isT.max.
The default value of aChecked!(X, WithNaN) is its NaN value, so care mustbe taken that all variables are explicitly initialized. Any arithmetic and logicoperation involving at least on NaN becomes NaN itself. All ofa == b,a < b,a > b,a <= b,a >= b yieldfalse if at least one ofa andb is NaN.
Examples:auto x1 = Checked!(int,WithNaN)();assert(x1.isNaN);writeln(x1.get);// int.minassert(x1 != x1);assert(!(x1 < x1));assert(!(x1 > x1));assert(!(x1 == x1));++x1;assert(x1.isNaN);writeln(x1.get);// int.min--x1;assert(x1.isNaN);writeln(x1.get);// int.minx1 = 42;assert(!x1.isNaN);writeln(x1);// x1assert(x1 <= x1);assert(x1 >= x1);staticassert(x1.min ==int.min + 1);x1 +=long(int.max);
The default value used for values not explicitly initialized. It is the NaN value, i.e.T.min for signed integrals andT.max for unsigned integrals.
enum T
max(T);
enum T
min(T);
The maximum value representable isT.max for signed integrals, T.max - 1 for unsigned integrals. The minimum value representable is T.min + 1 for signed integrals,0 for unsigned integrals.
Lhs
hookOpCast(Lhs, Rhs)(Rhs
rhs);
Ifrhs isWithNaN.defaultValue!Rhs, returnsWithNaN.defaultValue!Lhs. Otherwise, returnscast(Lhs) rhs.
Parameters:Rhsrhs | the value being cast (Rhs is the first argument toChecked) |
| Lhs | the target type of the cast |
Returns:The result of the cast operation.
Examples:auto x = checked!WithNaN(422);writeln((cast(ubyte)x));// 255x = checked!WithNaN(-422);writeln((cast(byte)x));// -128writeln(cast(short)x);// -422assert(cast(bool) x);x = x.init;// set back to NaNassert(x !=true);assert(x !=false);
bool
hookOpEquals(Lhs, Rhs)(Lhs
lhs, Rhs
rhs);
Returnsfalse iflhs == WithNaN.defaultValue!Lhs,lhs == rhs otherwise.
Parameters:Lhslhs | The left-hand side of the comparison (Lhs is the first argument toChecked) |
Rhsrhs | The right-hand side of the comparison |
Returns:lhs != WithNaN.defaultValue!Lhs &&lhs ==rhs
double
hookOpCmp(Lhs, Rhs)(Lhs
lhs, Rhs
rhs);
Iflhs == WithNaN.defaultValue!Lhs, returnsdouble.init. Otherwise, has the same semantics as the default comparison.
Parameters:Lhslhs | The left-hand side of the comparison (Lhs is the first argument toChecked) |
Rhsrhs | The right-hand side of the comparison |
Returns:double.init iflhs == WitnNaN.defaultValue!Lhs,-1.0 if lhs < rhs,0.0 iflhs == rhs,1.0 iflhs > rhs.
Examples:Checked!(int, WithNaN) x;assert(!(x < 0) && !(x > 0) && !(x == 0));x = 1;assert(x > 0 && !(x < 0) && !(x == 0));
auto
hookOpUnary(string x, T)(ref T
v);
Defines hooks for unary operators-,~,++, and--.
For
- and
~, if
v == WithNaN.defaultValue!T, returns
WithNaN.defaultValue!T. Otherwise, the semantics is the same as for the built-in operator.
For
++ and
--, if
v == WithNaN.defaultValue!Lhs or the operation would result in an overflow, sets
v to
WithNaN.defaultValue!T. Otherwise, the semantics is the same as for the built-in operator.
Parameters:| x | The operator symbol |
Tv | The left-hand side of the comparison (T is the first argument toChecked) |
Returns:- Forx == "-" || x == "~": Ifv == WithNaN.defaultValue!T, the function returnsWithNaN.defaultValue!T. Otherwise it returns the normal result of the operator.
- Forx == "++" || x == "--": The function returnsvoid.
Examples:Checked!(int, WithNaN) x;++x;assert(x.isNaN);x = 1;assert(!x.isNaN);x = -x;++x;assert(!x.isNaN);
auto
hookOpBinary(string x, L, R)(L
lhs, R
rhs);
Defines hooks for binary operators+,-,*,/,%,^^,&,|,^,<<,>>, and>>> for cases where aChecked object is the left-hand side operand. Iflhs == WithNaN.defaultValue!Lhs, returnsWithNaN.defaultValue!(typeof(lhs + rhs)) without evaluating the operand. Otherwise, evaluates the operand. If evaluation does not overflow, returns the result. Otherwise, returnsWithNaN.defaultValue!(typeof(lhs + rhs)).
Parameters:| x | The operator symbol |
Llhs | The left-hand side operand (Lhs is the first argument toChecked) |
Rrhs | The right-hand side operand |
Returns:Iflhs != WithNaN.defaultValue!Lhs and the operator does not overflow, the function returns the same result as the built-in operator. In all other cases, returnsWithNaN.defaultValue!(typeof(lhs + rhs)).
Examples:Checked!(int, WithNaN) x;assert((x + 1).isNaN);x = 100;assert(!(x + 1).isNaN);
auto
hookOpBinaryRight(string x, L, R)(L
lhs, R
rhs);
Defines hooks for binary operators+,-,*,/,%,^^,&,|,^,<<,>>, and>>> for cases where aChecked object is the right-hand side operand. Ifrhs == WithNaN.defaultValue!Rhs, returnsWithNaN.defaultValue!(typeof(lhs + rhs)) without evaluating the operand. Otherwise, evaluates the operand. If evaluation does not overflow, returns the result. Otherwise, returnsWithNaN.defaultValue!(typeof(lhs + rhs)).
Parameters:| x | The operator symbol |
Llhs | The left-hand side operand |
Rrhs | The right-hand side operand (Rhs is the first argument toChecked) |
Returns:Ifrhs != WithNaN.defaultValue!Rhs and the operator does not overflow, the function returns the same result as the built-in operator. In all other cases, returnsWithNaN.defaultValue!(typeof(lhs + rhs)).
Examples:Checked!(int, WithNaN) x;assert((1 + x).isNaN);x = 100;assert(!(1 + x).isNaN);
void
hookOpOpAssign(string x, L, R)(ref L
lhs, R
rhs);
Defines hooks for binary operators+=,-=,*=,/=,%=,^^=,&=,|=,^=,<<=,>>=, and>>>= for cases where aChecked object is the left-hand side operand. Iflhs == WithNaN.defaultValue!Lhs, no action is carried. Otherwise, evaluates the operand. If evaluation does not overflow and fits inLhs without loss of information or change of sign, setslhs to the result. Otherwise, setslhs toWithNaN.defaultValue!Lhs.
Parameters:| x | The operator symbol (without the=) |
Llhs | The left-hand side operand (Lhs is the first argument toChecked) |
Rrhs | The right-hand side operand |
Examples:Checked!(int, WithNaN) x;x += 4;assert(x.isNaN);x = 0;x += 4;assert(!x.isNaN);x +=int.max;assert(x.isNaN);
bool
isNaN(T)(const Checked!(T, WithNaN)
x);
Queries whether aChecked!(T, WithNaN) object is not a number (NaN).
Parameters:Checked!(T, WithNaN)x | theChecked instance queried |
Returns:true ifx is a NaN,false otherwise
Examples:auto x1 = Checked!(int, WithNaN)();assert(x1.isNaN);x1 = 1;assert(!x1.isNaN);x1 = x1.init;assert(x1.isNaN);
Hook that implementssaturation, i.e. any arithmetic operation that wouldoverflow leaves the result at its extreme value (min ormax depending on thedirection of the overflow).
Saturation is not sticky; if a value reaches its saturation value, anotheroperation may take it back to normal range.
Examples:auto x = checked!Saturate(int.max);++x;writeln(x);// int.max--x;writeln(x);// int.max - 1x =int.min;writeln(-x);// int.maxx -= 42;writeln(x);// int.minwriteln(x * -2);// int.max
T
onLowerBound(Rhs, T)(Rhs, T
bound);
T
onUpperBound(Rhs, T)(Rhs, T
bound);
Implements saturation for operators+=,-=,*=,/=,%=,^^=,&=,|=,^=,<<=,>>=, and>>>=. This hook is called if the result of the binary operation does not fit inLhs without loss of information or a change in sign.
Parameters:| Rhs | The right-hand side type in the assignment, after the operation has been computed |
Tbound | The bound being violated |
Returns:Lhs.max ifrhs >= 0,Lhs.min otherwise.
Examples:auto x = checked!Saturate(short(100));x += 33000;writeln(x);// short.maxx -= 70000;writeln(x);// short.min
auto
onOverflow(string x, Lhs)(Lhs);
typeof(Lhs() + Rhs())
onOverflow(string x, Lhs, Rhs)(Lhs
lhs, Rhs
rhs);
Implements saturation for operators+,- (unary and binary),*,/,%,^^,&,|,^,<<,>>, and>>>.
For unary
-,
onOverflow is called if
lhs == Lhs.min and
Lhs is a signed type. The function returns
Lhs.max.
For binary operators, the result is as follows:
- Lhs.max if the result overflows in the positive direction, on division by0, or on shifting right by a negative value
- Lhs.min if the result overflows in the negative direction
- 0 if
lhs is being shifted left by a negative value, or shifted right by a large positive value
Parameters:| x | The operator involved in theopAssign operation |
| Lhs | The left-hand side type of the operator (Lhs is the first argument toChecked) |
| Rhs | The right-hand side type in the operator |
Returns:The saturated result of the operator.
Examples:writeln(checked!Saturate(int.max) + 1);// int.maxwriteln(checked!Saturate(100)^^10);// int.maxwriteln(checked!Saturate(-100)^^10);// int.maxwriteln(checked!Saturate(100) / 0);// int.maxwriteln(checked!Saturate(100) << -1);// 0writeln(checked!Saturate(100) << 33);// int.maxwriteln(checked!Saturate(100) >> -1);// int.maxwriteln(checked!Saturate(100) >> 33);// 0
typeof(mixin(x == "cmp" ? "0" : "L() " ~ x ~ " R()"))
opChecked(string x, L, R)(const L
lhs, const R
rhs, ref bool
overflow)
if (isIntegral!L && isIntegral!R);
Defines binary operations with overflow checking for any two integral types.The result type obeys the language rules (even when they may becounterintuitive), andoverflow is set if an overflow occurs (includinginadvertent change of signedness, e.g.-1 is converted touint).Conceptually the behavior is:
- Perform the operation in infinite precision
- If the infinite-precision result fits in the result type, return it anddo not touch
overflow - Otherwise, set
overflow totrue and return an unspecified value
The implementation exploits properties of types and operations to minimizeadditional work.
Parameters:| x | The binary operator involved, e.g./ |
Llhs | The left-hand side of the operator |
Rrhs | The right-hand side of the operator |
booloverflow | The overflow indicator (assignedtrue in case there's an error) |
Returns:The result of the operation, which is the same as the built-in operator
Examples:booloverflow;assert(opChecked!"+"(constshort(1),short(1),overflow) == 2 && !overflow);assert(opChecked!"+"(1, 1,overflow) == 2 && !overflow);assert(opChecked!"+"(1, 1u,overflow) == 2 && !overflow);assert(opChecked!"+"(-1, 1u,overflow) == 0 && !overflow);assert(opChecked!"+"(1u, -1,overflow) == 0 && !overflow);
Examples:booloverflow;assert(opChecked!"-"(1, 1,overflow) == 0 && !overflow);assert(opChecked!"-"(1, 1u,overflow) == 0 && !overflow);assert(opChecked!"-"(1u, -1,overflow) == 2 && !overflow);assert(opChecked!"-"(-1, 1u,overflow) == 0 &&overflow);
