doc/help/api-array.html

   1 <!doctype html>
   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.11">
   9     <meta name="author" content="Unknown">
  10     <meta name="copyright" content="Unknown">
  11     <style type="text/css"><!--
  12 BODY {
  13   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  14 }
  15
  16 H1, H2, H3, H4, H5, H6, P, TD, TH {
  17   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  18 }
  19
  20 KBD {
  21   font-family: monaco, courier, monospace;
  22   font-weight: bold;
  23 }
  24
  25 PRE {
  26   font-family: monaco, courier, monospace;
  27 }
  28
  29 PRE.command {
  30   border: dotted thin #7f7f7f;
  31   margin-left: 36pt;
  32   padding: 10px;
  33 }
  34
  35 P.compact {
  36   margin: 0;
  37 }
  38
  39 P.example {
  40   font-style: italic;
  41   margin-left: 36pt;
  42 }
  43
  44 DL.man DD {
  45   margin-left: 5em;
  46 }
  47
  48 DL.man DT {
  49   margin-left: 0;
  50 }
  51
  52 PRE.man {
  53   margin: 0;
  54 }
  55
  56 PRE.example {
  57   background: #eeeeee;
  58   border: dotted thin #999999;
  59   margin-left: 36pt;
  60   padding: 10pt;
  61 }
  62
  63 PRE.command EM, PRE.example EM {
  64   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  65 }
  66
  67 P.command {
  68   font-family: monaco, courier, monospace;
  69   margin-left: 36pt;
  70 }
  71
  72 P.formula {
  73   font-style: italic;
  74   margin-left: 36pt;
  75 }
  76
  77 BLOCKQUOTE {
  78   background: #eeeeee;
  79   border: solid thin #999999;
  80   padding: 10pt;
  81 }
  82
  83 A IMG {
  84   border: none;
  85 }
  86
  87 A:link:hover IMG {
  88   background: #f0f0f0;
  89   border-radius: 10px;
  90   -moz-border-radius: 10px;
  91 }
  92
  93 A:link, A:visited {
  94   font-weight: inherit;
  95   text-decoration: none;
  96 }
  97
  98 A:link:hover, A:visited:hover, A:active {
  99   text-decoration: underline;
 100 }
 101
 102 SUB, SUP {
 103   font-size: 50%;
 104 }
 105
 106 TR.data, TD.data, TR.data TD {
 107   margin-top: 10pt;
 108   padding: 5pt;
 109   border-bottom: solid 1pt #999999;
 110 }
 111
 112 TR.data TH {
 113   border-bottom: solid 1pt #999999;
 114   padding-top: 10pt;
 115   padding-left: 5pt;
 116   text-align: left;
 117 }
 118
 119 DIV.table TABLE {
 120   border: solid thin #999999;
 121   border-collapse: collapse;
 122   border-spacing: 0;
 123   margin-left: auto;
 124   margin-right: auto;
 125 }
 126
 127 DIV.table CAPTION {
 128   caption-side: top;
 129   font-size: 120%;
 130   font-style: italic;
 131   font-weight: bold;
 132   margin-left: auto;
 133   margin-right: auto;
 134 }
 135
 136 DIV.table TABLE TD {
 137   border: solid thin #cccccc;
 138   padding-top: 5pt;
 139 }
 140
 141 DIV.table TABLE TH {
 142   background: #cccccc;
 143   border: none;
 144   border-bottom: solid thin #999999;
 145 }
 146
 147 DIV.figure TABLE {
 148   margin-left: auto;
 149   margin-right: auto;
 150 }
 151
 152 DIV.figure CAPTION {
 153   caption-side: bottom;
 154   font-size: 120%;
 155   font-style: italic;
 156   font-weight: bold;
 157   margin-left: auto;
 158   margin-right: auto;
 159 }
 160
 161 TH.label {
 162   text-align: right;
 163   vertical-align: top;
 164 }
 165
 166 TH.sublabel {
 167   text-align: right;
 168   font-weight: normal;
 169 }
 170
 171 HR {
 172   border: solid thin;
 173 }
 174
 175 SPAN.info {
 176   background: black;
 177   border: thin solid black;
 178   color: white;
 179   font-size: 80%;
 180   font-style: italic;
 181   font-weight: bold;
 182   white-space: nowrap;
 183 }
 184
 185 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
 186   float: right;
 187   font-size: 100%;
 188 }
 189
 190 H1.title {
 191 }
 192
 193 H2.title, H3.title {
 194   border-bottom: solid 2pt #000000;
 195 }
 196
 197 DIV.indent, TABLE.indent {
 198   margin-top: 2em;
 199   margin-left: auto;
 200   margin-right: auto;
 201   width: 90%;
 202 }
 203
 204 TABLE.indent {
 205   border-collapse: collapse;
 206 }
 207
 208 TABLE.indent TD, TABLE.indent TH {
 209   padding: 0;
 210 }
 211
 212 TABLE.list {
 213   border-collapse: collapse;
 214   margin-left: auto;
 215   margin-right: auto;
 216   width: 90%;
 217 }
 218
 219 TABLE.list TH {
 220   background: white;
 221   border-bottom: solid thin #cccccc;
 222   color: #444444;
 223   padding-top: 10pt;
 224   padding-left: 5pt;
 225   text-align: left;
 226   vertical-align: bottom;
 227   white-space: nowrap;
 228 }
 229
 230 TABLE.list TH A {
 231   color: #4444cc;
 232 }
 233
 234 TABLE.list TD {
 235   border-bottom: solid thin #eeeeee;
 236   padding-top: 5pt;
 237   padding-left: 5pt;
 238 }
 239
 240 TABLE.list TR:nth-child(even) {
 241   background: #f8f8f8;
 242 }
 243
 244 TABLE.list TR:nth-child(odd) {
 245   background: #f4f4f4;
 246 }
 247
 248 DT {
 249   margin-left: 36pt;
 250   margin-top: 12pt;
 251 }
 252
 253 DD {
 254   margin-left: 54pt;
 255 }
 256
 257 DL.category DT {
 258   font-weight: bold;
 259 }
 260
 261 P.summary {
 262   margin-left: 36pt;
 263   font-family: monaco, courier, monospace;
 264 }
 265
 266 DIV.summary TABLE {
 267   border: solid thin #999999;
 268   border-collapse: collapse;
 269   border-spacing: 0;
 270   margin: 10px;
 271 }
 272
 273 DIV.summary TABLE TD, DIV.summary TABLE TH {
 274   border: solid thin #999999;
 275   padding: 5px;
 276   text-align: left;
 277   vertical-align: top;
 278 }
 279
 280 DIV.summary TABLE THEAD TH {
 281   background: #eeeeee;
 282 }
 283
 284 /* API documentation styles... */
 285 div.body h1 {
 286   margin: 0;
 287 }
 288 div.body h2 {
 289   margin-top: 1.5em;
 290 }
 291 div.body h3, div.body h4, div.body h5 {
 292   margin-bottom: 0.5em;
 293   margin-top: 1.5em;
 294 }
 295 .class, .enumeration, .function, .struct, .typedef, .union {
 296   border-bottom: solid thin #999999;
 297   margin-bottom: 0;
 298   margin-top: 2em;
 299 }
 300 .description {
 301   margin-top: 0.5em;
 302 }
 303 code, p.code, pre, ul.code li {
 304   font-family: monaco, courier, monospace;
 305   font-size: 90%;
 306 }
 307 ul.code, ul.contents, ul.subcontents {
 308   list-style-type: none;
 309   margin: 0;
 310   padding-left: 0;
 311 }
 312 ul.code li {
 313   margin: 0;
 314 }
 315 ul.contents > li {
 316   margin-top: 1em;
 317 }
 318 ul.contents li ul.code, ul.contents li ul.subcontents {
 319   padding-left: 2em;
 320 }
 321 div.body dl {
 322   margin-left: 0;
 323   margin-top: 0;
 324 }
 325 div.body dt {
 326   font-style: italic;
 327   margin-left: 0;
 328   margin-top: 0;
 329 }
 330 div.body dd {
 331   margin-bottom: 0.5em;
 332 }
 333
 334 /* This is just for the HTML files generated with the framedhelp target */
 335 div.contents {
 336   background: #e8e8e8;
 337   border: solid thin black;
 338   padding: 10px;
 339 }
 340 div.contents h1 {
 341   font-size: 110%;
 342 }
 343 div.contents h2 {
 344   font-size: 100%;
 345 }
 346 div.contents ul.contents {
 347   font-size: 80%;
 348 }
 349 div.contents ul.subcontents li {
 350   margin-left: 1em;
 351   text-indent: -1em;
 352 }
 353 --></style>
 354   </head>
 355   <body>
 356 <!--
 357   Array API header for CUPS.
 358
 359   Copyright 2008-2011 by Apple Inc.
 360
 361   These coded instructions, statements, and computer programs are the
 362   property of Apple Inc. and are protected by Federal copyright
 363   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 364   which should have been included with this file.  If this file is
 365   file is missing or damaged, see the license at "http://www.cups.org/".
 366 -->
 367
 368 <h1 class='title'>Array API</h1>
 369
 370 <div class='summary'><table summary='General Information'>
 371 <thead>
 372 <tr>
 373         <th>Header</th>
 374         <th>cups/array.h</th>
 375 </tr>
 376 </thead>
 377 <tbody>
 378 <tr>
 379         <th>Library</th>
 380         <td>-lcups</td>
 381 </tr>
 382 <tr>
 383         <th>See Also</th>
 384         <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a></td>
 385 </tr>
 386 </tbody>
 387 </table></div>
 388     <div class="contents">
 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="subcontents">
 396           <li><a href="#cupsArrayAdd">cupsArrayAdd</a></li>
 397           <li><a href="#cupsArrayClear">cupsArrayClear</a></li>
 398           <li><a href="#cupsArrayCount">cupsArrayCount</a></li>
 399           <li><a href="#cupsArrayCurrent">cupsArrayCurrent</a></li>
 400           <li><a href="#cupsArrayDelete">cupsArrayDelete</a></li>
 401           <li><a href="#cupsArrayDup">cupsArrayDup</a></li>
 402           <li><a href="#cupsArrayFind">cupsArrayFind</a></li>
 403           <li><a href="#cupsArrayFirst">cupsArrayFirst</a></li>
 404           <li><a href="#cupsArrayGetIndex">cupsArrayGetIndex</a></li>
 405           <li><a href="#cupsArrayGetInsert">cupsArrayGetInsert</a></li>
 406           <li><a href="#cupsArrayIndex">cupsArrayIndex</a></li>
 407           <li><a href="#cupsArrayInsert">cupsArrayInsert</a></li>
 408           <li><a href="#cupsArrayLast">cupsArrayLast</a></li>
 409           <li><a href="#cupsArrayNew">cupsArrayNew</a></li>
 410           <li><a href="#cupsArrayNew2">cupsArrayNew2</a></li>
 411           <li><a href="#cupsArrayNew3">cupsArrayNew3</a></li>
 412           <li><a href="#cupsArrayNext">cupsArrayNext</a></li>
 413           <li><a href="#cupsArrayPrev">cupsArrayPrev</a></li>
 414           <li><a href="#cupsArrayRemove">cupsArrayRemove</a></li>
 415           <li><a href="#cupsArrayRestore">cupsArrayRestore</a></li>
 416           <li><a href="#cupsArraySave">cupsArraySave</a></li>
 417           <li><a href="#cupsArrayUserData">cupsArrayUserData</a></li>
 418         </ul></li>
 419         <li><a href="#TYPES">Data Types</a><ul class="subcontents">
 420           <li><a href="#cups_acopy_func_t">cups_acopy_func_t</a></li>
 421           <li><a href="#cups_afree_func_t">cups_afree_func_t</a></li>
 422           <li><a href="#cups_ahash_func_t">cups_ahash_func_t</a></li>
 423           <li><a href="#cups_array_func_t">cups_array_func_t</a></li>
 424           <li><a href="#cups_array_t">cups_array_t</a></li>
 425         </ul></li>
 426       </ul>
 427     </div>
 428     <div class="body">
 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 id="FUNCTIONS">Functions</a></h2>
 624 <h3 class="function"><span class="info">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="cupsArrayAdd">cupsArrayAdd</a></h3>
 625         <p class="description">Add an element to the array.</p>
 626 <p class="code">
 627 int cupsArrayAdd (<br />
 628 &#160;&#160;&#160;&#160;<a href="#cups_array_t">cups_array_t</a> *a,<br />
 629 &#160;&#160;&#160;&#160;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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="cupsArrayClear">cupsArrayClear</a></h3>
 647         <p class="description">Clear the array.</p>
 648 <p class="code">
 649 void cupsArrayClear (<br />
 650 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="cupsArrayFind">cupsArrayFind</a></h3>
 724         <p class="description">Find an element in the array.</p>
 725 <p class="code">
 726 void *cupsArrayFind (<br />
 727 &#160;&#160;&#160;&#160;<a href="#cups_array_t">cups_array_t</a> *a,<br />
 728 &#160;&#160;&#160;&#160;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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.3/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.3/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<a href="#cups_array_t">cups_array_t</a> *a,<br />
 788 &#160;&#160;&#160;&#160;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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="cupsArrayInsert">cupsArrayInsert</a></h3>
 800         <p class="description">Insert an element in the array.</p>
 801 <p class="code">
 802 int cupsArrayInsert (<br />
 803 &#160;&#160;&#160;&#160;<a href="#cups_array_t">cups_array_t</a> *a,<br />
 804 &#160;&#160;&#160;&#160;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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<a href="#cups_array_func_t">cups_array_func_t</a> f,<br />
 839 &#160;&#160;&#160;&#160;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">&#160;CUPS 1.3/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<a href="#cups_array_func_t">cups_array_func_t</a> f,<br />
 862 &#160;&#160;&#160;&#160;void *d,<br />
 863 &#160;&#160;&#160;&#160;<a href="#cups_ahash_func_t">cups_ahash_func_t</a> h,<br />
 864 &#160;&#160;&#160;&#160;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">&#160;CUPS 1.5/macOS 10.7&#160;</span><a id="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 &#160;&#160;&#160;&#160;<a href="#cups_array_func_t">cups_array_func_t</a> f,<br />
 894 &#160;&#160;&#160;&#160;void *d,<br />
 895 &#160;&#160;&#160;&#160;<a href="#cups_ahash_func_t">cups_ahash_func_t</a> h,<br />
 896 &#160;&#160;&#160;&#160;int hsize,<br />
 897 &#160;&#160;&#160;&#160;<a href="#cups_acopy_func_t">cups_acopy_func_t</a> cf,<br />
 898 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="cupsArrayRemove">cupsArrayRemove</a></h3>
 976         <p class="description">Remove an element from the array.</p>
 977 <p class="code">
 978 int cupsArrayRemove (<br />
 979 &#160;&#160;&#160;&#160;<a href="#cups_array_t">cups_array_t</a> *a,<br />
 980 &#160;&#160;&#160;&#160;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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<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">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="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 &#160;&#160;&#160;&#160;<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 id="TYPES">Data Types</a></h2>
1047       <h3 class="typedef"><a id="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 id="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 id="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 id="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 id="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>