$rangeChecks: what changed
Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | - | ||
| 2 | - | ||
| 3 | - | ||
| 4 | - | ||
| 5 | - | ||
| 6 | - | ||
| 7 | - | ||
| 8 | - | ||
| 9 | - | ||
| 10 | - | ||
| 11 | - | ||
| 12 | - | ||
| 13 | - | ||
| 14 | - | ||
| 15 | - | ||
| 16 | - | ||
| 17 | - | ||
| 18 | - | ||
| 19 | - | ||
| 20 | - | ||
| 21 | - | ||
| 22 | - | ||
| 23 | - | ||
| 24 | - | ||
| 25 | - | ||
| 1 | + | The [[FPC]]’s [[local compiler directives|local compiler directive]] **`{$rangeChecks}`** enables or disable range checks of ordinal data type expressions, the default being `{$rangeChecks off}`. The short form `{$R+}` and `{$R-}` is recognized too. | |
| 26 | 2 | ||
| 27 | 3 | ## range checks | |
| 28 | 4 | ||
| 29 | 5 | A range check ensures a value is within the domain of the destination operand. As soon as an operand needs to be “squeezed” into a smaller range, the expression or statement is eligible to a range check. | |
| 30 | 6 | ||
| 31 | 7 | ### behavior | |
| 32 | 8 | ||
| 33 | 9 | If a range check fails, the [[runtime error]] 201 “Range check error” is generated. Thus the code sample | |
| 34 | 10 | ||
| 35 | 11 | ```delphi> | |
| 36 | 12 | {$rangeChecks on} | |
| 37 | 13 | x := y; | |
| 38 | 14 | </syntaxhighlight> | |
| 39 | 15 | is ''semantically'' equivalent to | |
| 40 | 16 | <syntaxhighlight lang= | |
| 41 | 17 | ``` | |
| 42 | 18 | ||
| 43 | 19 | ` {$rangeChecks off}`\ | |
| 44 | 20 | ` x := y;`\ | |
| 45 | 21 | ` if (x < low(x)) or (x > high(x)) then`\ | |
| 46 | 22 | ` begin`\ | |
| 47 | 23 | ` runError(201);`\ | |
| 48 | 24 | ` end;` | |
| 49 | 25 | ||
| 50 | 26 | </syntaxhighlight> | |
| 51 | 27 | ||
| 52 | 28 | (The reported memory address at which the error occurred will differ and the compiler may produce optimized code.) | |
| 53 | 29 | ||
| 54 | 30 | ### eligibility | |
| 55 | 31 | ||
| 56 | 32 | Range checks can be performed | |
| 57 | 33 | ||
| 58 | - | ||
| 59 | - | ||
| 60 | - | ||
| 61 | - | ||
| 62 | - | ||
| 63 | - | ||
| 64 | - | ||
| 34 | + | - in [[Becomes|assignments]] (`:=`), and more specifically | |
| 65 | 35 | - when passing actual parameters, or | |
| 66 | 36 | - indicating [[Array|array]] indices, but also | |
| 67 | 37 | - when doing [[Typecast|typecasts]]. | |
| 68 | 38 | ||
| 69 | 39 | For assignments involving constant expressions a range check is performed already at [[compile-time error|compile-time]], but is either a warning or error depending on the current setting. | |
| 70 | 40 | ||
| 71 | 41 | ### placement | |
| 72 | 42 | ||
| 73 | 43 | The FPC allows enabling and disabling range checks on a per-statement basis, while Delphi allows changing the setting only a per-routine level. | |
| 74 | 44 | ||
| 75 | 45 | ## caveats | |
| 76 | 46 | ||
| 77 | - | ||
| 78 | - | ||
| 79 | - | ||
| 80 | - | ||
| 81 | - | ||
| 82 | - | ||
| 47 | + | - It is important to remember that in [[Pascal]] *arithmetic* [[expression|expressions]] are always evaluated on a computer’s “native” (signed) integer data type. If the destination operand of an arithmetic expression is, for instance a `ALUSInt`, this will never trigger a runtime error. | |
| 83 | 48 | - If range checks are meant to be performed when passing parameters, range checks must be enabled *at* the call site. | |
| 84 | 49 | ||
| 85 | 50 | ## application | |
| 86 | 51 | ||
| 87 | - | ||
| 88 | - | ||
| 89 | - | ||
| 90 | - | ||
| 91 | - | ||
| 92 | - | ||
| 52 | + | Range checks can incur a significant performance penalty. Therefore, the FPC disables range checks by default. However, at least *during* development and prior releases of software, range checks should be enabled to find “obvious” programming mistakes. As a consequence of this practice, if a code fragment is *meant to* exceed the permissible range, it should be documented like this: | |
| 93 | 53 | ||
| 54 | + | ```delphi> | |
| 55 | + | {$push} | |
| 56 | + | {$rangeChecks off} | |
| 57 | + | x := y; | |
| 58 | + | {$pop} | |
| 94 | 59 | </syntaxhighlight> | |
| 95 | 60 | ||
| 96 | - | ||
| 97 | - | ||
| 98 | - | ||
| 99 | - | ||
| 61 | + | Use <code>{$ifOpt}</code> if code needs to be different on the current range-check-setting: | |
| 62 | + | <syntaxhighlight lang= | |
| 100 | 63 | ``` | |
| 101 | - | ||
| 102 | - | ||
| 103 | 64 | ||
| 104 | 65 | ` {$ifOpt R-} // or R+`\ | |
| 105 | 66 | ` …`\ | |
| 106 | 67 | ` {$endIf}` | |
| 107 | 68 | ||
| 108 | 69 | </syntaxhighlight> | |
| 109 | 70 | ||
| 110 | 71 | --- | |
| 111 | 72 | *From the Free Pascal wiki, page "$rangeChecks", as it stood on 2022-03-05 after a change by Alextp, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* | |
| 112 | 73 | Category: FPC |