/
stdlib.html
546 lines (481 loc) · 34.3 KB
/
stdlib.html
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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>stdlib.h</TITLE>
<STYLE TYPE="TEXT/CSS">
<!--
.IE3-DUMMY { CONT-SIZE: 100%; }
BODY { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; }
P { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H1 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H2 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H3 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H4 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H5 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H6 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
UL { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #FFFFFF; }
.NOBORDER { BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }
.NOBORDER TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }
.CODE { FONT-FAMILY: Courier New; }
-->
</STYLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#E0E0E0">
<FONT SIZE="5"><B>The <stdlib.h> Header File</B></FONT>
<HR>
<P><B>Some useful routines proposed by ANSI (sorting, searching, etc.)</B></P>
<H3><U>Functions</U></H3>
<DL INDENT="20"><DT><B><A HREF="#abort">abort</A></B><DD>Abnormal termination of a process.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#abs">abs</A></B><DD>Absolute value of a number.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="alloc.html#alloca">alloca</A></B><DD>Allocates memory on the local storage space.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#atexit">atexit</A></B><DD>Registers a termination function.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="timath.html#atof">atof</A></B><DD>Converts a string to a floating point.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#atoi">atoi</A></B><DD>Converts a string to a short integer.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#atol">atol</A></B><DD>Converts a string to a long integer.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#bsearch">bsearch</A></B><DD>Binary search.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="alloc.html#calloc">calloc</A></B><DD>Allocates a memory block for a given number and size of items.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#div">div</A></B><DD>Divides two short integers, and returns quotient and remainder.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#exit">exit</A></B><DD>Forced termination of the program.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="timath.html#fabs">fabs</A></B><DD>Absolute value of a floating point number.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="alloc.html#free">free</A></B><DD>Frees an allocated block.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#labs">labs</A></B><DD>Absolute value of a long integer number.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ldiv">ldiv</A></B><DD>Divides two long integers, and returns quotient and remainder.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="alloc.html#malloc">malloc</A></B><DD>Allocates a memory block.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#max">max</A></B><DD>Maximum of two integer numbers.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#min">min</A></B><DD>Minimum of two integer values.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#qsort">qsort</A></B><DD>Sorts an area of items.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#rand">rand</A></B><DD>Returns a pseudorandom number.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#random">random</A></B><DD>Generates a random integer in a given range.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#randomize">randomize</A></B><DD>Initializes random number generator with a random value.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="alloc.html#realloc">realloc</A></B><DD>Reallocates allocated memory.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#srand">srand</A></B><DD>Initializes random number generator.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#strtod">strtod</A></B><DD>Converts a string to a floating point value, with optional error-checking.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#strtol">strtol</A></B><DD>Converts a string to a long integer using a given radix, with detection of overflows and errors.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#strtoul">strtoul</A></B><DD>Converts a string to an unsigned long integer using a given radix, with detection of overflows and errors.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#TIOS_strtod">TIOS_strtod</A></B><BR><BR></DL>
<H3><U>Constants</U></H3>
<DL INDENT="20"><DT><B><A HREF="#EXIT_FAILURE">EXIT_FAILURE</A></B><DD>Failure exit code for <A HREF="#exit">exit</A>.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#EXIT_SUCCESS">EXIT_SUCCESS</A></B><DD>Normal exit code for <A HREF="#exit">exit</A>.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="alloc.html#NULL">NULL</A></B><DD>A null-pointer value.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#RAND_MAX">RAND_MAX</A></B><DD>Returns the largest number returned by <A HREF="#rand">rand</A>.</DL>
<H3><U>Predefined Types</U></H3>
<DL INDENT="20"><DT><B><A HREF="#atexit_t">atexit_t</A></B><DD>Describes an exit function passed to <A HREF="#atexit">atexit</A>.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#compare_t">compare_t</A></B><DD>Describes a comparison function.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#div_t">div_t</A></B><DD>An integer division return type used in the <A HREF="#div">div</A> function.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ldiv_t">ldiv_t</A></B><DD>A long integer division return type used in the <A HREF="#ldiv">ldiv</A> function.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="stddef.html#size_t">size_t</A></B><DD>A type to define sizes of strings and memory blocks.</DL>
<HR>
<H3><A NAME="abort"><U>abort</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> abort (<B><A HREF="keywords.html#void">void</A></B>);</TD></TR></TABLE></P>
<P><B>Abnormal termination of a process.</B></P>
<P>abort writes a termination message ("ABNORMAL PROGRAM TERMINATION") in the status line,
then aborts the program by a call to <A HREF="#exit">exit</A> (passing 0 to it).
<BR><BR>
Note that the status line text will not be visible if <CODE>SAVE_SCREEN</CODE> is defined.</P>
<HR>
<H3><A NAME="abs"><U>abs</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE">any_type abs (any_type x);</TD></TR></TABLE></P>
<P><B>Absolute value of a number.</B></P>
<P>abs returns the absolute value of a numeric argument <I>x</I>, which may be either an integer
or a floating point value. The returned value is of the same type as the argument.
<BR><BR>
<B>Note:</B> abs is a smart macro compiling to open code which depends on the type of the
argument.</P>
<P>See also: <A HREF="#labs">labs</A>, <A HREF="timath.html#fabs">fabs</A></P>
<HR>
<H3><A NAME="atexit"><U>atexit</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> atexit (<A HREF="#atexit_t">atexit_t</A> func);</TD></TR></TABLE></P>
<P><B>Registers a termination function.</B></P>
<P>atexit registers the function pointed to by <I>func</I> as an exit function.
Upon normal termination of the program (including termination using the
<A HREF="#exit">exit</A> function), <I>func</I> is called just before
returning to the TIOS. Each call to atexit registers another exit function.
The number of function which can be registered depends on the current number
of free handles. All registered termination functions are executed on a last-in,
first-out basis (the last function registered is the first to be executed).
atexit returns 0 on success and nonzero on failure (no space left to register
the function).
<BR><BR>
<B>Note:</B> Termination functions are not called on abnormal termination of the
program (i.e. if an error is thrown from the program).
<BR><BR>
atexit does not work with <A HREF="system.html#enter_ghost_space">enter_ghost_space</A>.
However, if a program is already executed in the ghost space (because of ExePack
compression or because it has been called from a launcher), there should not be
any problems.</P>
<HR>
<H3><A NAME="atoi"><U>atoi</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> atoi (<B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *str);</TD></TR></TABLE></P>
<P><B>Converts a string to a short integer.</B></P>
<P>atoi converts the string pointed to by <I>str</I> to integer. atoi recognizes (in the
following order):</P>
<UL>
<LI><P>an optional string of spaces [ws];</P></LI>
<LI><P>an optional sign ('+', '-', or special "small" minus used in TI-Basic) [sn];</P></LI>
<LI><P>a string of digits [ddd].</P></LI>
</UL>
<P>The characters must match this generic format:
<BR><BR>
[ws] [sn] [ddd]
<BR><BR>
In atoi, the first unrecognized character ends the conversion. There are no provisions for
overflow in atoi (results are wrong in a case of overflow). atoi returns the converted value
of the input string. If the string cannot be converted, the return value is 0. See
<A HREF="#strtol">strtol</A> and <A HREF="#strtoul">strtoul</A> for conversions which
allow much greater flexibility.</P>
<HR>
<H3><A NAME="atol"><U>atol</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">long</A></B> atol (<B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *str);</TD></TR></TABLE></P>
<P><B>Converts a string to a long integer.</B></P>
<P>atol is similar to <A HREF="#atoi">atoi</A>, but converts the string to a long integer.</P>
<HR>
<H3><A NAME="bsearch"><U>bsearch</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> *bsearch (<B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#void">void</A></B> *Key, <B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#void">void</A></B> *BasePtr, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> NoOfElements, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> Width, <A HREF="#compare_t">compare_t</A> cmp_func);</TD></TR></TABLE></P>
<P><B>Binary search.</B></P>
<P>bsearch searches a table (array) of <I>NoOfElements</I> elements in memory, and returns
the address of the first entry in the table that matches the search key. Because this is a
binary search, the first matching entry is not necessarily the first entry in the table.
If no match is found, bsearch returns <A HREF="alloc.html#NULL">NULL</A>.
<I>NoOfElements</I> gives the number of elements in the table.
<I>Width</I> specifies the number of bytes in each table entry.
<I>BasePtr</I> points to the base (0-th element) of the table to be sorted.
<I>Key</I> is a pointer to the search key.
<I>cmp_func</I>, the comparison function, accepts two arguments,
<I>elem1</I> and <I>elem2</I>, each a pointer to an entry in the table.
The comparison function compares each of the pointed-to items (*<I>elem1</I> and
*<I>elem2</I>), and returns a short integer based on the result of the comparison:</P>
<UL>
<LI><P>If *<I>elem1</I> < *<I>elem2</I>, <I>cmp_func</I> should return an integer < 0.</P></LI>
<LI><P>If *<I>elem1</I> == *<I>elem2</I>, <I>cmp_func</I> should return 0.</P></LI>
<LI><P>If *<I>elem1</I> > *<I>elem2</I>, <I>cmp_func</I> should return an integer > 0.</P></LI>
</UL>
<P>Here is a complete example of usage (called "Binary Search"):</P>
<PRE>// Search integer values using a binary search.
#define USE_TI89 // Compile for TI-89
#define USE_TI92PLUS // Compile for TI-92 Plus
#define USE_V200 // Compile for V200
#define OPTIMIZE_ROM_CALLS
#define MIN_AMS 100 // Compile for AMS 1.00 or higher
#define SAVE_SCREEN // Save/Restore LCD Contents
#include <tigcclib.h> // Include All Header Files
// Comparison Function
CALLBACK short int_comp(const void *a, const void *b)
{
return (*(const short*)a) - (*(const short*)b);
}
// Main Function
void _main(void)
{
short list[10] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
short i;
short font;
void *p;
font = FontGetSys();
FontSetSys(F_4x6);
clrscr ();
for (i = -1; i < 11; i++) {
p = bsearch (&i, list, sizeof(list)/sizeof(list[0]), sizeof (list[0]), int_comp);
if (p == NULL) {
printf ("%d not found\n", i);
}
else {
printf ("%d is at index %lu\n", i, ((void *)p - (void *)list)/sizeof(list[0]));
}
}
FontSetSys(font);
ngetchx ();
}
</PRE>
<P>
<B>Note: if speed matters, create a bsearch() routine in your program, and inline the comparison
function and element copy/swap codes. Your routine will be significantly faster and smaller that way.</B></P>
<P>See also: <A HREF="#qsort">qsort</A></P>
<HR>
<H3><A NAME="div"><U>div</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="#div_t">div_t</A> div (<B><A HREF="keywords.html#short">short</A></B> numer, <B><A HREF="keywords.html#short">short</A></B> denom);</TD></TR></TABLE></P>
<P><B>Divides two short integers, and returns quotient and remainder.</B></P>
<P>div divides two integers and returns both the quotient and the remainder as
a <A HREF="#div_t">div_t</A> type. <I>numer</I> and <I>denom</I> are the numerator and the
denominator, respectively. div returns a structure whose elements are <I>quot</I> (the
quotient) and <I>rem</I> (the remainder).
<BR><BR>
<B>Note:</B> div is an inline function, implemented using GNU C smart macros.</P>
<HR>
<H3><A NAME="exit"><U>exit</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> exit (<B><A HREF="keywords.html#short">short</A></B> code);</TD></TR></TABLE></P>
<P><B>Forced termination of the program.</B></P>
<P>exit terminates the program (it may be called from any nesting level). Before termination, any
registered "exit functions" (posted with <A HREF="#atexit">atexit</A>) are called. ANSI proposes
that exit also closes all open files. Such behaviour is not implemented here, you need to do
it manually if necessary.
<BR><BR>
<I>code</I> is the exit status. Value of 0 (<A HREF="#EXIT_SUCCESS">EXIT_SUCCESS</A>) is used to
indicate a normal exit. If <I>code</I> is nonzero (e.g. <A HREF="#EXIT_FAILURE">EXIT_FAILURE</A>),
an error message dialog which corresponds with code <I>code</I> will be displayed before exiting. Note that
this is not the same as throwing error <I>code</I> using <A HREF="error.html#ER_throwVar">ER_throwVar</A>.
Throwing an error is much more a "barbaric" method for exiting from the program. Among others, by throwing an
error, no registered "exit functions" will be called.</P>
<HR>
<H3><A NAME="labs"><U>labs</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">long</A></B> labs (<B><A HREF="keywords.html#short">long</A></B> x);</TD></TR></TABLE></P>
<P><B>Absolute value of a long integer number.</B></P>
<P>labs returns the absolute value of (long) integer argument <I>x</I>.
<BR><BR>
<B>Note:</B> labs is a built-in function in the GCC compiler itself, and it compiles to open code instead of
a function call.</P>
<P>See also: <A HREF="#abs">abs</A>, <A HREF="timath.html#fabs">fabs</A></P>
<HR>
<H3><A NAME="ldiv"><U>ldiv</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="#ldiv_t">ldiv_t</A> ldiv (<B><A HREF="keywords.html#short">long</A></B> n, <B><A HREF="keywords.html#short">long</A></B> d);</TD></TR></TABLE></P>
<P><B>Divides two long integers, and returns quotient and remainder.</B></P>
<P>ldiv divides two long integers and returns both the quotient and the remainder as
a <A HREF="#ldiv_t">ldiv_t</A> type. <I>numer</I> and <I>denom</I> are the numerator and the
denominator, respectively. div returns a structure whose elements are <I>quot</I> (the
quotient) and <I>rem</I> (the remainder).
<BR><BR>
<B>Note:</B> ldiv is an inline function, implemented using GNU C smart macros.</P>
<HR>
<H3><A NAME="max"><U>max</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE">any_type max (any_type a, anytype b);</TD></TR></TABLE></P>
<P><B>Maximum of two integer numbers.</B></P>
<P>max is an inline function (implemented using GNU C smart macros) which returns the greater of
<I>a</I> and <I>b</I>.
They may be any numeric values, either integer or floating point
numbers, and they also may be pointers to the same base type. The result has the type of the
argument which has greater range of possible values (e.g. if one is float and second one is
long int, the result is of float type).</P>
<P>See also: <A HREF="#min">min</A></P>
<HR>
<H3><A NAME="min"><U>min</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE">any_type min (any_type a, anytype b);</TD></TR></TABLE></P>
<P><B>Minimum of two integer values.</B></P>
<P>min is an inline function (implemented using GNU C smart macros) which returns the smaller of
<I>a</I> and <I>b</I>. They may be any numeric values, either integer or floating point
numbers, and they also may be pointers to the same base type. The result has the type of the
argument which has greater range of possible values (e.g. if one is float and second one is
long int, the result is of float type).</P>
<P>See also: <A HREF="#max">max</A></P>
<HR>
<H3><A NAME="qsort"><U>qsort</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> qsort (<B><A HREF="keywords.html#void">void</A></B> *BasePtr, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> NoOfElements, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> Width, <A HREF="#compare_t">compare_t</A> cmp_func);</TD></TR></TABLE></P>
<P><B>Sorts an area of items.</B></P>
<P>qsort sorts the entries in a table by repeatedly calling the user-defined
comparison function pointed to by <I>cmp_func</I>. <I>BasePtr</I> points to the base
(0-th element) of the table to be sorted. <I>NoOfElement</I> is the number of
entries in the table. <I>Width</I> is the size of each entry in the table, in
bytes. <I>cmp_func</I>, the comparison function, accepts two arguments,
<I>elem1</I> and <I>elem2</I>, each a pointer to an entry in the table.
The comparison function compares each of the pointed-to items (*<I>elem1</I> and
*<I>elem2</I>), and returns a short integer based on the result of the comparison:</P>
<UL>
<LI><P>If *<I>elem1</I> < *<I>elem2</I>, <I>cmp_func</I> should return an integer < 0.</P></LI>
<LI><P>If *<I>elem1</I> == *<I>elem2</I>, <I>cmp_func</I> should return 0.</P></LI>
<LI><P>If *<I>elem1</I> > *<I>elem2</I>, <I>cmp_func</I> should return an integer > 0.</P></LI>
</UL>
<P>In the comparison, the less-than symbol (<) means the left element should
appear before the right element in the final, sorted sequence. Similarly, the
greater-than symbol (>) means the left element should appear after the right element
in the final, sorted sequence.
<BR><BR>
The ANSI standard proposes that the comparison function has to return a long integer.
However, <A HREF="string.html#strcmp">strcmp</A>, which is frequently
used as a comparison function, returns a short integer.
<BR><BR>
<B>Note: if speed matters, create a qsort() routine in your program, and inline the comparison
function and element copy/swap codes. Your routine will be significantly faster and smaller that way.</B>
<BR><BR>
Here is a complete example of usage (called "Sort Integers"):</P>
<PRE>// Sort a list of integer values
#define USE_TI89 // Compile for TI-89
#define USE_TI92PLUS // Compile for TI-92 Plus
#define USE_V200 // Compile for V200
#define MIN_AMS 100 // Compile for AMS 1.00 or higher
#define SAVE_SCREEN // Save/Restore LCD Contents
#include <tigcclib.h> // Include All Header Files
// Comparison Function
CALLBACK short int_comp(const void *a, const void *b)
{
return (*(const short*)a) - (*(const short*)b);
}
// Main Function
void _main(void)
{
short list[10] = {2, 9, 3, 6, 4, 2, 3, 3, 1, 5};
int i;
clrscr ();
qsort (list, 10, sizeof (short), int_comp);
for (i = 0; i < 10; i++)
printf ("%d ", list[i]);
ngetchx ();
}
</PRE>
<P>Note that the function <A HREF="string.html#strcmp">strcmp</A> is ideal for string comparisons.
However, its parameters are not void pointers. This may be solved using a typecast like</P>
<PRE>qsort (<I>StringArray</I>, <I>NoOfStrings</I>, <I>LenOfEachString</I>, (compare_t) strcmp);
</PRE>
<P>See also: <A HREF="#bsearch">bsearch</A></P>
<HR>
<H3><A NAME="rand"><U>rand</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> rand (<B><A HREF="keywords.html#void">void</A></B>);</TD></TR></TABLE></P>
<P><B>Returns a pseudorandom number.</B></P>
<P>rand uses a linear congruential random number generator to return successive pseudorandom
numbers in the range from 0 to <A HREF="#RAND_MAX">RAND_MAX</A> (i.e. from 0 to 32767).
It returns the generated pseudorandom number.</P>
<P>See also: <A HREF="#srand">srand</A>, <A HREF="#randomize">randomize</A>, <A HREF="#random">random</A></P>
<HR>
<H3><A NAME="random"><U>random</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> random (<B><A HREF="keywords.html#short">short</A></B> num);</TD></TR></TABLE></P>
<P><B>Generates a random integer in a given range.</B></P>
<P>random is a macro which uses <A HREF="#rand">rand</A> to return a random number
between 0 and (<I>num</I>-1).</P>
<P>See also: <A HREF="#rand">rand</A>, <A HREF="#srand">srand</A>, <A HREF="#randomize">randomize</A></P>
<HR>
<H3><A NAME="randomize"><U>randomize</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> randomize (<B><A HREF="keywords.html#void">void</A></B>);</TD></TR></TABLE></P>
<P><B>Initializes random number generator with a random value.</B></P>
<P>randomize initializes the random number generator with a random value
(picked from the timer).</P>
<P>See also: <A HREF="#rand">rand</A>, <A HREF="#random">random</A>, <A HREF="#srand">srand</A></P>
<HR>
<H3><A NAME="srand"><U>srand</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> srand (<B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">long</A></B> seed);</TD></TR></TABLE></P>
<P><B>Initializes random number generator.</B></P>
<P>The random number generator is reinitialized by calling srand with an argument value of 1.
It can be set to a new starting point by calling srand with a given seed number (if
an argument is set to <I>seed</I>).</P>
<P>See also: <A HREF="#rand">rand</A>, <A HREF="#random">random</A>, <A HREF="#randomize">randomize</A></P>
<HR>
<H3><A NAME="strtod"><U>strtod</U></A></H3>
<P><A HREF="httigcc.html#minams">AMS 2.00 or higher</A></P>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#float">double</A></B> strtod(<B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *str, <B><A HREF="keywords.html#int">char</A></B> **endptr);</TD></TR></TABLE></P>
<P><B>Converts a string to a floating point value, with optional error-checking.</B></P>
<P>strtod converts a string pointed to by <I>s</I> to a floating point value. It recognizes
the following character representation of a floating point number:</P>
<UL>
<LI><P>an optional string of spaces;</P></LI>
<LI><P>an optional minus sign <B>(0xAD character, instead of ordinary '-')</B>;</P></LI>
<LI><P>a string of digits and an optional decimal point (the digits can be on both
sides of the decimal point);</P></LI>
<LI><P>an optional exponent followed by a (optionally signed) integer. <B>The exponent
character needs to be 0x95, instead of ordinary 'e' or 'E'.</B></P></LI>
</UL>
<P>
It is easy to "preprocess" any string to satisfy this convention before calling strtod,
by code such as the following snippet (assuming that <I>c</I> is a char variable, and <I>i</I>
is an integer variable):</P>
<PRE>for (i = 0; (c = s[i]); i++)
// <I>Yes, the second '=' is really '=', not '=='</I>...
{
if (c == '-') s[i] = 0xAD;
if ((c|32) == 'e') s[i] = 0x95;
}
</PRE>
<P>
strtod returns the converted value (BCD floating-point number). If <I>endptr</I>
is not NULL, the char pointer pointed to by it is assigned the address of
the first character of the string following the converted floating-point
number. If the conversion fails, 0.0 is returned and <I>*endptr</I> is assigned
the value <I>str</I>.<BR>
If the result of the conversion would cause overflow, strtod sets <A HREF="unknown.html#errno">errno</A>
to ERANGE and returns 9.9999999999999e+999. If the result of the conversion would cause underflow,
strtod sets <A HREF="unknown.html#errno">errno</A> to ERANGE and returns 0.
<BR><BR>
<B>Note:</B> This function is part of AMS, but it is wrapped in the library to prevent a crash when
<CODE>end_ptr == NULL</CODE> on early AMS 2.xx versions. In fact, <A HREF="timath.html#atof">atof</A>
ends up calling strtod, and using atof takes up more space into your program than strtod does, while not
providing the <I>endptr</I> argument, which helps for error checking.</P>
<P>See also: <A HREF="timath.html#atof">atof</A></P>
<HR>
<H3><A NAME="strtol"><U>strtol</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">long</A></B> strtol (<B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *str, <B><A HREF="keywords.html#int">char</A></B> **endptr, <B><A HREF="keywords.html#short">short</A></B> radix);</TD></TR></TABLE></P>
<P><B>Converts a string to a long integer using a given radix, with detection of overflows and errors.</B></P>
<P>strtol converts a character string <I>str</I> to a long integer value. <I>str</I> is a
sequence of characters that can be interpreted as a long value. The characters must match this
generic format:
<BR><BR>
[ws] [sn] [0] [x] [ddd]
<BR><BR>
where</P>
<UL>
<LI><P>[ws] is an optional string of spaces;</P></LI>
<LI><P>[sn] is an optional sign ('+', '-', or special "small" minus used in TI-Basic);</P></LI>
<LI><P>[0] is an optional zero (0);</P></LI>
<LI><P>[x] is an optional 'x' or 'X';</P></LI>
<LI><P>[ddd] is an optional string of digits.</P></LI>
</UL>
<P>strtol stops reading the string at the first character it doesn't recognize.</P>
<UL>
<LI><P>If <I>radix</I> is between 2 and 36, the long integer is expressed in base <I>radix</I>.</P></LI>
<LI><P>If <I>radix</I> is 0, the first few characters of <I>str</I> determine the base of the value
being converted.<BR><BR>
<TABLE BORDER CELLPADDING="5">
<TR><TD>First character</TD><TD>Second character</TD><TD>String interpreted as</TD></TR>
<TR><TD>0<BR>0<BR>1 - 9</TD>
<TD VALIGN="TOP">1 - 7<BR>x or X</TD>
<TD>Octal<BR>Hexadecimal<BR>Decimal</TD></TR></TABLE></P></LI>
<LI><P>If <I>radix</I> is 1, less than 0 or greater than 36, it is considered to be an invalid value.</P></LI>
</UL>
<P>The characters are interpreted according to the following table:
<BR><BR>
<TABLE BORDER CELLPADDING="5">
<TR><TD><B>Value in <I>str</I> meant to be interpreted as</B></TD>
<TD><B>Resulting Character Recognition</B></TD></TR>
<TR><TD>Octal</TD>
<TD>Any character other than 0 to 7 will be unrecognized.</TD></TR>
<TR><TD>Decimal</TD>
<TD>Any character other than 0 to 9 will be unrecognized.</TD></TR>
<TR><TD>A number in any other base</TD>
<TD>Only the numerals and letters used to represent numbers in that base will be
recognized (for example, if radix equals 5, only 0 to 4 will be recognized; if
radix equals 20, only 0 to 9 and A to J will be recognized).
</TD></TR></TABLE>
<BR>
If <I>endptr</I> is not <A HREF="alloc.html#NULL">NULL</A>, strtol sets the pointer variable pointed
to by <I>endptr</I> to point to the character that stopped the scan (i.e. *<I>endptr</I> = &stopper).
strtol returns the value of the converted string, or 0 on error. In a case of overflow,
strtol returns <A HREF="limits.html">LONG_MAX</A> or
<A HREF="limits.html">LONG_MIN</A>, depending of the sign.
<BR><BR>
<B>Note:</B> strtol is much more flexible than <A HREF="#atol">atol</A> (or <A HREF="#atoi">atoi</A>),
but as it is not built-in in the TIOS, usage of it makes the total size of the program much
greater.</P>
<HR>
<H3><A NAME="strtoul"><U>strtoul</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">long</A></B> strtoul (<B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *str, <B><A HREF="keywords.html#int">char</A></B> **endptr, <B><A HREF="keywords.html#short">short</A></B> radix);</TD></TR></TABLE></P>
<P><B>Converts a string to an unsigned long integer using a given radix, with detection of overflows and errors.</B></P>
<P>strtoul operates the same way as <A HREF="#strtol">strtol</A>, except that it converts a string
<I>str</I> to an unsigned long value (where <A HREF="#strtol">strtol</A> converts to a long).
See <A HREF="#strtol">strtol</A> for more information. In a case of overflow, strtoul
returns <A HREF="limits.html">ULONG_MAX</A>.</P>
<HR>
<H3><A NAME="TIOS_strtod"><U>TIOS_strtod</U></A></H3>
<P><A HREF="httigcc.html#minams">AMS 2.00 or higher</A></P>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#float">double</A></B> TIOS_strtod(<B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *str, <B><A HREF="keywords.html#int">char</A></B> **endptr);</TD></TR></TABLE></P>
<P><B>You really should use <A HREF="#strtod">strtod</A>, unless
you know what you, and your users, are doing.</B><BR>
This is the direct system call, which will usually take less space in your program than the
library routine for <A HREF="#strtod">strtod</A>.
<B>But if you use it on AMS 1.00-2.03, never pass NULL as <I>endptr</I>, otherwise the routine
will trigger a crash !</B></P>
<P>See also: <A HREF="#strtod">strtod</A></P>
<HR>
<H3><A NAME="EXIT_FAILURE"><U>EXIT_FAILURE</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="cpp.html#SEC10">#define</A></B> EXIT_FAILURE 1</TD></TR></TABLE></P>
<P><B>Failure exit code for <A HREF="#exit">exit</A>.</B></P>
<P>EXIT_FAILURE is a constant (here with value 1) which is usually defined in <A HREF="stdlib.html">stdlib.h</A>.
Its meaning is "the exit code upon failure for <A HREF="#exit">exit</A>".</P>
<HR>
<H3><A NAME="EXIT_SUCCESS"><U>EXIT_SUCCESS</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="cpp.html#SEC10">#define</A></B> EXIT_SUCCESS 0</TD></TR></TABLE></P>
<P><B>Normal exit code for <A HREF="#exit">exit</A>.</B></P>
<P>EXIT_SUCCESS is a constant (here with value 0) which is usually defined in <A HREF="stdlib.html">stdlib.h</A>.
Its meaning is "the exit code upon success for <A HREF="#exit">exit</A>".</P>
<HR>
<H3><A NAME="RAND_MAX"><U>RAND_MAX</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="cpp.html#SEC10">#define</A></B> RAND_MAX 32767</TD></TR></TABLE></P>
<P><B>Returns the largest number returned by <A HREF="#rand">rand</A>.</B></P>
<P>RAND_MAX is a constant (here with value 32767) which is usually defined in <A HREF="stdlib.html">stdlib.h</A>.
Its meaning is "the largest number returned by <A HREF="#rand">rand</A>".</P>
<HR>
<H3><A NAME="atexit_t"><U>atexit_t</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#typedef">typedef</A></B> <A HREF="gnuexts.html#SEC85">CALLBACK</A> <B><A HREF="keywords.html#void">void</A></B> (*atexit_t) (<B><A HREF="keywords.html#void">void</A></B>);</TD></TR></TABLE></P>
<P><B>Describes an exit function passed to <A HREF="#atexit">atexit</A>.</B></P>
<P>atexit_t is a type proposed in ANSI C for defining the type of an exit function
passed to <A HREF="#atexit">atexit</A>.</P>
<HR>
<H3><A NAME="compare_t"><U>compare_t</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#typedef">typedef</A></B> <A HREF="gnuexts.html#SEC85">CALLBACK</A> <B><A HREF="keywords.html#short">short</A></B> (*compare_t) (<B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#void">void</A></B> *elem1, <B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#void">void</A></B> *elem2);</TD></TR></TABLE></P>
<P><B>Describes a comparison function.</B></P>
<P>compare_t is a type for defining the type of a comparison function
passed to <A HREF="#bsearch">bsearch</A> or <A HREF="#qsort">qsort</A>.
<BR><BR>
Note that this type is not ANSI-compliant: It should have a <CODE>'long'</CODE>
return value. The reason it does not is that the <A HREF="string.html#strcmp">strcmp</A>
function, frequently cast to this type, returns a <CODE>'short'</CODE> value.</P>
<HR>
<H3><A NAME="div_t"><U>div_t</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#typedef">typedef</A></B> <B><A HREF="keywords.html#struct">struct</A></B> {
<TABLE><TR><TD WIDTH="12"></TD><TD CLASS="CODE">
<B><A HREF="keywords.html#short">short</A></B> quot, rem;<BR>
</TD></TR></TABLE>
} div_t;</TD></TR></TABLE></P>
<P><B>An integer division return type used in the <A HREF="#div">div</A> function.</B></P>
<HR>
<H3><A NAME="ldiv_t"><U>ldiv_t</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#typedef">typedef</A></B> <B><A HREF="keywords.html#struct">struct</A></B> {
<TABLE><TR><TD WIDTH="12"></TD><TD CLASS="CODE">
<B><A HREF="keywords.html#short">long</A></B> quot, rem;<BR>
</TD></TR></TABLE>
} ldiv_t;</TD></TR></TABLE></P>
<P><B>A long integer division return type used in the <A HREF="#ldiv">ldiv</A> function.</B></P>
<HR>
<H3><A HREF="index.html">Return to the main index</A></H3>
</BODY>
</HTML>