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