]> git.ipfire.org Git - thirdparty/cups.git/blame - doc/help/api-array.html
Remove svn:keywords since they cause svn_load_dirs.pl to complain about every file.
[thirdparty/cups.git] / doc / help / api-array.html
CommitLineData
ef416fc2 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
2<html>
3<!-- SECTION: Programming -->
4<head>
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; }
15 --></style>
16</head>
17<body>
18<!--
c07d5b2d 19 "$Id: api-array.html 177 2006-06-21 00:20:03Z jlovell $"
ef416fc2 20
21 Array API introduction for the Common UNIX Printing System (CUPS).
22
ecdc0628 23 Copyright 1997-2006 by Easy Software Products.
ef416fc2 24
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
30 at:
31
32 Attn: CUPS Licensing Information
33 Easy Software Products
34 44141 Airport View Drive, Suite 204
35 Hollywood, Maryland 20636 USA
36
37 Voice: (301) 373-9600
38 EMail: cups-info@cups.org
39 WWW: http://www.cups.org
40-->
41
42<h2 class='title'>Introduction</h2>
43
44<p>The CUPS array API provides a high-performance generic array
45container. The contents of the array container can be sorted and
46the container itself is designed for optimal speed and memory
47usage under a wide variety of conditions.</p>
48
49<p>The CUPS scheduler (<tt>cupsd</tt>) and many of the CUPS API
50functions use the array API to efficiently manage large lists of
51data.</p>
52
53<h2 class='title'>General Usage</h2>
54
55<p>The <var>&lt;cups/array.h&gt;</var> header file must be
56included to use the <tt>cupsArray</tt> functions.</p>
57
58<p>Programs using these functions must be linked to the CUPS
59library: <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
62command compiles <var>myprogram.c</var> using GCC and the CUPS
63library:</p>
64
65<pre class='command'>
66<kbd>gcc -o myprogram myprogram.c -lcups</kbd>
67</pre>
68
69<h2 class='title'>Compatibility</h2>
70
71<p>All of these functions require CUPS 1.2 or higher.</p>
72<h2 class='title'>Contents</h2>
73<ul>
74 <li><a href='#FUNCTIONS'>Functions</a></li>
75 <li><a href='#TYPES'>Types</a></li>
76</ul>
77<!-- NEW PAGE -->
78<h2 class='title'><a name='FUNCTIONS'>Functions</a></h2>
79<ul>
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>
ecdc0628 88 <li><a href='#cupsArrayIndex'><tt>cupsArrayIndex()</tt></a> </li>
89 <li><a href='#cupsArrayInsert'><tt>cupsArrayInsert()</tt></a> </li>
ef416fc2 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>
80ca4592 97 <li><a href='#cupsArrayUserData'><tt>cupsArrayUserData()</tt></a> </li>
ef416fc2 98</ul>
99<!-- NEW PAGE -->
100<h3 class='title'><a name='cupsArrayAdd'>cupsArrayAdd()</a></h3>
101<h4>Description</h4>
ecdc0628 102<p>Add an element to the array.
103
104When adding an element to a sorted array, non-unique elements are
105appended at the end of the run. For unsorted arrays, the element
106is inserted at the end of the array.</p>
ef416fc2 107<h4>Syntax</h4>
108<pre>
109int
110cupsArrayAdd(
111 <a href='#cups_array_t'>cups_array_t</a> * a,
112 void * e);
113</pre>
114<h4>Arguments</h4>
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>
117<tbody>
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>
121<h4>Returns</h4>
122<p>1 on success, 0 on failure</p>
123<!-- NEW PAGE -->
124<h3 class='title'><a name='cupsArrayClear'>cupsArrayClear()</a></h3>
125<h4>Description</h4>
126<p>Clear the array.</p>
127<h4>Syntax</h4>
128<pre>
129void
130cupsArrayClear(
131 <a href='#cups_array_t'>cups_array_t</a> * a);
132</pre>
133<h4>Arguments</h4>
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>
136<tbody>
137<tr><td><tt>a</tt></td><td>Array</td></tr>
138</tbody></table></div>
139<h4>Returns</h4>
140<p>Nothing.</p>
141<!-- NEW PAGE -->
142<h3 class='title'><a name='cupsArrayCount'>cupsArrayCount()</a></h3>
143<h4>Description</h4>
144<p>Get the number of elements in the array.</p>
145<h4>Syntax</h4>
146<pre>
147int
148cupsArrayCount(
149 <a href='#cups_array_t'>cups_array_t</a> * a);
150</pre>
151<h4>Arguments</h4>
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>
154<tbody>
155<tr><td><tt>a</tt></td><td>Array</td></tr>
156</tbody></table></div>
157<h4>Returns</h4>
158<p>Number of elements</p>
159<!-- NEW PAGE -->
160<h3 class='title'><a name='cupsArrayCurrent'>cupsArrayCurrent()</a></h3>
161<h4>Description</h4>
162<p>Return the current element in the array.</p>
163<h4>Syntax</h4>
164<pre>
165void *
166cupsArrayCurrent(
167 <a href='#cups_array_t'>cups_array_t</a> * a);
168</pre>
169<h4>Arguments</h4>
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>
172<tbody>
173<tr><td><tt>a</tt></td><td>Array</td></tr>
174</tbody></table></div>
175<h4>Returns</h4>
176<p>Element</p>
177<!-- NEW PAGE -->
178<h3 class='title'><a name='cupsArrayDelete'>cupsArrayDelete()</a></h3>
179<h4>Description</h4>
180<p>Free all memory used by the array.</p>
181<h4>Syntax</h4>
182<pre>
183void
184cupsArrayDelete(
185 <a href='#cups_array_t'>cups_array_t</a> * a);
186</pre>
187<h4>Arguments</h4>
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>
190<tbody>
191<tr><td><tt>a</tt></td><td>Array</td></tr>
192</tbody></table></div>
193<h4>Returns</h4>
194<p>Nothing.</p>
195<!-- NEW PAGE -->
196<h3 class='title'><a name='cupsArrayDup'>cupsArrayDup()</a></h3>
197<h4>Description</h4>
198<p>Duplicate the array.</p>
199<h4>Syntax</h4>
200<pre>
201<a href='#cups_array_t'>cups_array_t</a> *
202cupsArrayDup(
203 <a href='#cups_array_t'>cups_array_t</a> * a);
204</pre>
205<h4>Arguments</h4>
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>
208<tbody>
209<tr><td><tt>a</tt></td><td>Array</td></tr>
210</tbody></table></div>
211<h4>Returns</h4>
212<p>Duplicate array</p>
213<!-- NEW PAGE -->
214<h3 class='title'><a name='cupsArrayFind'>cupsArrayFind()</a></h3>
215<h4>Description</h4>
216<p>Find an element in the array.</p>
217<h4>Syntax</h4>
218<pre>
219void *
220cupsArrayFind(
221 <a href='#cups_array_t'>cups_array_t</a> * a,
222 void * e);
223</pre>
224<h4>Arguments</h4>
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>
227<tbody>
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>
231<h4>Returns</h4>
232<p>Element found or NULL</p>
233<!-- NEW PAGE -->
234<h3 class='title'><a name='cupsArrayFirst'>cupsArrayFirst()</a></h3>
235<h4>Description</h4>
236<p>Get the first element in the array.</p>
237<h4>Syntax</h4>
238<pre>
239void *
240cupsArrayFirst(
241 <a href='#cups_array_t'>cups_array_t</a> * a);
242</pre>
243<h4>Arguments</h4>
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>
246<tbody>
247<tr><td><tt>a</tt></td><td>Array</td></tr>
248</tbody></table></div>
249<h4>Returns</h4>
250<p>First element or NULL</p>
251<!-- NEW PAGE -->
ecdc0628 252<h3 class='title'><a name='cupsArrayIndex'>cupsArrayIndex()</a></h3>
253<h4>Description</h4>
254<p>Get the N-th element in the array.</p>
255<h4>Syntax</h4>
256<pre>
257void *
258cupsArrayIndex(
259 <a href='#cups_array_t'>cups_array_t</a> * a,
260 int n);
261</pre>
262<h4>Arguments</h4>
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>
265<tbody>
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>
269<h4>Returns</h4>
270<p>N-th element or NULL</p>
271<!-- NEW PAGE -->
272<h3 class='title'><a name='cupsArrayInsert'>cupsArrayInsert()</a></h3>
273<h4>Description</h4>
274<p>Insert an element in the array.
275
276When inserting an element in a sorted array, non-unique elements are
277inserted at the beginning of the run. For unsorted arrays, the element
278is inserted at the beginning of the array.</p>
279<h4>Syntax</h4>
280<pre>
281int
282cupsArrayInsert(
283 <a href='#cups_array_t'>cups_array_t</a> * a,
284 void * e);
285</pre>
286<h4>Arguments</h4>
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>
289<tbody>
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>
293<h4>Returns</h4>
294<p>0 on failure, 1 on success</p>
295<!-- NEW PAGE -->
ef416fc2 296<h3 class='title'><a name='cupsArrayLast'>cupsArrayLast()</a></h3>
297<h4>Description</h4>
298<p>Get the last element in the array.</p>
299<h4>Syntax</h4>
300<pre>
301void *
302cupsArrayLast(
303 <a href='#cups_array_t'>cups_array_t</a> * a);
304</pre>
305<h4>Arguments</h4>
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>
308<tbody>
309<tr><td><tt>a</tt></td><td>Array</td></tr>
310</tbody></table></div>
311<h4>Returns</h4>
312<p>Last element or NULL</p>
313<!-- NEW PAGE -->
314<h3 class='title'><a name='cupsArrayNew'>cupsArrayNew()</a></h3>
315<h4>Description</h4>
316<p>Create a new array.</p>
317<h4>Syntax</h4>
318<pre>
319<a href='#cups_array_t'>cups_array_t</a> *
320cupsArrayNew(
321 <a href='#cups_array_func_t'>cups_array_func_t</a> f,
322 void * d);
323</pre>
324<h4>Arguments</h4>
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>
327<tbody>
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>
331<h4>Returns</h4>
332<p>Array</p>
333<!-- NEW PAGE -->
334<h3 class='title'><a name='cupsArrayNext'>cupsArrayNext()</a></h3>
335<h4>Description</h4>
336<p>Get the next element in the array.</p>
337<h4>Syntax</h4>
338<pre>
339void *
340cupsArrayNext(
341 <a href='#cups_array_t'>cups_array_t</a> * a);
342</pre>
343<h4>Arguments</h4>
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>
346<tbody>
347<tr><td><tt>a</tt></td><td>Array</td></tr>
348</tbody></table></div>
349<h4>Returns</h4>
350<p>Next element or NULL</p>
351<!-- NEW PAGE -->
352<h3 class='title'><a name='cupsArrayPrev'>cupsArrayPrev()</a></h3>
353<h4>Description</h4>
354<p>Get the previous element in the array.</p>
355<h4>Syntax</h4>
356<pre>
357void *
358cupsArrayPrev(
359 <a href='#cups_array_t'>cups_array_t</a> * a);
360</pre>
361<h4>Arguments</h4>
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>
364<tbody>
365<tr><td><tt>a</tt></td><td>Array</td></tr>
366</tbody></table></div>
367<h4>Returns</h4>
368<p>Previous element or NULL</p>
369<!-- NEW PAGE -->
370<h3 class='title'><a name='cupsArrayRemove'>cupsArrayRemove()</a></h3>
371<h4>Description</h4>
372<p>Remove an element from the array.</p>
373<h4>Syntax</h4>
374<pre>
375int
376cupsArrayRemove(
377 <a href='#cups_array_t'>cups_array_t</a> * a,
378 void * e);
379</pre>
380<h4>Arguments</h4>
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>
383<tbody>
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>
387<h4>Returns</h4>
388<p>1 on success, 0 on failure</p>
389<!-- NEW PAGE -->
390<h3 class='title'><a name='cupsArrayRestore'>cupsArrayRestore()</a></h3>
391<h4>Description</h4>
392<p>Reset the current element to the last cupsArraySave.</p>
393<h4>Syntax</h4>
394<pre>
395void *
396cupsArrayRestore(
397 <a href='#cups_array_t'>cups_array_t</a> * a);
398</pre>
399<h4>Arguments</h4>
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>
402<tbody>
403<tr><td><tt>a</tt></td><td>Array</td></tr>
404</tbody></table></div>
405<h4>Returns</h4>
406<p>New current element</p>
407<!-- NEW PAGE -->
408<h3 class='title'><a name='cupsArraySave'>cupsArraySave()</a></h3>
409<h4>Description</h4>
410<p>Mark the current element for a later cupsArrayRestore.
411
412The save/restore stack is guaranteed to be at least 32 elements deep.</p>
413<h4>Syntax</h4>
414<pre>
415int
416cupsArraySave(
417 <a href='#cups_array_t'>cups_array_t</a> * a);
418</pre>
419<h4>Arguments</h4>
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>
422<tbody>
423<tr><td><tt>a</tt></td><td>Array</td></tr>
424</tbody></table></div>
425<h4>Returns</h4>
426<p>1 on success, 0 on failure</p>
427<!-- NEW PAGE -->
80ca4592 428<h3 class='title'><a name='cupsArrayUserData'>cupsArrayUserData()</a></h3>
429<h4>Description</h4>
430<p>Return the user data for an array.</p>
431<h4>Syntax</h4>
432<pre>
433void *
434cupsArrayUserData(
435 <a href='#cups_array_t'>cups_array_t</a> * a);
436</pre>
437<h4>Arguments</h4>
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>
440<tbody>
441<tr><td><tt>a</tt></td><td>Array</td></tr>
442</tbody></table></div>
443<h4>Returns</h4>
444<p>User data</p>
445<!-- NEW PAGE -->
ef416fc2 446<h2 class='title'><a name='TYPES'>Types</a></h2>
447<ul>
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>
450</ul>
451<!-- NEW PAGE -->
452<h3 class='title'><a name='cups_array_func_t'>cups_array_func_t</a></h3>
453<h4>Description</h4>
454<p>Array comparison function</p>
455<h4>Definition</h4>
456<pre>
457typedef int (*cups_array_func_t)(void *first, void *second, void *data);
458</pre>
459<!-- NEW PAGE -->
460<h3 class='title'><a name='cups_array_t'>cups_array_t</a></h3>
461<h4>Description</h4>
462<p>CUPS array type</p>
463<h4>Definition</h4>
464<pre>
465typedef struct _cups_array_s cups_array_t;
466</pre>
467</body>
468</html>