1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
3 <!-- SECTION: Programming -->
5 <title>Array API
</title>
6 <meta name='keywords' content='Programming'
>
7 <meta name='creator' content='Mini-XML v2.3'
>
8 <style type='text/css'
><!--
9 h1, h2, h3, p { font-family: sans-serif; text-align: justify; }
10 tt, pre a:link, pre a:visited, tt a:link, tt a:visited { font-weight: bold; color: #7f0000; }
11 pre { font-weight: bold; color: #7f0000; margin-left: 2em; }
12 span.info { background: #000000; border: solid thin #000000; color: #ffffff; font-size: 80%; font-style: italic; font-weight: bold; white-space: nowrap; }
13 h3 span.info { float: right; font-size: 100%; }
14 h1.title, h2.title, h3.title { border-bottom: solid 2px #000000; }
21 Array API introduction for the Common UNIX Printing System (CUPS).
23 Copyright 1997-2006 by Easy Software Products.
25 These coded instructions, statements, and computer programs are the
26 property of Easy Software Products and are protected by Federal
27 copyright law. Distribution and use rights are outlined in the file
28 "LICENSE.txt" which should have been included with this file. If this
29 file is missing or damaged please contact Easy Software Products
32 Attn: CUPS Licensing Information
33 Easy Software Products
34 44141 Airport View Drive, Suite 204
35 Hollywood, Maryland 20636 USA
38 EMail: cups-info@cups.org
39 WWW: http://www.cups.org
42 <h2 class='title'
>Introduction
</h2>
44 <p>The CUPS array API provides a high-performance generic array
45 container. The contents of the array container can be sorted and
46 the container itself is designed for optimal speed and memory
47 usage under a wide variety of conditions.
</p>
49 <p>The CUPS scheduler (
<tt>cupsd
</tt>) and many of the CUPS API
50 functions use the array API to efficiently manage large lists of
53 <h2 class='title'
>General Usage
</h2>
55 <p>The
<var><cups/array.h
></var> header file must be
56 included to use the
<tt>cupsArray
</tt> functions.
</p>
58 <p>Programs using these functions must be linked to the CUPS
59 library:
<var>libcups.a
</var>,
<var>libcups.so
.2</var>,
60 <var>libcups
.2.dylib
</var>,
<var>libcups_s.a
</var>, or
61 <var>libcups2.lib
</var> depending on the platform. The following
62 command compiles
<var>myprogram.c
</var> using GCC and the CUPS
66 <kbd>gcc -o myprogram myprogram.c -lcups
</kbd>
69 <h2 class='title'
>Compatibility
</h2>
71 <p>All of these functions require CUPS
1.2 or higher.
</p>
72 <h2 class='title'
>Contents
</h2>
74 <li><a href='#FUNCTIONS'
>Functions
</a></li>
75 <li><a href='#TYPES'
>Types
</a></li>
78 <h2 class='title'
><a name='FUNCTIONS'
>Functions
</a></h2>
80 <li><a href='#cupsArrayAdd'
><tt>cupsArrayAdd()
</tt></a> </li>
81 <li><a href='#cupsArrayClear'
><tt>cupsArrayClear()
</tt></a> </li>
82 <li><a href='#cupsArrayCount'
><tt>cupsArrayCount()
</tt></a> </li>
83 <li><a href='#cupsArrayCurrent'
><tt>cupsArrayCurrent()
</tt></a> </li>
84 <li><a href='#cupsArrayDelete'
><tt>cupsArrayDelete()
</tt></a> </li>
85 <li><a href='#cupsArrayDup'
><tt>cupsArrayDup()
</tt></a> </li>
86 <li><a href='#cupsArrayFind'
><tt>cupsArrayFind()
</tt></a> </li>
87 <li><a href='#cupsArrayFirst'
><tt>cupsArrayFirst()
</tt></a> </li>
88 <li><a href='#cupsArrayIndex'
><tt>cupsArrayIndex()
</tt></a> </li>
89 <li><a href='#cupsArrayInsert'
><tt>cupsArrayInsert()
</tt></a> </li>
90 <li><a href='#cupsArrayLast'
><tt>cupsArrayLast()
</tt></a> </li>
91 <li><a href='#cupsArrayNew'
><tt>cupsArrayNew()
</tt></a> </li>
92 <li><a href='#cupsArrayNext'
><tt>cupsArrayNext()
</tt></a> </li>
93 <li><a href='#cupsArrayPrev'
><tt>cupsArrayPrev()
</tt></a> </li>
94 <li><a href='#cupsArrayRemove'
><tt>cupsArrayRemove()
</tt></a> </li>
95 <li><a href='#cupsArrayRestore'
><tt>cupsArrayRestore()
</tt></a> </li>
96 <li><a href='#cupsArraySave'
><tt>cupsArraySave()
</tt></a> </li>
97 <li><a href='#cupsArrayUserData'
><tt>cupsArrayUserData()
</tt></a> </li>
100 <h3 class='title'
><a name='cupsArrayAdd'
>cupsArrayAdd()
</a></h3>
102 <p>Add an element to the array.
104 When adding an element to a sorted array, non-unique elements are
105 appended at the end of the run. For unsorted arrays, the element
106 is inserted at the end of the array.
</p>
111 <a href='#cups_array_t'
>cups_array_t
</a> * a,
115 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
116 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
118 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
119 <tr><td><tt>e
</tt></td><td>Element
</td></tr>
120 </tbody></table></div>
122 <p>1 on success,
0 on failure
</p>
124 <h3 class='title'
><a name='cupsArrayClear'
>cupsArrayClear()
</a></h3>
126 <p>Clear the array.
</p>
131 <a href='#cups_array_t'
>cups_array_t
</a> * a);
134 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
135 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
137 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
138 </tbody></table></div>
142 <h3 class='title'
><a name='cupsArrayCount'
>cupsArrayCount()
</a></h3>
144 <p>Get the number of elements in the array.
</p>
149 <a href='#cups_array_t'
>cups_array_t
</a> * a);
152 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
153 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
155 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
156 </tbody></table></div>
158 <p>Number of elements
</p>
160 <h3 class='title'
><a name='cupsArrayCurrent'
>cupsArrayCurrent()
</a></h3>
162 <p>Return the current element in the array.
</p>
167 <a href='#cups_array_t'
>cups_array_t
</a> * a);
170 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
171 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
173 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
174 </tbody></table></div>
178 <h3 class='title'
><a name='cupsArrayDelete'
>cupsArrayDelete()
</a></h3>
180 <p>Free all memory used by the array.
</p>
185 <a href='#cups_array_t'
>cups_array_t
</a> * a);
188 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
189 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
191 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
192 </tbody></table></div>
196 <h3 class='title'
><a name='cupsArrayDup'
>cupsArrayDup()
</a></h3>
198 <p>Duplicate the array.
</p>
201 <a href='#cups_array_t'
>cups_array_t
</a> *
203 <a href='#cups_array_t'
>cups_array_t
</a> * a);
206 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
207 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
209 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
210 </tbody></table></div>
212 <p>Duplicate array
</p>
214 <h3 class='title'
><a name='cupsArrayFind'
>cupsArrayFind()
</a></h3>
216 <p>Find an element in the array.
</p>
221 <a href='#cups_array_t'
>cups_array_t
</a> * a,
225 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
226 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
228 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
229 <tr><td><tt>e
</tt></td><td>Element
</td></tr>
230 </tbody></table></div>
232 <p>Element found or NULL
</p>
234 <h3 class='title'
><a name='cupsArrayFirst'
>cupsArrayFirst()
</a></h3>
236 <p>Get the first element in the array.
</p>
241 <a href='#cups_array_t'
>cups_array_t
</a> * a);
244 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
245 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
247 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
248 </tbody></table></div>
250 <p>First element or NULL
</p>
252 <h3 class='title'
><a name='cupsArrayIndex'
>cupsArrayIndex()
</a></h3>
254 <p>Get the N-th element in the array.
</p>
259 <a href='#cups_array_t'
>cups_array_t
</a> * a,
263 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
264 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
266 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
267 <tr><td><tt>n
</tt></td><td>Index into array, starting at
0</td></tr>
268 </tbody></table></div>
270 <p>N-th element or NULL
</p>
272 <h3 class='title'
><a name='cupsArrayInsert'
>cupsArrayInsert()
</a></h3>
274 <p>Insert an element in the array.
276 When inserting an element in a sorted array, non-unique elements are
277 inserted at the beginning of the run. For unsorted arrays, the element
278 is inserted at the beginning of the array.
</p>
283 <a href='#cups_array_t'
>cups_array_t
</a> * a,
287 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
288 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
290 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
291 <tr><td><tt>e
</tt></td><td>Element
</td></tr>
292 </tbody></table></div>
294 <p>0 on failure,
1 on success
</p>
296 <h3 class='title'
><a name='cupsArrayLast'
>cupsArrayLast()
</a></h3>
298 <p>Get the last element in the array.
</p>
303 <a href='#cups_array_t'
>cups_array_t
</a> * a);
306 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
307 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
309 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
310 </tbody></table></div>
312 <p>Last element or NULL
</p>
314 <h3 class='title'
><a name='cupsArrayNew'
>cupsArrayNew()
</a></h3>
316 <p>Create a new array.
</p>
319 <a href='#cups_array_t'
>cups_array_t
</a> *
321 <a href='#cups_array_func_t'
>cups_array_func_t
</a> f,
325 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
326 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
328 <tr><td><tt>f
</tt></td><td>Comparison function
</td></tr>
329 <tr><td><tt>d
</tt></td><td>User data
</td></tr>
330 </tbody></table></div>
334 <h3 class='title'
><a name='cupsArrayNext'
>cupsArrayNext()
</a></h3>
336 <p>Get the next element in the array.
</p>
341 <a href='#cups_array_t'
>cups_array_t
</a> * a);
344 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
345 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
347 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
348 </tbody></table></div>
350 <p>Next element or NULL
</p>
352 <h3 class='title'
><a name='cupsArrayPrev'
>cupsArrayPrev()
</a></h3>
354 <p>Get the previous element in the array.
</p>
359 <a href='#cups_array_t'
>cups_array_t
</a> * a);
362 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
363 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
365 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
366 </tbody></table></div>
368 <p>Previous element or NULL
</p>
370 <h3 class='title'
><a name='cupsArrayRemove'
>cupsArrayRemove()
</a></h3>
372 <p>Remove an element from the array.
</p>
377 <a href='#cups_array_t'
>cups_array_t
</a> * a,
381 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
382 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
384 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
385 <tr><td><tt>e
</tt></td><td>Element
</td></tr>
386 </tbody></table></div>
388 <p>1 on success,
0 on failure
</p>
390 <h3 class='title'
><a name='cupsArrayRestore'
>cupsArrayRestore()
</a></h3>
392 <p>Reset the current element to the last cupsArraySave.
</p>
397 <a href='#cups_array_t'
>cups_array_t
</a> * a);
400 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
401 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
403 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
404 </tbody></table></div>
406 <p>New current element
</p>
408 <h3 class='title'
><a name='cupsArraySave'
>cupsArraySave()
</a></h3>
410 <p>Mark the current element for a later cupsArrayRestore.
412 The save/restore stack is guaranteed to be at least
32 elements deep.
</p>
417 <a href='#cups_array_t'
>cups_array_t
</a> * a);
420 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
421 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
423 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
424 </tbody></table></div>
426 <p>1 on success,
0 on failure
</p>
428 <h3 class='title'
><a name='cupsArrayUserData'
>cupsArrayUserData()
</a></h3>
430 <p>Return the user data for an array.
</p>
435 <a href='#cups_array_t'
>cups_array_t
</a> * a);
438 <div class='table'
><table align='center' border='
1' width='
80%' cellpadding='
5' cellspacing='
0'
>
439 <thead><tr><th>Name
</th><th>Description
</th></tr></thead>
441 <tr><td><tt>a
</tt></td><td>Array
</td></tr>
442 </tbody></table></div>
446 <h2 class='title'
><a name='TYPES'
>Types
</a></h2>
448 <li><a href='#cups_array_func_t'
><tt>cups_array_func_t
</tt></a> </li>
449 <li><a href='#cups_array_t'
><tt>cups_array_t
</tt></a> </li>
452 <h3 class='title'
><a name='cups_array_func_t'
>cups_array_func_t
</a></h3>
454 <p>Array comparison function
</p>
457 typedef int (*cups_array_func_t)(void *first, void *second, void *data);
460 <h3 class='title'
><a name='cups_array_t'
>cups_array_t
</a></h3>
462 <p>CUPS array type
</p>
465 typedef struct _cups_array_s cups_array_t;