doc/help/api-array.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!-- SECTION: Programming -->
   4 <head>
   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"><!--
  10 BODY {
  11   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  12 }
  13
  14 H1, H2, H3, H4, H5, H6, P, TD, TH {
  15   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  16 }
  17
  18 KBD {
  19   font-family: monaco, courier, monospace;
  20   font-weight: bold;
  21 }
  22
  23 PRE {
  24   font-family: monaco, courier, monospace;
  25 }
  26
  27 PRE.command {
  28   border: dotted thin #7f7f7f;
  29   margin-left: 36pt;
  30   padding: 10px;
  31 }
  32
  33 P.compact {
  34   margin: 0;
  35 }
  36
  37 P.example {
  38   font-style: italic;
  39   margin-left: 36pt;
  40 }
  41
  42 DL.man DD {
  43   margin-left: 5em;
  44 }
  45
  46 DL.man DT {
  47   margin-left: 0;
  48 }
  49
  50 PRE.man {
  51   margin: 0;
  52 }
  53
  54 PRE.example {
  55   background: #eeeeee;
  56   border: dotted thin #999999;
  57   margin-left: 36pt;
  58   padding: 10pt;
  59 }
  60
  61 PRE.command EM, PRE.example EM {
  62   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  63 }
  64
  65 P.command {
  66   font-family: monaco, courier, monospace;
  67   margin-left: 36pt;
  68 }
  69
  70 P.formula {
  71   font-style: italic;
  72   margin-left: 36pt;
  73 }
  74
  75 BLOCKQUOTE {
  76   background: #eeeeee;
  77   border: solid thin #999999;
  78   padding: 10pt;
  79 }
  80
  81 A IMG {
  82   border: none;
  83 }
  84
  85 A:link:hover IMG {
  86   background: #f0f0f0;
  87   border-radius: 10px;
  88   -moz-border-radius: 10px;
  89 }
  90
  91 A:link, A:visited {
  92   font-weight: inherit;
  93   text-decoration: none;
  94 }
  95
  96 A:link:hover, A:visited:hover, A:active {
  97   text-decoration: underline;
  98 }
  99
 100 SUB, SUP {
 101   font-size: 50%;
 102 }
 103
 104 TR.data, TD.data, TR.data TD {
 105   margin-top: 10pt;
 106   padding: 5pt;
 107   border-bottom: solid 1pt #999999;
 108 }
 109
 110 TR.data TH {
 111   border-bottom: solid 1pt #999999;
 112   padding-top: 10pt;
 113   padding-left: 5pt;
 114   text-align: left;
 115 }
 116
 117 DIV.table TABLE {
 118   border: solid thin #999999;
 119   border-collapse: collapse;
 120   border-spacing: 0;
 121   margin-left: auto;
 122   margin-right: auto;
 123 }
 124
 125 DIV.table CAPTION {
 126   caption-side: top;
 127   font-size: 120%;
 128   font-style: italic;
 129   font-weight: bold;
 130   margin-left: auto;
 131   margin-right: auto;
 132 }
 133
 134 DIV.table TABLE TD {
 135   border: solid thin #cccccc;
 136   padding-top: 5pt;
 137 }
 138
 139 DIV.table TABLE TH {
 140   background: #cccccc;
 141   border: none;
 142   border-bottom: solid thin #999999;
 143 }
 144
 145 DIV.figure TABLE {
 146   margin-left: auto;
 147   margin-right: auto;
 148 }
 149
 150 DIV.figure CAPTION {
 151   caption-side: bottom;
 152   font-size: 120%;
 153   font-style: italic;
 154   font-weight: bold;
 155   margin-left: auto;
 156   margin-right: auto;
 157 }
 158
 159 TH.label {
 160   text-align: right;
 161   vertical-align: top;
 162 }
 163
 164 TH.sublabel {
 165   text-align: right;
 166   font-weight: normal;
 167 }
 168
 169 HR {
 170   border: solid thin;
 171 }
 172
 173 SPAN.info {
 174   background: black;
 175   border: thin solid black;
 176   color: white;
 177   font-size: 80%;
 178   font-style: italic;
 179   font-weight: bold;
 180   white-space: nowrap;
 181 }
 182
 183 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
 184   float: right;
 185   font-size: 100%;
 186 }
 187
 188 H1.title {
 189 }
 190
 191 H2.title, H3.title {
 192   border-bottom: solid 2pt #000000;
 193 }
 194
 195 DIV.indent, TABLE.indent {
 196   margin-top: 2em;
 197   margin-left: auto;
 198   margin-right: auto;
 199   width: 90%;
 200 }
 201
 202 TABLE.indent {
 203   border-collapse: collapse;
 204 }
 205
 206 TABLE.indent TD, TABLE.indent TH {
 207   padding: 0;
 208 }
 209
 210 TABLE.list {
 211   border-collapse: collapse;
 212   margin-left: auto;
 213   margin-right: auto;
 214   width: 90%;
 215 }
 216
 217 TABLE.list TH {
 218   background: white;
 219   border-bottom: solid thin #cccccc;
 220   color: #444444;
 221   padding-top: 10pt;
 222   padding-left: 5pt;
 223   text-align: left;
 224   vertical-align: bottom;
 225   white-space: nowrap;
 226 }
 227
 228 TABLE.list TH A {
 229   color: #4444cc;
 230 }
 231
 232 TABLE.list TD {
 233   border-bottom: solid thin #eeeeee;
 234   padding-top: 5pt;
 235   padding-left: 5pt;
 236 }
 237
 238 TABLE.list TR:nth-child(even) {
 239   background: #f8f8f8;
 240 }
 241
 242 TABLE.list TR:nth-child(odd) {
 243   background: #f4f4f4;
 244 }
 245
 246 DT {
 247   margin-left: 36pt;
 248   margin-top: 12pt;
 249 }
 250
 251 DD {
 252   margin-left: 54pt;
 253 }
 254
 255 DL.category DT {
 256   font-weight: bold;
 257 }
 258
 259 P.summary {
 260   margin-left: 36pt;
 261   font-family: monaco, courier, monospace;
 262 }
 263
 264 DIV.summary TABLE {
 265   border: solid thin #999999;
 266   border-collapse: collapse;
 267   border-spacing: 0;
 268   margin: 10px;
 269 }
 270
 271 DIV.summary TABLE TD, DIV.summary TABLE TH {
 272   border: solid thin #999999;
 273   padding: 5px;
 274   text-align: left;
 275   vertical-align: top;
 276 }
 277
 278 DIV.summary TABLE THEAD TH {
 279   background: #eeeeee;
 280 }
 281
 282 /* API documentation styles... */
 283 div.body h1 {
 284   margin: 0;
 285 }
 286 div.body h2 {
 287   margin-top: 1.5em;
 288 }
 289 div.body h3, div.body h4, div.body h5 {
 290   margin-bottom: 0.5em;
 291   margin-top: 1.5em;
 292 }
 293 .class, .enumeration, .function, .struct, .typedef, .union {
 294   border-bottom: solid thin #999999;
 295   margin-bottom: 0;
 296   margin-top: 2em;
 297 }
 298 .description {
 299   margin-top: 0.5em;
 300 }
 301 code, p.code, pre, ul.code li {
 302   font-family: monaco, courier, monospace;
 303   font-size: 90%;
 304 }
 305 ul.code, ul.contents, ul.subcontents {
 306   list-style-type: none;
 307   margin: 0;
 308   padding-left: 0;
 309 }
 310 ul.code li {
 311   margin: 0;
 312 }
 313 ul.contents > li {
 314   margin-top: 1em;
 315 }
 316 ul.contents li ul.code, ul.contents li ul.subcontents {
 317   padding-left: 2em;
 318 }
 319 div.body dl {
 320   margin-left: 0;
 321   margin-top: 0;
 322 }
 323 div.body dt {
 324   font-style: italic;
 325   margin-left: 0;
 326   margin-top: 0;
 327 }
 328 div.body dd {
 329   margin-bottom: 0.5em;
 330 }
 331
 332 /* This is just for the HTML files generated with the framedhelp target */
 333 div.contents {
 334   background: #e8e8e8;
 335   border: solid thin black;
 336   padding: 10px;
 337 }
 338 div.contents h1 {
 339   font-size: 110%;
 340 }
 341 div.contents h2 {
 342   font-size: 100%;
 343 }
 344 div.contents ul.contents {
 345   font-size: 80%;
 346 }
 347 div.contents ul.subcontents li {
 348   margin-left: 1em;
 349   text-indent: -1em;
 350 }
 351 --></style>
 352 </head>
 353 <body>
 354 <div class='body'>
 355 <!--
 356   "$Id: api-array.header 7266 2008-01-29 02:15:29Z mike $"
 357
 358   Array API header for CUPS.
 359
 360   Copyright 2008-2011 by Apple Inc.
 361
 362   These coded instructions, statements, and computer programs are the
 363   property of Apple Inc. and are protected by Federal copyright
 364   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 365   which should have been included with this file.  If this file is
 366   file is missing or damaged, see the license at "http://www.cups.org/".
 367 -->
 368
 369 <h1 class='title'>Array API</h1>
 370
 371 <div class='summary'><table summary='General Information'>
 372 <thead>
 373 <tr>
 374         <th>Header</th>
 375         <th>cups/array.h</th>
 376 </tr>
 377 </thead>
 378 <tbody>
 379 <tr>
 380         <th>Library</th>
 381         <td>-lcups</td>
 382 </tr>
 383 <tr>
 384         <th>See Also</th>
 385         <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a></td>
 386 </tr>
 387 </tbody>
 388 </table></div>
 389 <h2 class="title">Contents</h2>
 390 <ul class="contents">
 391 <li><a href="#OVERVIEW">Overview</a><ul class="subcontents">
 392         <li><a href="#MANAGING_ARRAYS">Managing Arrays</a></li>
 393         <li><a href="#FINDING_AND_ENUMERATING">Finding and Enumerating Elements</a></li>
 394 </ul></li>
 395 <li><a href="#FUNCTIONS">Functions</a><ul class="code">
 396         <li><a href="#cupsArrayAdd" title="Add an element to the array.">cupsArrayAdd</a></li>
 397         <li><a href="#cupsArrayClear" title="Clear the array.">cupsArrayClear</a></li>
 398         <li><a href="#cupsArrayCount" title="Get the number of elements in the array.">cupsArrayCount</a></li>
 399         <li><a href="#cupsArrayCurrent" title="Return the current element in the array.">cupsArrayCurrent</a></li>
 400         <li><a href="#cupsArrayDelete" title="Free all memory used by the array.">cupsArrayDelete</a></li>
 401         <li><a href="#cupsArrayDup" title="Duplicate the array.">cupsArrayDup</a></li>
 402         <li><a href="#cupsArrayFind" title="Find an element in the array.">cupsArrayFind</a></li>
 403         <li><a href="#cupsArrayFirst" title="Get the first element in the array.">cupsArrayFirst</a></li>
 404         <li><a href="#cupsArrayGetIndex" title="Get the index of the current element.">cupsArrayGetIndex</a></li>
 405         <li><a href="#cupsArrayGetInsert" title="Get the index of the last inserted element.">cupsArrayGetInsert</a></li>
 406         <li><a href="#cupsArrayIndex" title="Get the N-th element in the array.">cupsArrayIndex</a></li>
 407         <li><a href="#cupsArrayInsert" title="Insert an element in the array.">cupsArrayInsert</a></li>
 408         <li><a href="#cupsArrayLast" title="Get the last element in the array.">cupsArrayLast</a></li>
 409         <li><a href="#cupsArrayNew" title="Create a new array.">cupsArrayNew</a></li>
 410         <li><a href="#cupsArrayNew2" title="Create a new array with hash.">cupsArrayNew2</a></li>
 411         <li><a href="#cupsArrayNew3" title="Create a new array with hash and/or free function.">cupsArrayNew3</a></li>
 412         <li><a href="#cupsArrayNext" title="Get the next element in the array.">cupsArrayNext</a></li>
 413         <li><a href="#cupsArrayPrev" title="Get the previous element in the array.">cupsArrayPrev</a></li>
 414         <li><a href="#cupsArrayRemove" title="Remove an element from the array.">cupsArrayRemove</a></li>
 415         <li><a href="#cupsArrayRestore" title="Reset the current element to the last cupsArraySave.">cupsArrayRestore</a></li>
 416         <li><a href="#cupsArraySave" title="Mark the current element for a later cupsArrayRestore.">cupsArraySave</a></li>
 417         <li><a href="#cupsArrayUserData" title="Return the user data for an array.">cupsArrayUserData</a></li>
 418 </ul></li>
 419 <li><a href="#TYPES">Data Types</a><ul class="code">
 420         <li><a href="#cups_acopy_func_t" title="Array element copy function">cups_acopy_func_t</a></li>
 421         <li><a href="#cups_afree_func_t" title="Array element free function">cups_afree_func_t</a></li>
 422         <li><a href="#cups_ahash_func_t" title="Array hash function">cups_ahash_func_t</a></li>
 423         <li><a href="#cups_array_func_t" title="Array comparison function">cups_array_func_t</a></li>
 424         <li><a href="#cups_array_t" title="CUPS array type">cups_array_t</a></li>
 425 </ul></li>
 426 </ul>
 427 <!--
 428   "$Id: api-array.shtml 7616 2008-05-28 00:34:13Z mike $"
 429
 430   Array API introduction for CUPS.
 431
 432   Copyright 2007-2011 by Apple Inc.
 433   Copyright 1997-2006 by Easy Software Products, all rights reserved.
 434
 435   These coded instructions, statements, and computer programs are the
 436   property of Apple Inc. and are protected by Federal copyright
 437   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 438   which should have been included with this file.  If this file is
 439   file is missing or damaged, see the license at "http://www.cups.org/".
 440 -->
 441
 442 <h2 class='title'><a name='OVERVIEW'>Overview</a></h2>
 443
 444 <p>The CUPS array API provides a high-performance generic array container.
 445 The contents of the array container can be sorted and the container itself is
 446 designed for optimal speed and memory usage under a wide variety of conditions.
 447 Sorted arrays use a binary search algorithm from the last found or inserted
 448 element to quickly find matching elements in the array. Arrays created with the
 449 optional hash function can often find elements with a single lookup. The
 450 <a href='#cups_array_t'><code>cups_array_t</code></a> type is used when
 451 referring to a CUPS array.</p>
 452
 453 <p>The CUPS scheduler (<tt>cupsd</tt>) and many of the CUPS API
 454 functions use the array API to efficiently manage large lists of
 455 data.</p>
 456
 457 <h3><a name='MANAGING_ARRAYS'>Managing Arrays</a></h3>
 458
 459 <p>Arrays are created using either the
 460 <a href='#cupsArrayNew'><code>cupsArrayNew</code></a>,
 461 <a href='#cupsArrayNew2'><code>cupsArrayNew2</code></a>, or
 462 <a href='#cupsArrayNew2'><code>cupsArrayNew3</code></a> functions. The
 463 first function creates a new array with the specified callback function
 464 and user data pointer:</p>
 465
 466 <pre class='example'>
 467 #include &lt;cups/array.h&gt;
 468
 469 static int compare_func(void *first, void *second, void *user_data);
 470
 471 void *user_data;
 472 <a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew'>cupsArrayNew</a>(compare_func, user_data);
 473 </pre>
 474
 475 <p>The comparison function (type
 476 <a href="#cups_arrayfunc_t"><code>cups_arrayfunc_t</code></a>) is called
 477 whenever an element is added to the array and can be <code>NULL</code> to
 478 create an unsorted array. The function returns -1 if the first element should
 479 come before the second, 0 if the first and second elements should have the same
 480 ordering, and 1 if the first element should come after the second.</p>
 481
 482 <p>The "user_data" pointer is passed to your comparison function. Pass
 483 <code>NULL</code> if you do not need to associate the elements in your array
 484 with additional information.</p>
 485
 486 <p>The <a href='#cupsArrayNew2'><code>cupsArrayNew2</code></a> function adds
 487 two more arguments to support hashed lookups, which can potentially provide
 488 instantaneous ("O(1)") lookups in your array:</p>
 489
 490 <pre class='example'>
 491 #include &lt;cups/array.h&gt;
 492
 493 #define HASH_SIZE 512 /* Size of hash table */
 494
 495 static int compare_func(void *first, void *second, void *user_data);
 496 static int hash_func(void *element, void *user_data);
 497
 498 void *user_data;
 499 <a href='#cups_array_t'>cups_array_t</a> *hash_array = <a href='#cupsArrayNew2'>cupsArrayNew2</a>(compare_func, user_data, hash_func, HASH_SIZE);
 500 </pre>
 501
 502 <p>The hash function (type
 503 <a href="#cups_ahash_func_t"><code>cups_ahash_func_t</code></a>) should return a
 504 number from 0 to (hash_size-1) that (hopefully) uniquely identifies the
 505 element and is called whenever you look up an element in the array with
 506 <a href='#cupsArrayFind'><code>cupsArrayFind</code></a>. The hash size is
 507 only limited by available memory, but generally should not be larger than
 508 16384 to realize any performance improvement.</p>
 509
 510 <p>The <a href='#cupsArrayNew3'><code>cupsArrayNew3</code></a> function adds
 511 copy and free callbacks to support basic memory management of elements:</p>
 512
 513 <pre class='example'>
 514 #include &lt;cups/array.h&gt;
 515
 516 #define HASH_SIZE 512 /* Size of hash table */
 517
 518 static int compare_func(void *first, void *second, void *user_data);
 519 static void *copy_func(void *element, void *user_data);
 520 static void free_func(void *element, void *user_data);
 521 static int hash_func(void *element, void *user_data);
 522
 523 void *user_data;
 524 <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);
 525
 526 <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);
 527 </pre>
 528
 529 <p>Once you have created the array, you add elements using the
 530 <a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a>
 531 <a href='#cupsArrayInsert'><code>cupsArrayInsert</code></a> functions.
 532 The first function adds an element to the array, adding the new element
 533 after any elements that have the same order, while the second inserts the
 534 element before others with the same order. For unsorted arrays,
 535 <a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a> appends the element to
 536 the end of the array while
 537 <a href='#cupsArrayInsert'><code>cupsArrayInsert</code></a> inserts the
 538 element at the beginning of the array. For example, the following code
 539 creates a sorted array of character strings:</p>
 540
 541 <pre class='example'>
 542 #include &lt;cups/array.h&gt;
 543
 544 /* Use strcmp() to compare strings - it will ignore the user_data pointer */
 545 <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);
 546
 547 /* Add four strings to the array */
 548 <a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "One Fish");
 549 <a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Two Fish");
 550 <a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Red Fish");
 551 <a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Blue Fish");
 552 </pre>
 553
 554 <p>Elements are removed using the
 555 <a href='#cupsArrayRemove'><code>cupsArrayRemove</code></a> function, for
 556 example:</p>
 557
 558 <pre class='example'>
 559 #include &lt;cups/array.h&gt;
 560
 561 /* Use strcmp() to compare strings - it will ignore the user_data pointer */
 562 <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);
 563
 564 /* Add four strings to the array */
 565 <a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "One Fish");
 566 <a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Two Fish");
 567 <a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Red Fish");
 568 <a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Blue Fish");
 569
 570 /* Remove "Red Fish" */
 571 <a href='#cupsArrayRemove'>cupsArrayRemove</a>(array, "Red Fish");
 572 </pre>
 573
 574 <p>Finally, you free the memory used by the array using the
 575 <a href='#cupsArrayDelete'><code>cupsArrayDelete</code></a> function. All
 576 of the memory for the array and hash table (if any) is freed, however <em>CUPS
 577 does not free the elements unless you provide copy and free functions</em>.</p>
 578
 579 <h3><a name='FINDING_AND_ENUMERATING'>Finding and Enumerating Elements</a></h3>
 580
 581 <p>CUPS provides several functions to find and enumerate elements in an
 582 array. Each one sets or updates a "current index" into the array, such that
 583 future lookups will start where the last one left off:</p>
 584
 585 <dl>
 586         <dt><a href='#cupsArrayFind'><code>cupsArrayFind</code></a></dt>
 587         <dd>Returns the first matching element.</dd>
 588         <dt><a href='#cupsArrayFirst'><code>cupsArrayFirst</code></a></dt>
 589         <dd>Returns the first element in the array.</dd>
 590         <dt><a href='#cupsArrayIndex'><code>cupsArrayIndex</code></a></dt>
 591         <dd>Returns the Nth element in the array, starting at 0.</dd>
 592         <dt><a href='#cupsArrayLast'><code>cupsArrayLast</code></a></dt>
 593         <dd>Returns the last element in the array.</dd>
 594         <dt><a href='#cupsArrayNext'><code>cupsArrayNext</code></a></dt>
 595         <dd>Returns the next element in the array.</dd>
 596         <dt><a href='#cupsArrayPrev'><code>cupsArrayPrev</code></a></dt>
 597         <dd>Returns the previous element in the array.</dd>
 598 </dl>
 599
 600 <p>Each of these functions returns <code>NULL</code> when there is no
 601 corresponding element.  For example, a simple <code>for</code> loop using the
 602 <a href='#cupsArrayFirst'><code>cupsArrayFirst</code></a> and
 603 <a href='#cupsArrayNext'><code>cupsArrayNext</code></a> functions will
 604 enumerate all of the strings in our previous example:</p>
 605
 606 <pre class='example'>
 607 #include &lt;cups/array.h&gt;
 608
 609 /* Use strcmp() to compare strings - it will ignore the user_data pointer */
 610 <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);
 611
 612 /* Add four strings to the array */
 613 <a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "One Fish");
 614 <a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Two Fish");
 615 <a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Red Fish");
 616 <a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Blue Fish");
 617
 618 /* Show all of the strings in the array */
 619 char *s;
 620 for (s = (char *)<a href='#cupsArrayFirst'>cupsArrayFirst</a>(array); s != NULL; s = (char *)<a href='#cupsArrayNext'>cupsArrayNext</a>(array))
 621   puts(s);
 622 </pre>
 623 <h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
 624 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayAdd">cupsArrayAdd</a></h3>
 625 <p class="description">Add an element to the array.</p>
 626 <p class="code">
 627 int cupsArrayAdd (<br>
 628 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a,<br>
 629 &nbsp;&nbsp;&nbsp;&nbsp;void *e<br>
 630 );</p>
 631 <h4 class="parameters">Parameters</h4>
 632 <dl>
 633 <dt>a</dt>
 634 <dd class="description">Array</dd>
 635 <dt>e</dt>
 636 <dd class="description">Element</dd>
 637 </dl>
 638 <h4 class="returnvalue">Return Value</h4>
 639 <p class="description">1 on success, 0 on failure</p>
 640 <h4 class="discussion">Discussion</h4>
 641 <p class="discussion">When adding an element to a sorted array, non-unique elements are
 642 appended at the end of the run of identical elements.  For unsorted arrays,
 643 the element is appended to the end of the array.
 644
 645 </p>
 646 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayClear">cupsArrayClear</a></h3>
 647 <p class="description">Clear the array.</p>
 648 <p class="code">
 649 void cupsArrayClear (<br>
 650 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
 651 );</p>
 652 <h4 class="parameters">Parameters</h4>
 653 <dl>
 654 <dt>a</dt>
 655 <dd class="description">Array</dd>
 656 </dl>
 657 <h4 class="discussion">Discussion</h4>
 658 <p class="discussion">This function is equivalent to removing all elements in the array.
 659 The caller is responsible for freeing the memory used by the
 660 elements themselves.
 661
 662 </p>
 663 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayCount">cupsArrayCount</a></h3>
 664 <p class="description">Get the number of elements in the array.</p>
 665 <p class="code">
 666 int cupsArrayCount (<br>
 667 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
 668 );</p>
 669 <h4 class="parameters">Parameters</h4>
 670 <dl>
 671 <dt>a</dt>
 672 <dd class="description">Array</dd>
 673 </dl>
 674 <h4 class="returnvalue">Return Value</h4>
 675 <p class="description">Number of elements</p>
 676 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayCurrent">cupsArrayCurrent</a></h3>
 677 <p class="description">Return the current element in the array.</p>
 678 <p class="code">
 679 void *cupsArrayCurrent (<br>
 680 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
 681 );</p>
 682 <h4 class="parameters">Parameters</h4>
 683 <dl>
 684 <dt>a</dt>
 685 <dd class="description">Array</dd>
 686 </dl>
 687 <h4 class="returnvalue">Return Value</h4>
 688 <p class="description">Element</p>
 689 <h4 class="discussion">Discussion</h4>
 690 <p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
 691 <a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>.
 692
 693 </p>
 694 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayDelete">cupsArrayDelete</a></h3>
 695 <p class="description">Free all memory used by the array.</p>
 696 <p class="code">
 697 void cupsArrayDelete (<br>
 698 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
 699 );</p>
 700 <h4 class="parameters">Parameters</h4>
 701 <dl>
 702 <dt>a</dt>
 703 <dd class="description">Array</dd>
 704 </dl>
 705 <h4 class="discussion">Discussion</h4>
 706 <p class="discussion">The caller is responsible for freeing the memory used by the
 707 elements themselves.
 708
 709 </p>
 710 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayDup">cupsArrayDup</a></h3>
 711 <p class="description">Duplicate the array.</p>
 712 <p class="code">
 713 <a href="#cups_array_t">cups_array_t</a> *cupsArrayDup (<br>
 714 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
 715 );</p>
 716 <h4 class="parameters">Parameters</h4>
 717 <dl>
 718 <dt>a</dt>
 719 <dd class="description">Array</dd>
 720 </dl>
 721 <h4 class="returnvalue">Return Value</h4>
 722 <p class="description">Duplicate array</p>
 723 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayFind">cupsArrayFind</a></h3>
 724 <p class="description">Find an element in the array.</p>
 725 <p class="code">
 726 void *cupsArrayFind (<br>
 727 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a,<br>
 728 &nbsp;&nbsp;&nbsp;&nbsp;void *e<br>
 729 );</p>
 730 <h4 class="parameters">Parameters</h4>
 731 <dl>
 732 <dt>a</dt>
 733 <dd class="description">Array</dd>
 734 <dt>e</dt>
 735 <dd class="description">Element</dd>
 736 </dl>
 737 <h4 class="returnvalue">Return Value</h4>
 738 <p class="description">Element found or <code>NULL</code></p>
 739 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayFirst">cupsArrayFirst</a></h3>
 740 <p class="description">Get the first element in the array.</p>
 741 <p class="code">
 742 void *cupsArrayFirst (<br>
 743 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
 744 );</p>
 745 <h4 class="parameters">Parameters</h4>
 746 <dl>
 747 <dt>a</dt>
 748 <dd class="description">Array</dd>
 749 </dl>
 750 <h4 class="returnvalue">Return Value</h4>
 751 <p class="description">First element or <code>NULL</code> if the array is empty</p>
 752 <h3 class="function"><span class="info">&nbsp;CUPS 1.3/OS X 10.5&nbsp;</span><a name="cupsArrayGetIndex">cupsArrayGetIndex</a></h3>
 753 <p class="description">Get the index of the current element.</p>
 754 <p class="code">
 755 int cupsArrayGetIndex (<br>
 756 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
 757 );</p>
 758 <h4 class="parameters">Parameters</h4>
 759 <dl>
 760 <dt>a</dt>
 761 <dd class="description">Array</dd>
 762 </dl>
 763 <h4 class="returnvalue">Return Value</h4>
 764 <p class="description">Index of the current element, starting at 0</p>
 765 <h4 class="discussion">Discussion</h4>
 766 <p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
 767 <a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>.
 768
 769 </p>
 770 <h3 class="function"><span class="info">&nbsp;CUPS 1.3/OS X 10.5&nbsp;</span><a name="cupsArrayGetInsert">cupsArrayGetInsert</a></h3>
 771 <p class="description">Get the index of the last inserted element.</p>
 772 <p class="code">
 773 int cupsArrayGetInsert (<br>
 774 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
 775 );</p>
 776 <h4 class="parameters">Parameters</h4>
 777 <dl>
 778 <dt>a</dt>
 779 <dd class="description">Array</dd>
 780 </dl>
 781 <h4 class="returnvalue">Return Value</h4>
 782 <p class="description">Index of the last inserted element, starting at 0</p>
 783 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayIndex">cupsArrayIndex</a></h3>
 784 <p class="description">Get the N-th element in the array.</p>
 785 <p class="code">
 786 void *cupsArrayIndex (<br>
 787 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a,<br>
 788 &nbsp;&nbsp;&nbsp;&nbsp;int n<br>
 789 );</p>
 790 <h4 class="parameters">Parameters</h4>
 791 <dl>
 792 <dt>a</dt>
 793 <dd class="description">Array</dd>
 794 <dt>n</dt>
 795 <dd class="description">Index into array, starting at 0</dd>
 796 </dl>
 797 <h4 class="returnvalue">Return Value</h4>
 798 <p class="description">N-th element or <code>NULL</code></p>
 799 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayInsert">cupsArrayInsert</a></h3>
 800 <p class="description">Insert an element in the array.</p>
 801 <p class="code">
 802 int cupsArrayInsert (<br>
 803 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a,<br>
 804 &nbsp;&nbsp;&nbsp;&nbsp;void *e<br>
 805 );</p>
 806 <h4 class="parameters">Parameters</h4>
 807 <dl>
 808 <dt>a</dt>
 809 <dd class="description">Array</dd>
 810 <dt>e</dt>
 811 <dd class="description">Element</dd>
 812 </dl>
 813 <h4 class="returnvalue">Return Value</h4>
 814 <p class="description">0 on failure, 1 on success</p>
 815 <h4 class="discussion">Discussion</h4>
 816 <p class="discussion">When inserting an element in a sorted array, non-unique elements are
 817 inserted at the beginning of the run of identical elements.  For unsorted
 818 arrays, the element is inserted at the beginning of the array.
 819
 820 </p>
 821 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayLast">cupsArrayLast</a></h3>
 822 <p class="description">Get the last element in the array.</p>
 823 <p class="code">
 824 void *cupsArrayLast (<br>
 825 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
 826 );</p>
 827 <h4 class="parameters">Parameters</h4>
 828 <dl>
 829 <dt>a</dt>
 830 <dd class="description">Array</dd>
 831 </dl>
 832 <h4 class="returnvalue">Return Value</h4>
 833 <p class="description">Last element or <code>NULL</code> if the array is empty</p>
 834 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayNew">cupsArrayNew</a></h3>
 835 <p class="description">Create a new array.</p>
 836 <p class="code">
 837 <a href="#cups_array_t">cups_array_t</a> *cupsArrayNew (<br>
 838 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_func_t">cups_array_func_t</a> f,<br>
 839 &nbsp;&nbsp;&nbsp;&nbsp;void *d<br>
 840 );</p>
 841 <h4 class="parameters">Parameters</h4>
 842 <dl>
 843 <dt>f</dt>
 844 <dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd>
 845 <dt>d</dt>
 846 <dd class="description">User data pointer or <code>NULL</code></dd>
 847 </dl>
 848 <h4 class="returnvalue">Return Value</h4>
 849 <p class="description">Array</p>
 850 <h4 class="discussion">Discussion</h4>
 851 <p class="discussion">The comparison function (&quot;f&quot;) is used to create a sorted array. The function
 852 receives pointers to two elements and the user data pointer (&quot;d&quot;) - the user
 853 data pointer argument can safely be omitted when not required so functions
 854 like <code>strcmp</code> can be used for sorted string arrays.
 855
 856 </p>
 857 <h3 class="function"><span class="info">&nbsp;CUPS 1.3/OS X 10.5&nbsp;</span><a name="cupsArrayNew2">cupsArrayNew2</a></h3>
 858 <p class="description">Create a new array with hash.</p>
 859 <p class="code">
 860 <a href="#cups_array_t">cups_array_t</a> *cupsArrayNew2 (<br>
 861 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_func_t">cups_array_func_t</a> f,<br>
 862 &nbsp;&nbsp;&nbsp;&nbsp;void *d,<br>
 863 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_ahash_func_t">cups_ahash_func_t</a> h,<br>
 864 &nbsp;&nbsp;&nbsp;&nbsp;int hsize<br>
 865 );</p>
 866 <h4 class="parameters">Parameters</h4>
 867 <dl>
 868 <dt>f</dt>
 869 <dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd>
 870 <dt>d</dt>
 871 <dd class="description">User data or <code>NULL</code></dd>
 872 <dt>h</dt>
 873 <dd class="description">Hash function or <code>NULL</code> for unhashed lookups</dd>
 874 <dt>hsize</dt>
 875 <dd class="description">Hash size (&gt;= 0)</dd>
 876 </dl>
 877 <h4 class="returnvalue">Return Value</h4>
 878 <p class="description">Array</p>
 879 <h4 class="discussion">Discussion</h4>
 880 <p class="discussion">The comparison function (&quot;f&quot;) is used to create a sorted array. The function
 881 receives pointers to two elements and the user data pointer (&quot;d&quot;) - the user
 882 data pointer argument can safely be omitted when not required so functions
 883 like <code>strcmp</code> can be used for sorted string arrays.<br>
 884 <br>
 885 The hash function (&quot;h&quot;) is used to implement cached lookups with the
 886 specified hash size (&quot;hsize&quot;).
 887
 888 </p>
 889 <h3 class="function"><span class="info">&nbsp;CUPS 1.5/OS X 10.7&nbsp;</span><a name="cupsArrayNew3">cupsArrayNew3</a></h3>
 890 <p class="description">Create a new array with hash and/or free function.</p>
 891 <p class="code">
 892 <a href="#cups_array_t">cups_array_t</a> *cupsArrayNew3 (<br>
 893 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_func_t">cups_array_func_t</a> f,<br>
 894 &nbsp;&nbsp;&nbsp;&nbsp;void *d,<br>
 895 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_ahash_func_t">cups_ahash_func_t</a> h,<br>
 896 &nbsp;&nbsp;&nbsp;&nbsp;int hsize,<br>
 897 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_acopy_func_t">cups_acopy_func_t</a> cf,<br>
 898 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_afree_func_t">cups_afree_func_t</a> ff<br>
 899 );</p>
 900 <h4 class="parameters">Parameters</h4>
 901 <dl>
 902 <dt>f</dt>
 903 <dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd>
 904 <dt>d</dt>
 905 <dd class="description">User data or <code>NULL</code></dd>
 906 <dt>h</dt>
 907 <dd class="description">Hash function or <code>NULL</code> for unhashed lookups</dd>
 908 <dt>hsize</dt>
 909 <dd class="description">Hash size (&gt;= 0)</dd>
 910 <dt>cf</dt>
 911 <dd class="description">Copy function</dd>
 912 <dt>ff</dt>
 913 <dd class="description">Free function</dd>
 914 </dl>
 915 <h4 class="returnvalue">Return Value</h4>
 916 <p class="description">Array</p>
 917 <h4 class="discussion">Discussion</h4>
 918 <p class="discussion">The comparison function (&quot;f&quot;) is used to create a sorted array. The function
 919 receives pointers to two elements and the user data pointer (&quot;d&quot;) - the user
 920 data pointer argument can safely be omitted when not required so functions
 921 like <code>strcmp</code> can be used for sorted string arrays.<br>
 922 <br>
 923 The hash function (&quot;h&quot;) is used to implement cached lookups with the
 924 specified hash size (&quot;hsize&quot;).<br>
 925 <br>
 926 The copy function (&quot;cf&quot;) is used to automatically copy/retain elements when
 927 added or the array is copied.<br>
 928 <br>
 929 The free function (&quot;cf&quot;) is used to automatically free/release elements when
 930 removed or the array is deleted.
 931
 932 </p>
 933 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayNext">cupsArrayNext</a></h3>
 934 <p class="description">Get the next element in the array.</p>
 935 <p class="code">
 936 void *cupsArrayNext (<br>
 937 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
 938 );</p>
 939 <h4 class="parameters">Parameters</h4>
 940 <dl>
 941 <dt>a</dt>
 942 <dd class="description">Array</dd>
 943 </dl>
 944 <h4 class="returnvalue">Return Value</h4>
 945 <p class="description">Next element or <code>NULL</code></p>
 946 <h4 class="discussion">Discussion</h4>
 947 <p class="discussion">This function is equivalent to &quot;cupsArrayIndex(a, cupsArrayGetIndex(a) + 1)&quot;.<br>
 948 <br>
 949 The next element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
 950 <a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>
 951 to set the current element.
 952
 953 </p>
 954 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayPrev">cupsArrayPrev</a></h3>
 955 <p class="description">Get the previous element in the array.</p>
 956 <p class="code">
 957 void *cupsArrayPrev (<br>
 958 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
 959 );</p>
 960 <h4 class="parameters">Parameters</h4>
 961 <dl>
 962 <dt>a</dt>
 963 <dd class="description">Array</dd>
 964 </dl>
 965 <h4 class="returnvalue">Return Value</h4>
 966 <p class="description">Previous element or <code>NULL</code></p>
 967 <h4 class="discussion">Discussion</h4>
 968 <p class="discussion">This function is equivalent to &quot;cupsArrayIndex(a, cupsArrayGetIndex(a) - 1)&quot;.<br>
 969 <br>
 970 The previous element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
 971 <a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>
 972 to set the current element.
 973
 974 </p>
 975 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayRemove">cupsArrayRemove</a></h3>
 976 <p class="description">Remove an element from the array.</p>
 977 <p class="code">
 978 int cupsArrayRemove (<br>
 979 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a,<br>
 980 &nbsp;&nbsp;&nbsp;&nbsp;void *e<br>
 981 );</p>
 982 <h4 class="parameters">Parameters</h4>
 983 <dl>
 984 <dt>a</dt>
 985 <dd class="description">Array</dd>
 986 <dt>e</dt>
 987 <dd class="description">Element</dd>
 988 </dl>
 989 <h4 class="returnvalue">Return Value</h4>
 990 <p class="description">1 on success, 0 on failure</p>
 991 <h4 class="discussion">Discussion</h4>
 992 <p class="discussion">If more than one element matches &quot;e&quot;, only the first matching element is
 993 removed.<br>
 994 <br>
 995 The caller is responsible for freeing the memory used by the
 996 removed element.
 997
 998 </p>
 999 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayRestore">cupsArrayRestore</a></h3>
1000 <p class="description">Reset the current element to the last <a href="#cupsArraySave"><code>cupsArraySave</code></a>.</p>
1001 <p class="code">
1002 void *cupsArrayRestore (<br>
1003 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
1004 );</p>
1005 <h4 class="parameters">Parameters</h4>
1006 <dl>
1007 <dt>a</dt>
1008 <dd class="description">Array</dd>
1009 </dl>
1010 <h4 class="returnvalue">Return Value</h4>
1011 <p class="description">New current element</p>
1012 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArraySave">cupsArraySave</a></h3>
1013 <p class="description">Mark the current element for a later <a href="#cupsArrayRestore"><code>cupsArrayRestore</code></a>.</p>
1014 <p class="code">
1015 int cupsArraySave (<br>
1016 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
1017 );</p>
1018 <h4 class="parameters">Parameters</h4>
1019 <dl>
1020 <dt>a</dt>
1021 <dd class="description">Array</dd>
1022 </dl>
1023 <h4 class="returnvalue">Return Value</h4>
1024 <p class="description">1 on success, 0 on failure</p>
1025 <h4 class="discussion">Discussion</h4>
1026 <p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
1027 <a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>
1028 to set the current element.<br>
1029 <br>
1030 The save/restore stack is guaranteed to be at least 32 elements deep.
1031
1032 </p>
1033 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsArrayUserData">cupsArrayUserData</a></h3>
1034 <p class="description">Return the user data for an array.</p>
1035 <p class="code">
1036 void *cupsArrayUserData (<br>
1037 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_array_t">cups_array_t</a> *a<br>
1038 );</p>
1039 <h4 class="parameters">Parameters</h4>
1040 <dl>
1041 <dt>a</dt>
1042 <dd class="description">Array</dd>
1043 </dl>
1044 <h4 class="returnvalue">Return Value</h4>
1045 <p class="description">User data</p>
1046 <h2 class="title"><a name="TYPES">Data Types</a></h2>
1047 <h3 class="typedef"><a name="cups_acopy_func_t">cups_acopy_func_t</a></h3>
1048 <p class="description">Array element copy function</p>
1049 <p class="code">
1050 typedef void *(*cups_acopy_func_t)(void *element, void *data);
1051 </p>
1052 <h3 class="typedef"><a name="cups_afree_func_t">cups_afree_func_t</a></h3>
1053 <p class="description">Array element free function</p>
1054 <p class="code">
1055 typedef void (*cups_afree_func_t)(void *element, void *data);
1056 </p>
1057 <h3 class="typedef"><a name="cups_ahash_func_t">cups_ahash_func_t</a></h3>
1058 <p class="description">Array hash function</p>
1059 <p class="code">
1060 typedef int (*cups_ahash_func_t)(void *element, void *data);
1061 </p>
1062 <h3 class="typedef"><a name="cups_array_func_t">cups_array_func_t</a></h3>
1063 <p class="description">Array comparison function</p>
1064 <p class="code">
1065 typedef int (*cups_array_func_t)(void *first, void *second, void *data);
1066 </p>
1067 <h3 class="typedef"><a name="cups_array_t">cups_array_t</a></h3>
1068 <p class="description">CUPS array type</p>
1069 <p class="code">
1070 typedef struct _cups_array_s cups_array_t;
1071 </p>
1072 </div>
1073 </body>
1074 </html>