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