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