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