assert: what changed
Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.
Title: assert
| Old | New | Line | |
|---|---|---|---|
| 1 | + | The compiler procedure [`assert`](https://www.freepascal.org/docs-html/rtl/system/assert.html) inserts an assertion. This is a procedure requiring the [[Boolean]] value [[false and true|true]] in order to proceed, otherwise a [[runtime error|run-time error]] is generated. | |
| 2 | + | ||
| 3 | + | ## use | |
| 4 | + | ||
| 5 | + | The procedure `assert` has the following signature: | |
| 6 | + | ||
| 7 | + | ``` pascal | |
| 8 | + | assert(Boolean) | |
| 9 | + | ``` | |
| 10 | + | ||
| 11 | + | The passed parameter has to be `true` to continue program flow. Usually this is an expression. | |
| 12 | + | ||
| 13 | + | By default the [[FPC]] has code generation for assertions disabled. That means, invocations of `assert` do not end up in the generated binary, thus have no effect whatsoever. By specifying the [[local compiler directives|local compiler directive]] [[$Assertions|{$assertions on}]] (or `{$C+}` for short) or specifying the `‑Sa` command-line switch, appropriate code for assertions is inserted. | |
| 14 | + | ||
| 15 | + | ## behavior | |
| 16 | + | ||
| 17 | + | If the first parameter is `false`, the [`assertErrorProc` procedure](https://www.freepascal.org/docs-html/rtl/system/asserterrorproc.html) is called. This is by default a procedure generating the RTE 227 “Assertion failed error”. In order to convey more information, the `assert` procedure accepts a second optional short string parameter: | |
| 18 | + | ||
| 19 | + | ``` pascal | |
| 20 | + | assert(Boolean, shortstring) | |
| 21 | + | ``` | |
| 22 | + | ||
| 23 | + | The second parameter’s value is passed to the current `assertErrorProc`. The default handler prints the message to standard error. | |
| 24 | + | ||
| 25 | + | > **Note:** The [[sysutils|sysUtils unit]] installs an `assertErrorProc` handler generating an [`eAssertionFailed` exception](https://www.freepascal.org/docs-html/rtl/sysutils/eassertionfailed.html). | |
| 26 | + | ||
| 27 | + | ## application | |
| 28 | + | ||
| 29 | + | Assertions are a straightforward concept ensuring certain statements hold true. However, they do not guarantee your program is indeed correct: Assertions can be a tool to *confirm the presence* of programming mistakes (“bugs”), but they *cannot* prove the *absence* of any. | |
| 30 | + | ||
| 31 | + | Assertions are frequently used *during development*. For example, in the following [[Operator overloading|operator overload]] the assertion ensures certain properties about the `‑` operation: | |
| 32 | + | ||
| 33 | + | ``` pascal | |
| 34 | + | operator - (const positive: foo): foo; | |
| 35 | + | begin | |
| 36 | + | result := negation(foo); | |
| 37 | + | assert(sum(positive, result) = neutralElementOfAddition); | |
| 38 | + | end; | |
| 39 | + | ``` | |
| 40 | + | ||
| 41 | + | However, checking this over and over again is not necessary in a production program. This is a decision that has to be made on a per-application-basis, sometimes on a per-assertion basis. | |
| 42 | + | ||
| 43 | + | Although `assert` is usually provided with a non-trivial Boolean expression, constants are allowed too. In the following piece of code the programmer used an assertion to ensure there is always one alternative taken. | |
| 44 | + | ||
| 45 | + | ``` pascal | |
| 46 | + | case … of | |
| 47 | + | a: … | |
| 48 | + | b: … | |
| 49 | + | c: … | |
| 50 | + | otherwise | |
| 51 | + | begin | |
| 52 | + | assert(false, 'one case has to match!'); | |
| 53 | + | end; | |
| 54 | + | end; | |
| 55 | + | ``` | |
| 56 | + | ||
| 57 | + | Otherwise, for Delphi-compatibility there would be no error if no case matches. Using an `assert` statement provides the flexibility to include or omit it from the generated code, though. | |
| 58 | + | ||
| 59 | + | Assertions are *not* used to verify that the compiler works: | |
| 60 | + | ||
| 61 | + | ``` pascal | |
| 62 | + | procedure foo(var bar: toot); | |
| 63 | + | begin | |
| 64 | + | assert(assigned(@bar)); // wrong | |
| 65 | + | … | |
| 66 | + | ``` | |
| 67 | + | ||
| 68 | + | Assertions are also not used for circumstances more specialized means are available for. That means, assertions are not supposed to replace | |
| 69 | + | ||
| 70 | + | - [[$rangeChecks|{$rangeChecks}]] | |
| 71 | + | - [[$objectChecks|{$objectChecks}]] | |
| 72 | + | - [[$overflowChecks|{$overflowChecks}]] | |
| 73 | + | ||
| 74 | + | among other kinds of checks. | |
| 75 | + | ||
| 76 | + | The paper [[The Power of 10|the power of 10]] suggest two assertions minimum per function. See also | |
| 77 | + | ||
| 78 | + | - [[The Power of Proper Planning and Practices]]. | |
| 79 | + | - [[Defensive programming techniques|Defensive programming techniques § “How to use meaningful Assertions”]] | |
| 80 | + | ||
| 81 | + | ## see also | |
| 82 | + | ||
| 83 | + | - Article: [Assertion (software development)](https://en.wikipedia.org/wiki/Assertion_(software_development)) in the English Wikipedia | |
| 84 | + | ||
| 85 | + | --- | |
| 86 | + | *From the Free Pascal wiki, page "assert", as it stood on 2022-03-04 after a change by Kai Burghardt, 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).* | |
| 87 | + | Category: Pascal |