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;
37 border: dotted thin #999999;
42 PRE.command EM, PRE.example EM {
43 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
47 font-family: monaco, courier, monospace;
58 border: solid thin #999999;
69 -moz-border-radius: 10px;
74 text-decoration: none;
77 A:link:hover, A:visited:hover, A:active {
78 text-decoration: underline;
85 TR.data, TD.data, TR.data TD {
88 border-bottom: solid 1pt #999999;
92 border-bottom: solid 1pt #999999;
99 border: solid thin #999999;
100 border-collapse: collapse;
116 border: solid thin #cccccc;
123 border-bottom: solid thin #999999;
132 caption-side: bottom;
156 border: thin solid black;
164 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
170 border-bottom: solid 2pt #000000;
173 DIV.indent, TABLE.indent {
181 border-collapse: collapse;
184 TABLE.indent TD, TABLE.indent TH {
189 border-collapse: collapse;
197 border-bottom: solid thin #cccccc;
202 vertical-align: bottom;
211 border-bottom: solid thin #eeeeee;
216 TABLE.list TR:nth-child(even) {
220 TABLE.list TR:nth-child(odd) {
239 font-family: monaco, courier, monospace;
243 border: solid thin #999999;
244 border-collapse: collapse;
249 DIV.summary TABLE TD, DIV.summary TABLE TH {
250 border: solid thin #999999;
256 DIV.summary TABLE THEAD TH {
260 /* API documentation styles... */
267 div.body h3, div.body h4, div.body h5 {
268 margin-bottom: 0.5em;
271 .class, .enumeration, .function, .struct, .typedef, .union {
272 border-bottom: solid thin #999999;
279 code, p.code, pre, ul.code li {
280 font-family: monaco, courier, monospace;
283 ul.code, ul.contents, ul.subcontents {
284 list-style-type: none;
294 ul.contents li ul.code, ul.contents li ul.subcontents {
307 margin-bottom: 0.5em;
310 /* This is just for the HTML files generated with the framedhelp target */
313 border: solid thin black;
322 div.contents ul.contents {
325 div.contents ul.subcontents li {
334 "$Id: api-array.header 7266 2008-01-29 02:15:29Z mike $"
336 Array API header for the Common UNIX Printing System (CUPS).
338 Copyright 2008 by Apple Inc.
340 These coded instructions, statements, and computer programs are the
341 property of Apple Inc. and are protected by Federal copyright
342 law. Distribution and use rights are outlined in the file "LICENSE.txt"
343 which should have been included with this file. If this file is
344 file is missing or damaged, see the license at "http://www.cups.org/".
347 <div class='summary'
><table summary='General Information'
>
351 <th>cups/array.h
</th>
361 <td>Programming:
<a href='api-overview.html' target='_top'
>Introduction to CUPS Programming
</a></td>
365 <h2 class=
"title">Contents
</h2>
366 <ul class=
"contents">
368 <li><a href=
"#OVERVIEW">Overview
</a><ul class=
"subcontents">
369 <li><a href=
"#MANAGING_ARRAYS">Managing Arrays
</a></li>
370 <li><a href=
"#FINDING_AND_ENUMERATING">Finding and Enumerating Elements
</a></li>
372 <li><a href=
"#FUNCTIONS">Functions
</a><ul class=
"code">
373 <li><a href=
"#cupsArrayAdd" title=
"Add an element to the array.">cupsArrayAdd
</a></li>
374 <li><a href=
"#cupsArrayClear" title=
"Clear the array.">cupsArrayClear
</a></li>
375 <li><a href=
"#cupsArrayCount" title=
"Get the number of elements in the array.">cupsArrayCount
</a></li>
376 <li><a href=
"#cupsArrayCurrent" title=
"Return the current element in the array.">cupsArrayCurrent
</a></li>
377 <li><a href=
"#cupsArrayDelete" title=
"Free all memory used by the array.">cupsArrayDelete
</a></li>
378 <li><a href=
"#cupsArrayDup" title=
"Duplicate the array.">cupsArrayDup
</a></li>
379 <li><a href=
"#cupsArrayFind" title=
"Find an element in the array.">cupsArrayFind
</a></li>
380 <li><a href=
"#cupsArrayFirst" title=
"Get the first element in the array.">cupsArrayFirst
</a></li>
381 <li><a href=
"#cupsArrayGetIndex" title=
"Get the index of the current element.">cupsArrayGetIndex
</a></li>
382 <li><a href=
"#cupsArrayGetInsert" title=
"Get the index of the last inserted element.">cupsArrayGetInsert
</a></li>
383 <li><a href=
"#cupsArrayIndex" title=
"Get the N-th element in the array.">cupsArrayIndex
</a></li>
384 <li><a href=
"#cupsArrayInsert" title=
"Insert an element in the array.">cupsArrayInsert
</a></li>
385 <li><a href=
"#cupsArrayLast" title=
"Get the last element in the array.">cupsArrayLast
</a></li>
386 <li><a href=
"#cupsArrayNew" title=
"Create a new array.">cupsArrayNew
</a></li>
387 <li><a href=
"#cupsArrayNew2" title=
"Create a new array with hash.">cupsArrayNew2
</a></li>
388 <li><a href=
"#cupsArrayNext" title=
"Get the next element in the array.">cupsArrayNext
</a></li>
389 <li><a href=
"#cupsArrayPrev" title=
"Get the previous element in the array.">cupsArrayPrev
</a></li>
390 <li><a href=
"#cupsArrayRemove" title=
"Remove an element from the array.">cupsArrayRemove
</a></li>
391 <li><a href=
"#cupsArrayRestore" title=
"Reset the current element to the last <a href="#cupsArraySave
"><code>cupsArraySave</code></a>.">cupsArrayRestore
</a></li>
392 <li><a href=
"#cupsArraySave" title=
"Mark the current element for a later <a href="#cupsArrayRestore
"><code>cupsArrayRestore</code></a>.">cupsArraySave
</a></li>
393 <li><a href=
"#cupsArrayUserData" title=
"Return the user data for an array.">cupsArrayUserData
</a></li>
395 <li><a href=
"#TYPES">Data Types
</a><ul class=
"code">
396 <li><a href=
"#cups_ahash_func_t" title=
"Array hash function">cups_ahash_func_t
</a></li>
397 <li><a href=
"#cups_array_func_t" title=
"Array comparison function">cups_array_func_t
</a></li>
398 <li><a href=
"#cups_array_t" title=
"CUPS array type">cups_array_t
</a></li>
402 "$Id: api-array.shtml 7616 2008-05-28 00:34:13Z mike $"
404 Array API introduction for the Common UNIX Printing System (CUPS).
406 Copyright 2007-2008 by Apple Inc.
407 Copyright 1997-2006 by Easy Software Products, all rights reserved.
409 These coded instructions, statements, and computer programs are the
410 property of Apple Inc. and are protected by Federal copyright
411 law. Distribution and use rights are outlined in the file "LICENSE.txt"
412 which should have been included with this file. If this file is
413 file is missing or damaged, see the license at "http://www.cups.org/".
416 <h2 class='title'
><a name='OVERVIEW'
>Overview
</a></h2>
418 <p>The CUPS array API provides a high-performance generic array container.
419 The contents of the array container can be sorted and the container itself is
420 designed for optimal speed and memory usage under a wide variety of conditions.
421 Sorted arrays use a binary search algorithm from the last found or inserted
422 element to quickly find matching elements in the array. Arrays created with the
423 optional hash function can often find elements with a single lookup. The
424 <a href='#cups_array_t'
><code>cups_array_t
</code></a> type is used when
425 referring to a CUPS array.
</p>
427 <p>The CUPS scheduler (
<tt>cupsd
</tt>) and many of the CUPS API
428 functions use the array API to efficiently manage large lists of
431 <h3><a name='MANAGING_ARRAYS'
>Managing Arrays
</a></h3>
433 <p>Arrays are created using either the
434 <a href='#cupsArrayNew'
><code>cupsArrayNew
</code></a> or
435 <a href='#cupsArrayNew2'
><code>cupsArrayNew2
</code></a> functions. The
436 first function creates a new array with the specified callback function
437 and user data pointer:
</p>
439 <pre class='example'
>
440 #include
<cups/array.h
>
442 static int compare_func(void *first, void *second, void *user_data);
445 <a href='#cups_array_t'
>cups_array_t
</a> *array =
<a href='#cupsArrayNew'
>cupsArrayNew
</a>(compare_func, user_data);
448 <p>The comparison function (type
449 <a href=
"#cups_arrayfunc_t"><code>cups_arrayfunc_t
</code></a>) is called
450 whenever an element is added to the array and can be
<code>NULL
</code> to
451 create an unsorted array. The function returns -
1 if the first element should
452 come before the second,
0 if the first and second elements should have the same
453 ordering, and
1 if the first element should come after the second.
</p>
455 <p>The
"user_data" pointer is passed to your comparison function. Pass
456 <code>NULL
</code> if you do not need to associate the elements in your array
457 with additional information.
</p>
459 <p>The
<a href='#cupsArrayNew2'
><code>cupsArrayNew2
</code></a> function adds
460 two more arguments to support hashed lookups, which can potentially provide
461 instantaneous (
"O(1)") lookups in your array:
</p>
463 <pre class='example'
>
464 #include
<cups/array.h
>
466 #define HASH_SIZE
512 /* Size of hash table */
468 static int compare_func(void *first, void *second, void *user_data);
469 static int hash_func(void *element, void *user_data);
472 <a href='#cups_array_t'
>cups_array_t
</a> *array =
<a href='#cupsArrayNew2'
>cupsArrayNew2
</a>(compare_func, user_data, hash_func, HASH_SIZE);
475 <p>The hash function (type
476 <a href=
"#cups_ahash_func_t"><code>cups_ahash_func_t
</code></a>) should return a
477 number from
0 to (hash_size-
1) that (hopefully) uniquely identifies the
478 element and is called whenever you look up an element in the array with
479 <a href='#cupsArrayFind'
><code>cupsArrayFind
</code></a>. The hash size is
480 only limited by available memory, but generally should not be larger than
481 16384 to realize any performance improvement.
</p>
483 <p>Once you have created the array, you add elements using the
484 <a href='#cupsArrayAdd'
><code>cupsArrayAdd
</code></a>
485 <a href='#cupsArrayInsert'
><code>cupsArrayInsert
</code></a> functions.
486 The first function adds an element to the array, adding the new element
487 after any elements that have the same order, while the second inserts the
488 element before others with the same order. For unsorted arrays,
489 <a href='#cupsArrayAdd'
><code>cupsArrayAdd
</code></a> appends the element to
490 the end of the array while
491 <a href='#cupsArrayInsert'
><code>cupsArrayInsert
</code></a> inserts the
492 element at the beginning of the array. For example, the following code
493 creates a sorted array of character strings:
</p>
495 <pre class='example'
>
496 #include
<cups/array.h
>
498 /* Use strcmp() to compare strings - it will ignore the user_data pointer */
499 <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);
501 /* Add four strings to the array */
502 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"One Fish");
503 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Two Fish");
504 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Red Fish");
505 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Blue Fish");
508 <p>Elements are removed using the
509 <a href='#cupsArrayRemove'
><code>cupsArrayRemove
</code></a> function, for
512 <pre class='example'
>
513 #include
<cups/array.h
>
515 /* Use strcmp() to compare strings - it will ignore the user_data pointer */
516 <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);
518 /* Add four strings to the array */
519 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"One Fish");
520 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Two Fish");
521 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Red Fish");
522 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Blue Fish");
524 /* Remove
"Red Fish" */
525 <a href='#cupsArrayRemove'
>cupsArrayRemove
</a>(array,
"Red Fish");
528 <p>Finally, you free the memory used by the array using the
529 <a href='#cupsArrayDelete'
><code>cupsArrayDelete
</code></a> function. All
530 of the memory for the array and hash table (if any) is freed, however
<em>CUPS
531 does not free the elements
</em> - if necessary, you must allocate and free the
532 elements yourself.
</p>
534 <h3><a name='FINDING_AND_ENUMERATING'
>Finding and Enumerating Elements
</a></h3>
536 <p>CUPS provides several functions to find and enumerate elements in an
537 array. Each one sets or updates a
"current index" into the array, such that
538 future lookups will start where the last one left off:
</p>
541 <dt><a href='#cupsArrayFind'
><code>cupsArrayFind
</code></a></dt>
542 <dd>Returns the first matching element.
</dd>
543 <dt><a href='#cupsArrayFirst'
><code>cupsArrayFirst
</code></a></dt>
544 <dd>Returns the first element in the array.
</dd>
545 <dt><a href='#cupsArrayIndex'
><code>cupsArrayIndex
</code></a></dt>
546 <dd>Returns the Nth element in the array, starting at
0.
</dd>
547 <dt><a href='#cupsArrayLast'
><code>cupsArrayLast
</code></a></dt>
548 <dd>Returns the last element in the array.
</dd>
549 <dt><a href='#cupsArrayNext'
><code>cupsArrayNext
</code></a></dt>
550 <dd>Returns the next element in the array.
</dd>
551 <dt><a href='#cupsArrayPrev'
><code>cupsArrayPrev
</code></a></dt>
552 <dd>Returns the previous element in the array.
</dd>
555 <p>Each of these functions returns
<code>NULL
</code> when there is no
556 corresponding element. For example, a simple
<code>for
</code> loop using the
557 <a href='#cupsArrayFirst'
><code>cupsArrayFirst
</code></a> and
558 <a href='#cupsArrayNext'
><code>cupsArrayNext
</code></a> functions will
559 enumerate all of the strings in our previous example:
</p>
561 <pre class='example'
>
562 #include
<cups/array.h
>
564 /* Use strcmp() to compare strings - it will ignore the user_data pointer */
565 <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);
567 /* Add four strings to the array */
568 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"One Fish");
569 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Two Fish");
570 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Red Fish");
571 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Blue Fish");
573 /* Show all of the strings in the array */
575 for (s = (char *)
<a href='#cupsArrayFirst'
>cupsArrayFirst
</a>(array); s != NULL; s = (char *)
<a href='#cupsArrayNext'
>cupsArrayNext
</a>(array))
578 <h2 class=
"title"><a name=
"FUNCTIONS">Functions
</a></h2>
579 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayAdd">cupsArrayAdd
</a></h3>
580 <p class=
"description">Add an element to the array.
</p>
582 int cupsArrayAdd (
<br>
583 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
584 void *e
<br>
586 <h4 class=
"parameters">Parameters
</h4>
589 <dd class=
"description">Array
</dd>
591 <dd class=
"description">Element
</dd>
593 <h4 class=
"returnvalue">Return Value
</h4>
594 <p class=
"description">1 on success,
0 on failure
</p>
595 <h4 class=
"discussion">Discussion
</h4>
596 <p class=
"discussion">When adding an element to a sorted array, non-unique elements are
597 appended at the end of the run of identical elements. For unsorted arrays,
598 the element is appended to the end of the array.
601 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayClear">cupsArrayClear
</a></h3>
602 <p class=
"description">Clear the array.
</p>
604 void cupsArrayClear (
<br>
605 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
607 <h4 class=
"parameters">Parameters
</h4>
610 <dd class=
"description">Array
</dd>
612 <h4 class=
"discussion">Discussion
</h4>
613 <p class=
"discussion">This function is equivalent to removing all elements in the array.
614 The caller is responsible for freeing the memory used by the
618 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayCount">cupsArrayCount
</a></h3>
619 <p class=
"description">Get the number of elements in the array.
</p>
621 int cupsArrayCount (
<br>
622 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
624 <h4 class=
"parameters">Parameters
</h4>
627 <dd class=
"description">Array
</dd>
629 <h4 class=
"returnvalue">Return Value
</h4>
630 <p class=
"description">Number of elements
</p>
631 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayCurrent">cupsArrayCurrent
</a></h3>
632 <p class=
"description">Return the current element in the array.
</p>
634 void *cupsArrayCurrent (
<br>
635 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
637 <h4 class=
"parameters">Parameters
</h4>
640 <dd class=
"description">Array
</dd>
642 <h4 class=
"returnvalue">Return Value
</h4>
643 <p class=
"description">Element
</p>
644 <h4 class=
"discussion">Discussion
</h4>
645 <p class=
"discussion">The current element is undefined until you call
<a href=
"#cupsArrayFind"><code>cupsArrayFind
</code></a>,
646 <a href=
"#cupsArrayFirst"><code>cupsArrayFirst
</code></a>, or
<a href=
"#cupsArrayIndex"><code>cupsArrayIndex
</code></a>, or
<a href=
"#cupsArrayLast"><code>cupsArrayLast
</code></a>.
649 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayDelete">cupsArrayDelete
</a></h3>
650 <p class=
"description">Free all memory used by the array.
</p>
652 void cupsArrayDelete (
<br>
653 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
655 <h4 class=
"parameters">Parameters
</h4>
658 <dd class=
"description">Array
</dd>
660 <h4 class=
"discussion">Discussion
</h4>
661 <p class=
"discussion">The caller is responsible for freeing the memory used by the
665 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayDup">cupsArrayDup
</a></h3>
666 <p class=
"description">Duplicate the array.
</p>
668 <a href=
"#cups_array_t">cups_array_t
</a> *cupsArrayDup (
<br>
669 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
671 <h4 class=
"parameters">Parameters
</h4>
674 <dd class=
"description">Array
</dd>
676 <h4 class=
"returnvalue">Return Value
</h4>
677 <p class=
"description">Duplicate array
</p>
678 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayFind">cupsArrayFind
</a></h3>
679 <p class=
"description">Find an element in the array.
</p>
681 void *cupsArrayFind (
<br>
682 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
683 void *e
<br>
685 <h4 class=
"parameters">Parameters
</h4>
688 <dd class=
"description">Array
</dd>
690 <dd class=
"description">Element
</dd>
692 <h4 class=
"returnvalue">Return Value
</h4>
693 <p class=
"description">Element found or
<code>NULL
</code></p>
694 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayFirst">cupsArrayFirst
</a></h3>
695 <p class=
"description">Get the first element in the array.
</p>
697 void *cupsArrayFirst (
<br>
698 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
700 <h4 class=
"parameters">Parameters
</h4>
703 <dd class=
"description">Array
</dd>
705 <h4 class=
"returnvalue">Return Value
</h4>
706 <p class=
"description">First element or
<code>NULL
</code> if the array is empty
</p>
707 <h3 class=
"function"><span class=
"info"> CUPS
1.3 </span><a name=
"cupsArrayGetIndex">cupsArrayGetIndex
</a></h3>
708 <p class=
"description">Get the index of the current element.
</p>
710 int cupsArrayGetIndex (
<br>
711 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
713 <h4 class=
"parameters">Parameters
</h4>
716 <dd class=
"description">Array
</dd>
718 <h4 class=
"returnvalue">Return Value
</h4>
719 <p class=
"description">Index of the current element, starting at
0</p>
720 <h4 class=
"discussion">Discussion
</h4>
721 <p class=
"discussion">The current element is undefined until you call
<a href=
"#cupsArrayFind"><code>cupsArrayFind
</code></a>,
722 <a href=
"#cupsArrayFirst"><code>cupsArrayFirst
</code></a>, or
<a href=
"#cupsArrayIndex"><code>cupsArrayIndex
</code></a>, or
<a href=
"#cupsArrayLast"><code>cupsArrayLast
</code></a>.
725 <h3 class=
"function"><span class=
"info"> CUPS
1.3 </span><a name=
"cupsArrayGetInsert">cupsArrayGetInsert
</a></h3>
726 <p class=
"description">Get the index of the last inserted element.
</p>
728 int cupsArrayGetInsert (
<br>
729 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
731 <h4 class=
"parameters">Parameters
</h4>
734 <dd class=
"description">Array
</dd>
736 <h4 class=
"returnvalue">Return Value
</h4>
737 <p class=
"description">Index of the last inserted element, starting at
0</p>
738 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayIndex">cupsArrayIndex
</a></h3>
739 <p class=
"description">Get the N-th element in the array.
</p>
741 void *cupsArrayIndex (
<br>
742 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
743 int n
<br>
745 <h4 class=
"parameters">Parameters
</h4>
748 <dd class=
"description">Array
</dd>
750 <dd class=
"description">Index into array, starting at
0</dd>
752 <h4 class=
"returnvalue">Return Value
</h4>
753 <p class=
"description">N-th element or
<code>NULL
</code></p>
754 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayInsert">cupsArrayInsert
</a></h3>
755 <p class=
"description">Insert an element in the array.
</p>
757 int cupsArrayInsert (
<br>
758 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
759 void *e
<br>
761 <h4 class=
"parameters">Parameters
</h4>
764 <dd class=
"description">Array
</dd>
766 <dd class=
"description">Element
</dd>
768 <h4 class=
"returnvalue">Return Value
</h4>
769 <p class=
"description">0 on failure,
1 on success
</p>
770 <h4 class=
"discussion">Discussion
</h4>
771 <p class=
"discussion">When inserting an element in a sorted array, non-unique elements are
772 inserted at the beginning of the run of identical elements. For unsorted
773 arrays, the element is inserted at the beginning of the array.
776 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayLast">cupsArrayLast
</a></h3>
777 <p class=
"description">Get the last element in the array.
</p>
779 void *cupsArrayLast (
<br>
780 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
782 <h4 class=
"parameters">Parameters
</h4>
785 <dd class=
"description">Array
</dd>
787 <h4 class=
"returnvalue">Return Value
</h4>
788 <p class=
"description">Last element or
<code>NULL
</code> if the array is empty
</p>
789 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayNew">cupsArrayNew
</a></h3>
790 <p class=
"description">Create a new array.
</p>
792 <a href=
"#cups_array_t">cups_array_t
</a> *cupsArrayNew (
<br>
793 <a href=
"#cups_array_func_t">cups_array_func_t
</a> f,
<br>
794 void *d
<br>
796 <h4 class=
"parameters">Parameters
</h4>
799 <dd class=
"description">Comparison function or
<code>NULL
</code> for an unsorted array
</dd>
801 <dd class=
"description">User data pointer or
<code>NULL
</code></dd>
803 <h4 class=
"returnvalue">Return Value
</h4>
804 <p class=
"description">Array
</p>
805 <h4 class=
"discussion">Discussion
</h4>
806 <p class=
"discussion">The comparison function (
"f
") is used to create a sorted array. The function
807 receives pointers to two elements and the user data pointer (
"d
") - the user
808 data pointer argument can safely be omitted when not required so functions
809 like
<code>strcmp
</code> can be used for sorted string arrays.
812 <h3 class=
"function"><span class=
"info"> CUPS
1.3 </span><a name=
"cupsArrayNew2">cupsArrayNew2
</a></h3>
813 <p class=
"description">Create a new array with hash.
</p>
815 <a href=
"#cups_array_t">cups_array_t
</a> *cupsArrayNew2 (
<br>
816 <a href=
"#cups_array_func_t">cups_array_func_t
</a> f,
<br>
817 void *d,
<br>
818 <a href=
"#cups_ahash_func_t">cups_ahash_func_t
</a> h,
<br>
819 int hsize
<br>
821 <h4 class=
"parameters">Parameters
</h4>
824 <dd class=
"description">Comparison function or
<code>NULL
</code> for an unsorted array
</dd>
826 <dd class=
"description">User data or
<code>NULL
</code></dd>
828 <dd class=
"description">Hash function or
<code>NULL
</code> for unhashed lookups
</dd>
830 <dd class=
"description">Hash size (
>=
0)
</dd>
832 <h4 class=
"returnvalue">Return Value
</h4>
833 <p class=
"description">Array
</p>
834 <h4 class=
"discussion">Discussion
</h4>
835 <p class=
"discussion">The comparison function (
"f
") is used to create a sorted array. The function
836 receives pointers to two elements and the user data pointer (
"d
") - the user
837 data pointer argument can safely be omitted when not required so functions
838 like
<code>strcmp
</code> can be used for sorted string arrays.
<br>
840 The hash function (
"h
") is used to implement cached lookups with the
841 specified hash size (
"hsize
").
844 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayNext">cupsArrayNext
</a></h3>
845 <p class=
"description">Get the next element in the array.
</p>
847 void *cupsArrayNext (
<br>
848 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
850 <h4 class=
"parameters">Parameters
</h4>
853 <dd class=
"description">Array
</dd>
855 <h4 class=
"returnvalue">Return Value
</h4>
856 <p class=
"description">Next element or
<code>NULL
</code></p>
857 <h4 class=
"discussion">Discussion
</h4>
858 <p class=
"discussion">This function is equivalent to
"cupsArrayIndex(a, cupsArrayGetIndex(a) +
1)
".
<br>
860 The next element is undefined until you call
<a href=
"#cupsArrayFind"><code>cupsArrayFind
</code></a>,
861 <a href=
"#cupsArrayFirst"><code>cupsArrayFirst
</code></a>, or
<a href=
"#cupsArrayIndex"><code>cupsArrayIndex
</code></a>, or
<a href=
"#cupsArrayLast"><code>cupsArrayLast
</code></a>
862 to set the current element.
865 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayPrev">cupsArrayPrev
</a></h3>
866 <p class=
"description">Get the previous element in the array.
</p>
868 void *cupsArrayPrev (
<br>
869 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
871 <h4 class=
"parameters">Parameters
</h4>
874 <dd class=
"description">Array
</dd>
876 <h4 class=
"returnvalue">Return Value
</h4>
877 <p class=
"description">Previous element or
<code>NULL
</code></p>
878 <h4 class=
"discussion">Discussion
</h4>
879 <p class=
"discussion">This function is equivalent to
"cupsArrayIndex(a, cupsArrayGetIndex(a) -
1)
".
<br>
881 The previous element is undefined until you call
<a href=
"#cupsArrayFind"><code>cupsArrayFind
</code></a>,
882 <a href=
"#cupsArrayFirst"><code>cupsArrayFirst
</code></a>, or
<a href=
"#cupsArrayIndex"><code>cupsArrayIndex
</code></a>, or
<a href=
"#cupsArrayLast"><code>cupsArrayLast
</code></a>
883 to set the current element.
886 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayRemove">cupsArrayRemove
</a></h3>
887 <p class=
"description">Remove an element from the array.
</p>
889 int cupsArrayRemove (
<br>
890 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
891 void *e
<br>
893 <h4 class=
"parameters">Parameters
</h4>
896 <dd class=
"description">Array
</dd>
898 <dd class=
"description">Element
</dd>
900 <h4 class=
"returnvalue">Return Value
</h4>
901 <p class=
"description">1 on success,
0 on failure
</p>
902 <h4 class=
"discussion">Discussion
</h4>
903 <p class=
"discussion">If more than one element matches
"e
", only the first matching element is
906 The caller is responsible for freeing the memory used by the
910 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayRestore">cupsArrayRestore
</a></h3>
911 <p class=
"description">Reset the current element to the last
<a href=
"#cupsArraySave"><code>cupsArraySave
</code></a>.
</p>
913 void *cupsArrayRestore (
<br>
914 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
916 <h4 class=
"parameters">Parameters
</h4>
919 <dd class=
"description">Array
</dd>
921 <h4 class=
"returnvalue">Return Value
</h4>
922 <p class=
"description">New current element
</p>
923 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArraySave">cupsArraySave
</a></h3>
924 <p class=
"description">Mark the current element for a later
<a href=
"#cupsArrayRestore"><code>cupsArrayRestore
</code></a>.
</p>
926 int cupsArraySave (
<br>
927 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
929 <h4 class=
"parameters">Parameters
</h4>
932 <dd class=
"description">Array
</dd>
934 <h4 class=
"returnvalue">Return Value
</h4>
935 <p class=
"description">1 on success,
0 on failure
</p>
936 <h4 class=
"discussion">Discussion
</h4>
937 <p class=
"discussion">The current element is undefined until you call
<a href=
"#cupsArrayFind"><code>cupsArrayFind
</code></a>,
938 <a href=
"#cupsArrayFirst"><code>cupsArrayFirst
</code></a>, or
<a href=
"#cupsArrayIndex"><code>cupsArrayIndex
</code></a>, or
<a href=
"#cupsArrayLast"><code>cupsArrayLast
</code></a>
939 to set the current element.
<br>
941 The save/restore stack is guaranteed to be at least
32 elements deep.
944 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsArrayUserData">cupsArrayUserData
</a></h3>
945 <p class=
"description">Return the user data for an array.
</p>
947 void *cupsArrayUserData (
<br>
948 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
950 <h4 class=
"parameters">Parameters
</h4>
953 <dd class=
"description">Array
</dd>
955 <h4 class=
"returnvalue">Return Value
</h4>
956 <p class=
"description">User data
</p>
957 <h2 class=
"title"><a name=
"TYPES">Data Types
</a></h2>
958 <h3 class=
"typedef"><a name=
"cups_ahash_func_t">cups_ahash_func_t
</a></h3>
959 <p class=
"description">Array hash function
</p>
961 typedef int (*cups_ahash_func_t)(void *element, void *data);
963 <h3 class=
"typedef"><a name=
"cups_array_func_t">cups_array_func_t
</a></h3>
964 <p class=
"description">Array comparison function
</p>
966 typedef int (*cups_array_func_t)(void *first, void *second, void *data);
968 <h3 class=
"typedef"><a name=
"cups_array_t">cups_array_t
</a></h3>
969 <p class=
"description">CUPS array type
</p>
971 typedef struct _cups_array_s cups_array_t;