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.5">
8 <style type=
"text/css"><!--
10 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
13 H1, H2, H3, H4, H5, H6, P, TD, TH {
14 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
18 font-family: monaco, courier, monospace;
23 font-family: monaco, courier, monospace;
32 border: dotted thin #999999;
37 PRE.command EM, PRE.example EM {
38 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
42 font-family: monaco, courier, monospace;
53 border: solid thin #999999;
58 text-decoration: none;
62 A:link:hover, A:visited:hover, A:active {
63 text-decoration: underline;
72 border: solid thin #999999;
73 border-collapse: collapse;
89 border: solid thin #cccccc;
96 border-bottom: solid thin #999999;
105 caption-side: bottom;
125 border: thin solid #000000;
133 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
139 border-bottom: solid 2pt #000000;
157 font-family: monaco, courier, monospace;
166 border: solid thin #999999;
167 border-collapse: collapse;
172 DIV.summary TABLE TD, DIV.summary TABLE TH {
173 border: solid thin #999999;
179 DIV.summary TABLE THEAD TH {
183 /* API documentation styles... */
190 div.body h3, div.body h4, div.body h5 {
191 margin-bottom: 0.5em;
194 .class, .enumeration, .function, .struct, .typedef, .union {
195 border-bottom: solid thin #999999;
202 code, p.code, pre, ul.code li {
203 font-family: monaco, courier, monospace;
206 ul.code, ul.contents, ul.subcontents {
207 list-style-type: none;
217 ul.contents li ul.code, ul.contents li ul.subcontents {
230 margin-bottom: 0.5em;
233 /* This is just for the HTML files generated with the framedhelp target */
236 border: solid thin black;
245 div.contents ul.contents {
248 div.contents ul.subcontents li {
257 "$Id: api-array.header 7266 2008-01-29 02:15:29Z mike $"
259 Array API header for the Common UNIX Printing System (CUPS).
261 Copyright 2008 by Apple Inc.
263 These coded instructions, statements, and computer programs are the
264 property of Apple Inc. and are protected by Federal copyright
265 law. Distribution and use rights are outlined in the file "LICENSE.txt"
266 which should have been included with this file. If this file is
267 file is missing or damaged, see the license at "http://www.cups.org/".
270 <h1 class=
"title">Array API
</h1>
272 <div class='summary'
><table summary='General Information'
>
276 <th>cups/array.h
</th>
286 <td>Programming:
<a href='api-overview.html' target='_top'
>Introduction to CUPS Programming
</a></td>
290 <h2 class=
"title">Contents
</h2>
291 <ul class=
"contents">
293 <li><a href=
"#OVERVIEW">Overview
</a><ul class=
"subcontents">
294 <li><a href=
"#MANAGING_ARRAYS">Managing Arrays
</a></li>
295 <li><a href=
"#FINDING_AND_ENUMERATING">Finding and Enumerating Elements
</a></li>
297 <li><a href=
"#FUNCTIONS">Functions
</a><ul class=
"code">
298 <li><a href=
"#cupsArrayAdd" title=
"Add an element to the array.">cupsArrayAdd
</a></li>
299 <li><a href=
"#cupsArrayClear" title=
"Clear the array.">cupsArrayClear
</a></li>
300 <li><a href=
"#cupsArrayCount" title=
"Get the number of elements in the array.">cupsArrayCount
</a></li>
301 <li><a href=
"#cupsArrayCurrent" title=
"Return the current element in the array.">cupsArrayCurrent
</a></li>
302 <li><a href=
"#cupsArrayDelete" title=
"Free all memory used by the array.">cupsArrayDelete
</a></li>
303 <li><a href=
"#cupsArrayDup" title=
"Duplicate the array.">cupsArrayDup
</a></li>
304 <li><a href=
"#cupsArrayFind" title=
"Find an element in the array.">cupsArrayFind
</a></li>
305 <li><a href=
"#cupsArrayFirst" title=
"Get the first element in the array.">cupsArrayFirst
</a></li>
306 <li><a href=
"#cupsArrayGetIndex" title=
"Get the index of the current element.">cupsArrayGetIndex
</a></li>
307 <li><a href=
"#cupsArrayGetInsert" title=
"Get the index of the last inserted element.">cupsArrayGetInsert
</a></li>
308 <li><a href=
"#cupsArrayIndex" title=
"Get the N-th element in the array.">cupsArrayIndex
</a></li>
309 <li><a href=
"#cupsArrayInsert" title=
"Insert an element in the array.">cupsArrayInsert
</a></li>
310 <li><a href=
"#cupsArrayLast" title=
"Get the last element in the array.">cupsArrayLast
</a></li>
311 <li><a href=
"#cupsArrayNew" title=
"Create a new array.">cupsArrayNew
</a></li>
312 <li><a href=
"#cupsArrayNew2" title=
"Create a new array with hash.">cupsArrayNew2
</a></li>
313 <li><a href=
"#cupsArrayNext" title=
"Get the next element in the array.">cupsArrayNext
</a></li>
314 <li><a href=
"#cupsArrayPrev" title=
"Get the previous element in the array.">cupsArrayPrev
</a></li>
315 <li><a href=
"#cupsArrayRemove" title=
"Remove an element from the array.">cupsArrayRemove
</a></li>
316 <li><a href=
"#cupsArrayRestore" title=
"Reset the current element to the last cupsArraySave.">cupsArrayRestore
</a></li>
317 <li><a href=
"#cupsArraySave" title=
"Mark the current element for a later cupsArrayRestore.">cupsArraySave
</a></li>
318 <li><a href=
"#cupsArrayUserData" title=
"Return the user data for an array.">cupsArrayUserData
</a></li>
320 <li><a href=
"#TYPES">Data Types
</a><ul class=
"code">
321 <li><a href=
"#cups_ahash_func_t" title=
"Array hash function">cups_ahash_func_t
</a></li>
322 <li><a href=
"#cups_array_func_t" title=
"Array comparison function">cups_array_func_t
</a></li>
323 <li><a href=
"#cups_array_t" title=
"CUPS array type">cups_array_t
</a></li>
327 "$Id: api-array.shtml 7266 2008-01-29 02:15:29Z mike $"
329 Array API introduction for the Common UNIX Printing System (CUPS).
331 Copyright 2007-2008 by Apple Inc.
332 Copyright 1997-2006 by Easy Software Products, all rights reserved.
334 These coded instructions, statements, and computer programs are the
335 property of Apple Inc. and are protected by Federal copyright
336 law. Distribution and use rights are outlined in the file "LICENSE.txt"
337 which should have been included with this file. If this file is
338 file is missing or damaged, see the license at "http://www.cups.org/".
341 <h2 class='title'
><a name='OVERVIEW'
>Overview
</a></h2>
343 <p>The CUPS array API provides a high-performance generic array container.
344 The contents of the array container can be sorted and the container itself is
345 designed for optimal speed and memory usage under a wide variety of conditions.
346 Sorted arrays use a binary search algorithm from the last found or inserted
347 element to quickly find matching elements in the array. Arrays created with the
348 optional hash function can often find elements with a single lookup. The
349 <a href='#cups_array_t'
><code>cups_array_t
</code></a> type is used when
350 referring to a CUPS array.
</p>
352 <p>The CUPS scheduler (
<tt>cupsd
</tt>) and many of the CUPS API
353 functions use the array API to efficiently manage large lists of
356 <h3><a name='MANAGING_ARRAYS'
>Managing Arrays
</a></h3>
358 <p>Arrays are created using either the
359 <a href='#cupsArrayNew'
><code>cupsArrayNew
</code></a> or
360 <a href='#cupsArrayNew2'
><code>cupsArrayNew2
</code></a> functions. The
361 first function creates a new array with the specified callback function
362 and user data pointer:
</p>
364 <pre class='example'
>
365 #include
<cups/array.h
>
367 static int compare_func(void *first, void *second, void *user_data);
370 <a href='#cups_array_t'
>cups_array_t
</a> *array =
<a href='#cupsArrayNew'
>cupsArrayNew
</a>(compare_func, user_data);
373 <p>The comparison function (type
374 <a href=
"#cups_arrayfunc_t"><code>cups_arrayfunc_t
</code></a>) is called
375 whenever an element is added to the array and can be
<code>NULL
</code> to
376 create an unsorted array. The function returns -
1 if the first element should
377 come before the second,
0 if the first and second elements should have the same
378 ordering, and
1 if the first element should come after the second.
</p>
380 <p>The
"user_data" pointer is passed to your comparison function. Pass
381 <code>NULL
</code> if you do not need to associate the elements in your array
382 with additional information.
</p>
384 <p>The
<a href='#cupsArrayNew2'
><code>cupsArrayNew2
</code></a> function adds
385 two more arguments to support hashed lookups, which can potentially provide
386 instantaneous (
"O(1)") lookups in your array:
</p>
388 <pre class='example'
>
389 #include
<cups/array.h
>
391 #define HASH_SIZE
512 /* Size of hash table */
393 static int compare_func(void *first, void *second, void *user_data);
394 static int hash_func(void *element, void *user_data);
397 <a href='#cups_array_t'
>cups_array_t
</a> *array =
<a href='#cupsArrayNew2'
>cupsArrayNew2
</a>(compare_func, user_data, hash_func, HASH_SIZE);
400 <p>The hash function (type
401 <a href=
"#cups_ahash_func_t"><code>cups_ahash_func_t
</code></a>) returns a
402 number from
0 to (hash_size-
1) that (hopefully) uniquely identifies the
403 element and is called whenever you look up an element in the array with
404 <a href='#cupsArrayFind'
><code>cupsArrayFind
</code></a>. The hash size is
405 only limited by available memory, but generally should not be larger than
406 16384 to realize any performance improvement.
</p>
408 <p>Once you have created the array, you add elements using the
409 <a href='#cupsArrayAdd'
><code>cupsArrayAdd
</code></a>
410 <a href='#cupsArrayInsert'
><code>cupsArrayInsert
</code></a> functions.
411 The first function adds an element to the array, adding the new element
412 after any elements that have the same order, while the second inserts the
413 element before others with the same order. For unsorted arrays,
414 <a href='#cupsArrayAdd'
><code>cupsArrayAdd
</code></a> appends the elemnt to
415 the end of the array while
416 <a href='#cupsArrayInsert'
><code>cupsArrayInsert
</code></a> inserts the
417 element at the beginning of the array. For example, the following code
418 creates a sorted array of character strings:
</p>
420 <pre class='example'
>
421 #include
<cups/array.h
>
423 /* Use strcmp() to compare strings - it will ignore the user_data pointer */
424 <a href='#cups_array_t'
>cups_array_t
</a> *array =
<a href='#cupsArrayNew'
>cupsArrayNew
</a>((
<a href='#cups_array_func_t'
>cups_array_func_t
</a>)strcmp, NULL);
426 /* Add four strings to the array */
427 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"One Fish");
428 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Two Fish");
429 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Red Fish");
430 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Blue Fish");
433 <p>Elements are removed using the
434 <a href='#cupsArrayRemove'
><code>cupsArrayRemove
</code></a> function, for
437 <pre class='example'
>
438 #include
<cups/array.h
>
440 /* Use strcmp() to compare strings - it will ignore the user_data pointer */
441 <a href='#cups_array_t'
>cups_array_t
</a> *array =
<a href='#cupsArrayNew'
>cupsArrayNew
</a>((
<a href='#cups_array_func_t'
>cups_array_func_t
</a>)strcmp, NULL);
443 /* Add four strings to the array */
444 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"One Fish");
445 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Two Fish");
446 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Red Fish");
447 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Blue Fish");
449 /* Remove
"Red Fish" */
450 <a href='#cupsArrayRemove'
>cupsArrayRemove
</a>(array,
"Red Fish");
453 <p>Finally, you free the memory used by the array using the
454 <a href='#cupsArrayDelete'
><code>cupsArrayDelete
</code></a> function. All
455 of the memory for the array and hash table (if any) is freed, however
<em>CUPS
456 does not free the elements
</em> - if necessary, you must allocate and free the
457 elements yourself.
</p>
459 <h3><a name='FINDING_AND_ENUMERATING'
>Finding and Enumerating Elements
</a></h3>
461 <p>CUPS provides several functions to find and enumerate elements in an
462 array. Each one sets or updates a
"current index" into the array, such that
463 future lookups will start where the last one left off:
</p>
466 <dt><a href='#cupsArrayFind'
><code>cupsArrayFind
</code></a></dt>
467 <dd>Returns the first matching element .
</dd>
468 <dt><a href='#cupsArrayFirst'
><code>cupsArrayFirst
</code></a></dt>
469 <dd>Returns the first element in the array.
</dd>
470 <dt><a href='#cupsArrayIndex'
><code>cupsArrayIndex
</code></a></dt>
471 <dd>Returns the Nth element in the array.
</dd>
472 <dt><a href='#cupsArrayLast'
><code>cupsArrayLast
</code></a></dt>
473 <dd>Returns the last element in the array.
</dd>
474 <dt><a href='#cupsArrayNext'
><code>cupsArrayNext
</code></a></dt>
475 <dd>Returns the next element in the array.
</dd>
476 <dt><a href='#cupsArrayPrev'
><code>cupsArrayPrev
</code></a></dt>
477 <dd>Returns the previous element in the array.
</dd>
480 <p>Each of these functions returns
<code>NULL
</code> when there is no
481 corresponding element. For example, a simple
<code>for
</code> loop using the
482 <a href='#cupsArrayFirst'
><code>cupsArrayFirst
</code></a> and
483 <a href='#cupsArrayNext'
><code>cupsArrayNext
</code></a> functions will
484 enumerate all of the strings in our previous example:
</p>
486 <pre class='example'
>
487 #include
<cups/array.h
>
489 /* Use strcmp() to compare strings - it will ignore the user_data pointer */
490 <a href='#cups_array_t'
>cups_array_t
</a> *array =
<a href='#cupsArrayNew'
>cupsArrayNew
</a>((
<a href='#cups_array_func_t'
>cups_array_func_t
</a>)strcmp, NULL);
492 /* Add four strings to the array */
493 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"One Fish");
494 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Two Fish");
495 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Red Fish");
496 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Blue Fish");
498 /* Show all of the strings in the array */
500 for (s = (char *)
<a href='#cupsArrayFirst'
>cupsArrayFirst
</a>(array); s != NULL; s = (char *)
<a href='#cupsArrayNext'
>cupsArrayNext
</a>(array))
503 <h2 class=
"title"><a name=
"FUNCTIONS">Functions
</a></h2>
504 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayAdd">cupsArrayAdd
</a></h3>
505 <p class=
"description">Add an element to the array.
</p>
507 int cupsArrayAdd (
<br>
508 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
509 void *e
<br>
511 <h4 class=
"parameters">Parameters
</h4>
514 <dd class=
"description">Array
</dd>
516 <dd class=
"description">Element
</dd>
518 <h4 class=
"returnvalue">Return Value
</h4>
519 <p class=
"description">1 on success,
0 on failure
</p>
520 <h4 class=
"discussion">Discussion
</h4>
521 <p class=
"discussion">When adding an element to a sorted array, non-unique elements are
522 appended at the end of the run. For unsorted arrays, the element
523 is inserted at the end of the array.
526 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayClear">cupsArrayClear
</a></h3>
527 <p class=
"description">Clear the array.
</p>
529 void cupsArrayClear (
<br>
530 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
532 <h4 class=
"parameters">Parameters
</h4>
535 <dd class=
"description">Array
</dd>
537 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayCount">cupsArrayCount
</a></h3>
538 <p class=
"description">Get the number of elements in the array.
</p>
540 int cupsArrayCount (
<br>
541 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
543 <h4 class=
"parameters">Parameters
</h4>
546 <dd class=
"description">Array
</dd>
548 <h4 class=
"returnvalue">Return Value
</h4>
549 <p class=
"description">Number of elements
</p>
550 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayCurrent">cupsArrayCurrent
</a></h3>
551 <p class=
"description">Return the current element in the array.
</p>
553 void *cupsArrayCurrent (
<br>
554 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
556 <h4 class=
"parameters">Parameters
</h4>
559 <dd class=
"description">Array
</dd>
561 <h4 class=
"returnvalue">Return Value
</h4>
562 <p class=
"description">Element
</p>
563 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayDelete">cupsArrayDelete
</a></h3>
564 <p class=
"description">Free all memory used by the array.
</p>
566 void cupsArrayDelete (
<br>
567 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
569 <h4 class=
"parameters">Parameters
</h4>
572 <dd class=
"description">Array
</dd>
574 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayDup">cupsArrayDup
</a></h3>
575 <p class=
"description">Duplicate the array.
</p>
577 <a href=
"#cups_array_t">cups_array_t
</a> *cupsArrayDup (
<br>
578 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
580 <h4 class=
"parameters">Parameters
</h4>
583 <dd class=
"description">Array
</dd>
585 <h4 class=
"returnvalue">Return Value
</h4>
586 <p class=
"description">Duplicate array
</p>
587 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayFind">cupsArrayFind
</a></h3>
588 <p class=
"description">Find an element in the array.
</p>
590 void *cupsArrayFind (
<br>
591 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
592 void *e
<br>
594 <h4 class=
"parameters">Parameters
</h4>
597 <dd class=
"description">Array
</dd>
599 <dd class=
"description">Element
</dd>
601 <h4 class=
"returnvalue">Return Value
</h4>
602 <p class=
"description">Element found or
<code>NULL
</code></p>
603 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayFirst">cupsArrayFirst
</a></h3>
604 <p class=
"description">Get the first element in the array.
</p>
606 void *cupsArrayFirst (
<br>
607 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
609 <h4 class=
"parameters">Parameters
</h4>
612 <dd class=
"description">Array
</dd>
614 <h4 class=
"returnvalue">Return Value
</h4>
615 <p class=
"description">First element or
<code>NULL
</code></p>
616 <h3 class=
"function"><span class=
"info"> CUPS
1.3 </span><a name=
"cupsArrayGetIndex">cupsArrayGetIndex
</a></h3>
617 <p class=
"description">Get the index of the current element.
</p>
619 int cupsArrayGetIndex (
<br>
620 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
622 <h4 class=
"parameters">Parameters
</h4>
625 <dd class=
"description">Array
</dd>
627 <h4 class=
"returnvalue">Return Value
</h4>
628 <p class=
"description">Index of the current element
</p>
629 <h3 class=
"function"><span class=
"info"> CUPS
1.3 </span><a name=
"cupsArrayGetInsert">cupsArrayGetInsert
</a></h3>
630 <p class=
"description">Get the index of the last inserted element.
</p>
632 int cupsArrayGetInsert (
<br>
633 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
635 <h4 class=
"parameters">Parameters
</h4>
638 <dd class=
"description">Array
</dd>
640 <h4 class=
"returnvalue">Return Value
</h4>
641 <p class=
"description">Index of the last inserted element
</p>
642 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayIndex">cupsArrayIndex
</a></h3>
643 <p class=
"description">Get the N-th element in the array.
</p>
645 void *cupsArrayIndex (
<br>
646 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
647 int n
<br>
649 <h4 class=
"parameters">Parameters
</h4>
652 <dd class=
"description">Array
</dd>
654 <dd class=
"description">Index into array, starting at
0</dd>
656 <h4 class=
"returnvalue">Return Value
</h4>
657 <p class=
"description">N-th element or
<code>NULL
</code></p>
658 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayInsert">cupsArrayInsert
</a></h3>
659 <p class=
"description">Insert an element in the array.
</p>
661 int cupsArrayInsert (
<br>
662 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
663 void *e
<br>
665 <h4 class=
"parameters">Parameters
</h4>
668 <dd class=
"description">Array
</dd>
670 <dd class=
"description">Element
</dd>
672 <h4 class=
"returnvalue">Return Value
</h4>
673 <p class=
"description">0 on failure,
1 on success
</p>
674 <h4 class=
"discussion">Discussion
</h4>
675 <p class=
"discussion">When inserting an element in a sorted array, non-unique elements are
676 inserted at the beginning of the run. For unsorted arrays, the element
677 is inserted at the beginning of the array.
680 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayLast">cupsArrayLast
</a></h3>
681 <p class=
"description">Get the last element in the array.
</p>
683 void *cupsArrayLast (
<br>
684 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
686 <h4 class=
"parameters">Parameters
</h4>
689 <dd class=
"description">Array
</dd>
691 <h4 class=
"returnvalue">Return Value
</h4>
692 <p class=
"description">Last element or
<code>NULL
</code></p>
693 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayNew">cupsArrayNew
</a></h3>
694 <p class=
"description">Create a new array.
</p>
696 <a href=
"#cups_array_t">cups_array_t
</a> *cupsArrayNew (
<br>
697 <a href=
"#cups_array_func_t">cups_array_func_t
</a> f,
<br>
698 void *d
<br>
700 <h4 class=
"parameters">Parameters
</h4>
703 <dd class=
"description">Comparison function
</dd>
705 <dd class=
"description">User data
</dd>
707 <h4 class=
"returnvalue">Return Value
</h4>
708 <p class=
"description">Array
</p>
709 <h3 class=
"function"><span class=
"info"> CUPS
1.3 </span><a name=
"cupsArrayNew2">cupsArrayNew2
</a></h3>
710 <p class=
"description">Create a new array with hash.
</p>
712 <a href=
"#cups_array_t">cups_array_t
</a> *cupsArrayNew2 (
<br>
713 <a href=
"#cups_array_func_t">cups_array_func_t
</a> f,
<br>
714 void *d,
<br>
715 <a href=
"#cups_ahash_func_t">cups_ahash_func_t
</a> h,
<br>
716 int hsize
<br>
718 <h4 class=
"parameters">Parameters
</h4>
721 <dd class=
"description">Comparison function
</dd>
723 <dd class=
"description">User data
</dd>
725 <dd class=
"description">Hash function
</dd>
727 <dd class=
"description">Hash size
</dd>
729 <h4 class=
"returnvalue">Return Value
</h4>
730 <p class=
"description">Array
</p>
731 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayNext">cupsArrayNext
</a></h3>
732 <p class=
"description">Get the next element in the array.
</p>
734 void *cupsArrayNext (
<br>
735 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
737 <h4 class=
"parameters">Parameters
</h4>
740 <dd class=
"description">Array
</dd>
742 <h4 class=
"returnvalue">Return Value
</h4>
743 <p class=
"description">Next element or
<code>NULL
</code></p>
744 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayPrev">cupsArrayPrev
</a></h3>
745 <p class=
"description">Get the previous element in the array.
</p>
747 void *cupsArrayPrev (
<br>
748 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
750 <h4 class=
"parameters">Parameters
</h4>
753 <dd class=
"description">Array
</dd>
755 <h4 class=
"returnvalue">Return Value
</h4>
756 <p class=
"description">Previous element or
<code>NULL
</code></p>
757 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayRemove">cupsArrayRemove
</a></h3>
758 <p class=
"description">Remove an element from the array.
</p>
760 int cupsArrayRemove (
<br>
761 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
762 void *e
<br>
764 <h4 class=
"parameters">Parameters
</h4>
767 <dd class=
"description">Array
</dd>
769 <dd class=
"description">Element
</dd>
771 <h4 class=
"returnvalue">Return Value
</h4>
772 <p class=
"description">1 on success,
0 on failure
</p>
773 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayRestore">cupsArrayRestore
</a></h3>
774 <p class=
"description">Reset the current element to the last cupsArraySave.
</p>
776 void *cupsArrayRestore (
<br>
777 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
779 <h4 class=
"parameters">Parameters
</h4>
782 <dd class=
"description">Array
</dd>
784 <h4 class=
"returnvalue">Return Value
</h4>
785 <p class=
"description">New current element
</p>
786 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArraySave">cupsArraySave
</a></h3>
787 <p class=
"description">Mark the current element for a later cupsArrayRestore.
</p>
789 int cupsArraySave (
<br>
790 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
792 <h4 class=
"parameters">Parameters
</h4>
795 <dd class=
"description">Array
</dd>
797 <h4 class=
"returnvalue">Return Value
</h4>
798 <p class=
"description">1 on success,
0 on failure
</p>
799 <h4 class=
"discussion">Discussion
</h4>
800 <p class=
"discussion">The save/restore stack is guaranteed to be at least
32 elements deep.
803 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayUserData">cupsArrayUserData
</a></h3>
804 <p class=
"description">Return the user data for an array.
</p>
806 void *cupsArrayUserData (
<br>
807 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
809 <h4 class=
"parameters">Parameters
</h4>
812 <dd class=
"description">Array
</dd>
814 <h4 class=
"returnvalue">Return Value
</h4>
815 <p class=
"description">User data
</p>
816 <h2 class=
"title"><a name=
"TYPES">Data Types
</a></h2>
817 <h3 class=
"typedef"><a name=
"cups_ahash_func_t">cups_ahash_func_t
</a></h3>
818 <p class=
"description">Array hash function
</p>
820 typedef int (*cups_ahash_func_t)(void *element, void *data);
822 <h3 class=
"typedef"><a name=
"cups_array_func_t">cups_array_func_t
</a></h3>
823 <p class=
"description">Array comparison function
</p>
825 typedef int (*cups_array_func_t)(void *first, void *second, void *data);
827 <h3 class=
"typedef"><a name=
"cups_array_t">cups_array_t
</a></h3>
828 <p class=
"description">CUPS array type
</p>
830 typedef struct _cups_array_s cups_array_t;