1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
3 <!-- SECTION: Programming -->
5 <title>Array API
</title>
6 <meta name=
"keywords" content=
"Programming">
7 <meta http-equiv=
"Content-Type" content=
"text/html;charset=utf-8">
8 <meta name=
"creator" content=
"Mini-XML v2.7">
9 <style type=
"text/css"><!--
11 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
14 H1, H2, H3, H4, H5, H6, P, TD, TH {
15 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
19 font-family: monaco, courier, monospace;
24 font-family: monaco, courier, monospace;
28 border: dotted thin #7f7f7f;
44 border: dotted thin #999999;
49 PRE.command EM, PRE.example EM {
50 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
54 font-family: monaco, courier, monospace;
65 border: solid thin #999999;
76 -moz-border-radius: 10px;
81 text-decoration: none;
84 A:link:hover, A:visited:hover, A:active {
85 text-decoration: underline;
92 TR.data, TD.data, TR.data TD {
95 border-bottom: solid 1pt #999999;
99 border-bottom: solid 1pt #999999;
106 border: solid thin #999999;
107 border-collapse: collapse;
123 border: solid thin #cccccc;
130 border-bottom: solid thin #999999;
139 caption-side: bottom;
163 border: thin solid black;
171 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
180 border-bottom: solid 2pt #000000;
183 DIV.indent, TABLE.indent {
191 border-collapse: collapse;
194 TABLE.indent TD, TABLE.indent TH {
199 border-collapse: collapse;
207 border-bottom: solid thin #cccccc;
212 vertical-align: bottom;
221 border-bottom: solid thin #eeeeee;
226 TABLE.list TR:nth-child(even) {
230 TABLE.list TR:nth-child(odd) {
249 font-family: monaco, courier, monospace;
253 border: solid thin #999999;
254 border-collapse: collapse;
259 DIV.summary TABLE TD, DIV.summary TABLE TH {
260 border: solid thin #999999;
266 DIV.summary TABLE THEAD TH {
270 /* API documentation styles... */
277 div.body h3, div.body h4, div.body h5 {
278 margin-bottom: 0.5em;
281 .class, .enumeration, .function, .struct, .typedef, .union {
282 border-bottom: solid thin #999999;
289 code, p.code, pre, ul.code li {
290 font-family: monaco, courier, monospace;
293 ul.code, ul.contents, ul.subcontents {
294 list-style-type: none;
304 ul.contents li ul.code, ul.contents li ul.subcontents {
317 margin-bottom: 0.5em;
320 /* This is just for the HTML files generated with the framedhelp target */
323 border: solid thin black;
332 div.contents ul.contents {
335 div.contents ul.subcontents li {
346 Array API header for the Common UNIX Printing System (CUPS).
348 Copyright 2008-2009 by Apple Inc.
350 These coded instructions, statements, and computer programs are the
351 property of Apple Inc. and are protected by Federal copyright
352 law. Distribution and use rights are outlined in the file "LICENSE.txt"
353 which should have been included with this file. If this file is
354 file is missing or damaged, see the license at "http://www.cups.org/".
357 <h1 class='title'
>Array API
</h1>
359 <div class='summary'
><table summary='General Information'
>
363 <th>cups/array.h
</th>
373 <td>Programming:
<a href='api-overview.html' target='_top'
>Introduction to CUPS Programming
</a></td>
377 <h2 class=
"title">Contents
</h2>
378 <ul class=
"contents">
379 <li><a href=
"#OVERVIEW">Overview
</a><ul class=
"subcontents">
380 <li><a href=
"#MANAGING_ARRAYS">Managing Arrays
</a></li>
381 <li><a href=
"#FINDING_AND_ENUMERATING">Finding and Enumerating Elements
</a></li>
383 <li><a href=
"#FUNCTIONS">Functions
</a><ul class=
"code">
384 <li><a href=
"#cupsArrayAdd" title=
"Add an element to the array.">cupsArrayAdd
</a></li>
385 <li><a href=
"#cupsArrayClear" title=
"Clear the array.">cupsArrayClear
</a></li>
386 <li><a href=
"#cupsArrayCount" title=
"Get the number of elements in the array.">cupsArrayCount
</a></li>
387 <li><a href=
"#cupsArrayCurrent" title=
"Return the current element in the array.">cupsArrayCurrent
</a></li>
388 <li><a href=
"#cupsArrayDelete" title=
"Free all memory used by the array.">cupsArrayDelete
</a></li>
389 <li><a href=
"#cupsArrayDup" title=
"Duplicate the array.">cupsArrayDup
</a></li>
390 <li><a href=
"#cupsArrayFind" title=
"Find an element in the array.">cupsArrayFind
</a></li>
391 <li><a href=
"#cupsArrayFirst" title=
"Get the first element in the array.">cupsArrayFirst
</a></li>
392 <li><a href=
"#cupsArrayGetIndex" title=
"Get the index of the current element.">cupsArrayGetIndex
</a></li>
393 <li><a href=
"#cupsArrayGetInsert" title=
"Get the index of the last inserted element.">cupsArrayGetInsert
</a></li>
394 <li><a href=
"#cupsArrayIndex" title=
"Get the N-th element in the array.">cupsArrayIndex
</a></li>
395 <li><a href=
"#cupsArrayInsert" title=
"Insert an element in the array.">cupsArrayInsert
</a></li>
396 <li><a href=
"#cupsArrayLast" title=
"Get the last element in the array.">cupsArrayLast
</a></li>
397 <li><a href=
"#cupsArrayNew" title=
"Create a new array.">cupsArrayNew
</a></li>
398 <li><a href=
"#cupsArrayNew2" title=
"Create a new array with hash.">cupsArrayNew2
</a></li>
399 <li><a href=
"#cupsArrayNew3" title=
"Create a new array with hash and/or free function.">cupsArrayNew3
</a></li>
400 <li><a href=
"#cupsArrayNext" title=
"Get the next element in the array.">cupsArrayNext
</a></li>
401 <li><a href=
"#cupsArrayPrev" title=
"Get the previous element in the array.">cupsArrayPrev
</a></li>
402 <li><a href=
"#cupsArrayRemove" title=
"Remove an element from the array.">cupsArrayRemove
</a></li>
403 <li><a href=
"#cupsArrayRestore" title=
"Reset the current element to the last cupsArraySave.">cupsArrayRestore
</a></li>
404 <li><a href=
"#cupsArraySave" title=
"Mark the current element for a later cupsArrayRestore.">cupsArraySave
</a></li>
405 <li><a href=
"#cupsArrayUserData" title=
"Return the user data for an array.">cupsArrayUserData
</a></li>
407 <li><a href=
"#TYPES">Data Types
</a><ul class=
"code">
408 <li><a href=
"#cups_acopy_func_t" title=
"Array element copy function">cups_acopy_func_t
</a></li>
409 <li><a href=
"#cups_afree_func_t" title=
"Array element free function">cups_afree_func_t
</a></li>
410 <li><a href=
"#cups_ahash_func_t" title=
"Array hash function">cups_ahash_func_t
</a></li>
411 <li><a href=
"#cups_array_func_t" title=
"Array comparison function">cups_array_func_t
</a></li>
412 <li><a href=
"#cups_array_t" title=
"CUPS array type">cups_array_t
</a></li>
418 Array API introduction for the Common UNIX Printing System (CUPS).
420 Copyright 2007-2008 by Apple Inc.
421 Copyright 1997-2006 by Easy Software Products, all rights reserved.
423 These coded instructions, statements, and computer programs are the
424 property of Apple Inc. and are protected by Federal copyright
425 law. Distribution and use rights are outlined in the file "LICENSE.txt"
426 which should have been included with this file. If this file is
427 file is missing or damaged, see the license at "http://www.cups.org/".
430 <h2 class='title'
><a name='OVERVIEW'
>Overview
</a></h2>
432 <p>The CUPS array API provides a high-performance generic array container.
433 The contents of the array container can be sorted and the container itself is
434 designed for optimal speed and memory usage under a wide variety of conditions.
435 Sorted arrays use a binary search algorithm from the last found or inserted
436 element to quickly find matching elements in the array. Arrays created with the
437 optional hash function can often find elements with a single lookup. The
438 <a href='#cups_array_t'
><code>cups_array_t
</code></a> type is used when
439 referring to a CUPS array.
</p>
441 <p>The CUPS scheduler (
<tt>cupsd
</tt>) and many of the CUPS API
442 functions use the array API to efficiently manage large lists of
445 <h3><a name='MANAGING_ARRAYS'
>Managing Arrays
</a></h3>
447 <p>Arrays are created using either the
448 <a href='#cupsArrayNew'
><code>cupsArrayNew
</code></a>,
449 <a href='#cupsArrayNew2'
><code>cupsArrayNew2
</code></a>, or
450 <a href='#cupsArrayNew2'
><code>cupsArrayNew3
</code></a> functions. The
451 first function creates a new array with the specified callback function
452 and user data pointer:
</p>
454 <pre class='example'
>
455 #include
<cups/array.h
>
457 static int compare_func(void *first, void *second, void *user_data);
460 <a href='#cups_array_t'
>cups_array_t
</a> *array =
<a href='#cupsArrayNew'
>cupsArrayNew
</a>(compare_func, user_data);
463 <p>The comparison function (type
464 <a href=
"#cups_arrayfunc_t"><code>cups_arrayfunc_t
</code></a>) is called
465 whenever an element is added to the array and can be
<code>NULL
</code> to
466 create an unsorted array. The function returns -
1 if the first element should
467 come before the second,
0 if the first and second elements should have the same
468 ordering, and
1 if the first element should come after the second.
</p>
470 <p>The
"user_data" pointer is passed to your comparison function. Pass
471 <code>NULL
</code> if you do not need to associate the elements in your array
472 with additional information.
</p>
474 <p>The
<a href='#cupsArrayNew2'
><code>cupsArrayNew2
</code></a> function adds
475 two more arguments to support hashed lookups, which can potentially provide
476 instantaneous (
"O(1)") lookups in your array:
</p>
478 <pre class='example'
>
479 #include
<cups/array.h
>
481 #define HASH_SIZE
512 /* Size of hash table */
483 static int compare_func(void *first, void *second, void *user_data);
484 static int hash_func(void *element, void *user_data);
487 <a href='#cups_array_t'
>cups_array_t
</a> *hash_array =
<a href='#cupsArrayNew2'
>cupsArrayNew2
</a>(compare_func, user_data, hash_func, HASH_SIZE);
490 <p>The hash function (type
491 <a href=
"#cups_ahash_func_t"><code>cups_ahash_func_t
</code></a>) should return a
492 number from
0 to (hash_size-
1) that (hopefully) uniquely identifies the
493 element and is called whenever you look up an element in the array with
494 <a href='#cupsArrayFind'
><code>cupsArrayFind
</code></a>. The hash size is
495 only limited by available memory, but generally should not be larger than
496 16384 to realize any performance improvement.
</p>
498 <p>The
<a href='#cupsArrayNew3'
><code>cupsArrayNew3
</code></a> function adds
499 copy and free callbacks to support basic memory management of elements:
</p>
501 <pre class='example'
>
502 #include
<cups/array.h
>
504 #define HASH_SIZE
512 /* Size of hash table */
506 static int compare_func(void *first, void *second, void *user_data);
507 static void *copy_func(void *element, void *user_data);
508 static void free_func(void *element, void *user_data);
509 static int hash_func(void *element, void *user_data);
512 <a href='#cups_array_t'
>cups_array_t
</a> *array =
<a href='#cupsArrayNew3'
>cupsArrayNew3
</a>(compare_func, user_data, NULL,
0, copy_func, free_func);
514 <a href='#cups_array_t'
>cups_array_t
</a> *hash_array =
<a href='#cupsArrayNew3'
>cupsArrayNew3
</a>(compare_func, user_data, hash_func, HASH_SIZE, copy_func, free_func);
517 <p>Once you have created the array, you add elements using the
518 <a href='#cupsArrayAdd'
><code>cupsArrayAdd
</code></a>
519 <a href='#cupsArrayInsert'
><code>cupsArrayInsert
</code></a> functions.
520 The first function adds an element to the array, adding the new element
521 after any elements that have the same order, while the second inserts the
522 element before others with the same order. For unsorted arrays,
523 <a href='#cupsArrayAdd'
><code>cupsArrayAdd
</code></a> appends the element to
524 the end of the array while
525 <a href='#cupsArrayInsert'
><code>cupsArrayInsert
</code></a> inserts the
526 element at the beginning of the array. For example, the following code
527 creates a sorted array of character strings:
</p>
529 <pre class='example'
>
530 #include
<cups/array.h
>
532 /* Use strcmp() to compare strings - it will ignore the user_data pointer */
533 <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);
535 /* Add four strings to the array */
536 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"One Fish");
537 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Two Fish");
538 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Red Fish");
539 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Blue Fish");
542 <p>Elements are removed using the
543 <a href='#cupsArrayRemove'
><code>cupsArrayRemove
</code></a> function, for
546 <pre class='example'
>
547 #include
<cups/array.h
>
549 /* Use strcmp() to compare strings - it will ignore the user_data pointer */
550 <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);
552 /* Add four strings to the array */
553 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"One Fish");
554 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Two Fish");
555 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Red Fish");
556 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Blue Fish");
558 /* Remove
"Red Fish" */
559 <a href='#cupsArrayRemove'
>cupsArrayRemove
</a>(array,
"Red Fish");
562 <p>Finally, you free the memory used by the array using the
563 <a href='#cupsArrayDelete'
><code>cupsArrayDelete
</code></a> function. All
564 of the memory for the array and hash table (if any) is freed, however
<em>CUPS
565 does not free the elements unless you provide copy and free functions
</em>.
</p>
567 <h3><a name='FINDING_AND_ENUMERATING'
>Finding and Enumerating Elements
</a></h3>
569 <p>CUPS provides several functions to find and enumerate elements in an
570 array. Each one sets or updates a
"current index" into the array, such that
571 future lookups will start where the last one left off:
</p>
574 <dt><a href='#cupsArrayFind'
><code>cupsArrayFind
</code></a></dt>
575 <dd>Returns the first matching element.
</dd>
576 <dt><a href='#cupsArrayFirst'
><code>cupsArrayFirst
</code></a></dt>
577 <dd>Returns the first element in the array.
</dd>
578 <dt><a href='#cupsArrayIndex'
><code>cupsArrayIndex
</code></a></dt>
579 <dd>Returns the Nth element in the array, starting at
0.
</dd>
580 <dt><a href='#cupsArrayLast'
><code>cupsArrayLast
</code></a></dt>
581 <dd>Returns the last element in the array.
</dd>
582 <dt><a href='#cupsArrayNext'
><code>cupsArrayNext
</code></a></dt>
583 <dd>Returns the next element in the array.
</dd>
584 <dt><a href='#cupsArrayPrev'
><code>cupsArrayPrev
</code></a></dt>
585 <dd>Returns the previous element in the array.
</dd>
588 <p>Each of these functions returns
<code>NULL
</code> when there is no
589 corresponding element. For example, a simple
<code>for
</code> loop using the
590 <a href='#cupsArrayFirst'
><code>cupsArrayFirst
</code></a> and
591 <a href='#cupsArrayNext'
><code>cupsArrayNext
</code></a> functions will
592 enumerate all of the strings in our previous example:
</p>
594 <pre class='example'
>
595 #include
<cups/array.h
>
597 /* Use strcmp() to compare strings - it will ignore the user_data pointer */
598 <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);
600 /* Add four strings to the array */
601 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"One Fish");
602 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Two Fish");
603 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Red Fish");
604 <a href='#cupsArrayAdd'
>cupsArrayAdd
</a>(array,
"Blue Fish");
606 /* Show all of the strings in the array */
608 for (s = (char *)
<a href='#cupsArrayFirst'
>cupsArrayFirst
</a>(array); s != NULL; s = (char *)
<a href='#cupsArrayNext'
>cupsArrayNext
</a>(array))
611 <h2 class=
"title"><a name=
"FUNCTIONS">Functions
</a></h2>
612 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayAdd">cupsArrayAdd
</a></h3>
613 <p class=
"description">Add an element to the array.
</p>
615 int cupsArrayAdd (
<br>
616 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
617 void *e
<br>
619 <h4 class=
"parameters">Parameters
</h4>
622 <dd class=
"description">Array
</dd>
624 <dd class=
"description">Element
</dd>
626 <h4 class=
"returnvalue">Return Value
</h4>
627 <p class=
"description">1 on success,
0 on failure
</p>
628 <h4 class=
"discussion">Discussion
</h4>
629 <p class=
"discussion">When adding an element to a sorted array, non-unique elements are
630 appended at the end of the run of identical elements. For unsorted arrays,
631 the element is appended to the end of the array.
634 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayClear">cupsArrayClear
</a></h3>
635 <p class=
"description">Clear the array.
</p>
637 void cupsArrayClear (
<br>
638 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
640 <h4 class=
"parameters">Parameters
</h4>
643 <dd class=
"description">Array
</dd>
645 <h4 class=
"discussion">Discussion
</h4>
646 <p class=
"discussion">This function is equivalent to removing all elements in the array.
647 The caller is responsible for freeing the memory used by the
651 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayCount">cupsArrayCount
</a></h3>
652 <p class=
"description">Get the number of elements in the array.
</p>
654 int cupsArrayCount (
<br>
655 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
657 <h4 class=
"parameters">Parameters
</h4>
660 <dd class=
"description">Array
</dd>
662 <h4 class=
"returnvalue">Return Value
</h4>
663 <p class=
"description">Number of elements
</p>
664 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayCurrent">cupsArrayCurrent
</a></h3>
665 <p class=
"description">Return the current element in the array.
</p>
667 void *cupsArrayCurrent (
<br>
668 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
670 <h4 class=
"parameters">Parameters
</h4>
673 <dd class=
"description">Array
</dd>
675 <h4 class=
"returnvalue">Return Value
</h4>
676 <p class=
"description">Element
</p>
677 <h4 class=
"discussion">Discussion
</h4>
678 <p class=
"discussion">The current element is undefined until you call
<a href=
"#cupsArrayFind"><code>cupsArrayFind
</code></a>,
679 <a href=
"#cupsArrayFirst"><code>cupsArrayFirst
</code></a>, or
<a href=
"#cupsArrayIndex"><code>cupsArrayIndex
</code></a>, or
<a href=
"#cupsArrayLast"><code>cupsArrayLast
</code></a>.
682 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayDelete">cupsArrayDelete
</a></h3>
683 <p class=
"description">Free all memory used by the array.
</p>
685 void cupsArrayDelete (
<br>
686 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
688 <h4 class=
"parameters">Parameters
</h4>
691 <dd class=
"description">Array
</dd>
693 <h4 class=
"discussion">Discussion
</h4>
694 <p class=
"discussion">The caller is responsible for freeing the memory used by the
698 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayDup">cupsArrayDup
</a></h3>
699 <p class=
"description">Duplicate the array.
</p>
701 <a href=
"#cups_array_t">cups_array_t
</a> *cupsArrayDup (
<br>
702 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
704 <h4 class=
"parameters">Parameters
</h4>
707 <dd class=
"description">Array
</dd>
709 <h4 class=
"returnvalue">Return Value
</h4>
710 <p class=
"description">Duplicate array
</p>
711 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayFind">cupsArrayFind
</a></h3>
712 <p class=
"description">Find an element in the array.
</p>
714 void *cupsArrayFind (
<br>
715 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
716 void *e
<br>
718 <h4 class=
"parameters">Parameters
</h4>
721 <dd class=
"description">Array
</dd>
723 <dd class=
"description">Element
</dd>
725 <h4 class=
"returnvalue">Return Value
</h4>
726 <p class=
"description">Element found or
<code>NULL
</code></p>
727 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayFirst">cupsArrayFirst
</a></h3>
728 <p class=
"description">Get the first element in the array.
</p>
730 void *cupsArrayFirst (
<br>
731 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
733 <h4 class=
"parameters">Parameters
</h4>
736 <dd class=
"description">Array
</dd>
738 <h4 class=
"returnvalue">Return Value
</h4>
739 <p class=
"description">First element or
<code>NULL
</code> if the array is empty
</p>
740 <h3 class=
"function"><span class=
"info"> CUPS
1.3/Mac OS X
10.5 </span><a name=
"cupsArrayGetIndex">cupsArrayGetIndex
</a></h3>
741 <p class=
"description">Get the index of the current element.
</p>
743 int cupsArrayGetIndex (
<br>
744 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
746 <h4 class=
"parameters">Parameters
</h4>
749 <dd class=
"description">Array
</dd>
751 <h4 class=
"returnvalue">Return Value
</h4>
752 <p class=
"description">Index of the current element, starting at
0</p>
753 <h4 class=
"discussion">Discussion
</h4>
754 <p class=
"discussion">The current element is undefined until you call
<a href=
"#cupsArrayFind"><code>cupsArrayFind
</code></a>,
755 <a href=
"#cupsArrayFirst"><code>cupsArrayFirst
</code></a>, or
<a href=
"#cupsArrayIndex"><code>cupsArrayIndex
</code></a>, or
<a href=
"#cupsArrayLast"><code>cupsArrayLast
</code></a>.
758 <h3 class=
"function"><span class=
"info"> CUPS
1.3/Mac OS X
10.5 </span><a name=
"cupsArrayGetInsert">cupsArrayGetInsert
</a></h3>
759 <p class=
"description">Get the index of the last inserted element.
</p>
761 int cupsArrayGetInsert (
<br>
762 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
764 <h4 class=
"parameters">Parameters
</h4>
767 <dd class=
"description">Array
</dd>
769 <h4 class=
"returnvalue">Return Value
</h4>
770 <p class=
"description">Index of the last inserted element, starting at
0</p>
771 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayIndex">cupsArrayIndex
</a></h3>
772 <p class=
"description">Get the N-th element in the array.
</p>
774 void *cupsArrayIndex (
<br>
775 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
776 int n
<br>
778 <h4 class=
"parameters">Parameters
</h4>
781 <dd class=
"description">Array
</dd>
783 <dd class=
"description">Index into array, starting at
0</dd>
785 <h4 class=
"returnvalue">Return Value
</h4>
786 <p class=
"description">N-th element or
<code>NULL
</code></p>
787 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayInsert">cupsArrayInsert
</a></h3>
788 <p class=
"description">Insert an element in the array.
</p>
790 int cupsArrayInsert (
<br>
791 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
792 void *e
<br>
794 <h4 class=
"parameters">Parameters
</h4>
797 <dd class=
"description">Array
</dd>
799 <dd class=
"description">Element
</dd>
801 <h4 class=
"returnvalue">Return Value
</h4>
802 <p class=
"description">0 on failure,
1 on success
</p>
803 <h4 class=
"discussion">Discussion
</h4>
804 <p class=
"discussion">When inserting an element in a sorted array, non-unique elements are
805 inserted at the beginning of the run of identical elements. For unsorted
806 arrays, the element is inserted at the beginning of the array.
809 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayLast">cupsArrayLast
</a></h3>
810 <p class=
"description">Get the last element in the array.
</p>
812 void *cupsArrayLast (
<br>
813 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
815 <h4 class=
"parameters">Parameters
</h4>
818 <dd class=
"description">Array
</dd>
820 <h4 class=
"returnvalue">Return Value
</h4>
821 <p class=
"description">Last element or
<code>NULL
</code> if the array is empty
</p>
822 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayNew">cupsArrayNew
</a></h3>
823 <p class=
"description">Create a new array.
</p>
825 <a href=
"#cups_array_t">cups_array_t
</a> *cupsArrayNew (
<br>
826 <a href=
"#cups_array_func_t">cups_array_func_t
</a> f,
<br>
827 void *d
<br>
829 <h4 class=
"parameters">Parameters
</h4>
832 <dd class=
"description">Comparison function or
<code>NULL
</code> for an unsorted array
</dd>
834 <dd class=
"description">User data pointer or
<code>NULL
</code></dd>
836 <h4 class=
"returnvalue">Return Value
</h4>
837 <p class=
"description">Array
</p>
838 <h4 class=
"discussion">Discussion
</h4>
839 <p class=
"discussion">The comparison function (
"f
") is used to create a sorted array. The function
840 receives pointers to two elements and the user data pointer (
"d
") - the user
841 data pointer argument can safely be omitted when not required so functions
842 like
<code>strcmp
</code> can be used for sorted string arrays.
845 <h3 class=
"function"><span class=
"info"> CUPS
1.3/Mac OS X
10.5 </span><a name=
"cupsArrayNew2">cupsArrayNew2
</a></h3>
846 <p class=
"description">Create a new array with hash.
</p>
848 <a href=
"#cups_array_t">cups_array_t
</a> *cupsArrayNew2 (
<br>
849 <a href=
"#cups_array_func_t">cups_array_func_t
</a> f,
<br>
850 void *d,
<br>
851 <a href=
"#cups_ahash_func_t">cups_ahash_func_t
</a> h,
<br>
852 int hsize
<br>
854 <h4 class=
"parameters">Parameters
</h4>
857 <dd class=
"description">Comparison function or
<code>NULL
</code> for an unsorted array
</dd>
859 <dd class=
"description">User data or
<code>NULL
</code></dd>
861 <dd class=
"description">Hash function or
<code>NULL
</code> for unhashed lookups
</dd>
863 <dd class=
"description">Hash size (
>=
0)
</dd>
865 <h4 class=
"returnvalue">Return Value
</h4>
866 <p class=
"description">Array
</p>
867 <h4 class=
"discussion">Discussion
</h4>
868 <p class=
"discussion">The comparison function (
"f
") is used to create a sorted array. The function
869 receives pointers to two elements and the user data pointer (
"d
") - the user
870 data pointer argument can safely be omitted when not required so functions
871 like
<code>strcmp
</code> can be used for sorted string arrays.
<br>
873 The hash function (
"h
") is used to implement cached lookups with the
874 specified hash size (
"hsize
").
877 <h3 class=
"function"><span class=
"info"> CUPS
1.5 </span><a name=
"cupsArrayNew3">cupsArrayNew3
</a></h3>
878 <p class=
"description">Create a new array with hash and/or free function.
</p>
880 <a href=
"#cups_array_t">cups_array_t
</a> *cupsArrayNew3 (
<br>
881 <a href=
"#cups_array_func_t">cups_array_func_t
</a> f,
<br>
882 void *d,
<br>
883 <a href=
"#cups_ahash_func_t">cups_ahash_func_t
</a> h,
<br>
884 int hsize,
<br>
885 <a href=
"#cups_acopy_func_t">cups_acopy_func_t
</a> cf,
<br>
886 <a href=
"#cups_afree_func_t">cups_afree_func_t
</a> ff
<br>
888 <h4 class=
"parameters">Parameters
</h4>
891 <dd class=
"description">Comparison function or
<code>NULL
</code> for an unsorted array
</dd>
893 <dd class=
"description">User data or
<code>NULL
</code></dd>
895 <dd class=
"description">Hash function or
<code>NULL
</code> for unhashed lookups
</dd>
897 <dd class=
"description">Hash size (
>=
0)
</dd>
899 <dd class=
"description">Copy function
</dd>
901 <dd class=
"description">Free function
</dd>
903 <h4 class=
"returnvalue">Return Value
</h4>
904 <p class=
"description">Array
</p>
905 <h4 class=
"discussion">Discussion
</h4>
906 <p class=
"discussion">The comparison function (
"f
") is used to create a sorted array. The function
907 receives pointers to two elements and the user data pointer (
"d
") - the user
908 data pointer argument can safely be omitted when not required so functions
909 like
<code>strcmp
</code> can be used for sorted string arrays.
<br>
911 The hash function (
"h
") is used to implement cached lookups with the
912 specified hash size (
"hsize
").
<br>
914 The copy function (
"cf
") is used to automatically copy/retain elements when
915 added or the array is copied.
<br>
917 The free function (
"cf
") is used to automatically free/release elements when
918 removed or the array is deleted.
921 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayNext">cupsArrayNext
</a></h3>
922 <p class=
"description">Get the next element in the array.
</p>
924 void *cupsArrayNext (
<br>
925 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
927 <h4 class=
"parameters">Parameters
</h4>
930 <dd class=
"description">Array
</dd>
932 <h4 class=
"returnvalue">Return Value
</h4>
933 <p class=
"description">Next element or
<code>NULL
</code></p>
934 <h4 class=
"discussion">Discussion
</h4>
935 <p class=
"discussion">This function is equivalent to
"cupsArrayIndex(a, cupsArrayGetIndex(a) +
1)
".
<br>
937 The next 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.
942 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayPrev">cupsArrayPrev
</a></h3>
943 <p class=
"description">Get the previous element in the array.
</p>
945 void *cupsArrayPrev (
<br>
946 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
948 <h4 class=
"parameters">Parameters
</h4>
951 <dd class=
"description">Array
</dd>
953 <h4 class=
"returnvalue">Return Value
</h4>
954 <p class=
"description">Previous element or
<code>NULL
</code></p>
955 <h4 class=
"discussion">Discussion
</h4>
956 <p class=
"discussion">This function is equivalent to
"cupsArrayIndex(a, cupsArrayGetIndex(a) -
1)
".
<br>
958 The previous element is undefined until you call
<a href=
"#cupsArrayFind"><code>cupsArrayFind
</code></a>,
959 <a href=
"#cupsArrayFirst"><code>cupsArrayFirst
</code></a>, or
<a href=
"#cupsArrayIndex"><code>cupsArrayIndex
</code></a>, or
<a href=
"#cupsArrayLast"><code>cupsArrayLast
</code></a>
960 to set the current element.
963 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayRemove">cupsArrayRemove
</a></h3>
964 <p class=
"description">Remove an element from the array.
</p>
966 int cupsArrayRemove (
<br>
967 <a href=
"#cups_array_t">cups_array_t
</a> *a,
<br>
968 void *e
<br>
970 <h4 class=
"parameters">Parameters
</h4>
973 <dd class=
"description">Array
</dd>
975 <dd class=
"description">Element
</dd>
977 <h4 class=
"returnvalue">Return Value
</h4>
978 <p class=
"description">1 on success,
0 on failure
</p>
979 <h4 class=
"discussion">Discussion
</h4>
980 <p class=
"discussion">If more than one element matches
"e
", only the first matching element is
983 The caller is responsible for freeing the memory used by the
987 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayRestore">cupsArrayRestore
</a></h3>
988 <p class=
"description">Reset the current element to the last
<a href=
"#cupsArraySave"><code>cupsArraySave
</code></a>.
</p>
990 void *cupsArrayRestore (
<br>
991 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
993 <h4 class=
"parameters">Parameters
</h4>
996 <dd class=
"description">Array
</dd>
998 <h4 class=
"returnvalue">Return Value
</h4>
999 <p class=
"description">New current element
</p>
1000 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArraySave">cupsArraySave
</a></h3>
1001 <p class=
"description">Mark the current element for a later
<a href=
"#cupsArrayRestore"><code>cupsArrayRestore
</code></a>.
</p>
1003 int cupsArraySave (
<br>
1004 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
1006 <h4 class=
"parameters">Parameters
</h4>
1009 <dd class=
"description">Array
</dd>
1011 <h4 class=
"returnvalue">Return Value
</h4>
1012 <p class=
"description">1 on success,
0 on failure
</p>
1013 <h4 class=
"discussion">Discussion
</h4>
1014 <p class=
"discussion">The current element is undefined until you call
<a href=
"#cupsArrayFind"><code>cupsArrayFind
</code></a>,
1015 <a href=
"#cupsArrayFirst"><code>cupsArrayFirst
</code></a>, or
<a href=
"#cupsArrayIndex"><code>cupsArrayIndex
</code></a>, or
<a href=
"#cupsArrayLast"><code>cupsArrayLast
</code></a>
1016 to set the current element.
<br>
1018 The save/restore stack is guaranteed to be at least
32 elements deep.
1021 <h3 class=
"function"><span class=
"info"> CUPS
1.2/Mac OS X
10.5 </span><a name=
"cupsArrayUserData">cupsArrayUserData
</a></h3>
1022 <p class=
"description">Return the user data for an array.
</p>
1024 void *cupsArrayUserData (
<br>
1025 <a href=
"#cups_array_t">cups_array_t
</a> *a
<br>
1027 <h4 class=
"parameters">Parameters
</h4>
1030 <dd class=
"description">Array
</dd>
1032 <h4 class=
"returnvalue">Return Value
</h4>
1033 <p class=
"description">User data
</p>
1034 <h2 class=
"title"><a name=
"TYPES">Data Types
</a></h2>
1035 <h3 class=
"typedef"><a name=
"cups_acopy_func_t">cups_acopy_func_t
</a></h3>
1036 <p class=
"description">Array element copy function
</p>
1038 typedef void *(*cups_acopy_func_t)(void *element, void *data);
1040 <h3 class=
"typedef"><a name=
"cups_afree_func_t">cups_afree_func_t
</a></h3>
1041 <p class=
"description">Array element free function
</p>
1043 typedef void (*cups_afree_func_t)(void *element, void *data);
1045 <h3 class=
"typedef"><a name=
"cups_ahash_func_t">cups_ahash_func_t
</a></h3>
1046 <p class=
"description">Array hash function
</p>
1048 typedef int (*cups_ahash_func_t)(void *element, void *data);
1050 <h3 class=
"typedef"><a name=
"cups_array_func_t">cups_array_func_t
</a></h3>
1051 <p class=
"description">Array comparison function
</p>
1053 typedef int (*cups_array_func_t)(void *first, void *second, void *data);
1055 <h3 class=
"typedef"><a name=
"cups_array_t">cups_array_t
</a></h3>
1056 <p class=
"description">CUPS array type
</p>
1058 typedef struct _cups_array_s cups_array_t;