Defensive programming techniques: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## How to catch and prevent Range Errors
2	2
3	3		Range errors are easy to introduce and sometimes hard to find. They can exist for years without being noticed. I have seen production units where range checks were deliberately turned off by adding \[\[sRangechecks\\|
4	4
5	5		``` pascal
6	6		{$R-}
7	7		```
8	8
9	9		\]\] in a unit and nobody noticed this for years. When I compiled the code during a review with range checks on
10	10
11	11		``` pascal
12	12		{$R+}
13	13		```
14	14
15	15		I found a huge bug that potentially could crash a vital piece of software. Mind you, there can be reasons to turn range checks off but never for a whole unit or a whole program, unless it is fully tested for a release.
16	16
17	17		I will show you how to find range errors, how to debug them and how to prevent them. Defensive programming is important with ranges.
18	18
19	19		### The bug
20	20
21	21		Let's introduce you to a small piece of code with a range bug.
22	22
23	23		``` pascal
24	24		program dtp_1a;
25	25		{$mode objfpc}
26	26		var
27	27		anArray:array[0..9] of integer; // ten elements
28	28		i:integer;
29	29		begin
30	30		for i := 1 to 10 do
31	31		begin
32	32		anArray[i] := i;
33	33		write(anArray[i]:3);
34	34		end;
35	35		end.
36	36		```
37	37
38	38		This code compiles without error and on some systems it even runs! without error:
39	39
40	40		``` bash
41	41		$ fpc -glh dtp_1a.pas
42	42		```
43	43
44	44		Note `-glh` obtains line info in case of an error. Running the program yields:
45	45
46	46		```text
47	47		dtp
48	48		1 2 3 4 5 6 7 8 9 10
49	49		```
50	50
51	51		That may seem right, but is wrong! It could also SEGFAULT or worse … Which you know if you have spotted the bug.
52	52
53	53		### Turn range checks on
54	54
55	55		Now let's see what happens when we compile with range checks:
56	56
57	57		``` pascal
58	58		program dtp_1b;
59	59		{$mode objfpc}
60	60		{$R+}
61	61		var
62	62		anArray:array[0..9] of integer; // ten elements
63	63		i:integer;
64	64		begin
65	65		for i := 1 to 10 do
66	66		begin
67	67		anArray[i] := i;
68	68		write(anArray[i]:3);
69	69		end;
70	70		end.
71	71		```
72	72
73	73		``` bash
74	74		$ fpc -glh dtp_1b.pas
75	75		```
76	76
77	77		You may not expect this code to compile if you discovered the error, but unfortunately it compiles without error or warning. The fun starts when you run it:
78	78
79	79		```text
80	80		dtp
81	81		1 2 3 4 5 6 7 8 9Runtime error 201 at $000101B8
82	82		$000101B8 main, line 10 of dtp.pas
83	83		$00010124
84	84
85	85		No heap dump by heaptrc unit
86	86		Exitcode = 201
87	87		```
88	88
89	89		Ok, we found a bug at line 10 of our program and 201 means range error. Useful, but not very, since we had to run the program to make it crash. Hardly acceptable. Furthermore not every programmer sees what the bug is since it occurs in a loop. Which is wrong?
90	90
91	91		``` pascal
92	92		i
93	93		```
94	94
95	95		or
96	96
97	97		``` pascal
98	98		anArray[i]
99	99		```
100	100
101	101		or both? And when it goes wrong is also not obvious to all.
102	102
103		-	Both the FP [[Textmode IDE\|textmode IDE]] and [[Lazarus]] are able to debug our program, so we set a breakpoint on line 10 and press <span class="kbd">F9</span> a couple of times. Note I also set a watch on
	103	+	Both the FP [[Textmode IDE\|textmode IDE]] and [[Lazarus]] are able to debug our program, so we set a breakpoint on line 10 and press F9 a couple of times. Note I also set a watch on
104	104
105	105		``` pascal
106	106		i
107	107		```
108	108
109	109		.
110	110
111		-	~~<figure>~~
112		-	~~<img src="dtp_1b.png" title="dtp_1b.png" />~~
113		-	~~<figcaption>dtp_1b.png</figcaption>~~
114		-	~~</figure>~~
	111	+	![](/wiki-images/d/d2/Dtp_1b.png)
115	112
116		-	~~So I pressed <span class="kbd">F9</span> ten times and hey presto, the error occurs when~~
	113	+	So I pressed F9 ten times and hey presto, the error occurs when
117	114
118	115		``` pascal
119	116		i
120	117		```
121	118
122	119		becomes 10 and we try to access
123	120
124	121		``` pascal
125	122		anArray[10]
126	123		```
127	124
128	125		. But that means the actual error is on line 9. We are over-indexing because the array is from
129	126
130	127		``` pascal
131	128		0..9
132	129		```
133	130
134	131		, not from
135	132
136	133		``` pascal
137	134		1
138	135		```
139	136
140	137		to
141	138
142	139		``` pascal
143	140		10
144	141		```
145	142
146	143		.
147	144
148	145		Bug found and cause of bug found. But not fixed, remember we found it at runtime, not at compile time.
149	146
150	147		> Note: To summarize, turning range checks on finds range errors at run time, but not always at compile time.
151	148
152	149		=== Declare ranges and use
153	150
154	151		``` pascal
155	152		low()
156	153		```
157	154
158	155		and
159	156
160	157		``` pascal
161	158		high()
162	159		```
163	160
164	161		=== Object Pascal has a nice feature that is a bit underused, but is very useful in our case, ranges. Basically, by declaring a range we can find range errors at compile time and that is exactly what we want.
165	162
166	163		``` pascal
167	164		program dtp_1c;
168	165		{$mode objfpc}{$R+}
169	166		var
170	167		anArray: array[0..9] of integer; // ten elements
171	168		i: 0..9; // range of 10 elements, same as array
172	169		begin
173	170		for i := 1 to 10 do
174	171		begin
175	172		anArray[i] := i;
176	173		write(anArray[i]:3);
177	174		end;
178	175		end.
179	176		```
180	177
181	178		By declaring a range instead of an integer we probably also immediately see the discrepancy in the for to code, but that is not always the case, so let's try to compile the code:
182	179
183		-	~~<figure>~~
184		-	~~<img src="dtp_1c.png" title="dtp_1c.png" />~~
185		-	~~<figcaption>dtp_1c.png</figcaption>~~
186		-	~~</figure>~~
	180	+	![](/wiki-images/4/41/Dtp_1c.png)
187	181
188	182		Does not work, as you can see. The code will not compile because we protected our index variable by applying a range to it. And that is exactly what we want, code that contains bugs should not compile.
189	183
190	184		It is a bit difficult to maintain such code, since we have to keep the array and the range in sync, but that is easy to fix with code like this: Note I also fixed the bug here, because we found the bug and a proper debugging message that the range was wrong.
191	185
192	186		``` pascal
193	187		program dtp_1d;
194	188		{$mode objfpc}{$R+}
195	189		var
196	190		anArray:array[0..9] of integer; // ten elements
197	191		// if we change the array size this is automatically also correct.
198	192		i: low(anArray)..high(anArray);
199	193		begin
200	194		for i := 0 to 9 do // can't write 10 here...
201	195		begin
202	196		anArray[i] := i;
203	197		write(anArray[i]:3);
204	198		end;
205	199		end.
206	200		```
207	201
208	202		For completeness you can also use it like this. If any size needs to change, simply change the type:
209	203
210	204		``` pascal
211	205		program dtp_1e;
212	206		{$mode objfpc}{$R+}
213	207		type
214	208		TmyRange = 0..9;
215	209		var
216	210		i:TMyRange;
217	211		anArray:array[TmyRange] of integer; // ten elements
218	212		begin
219	213		for i := Low(TMyRange) to High(TMyRange) do
220	214		begin
221	215		anArray[i] := i;
222	216		write(anArray[i]:3);
223	217		end;
224	218		end.
225	219		```
226	220
227	221		> Note: To summarize: Declaring a specific range can help you find range errors at compile time. Using
228	222		>
229	223		> ``` pascal
230	224		> low()
231	225		> ```
232	226		>
233	227		> and
234	228		>
235	229		> ``` pascal
236	230		> high()
237	231		> ```
238	232		>
239	233		> can prevent you from making range errors.
240	234
241	235		=== Use
242	236
243	237		``` pascal
244	238		for
245	239		```
246	240
247	241		…
248	242
249	243		``` pascal
250	244		in
251	245		```
252	246
253	247		…
254	248
255	249		``` pascal
256	250		do
257	251		```
258	252
259	253		=== Now, forget all the above. When it is possible, you should use \[\[For\\|
260	254
261	255		``` pascal
262	256		for
263	257		```
264	258
265	259		\]\] … \[\[In\\|
266	260
267	261		``` pascal
268	262		in
269	263		```
270	264
271	265		\]\] … \[\[Do\\|
272	266
273	267		``` pascal
274	268		do
275	269		```
276	270
277	271		\]\]. The Pascal language has
278	272
279	273		``` pascal
280	274		low()
281	275		```
282	276
283	277		and
284	278
285	279		``` pascal
286	280		high()
287	281		```
288	282
289	283		for many years and as shown above it can prevent you from introducing range errors. Modern Pascal has a new similar construct but with a new syntax: \[\[for-in loop\\|
290	284
291	285		``` pascal
292	286		for
293	287		```
294	288
295	289		…
296	290
297	291		``` pascal
298	292		in
299	293		```
300	294
301	295		…
302	296
303	297		``` pascal
304	298		do
305	299		```
306	300
307	301		\]\]. This syntax will simply iterate over all possible values in a collection of data like an array, but without an explicit index.
308	302
309	303		We can get rid of our bug by preventing it in the first place by removing the index altogether.
310	304
311	305		``` pascal
312	306		program dtp_1d;
313	307		{$mode objfpc}{$R+}
314	308		var
315	309		anArray:array[0..9] of integer; // ten elements
316	310		i:0..9; // could use j, but this is for clarity.
317	311		Item:integer; // Item is an integer here: it is not an index, but a value from the array
318	312		begin
319	313		// data to show what for in do does
320	314		for i := Low(anArray) to High(anArray) do anArray[i] := 100+i;
321	315		for Item in anArray do // for every integer value that is contained in the array
322	316		write(Item:4); // writes the value of an array cell, this is not an index.
323	317		end.
324	318		```
325	319
326	320		> Note: To summarize: with
327	321		>
328	322		> ``` pascal
329	323		> for
330	324		> ```
331	325		>
332	326		> …
333	327		>
334	328		> ``` pascal
335	329		> in
336	330		> ```
337	331		>
338	332		> …
339	333		>
340	334		> ``` pascal
341	335		> do
342	336		> ```
343	337		>
344	338		> you can safely iterate over a collection of data without using an explicit index and the risk of range errors.
345	339
346	340		### Bonus: Using a range? You may want a set, too!
347	341
348	342		If you have declared a range, why not declare a [[Set\|set]] as well? This will give you a safe way of performing filters on a data collection like an array.
349	343
350	344		A simple example looks like this:
351	345
352	346		``` pascal
353	347		program dtp_1f;
354	348		{$mode objfpc}{$R+}
355	349		type
356	350		TmyRange = 0..9;
357	351		var
358	352		i:TMyRange;
359	353		j:set of TMyRange;
360	354		anArray:array[TmyRange] of integer; // ten elements
361	355		begin
362	356		j:=[1,3,5,7,9];// odd elements
363	357		for i in j do
364	358		begin
365	359		anArray[i] := i;
366	360		write(anArray[i]:3);
367	361		end;
368	362		end.
369	363		```
370	364
371	365		Ranges are powerful, sets are even more so! And makes your code safe and readable.
372	366
373	367		### Conclusion
374	368
375	369		Range errors are common in every language, often hard to find, but if you are reading this you are probably using Pascal.
376	370
377	371		And with the right mindset a Pascal programmer can write code in such a way that range errors should hardly exist in the code.
378	372
379	373		Because Pascal is so strongly typed and has so many features to help you prevent range errors.
380	374
381	375		- use \[\[sRangechecks\\|
382	376		``` pascal
383	377		{$rangechecks on}
384	378		```
385	379
386	380		\]\] or
387	381
388	382		``` pascal
389	383		{$R+}
390	384		```
391	385
392	386		during development and run your code. Turn it off if you are sure there are no range errors but protect your code with ranges.
393	387		- use ranges instead of integers for your index and think about range when writing your code! It will prevent you from introducing range errors and you will catch them at compile time.
394	388		- use
395	389		``` pascal
396	390		low()
397	391		```
398	392
399	393		and
400	394
401	395		``` pascal
402	396		high()
403	397		```
404	398
405	399		not
406	400
407	401		``` pascal
408	402		1
409	403		```
410	404
411	405		to
412	406
413	407		``` pascal
414	408		10
415	409		```
416	410
417	411		or
418	412
419	413		``` pascal
420	414		0
421	415		```
422	416
423	417		to
424	418
425	419		``` pascal
426	420		9
427	421		```
428	422
429	423		when you iterate a data collection. Make it a habit.
430	424		- use
431	425		``` pascal
432	426		for
433	427		```
434	428
435	429		…
436	430
437	431		``` pascal
438	432		in
439	433		```
440	434
441	435		…
442	436
443	437		``` pascal
444	438		do
445	439		```
446	440
447	441		if applicable, try to make that your first option!
448	442		- use a set of range to safely filter
449	443
450	444		There is more to this subject, but if you follow these simple rules you avoid bugs and trust me: there is no speed penalty. A bit of “brains instead of fingers” will prevent this nasty category of bugs and prevents you from spending more debug time than coding time!
451	445
452	446		## How to prevent Overflow Errors, catch them and even misuse Overflow
453	447
454	448		### The bug
455	449
456	450		Let's introduce you to a small piece of code with an overflow bug.
457	451
458	452		``` pascal
459	453		program dtp_2a;
460	454		{$mode objfpc}
461	455		var
462	456		a:NativeInt = high(NativeInt);
463	457		begin
464	458		a:= a + 1;
465	459		writeln(a);
466	460		end.
467	461		```
468	462
469	463		Can you spot the bug? Concentrate, look again… Can you see it?
470	464
471	465		Now compile that like `fpc dtp_2a.pas`. Then run it:
472	466
473	467		``` bash
474	468		$ ./dtp_2a
475	469		-2147483648 //depending on nativeint: this is 32 bit
476	470		```
477	471
478	472		It does not crash, it simply prints `-2147483648`. But is that correct? Of course not! Now with overflowchcks on:
479	473
480	474		``` pascal
481	475		program dtp_2a;
482	476		{$mode objfpc}{$overflowchecks on}
483	477		var
484	478		a:NativeInt = high(NativeInt);
485	479		begin
486	480		a:= a + 1;
487	481		writeln(a);
488	482		end.
489	483		```
490	484
491	485		This code will compile, but it will generate an overflow error when you run it: 215. See the programmers guide on overflow checks.
492	486
493	487		## How to prevent Input and Output Errors (and how to catch them…)
494	488
495	489		## How to use meaningful Assertions
496	490
497	491		## To serve and protect: the story of try..finally
498	492
499	493		## Do you know your String Type? Really?
500	494
501	495		\[This should be written by Juha… not me…\]
502	496
503	497		string is a devil with many faces: It can be ShortString, AnsiString and UnicodeString.\
504	498		I have the habit to declare the exact species of string I am using, especially in library code, but what if the code just says string? Well, here's a little utility function to obtain the string type you are actually working with:
505	499
506	500		``` pascal
507	501		//{$mode delphi} // tkAString AnsiString
508	502		//{$mode delphi}{$H-} // tkSString ShortString
509	503		//{$mode delphiunicode} // tkUString Unicode string
510	504		//{$mode delphiunicode}{$H-} // tkSString ShortString
511	505		//{$mode objfpc} // tkSString ShortString
512	506		//{$mode objfpc}{$H+} //tkAString AnsiString
513	507		//{$mode fpc}{$modeswitch result} // tkSString ShortString
514	508		//{$mode fpc}{$H+}{$modeswitch result} // tkAString AnsiString
515	509		// etc.
516	510
517	511		uses typinfo;
518	512
519	513		function StringType(const s:string):TTypeKind;inline;
520	514		var info:PTypeInfo;
521	515		begin
522	516		info:=TypeInfo(s);
523	517		Result := Info^.Kind;
524	518		end;
525	519
526	520		var s: string = 'testme';
527	521		begin
528	522		writeln('My string type is ',StringType(s));
529	523		end.
530	524		```
531	525
532	526		string depends on mode,and this little gem will tell you what kind of string you are dealing with.\
533	527		That is not always obvious. Try to experiment with some of the mode settings and see what happens.\
534	528		The result may not always be what you expected, so use this function as a debug utility. You can be sure it returns what string means at any given unit.
535	529
536	530		---
537	531		From the Free Pascal wiki, page "Defensive programming techniques", as it stood on 2021-09-29 after a change by Thaddy, 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).
538	532		Category: Code
539	533		Category: Tutorials

Back to history