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