doc/help/api-array.html

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