Google Git
Sign in
android / platform / external / libcups / ef416fc25c4af449e930416117bedb12fc9924ba / . / doc / help / api-array.html
blob: 85b22235e2836fbc804c589afe37b64b48f831d5 [file] [log] [blame]
jlovellef416fc2006-01-13 01:51:53 +0000[diff] [blame^]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<!--
19 "$Id$"
20
21 Array API introduction for the Common UNIX Printing System (CUPS).
22
23 Copyright 1997-2005 by Easy Software Products.
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>
88 <li><a href='#cupsArrayLast'><tt>cupsArrayLast()</tt></a> </li>
89 <li><a href='#cupsArrayNew'><tt>cupsArrayNew()</tt></a> </li>
90 <li><a href='#cupsArrayNext'><tt>cupsArrayNext()</tt></a> </li>
91 <li><a href='#cupsArrayPrev'><tt>cupsArrayPrev()</tt></a> </li>
92 <li><a href='#cupsArrayRemove'><tt>cupsArrayRemove()</tt></a> </li>
93 <li><a href='#cupsArrayRestore'><tt>cupsArrayRestore()</tt></a> </li>
94 <li><a href='#cupsArraySave'><tt>cupsArraySave()</tt></a> </li>
95</ul>
96<!-- NEW PAGE -->
97<h3 class='title'><a name='cupsArrayAdd'>cupsArrayAdd()</a></h3>
98<h4>Description</h4>
99<p>Add an element to the array.</p>
100<h4>Syntax</h4>
101<pre>
102int
103cupsArrayAdd(
104 <a href='#cups_array_t'>cups_array_t</a> * a,
105 void * e);
106</pre>
107<h4>Arguments</h4>
108<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
109<thead><tr><th>Name</th><th>Description</th></tr></thead>
110<tbody>
111<tr><td><tt>a</tt></td><td>Array</td></tr>
112<tr><td><tt>e</tt></td><td>Element</td></tr>
113</tbody></table></div>
114<h4>Returns</h4>
115<p>1 on success, 0 on failure</p>
116<!-- NEW PAGE -->
117<h3 class='title'><a name='cupsArrayClear'>cupsArrayClear()</a></h3>
118<h4>Description</h4>
119<p>Clear the array.</p>
120<h4>Syntax</h4>
121<pre>
122void
123cupsArrayClear(
124 <a href='#cups_array_t'>cups_array_t</a> * a);
125</pre>
126<h4>Arguments</h4>
127<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
128<thead><tr><th>Name</th><th>Description</th></tr></thead>
129<tbody>
130<tr><td><tt>a</tt></td><td>Array</td></tr>
131</tbody></table></div>
132<h4>Returns</h4>
133<p>Nothing.</p>
134<!-- NEW PAGE -->
135<h3 class='title'><a name='cupsArrayCount'>cupsArrayCount()</a></h3>
136<h4>Description</h4>
137<p>Get the number of elements in the array.</p>
138<h4>Syntax</h4>
139<pre>
140int
141cupsArrayCount(
142 <a href='#cups_array_t'>cups_array_t</a> * a);
143</pre>
144<h4>Arguments</h4>
145<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
146<thead><tr><th>Name</th><th>Description</th></tr></thead>
147<tbody>
148<tr><td><tt>a</tt></td><td>Array</td></tr>
149</tbody></table></div>
150<h4>Returns</h4>
151<p>Number of elements</p>
152<!-- NEW PAGE -->
153<h3 class='title'><a name='cupsArrayCurrent'>cupsArrayCurrent()</a></h3>
154<h4>Description</h4>
155<p>Return the current element in the array.</p>
156<h4>Syntax</h4>
157<pre>
158void *
159cupsArrayCurrent(
160 <a href='#cups_array_t'>cups_array_t</a> * a);
161</pre>
162<h4>Arguments</h4>
163<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
164<thead><tr><th>Name</th><th>Description</th></tr></thead>
165<tbody>
166<tr><td><tt>a</tt></td><td>Array</td></tr>
167</tbody></table></div>
168<h4>Returns</h4>
169<p>Element</p>
170<!-- NEW PAGE -->
171<h3 class='title'><a name='cupsArrayDelete'>cupsArrayDelete()</a></h3>
172<h4>Description</h4>
173<p>Free all memory used by the array.</p>
174<h4>Syntax</h4>
175<pre>
176void
177cupsArrayDelete(
178 <a href='#cups_array_t'>cups_array_t</a> * a);
179</pre>
180<h4>Arguments</h4>
181<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
182<thead><tr><th>Name</th><th>Description</th></tr></thead>
183<tbody>
184<tr><td><tt>a</tt></td><td>Array</td></tr>
185</tbody></table></div>
186<h4>Returns</h4>
187<p>Nothing.</p>
188<!-- NEW PAGE -->
189<h3 class='title'><a name='cupsArrayDup'>cupsArrayDup()</a></h3>
190<h4>Description</h4>
191<p>Duplicate the array.</p>
192<h4>Syntax</h4>
193<pre>
194<a href='#cups_array_t'>cups_array_t</a> *
195cupsArrayDup(
196 <a href='#cups_array_t'>cups_array_t</a> * a);
197</pre>
198<h4>Arguments</h4>
199<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
200<thead><tr><th>Name</th><th>Description</th></tr></thead>
201<tbody>
202<tr><td><tt>a</tt></td><td>Array</td></tr>
203</tbody></table></div>
204<h4>Returns</h4>
205<p>Duplicate array</p>
206<!-- NEW PAGE -->
207<h3 class='title'><a name='cupsArrayFind'>cupsArrayFind()</a></h3>
208<h4>Description</h4>
209<p>Find an element in the array.</p>
210<h4>Syntax</h4>
211<pre>
212void *
213cupsArrayFind(
214 <a href='#cups_array_t'>cups_array_t</a> * a,
215 void * e);
216</pre>
217<h4>Arguments</h4>
218<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
219<thead><tr><th>Name</th><th>Description</th></tr></thead>
220<tbody>
221<tr><td><tt>a</tt></td><td>Array</td></tr>
222<tr><td><tt>e</tt></td><td>Element</td></tr>
223</tbody></table></div>
224<h4>Returns</h4>
225<p>Element found or NULL</p>
226<!-- NEW PAGE -->
227<h3 class='title'><a name='cupsArrayFirst'>cupsArrayFirst()</a></h3>
228<h4>Description</h4>
229<p>Get the first element in the array.</p>
230<h4>Syntax</h4>
231<pre>
232void *
233cupsArrayFirst(
234 <a href='#cups_array_t'>cups_array_t</a> * a);
235</pre>
236<h4>Arguments</h4>
237<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
238<thead><tr><th>Name</th><th>Description</th></tr></thead>
239<tbody>
240<tr><td><tt>a</tt></td><td>Array</td></tr>
241</tbody></table></div>
242<h4>Returns</h4>
243<p>First element or NULL</p>
244<!-- NEW PAGE -->
245<h3 class='title'><a name='cupsArrayLast'>cupsArrayLast()</a></h3>
246<h4>Description</h4>
247<p>Get the last element in the array.</p>
248<h4>Syntax</h4>
249<pre>
250void *
251cupsArrayLast(
252 <a href='#cups_array_t'>cups_array_t</a> * a);
253</pre>
254<h4>Arguments</h4>
255<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
256<thead><tr><th>Name</th><th>Description</th></tr></thead>
257<tbody>
258<tr><td><tt>a</tt></td><td>Array</td></tr>
259</tbody></table></div>
260<h4>Returns</h4>
261<p>Last element or NULL</p>
262<!-- NEW PAGE -->
263<h3 class='title'><a name='cupsArrayNew'>cupsArrayNew()</a></h3>
264<h4>Description</h4>
265<p>Create a new array.</p>
266<h4>Syntax</h4>
267<pre>
268<a href='#cups_array_t'>cups_array_t</a> *
269cupsArrayNew(
270 <a href='#cups_array_func_t'>cups_array_func_t</a> f,
271 void * d);
272</pre>
273<h4>Arguments</h4>
274<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
275<thead><tr><th>Name</th><th>Description</th></tr></thead>
276<tbody>
277<tr><td><tt>f</tt></td><td>Comparison function</td></tr>
278<tr><td><tt>d</tt></td><td>User data</td></tr>
279</tbody></table></div>
280<h4>Returns</h4>
281<p>Array</p>
282<!-- NEW PAGE -->
283<h3 class='title'><a name='cupsArrayNext'>cupsArrayNext()</a></h3>
284<h4>Description</h4>
285<p>Get the next element in the array.</p>
286<h4>Syntax</h4>
287<pre>
288void *
289cupsArrayNext(
290 <a href='#cups_array_t'>cups_array_t</a> * a);
291</pre>
292<h4>Arguments</h4>
293<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
294<thead><tr><th>Name</th><th>Description</th></tr></thead>
295<tbody>
296<tr><td><tt>a</tt></td><td>Array</td></tr>
297</tbody></table></div>
298<h4>Returns</h4>
299<p>Next element or NULL</p>
300<!-- NEW PAGE -->
301<h3 class='title'><a name='cupsArrayPrev'>cupsArrayPrev()</a></h3>
302<h4>Description</h4>
303<p>Get the previous element in the array.</p>
304<h4>Syntax</h4>
305<pre>
306void *
307cupsArrayPrev(
308 <a href='#cups_array_t'>cups_array_t</a> * a);
309</pre>
310<h4>Arguments</h4>
311<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
312<thead><tr><th>Name</th><th>Description</th></tr></thead>
313<tbody>
314<tr><td><tt>a</tt></td><td>Array</td></tr>
315</tbody></table></div>
316<h4>Returns</h4>
317<p>Previous element or NULL</p>
318<!-- NEW PAGE -->
319<h3 class='title'><a name='cupsArrayRemove'>cupsArrayRemove()</a></h3>
320<h4>Description</h4>
321<p>Remove an element from the array.</p>
322<h4>Syntax</h4>
323<pre>
324int
325cupsArrayRemove(
326 <a href='#cups_array_t'>cups_array_t</a> * a,
327 void * e);
328</pre>
329<h4>Arguments</h4>
330<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
331<thead><tr><th>Name</th><th>Description</th></tr></thead>
332<tbody>
333<tr><td><tt>a</tt></td><td>Array</td></tr>
334<tr><td><tt>e</tt></td><td>Element</td></tr>
335</tbody></table></div>
336<h4>Returns</h4>
337<p>1 on success, 0 on failure</p>
338<!-- NEW PAGE -->
339<h3 class='title'><a name='cupsArrayRestore'>cupsArrayRestore()</a></h3>
340<h4>Description</h4>
341<p>Reset the current element to the last cupsArraySave.</p>
342<h4>Syntax</h4>
343<pre>
344void *
345cupsArrayRestore(
346 <a href='#cups_array_t'>cups_array_t</a> * a);
347</pre>
348<h4>Arguments</h4>
349<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
350<thead><tr><th>Name</th><th>Description</th></tr></thead>
351<tbody>
352<tr><td><tt>a</tt></td><td>Array</td></tr>
353</tbody></table></div>
354<h4>Returns</h4>
355<p>New current element</p>
356<!-- NEW PAGE -->
357<h3 class='title'><a name='cupsArraySave'>cupsArraySave()</a></h3>
358<h4>Description</h4>
359<p>Mark the current element for a later cupsArrayRestore.
360
361The save/restore stack is guaranteed to be at least 32 elements deep.</p>
362<h4>Syntax</h4>
363<pre>
364int
365cupsArraySave(
366 <a href='#cups_array_t'>cups_array_t</a> * a);
367</pre>
368<h4>Arguments</h4>
369<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
370<thead><tr><th>Name</th><th>Description</th></tr></thead>
371<tbody>
372<tr><td><tt>a</tt></td><td>Array</td></tr>
373</tbody></table></div>
374<h4>Returns</h4>
375<p>1 on success, 0 on failure</p>
376<!-- NEW PAGE -->
377<h2 class='title'><a name='TYPES'>Types</a></h2>
378<ul>
379 <li><a href='#cups_array_func_t'><tt>cups_array_func_t</tt></a> </li>
380 <li><a href='#cups_array_t'><tt>cups_array_t</tt></a> </li>
381</ul>
382<!-- NEW PAGE -->
383<h3 class='title'><a name='cups_array_func_t'>cups_array_func_t</a></h3>
384<h4>Description</h4>
385<p>Array comparison function</p>
386<h4>Definition</h4>
387<pre>
388typedef int (*cups_array_func_t)(void *first, void *second, void *data);
389</pre>
390<!-- NEW PAGE -->
391<h3 class='title'><a name='cups_array_t'>cups_array_t</a></h3>
392<h4>Description</h4>
393<p>CUPS array type</p>
394<h4>Definition</h4>
395<pre>
396typedef struct _cups_array_s cups_array_t;
397</pre>
398</body>
399</html>