-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- SECTION: Programming -->
<head>
-<title>Array API</title>
-<meta name="keywords" content="Programming">
-<meta name="creator" content="Mini-XML v2.5">
+ <title>Array API </title>
+ <meta name="keywords" content="Programming">
+ <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
+ <meta name="creator" content="Mini-XML v2.7">
<style type="text/css"><!--
BODY {
font-family: lucida grande, geneva, helvetica, arial, sans-serif;
}
PRE.command {
+ border: dotted thin #7f7f7f;
margin-left: 36pt;
+ padding: 10px;
+}
+
+P.compact {
+ margin: 0;
+}
+
+P.example {
+ font-style: italic;
+ margin-left: 36pt;
+}
+
+DL.man DD {
+ margin-left: 5em;
+}
+
+DL.man DT {
+ margin-left: 0;
+}
+
+PRE.man {
+ margin: 0;
}
PRE.example {
background: #eeeeee;
border: dotted thin #999999;
margin-left: 36pt;
- padding: 10px;
+ padding: 10pt;
}
PRE.command EM, PRE.example EM {
}
BLOCKQUOTE {
- background: #cccccc;
+ background: #eeeeee;
border: solid thin #999999;
padding: 10pt;
}
+A IMG {
+ border: none;
+}
+
+A:link:hover IMG {
+ background: #f0f0f0;
+ border-radius: 10px;
+ -moz-border-radius: 10px;
+}
+
A:link, A:visited {
+ font-weight: inherit;
text-decoration: none;
- font-weight: bold;
}
A:link:hover, A:visited:hover, A:active {
text-decoration: underline;
- font-weight: bold;
}
SUB, SUP {
font-size: 50%;
}
+TR.data, TD.data, TR.data TD {
+ margin-top: 10pt;
+ padding: 5pt;
+ border-bottom: solid 1pt #999999;
+}
+
+TR.data TH {
+ border-bottom: solid 1pt #999999;
+ padding-top: 10pt;
+ padding-left: 5pt;
+ text-align: left;
+}
+
DIV.table TABLE {
border: solid thin #999999;
border-collapse: collapse;
}
TH.label {
- padding-top: 5pt;
text-align: right;
vertical-align: top;
}
+TH.sublabel {
+ text-align: right;
+ font-weight: normal;
+}
+
HR {
border: solid thin;
}
SPAN.info {
- background: #000000;
- border: thin solid #000000;
- color: #ffffff;
+ background: black;
+ border: thin solid black;
+ color: white;
font-size: 80%;
font-style: italic;
font-weight: bold;
font-size: 100%;
}
+H1.title {
+}
+
H2.title, H3.title {
border-bottom: solid 2pt #000000;
}
+DIV.indent, TABLE.indent {
+ margin-top: 2em;
+ margin-left: auto;
+ margin-right: auto;
+ width: 90%;
+}
+
+TABLE.indent {
+ border-collapse: collapse;
+}
+
+TABLE.indent TD, TABLE.indent TH {
+ padding: 0;
+}
+
+TABLE.list {
+ border-collapse: collapse;
+ margin-left: auto;
+ margin-right: auto;
+ width: 90%;
+}
+
+TABLE.list TH {
+ background: white;
+ border-bottom: solid thin #cccccc;
+ color: #444444;
+ padding-top: 10pt;
+ padding-left: 5pt;
+ text-align: left;
+ vertical-align: bottom;
+ white-space: nowrap;
+}
+
+TABLE.list TH A {
+ color: #4444cc;
+}
+
+TABLE.list TD {
+ border-bottom: solid thin #eeeeee;
+ padding-top: 5pt;
+ padding-left: 5pt;
+}
+
+TABLE.list TR:nth-child(even) {
+ background: #f8f8f8;
+}
+
+TABLE.list TR:nth-child(odd) {
+ background: #f4f4f4;
+}
+
DT {
margin-left: 36pt;
margin-top: 12pt;
font-family: monaco, courier, monospace;
}
-SPAN.message {
- font-style: italic;
- font-size: smaller;
-}
-
DIV.summary TABLE {
border: solid thin #999999;
border-collapse: collapse;
div.contents ul.contents {
font-size: 80%;
}
+div.contents ul.subcontents li {
+ margin-left: 1em;
+ text-indent: -1em;
+}
--></style>
</head>
<body>
<div class='body'>
<!--
- "$Id: api-array.header 7266 2008-01-29 02:15:29Z mike $"
-
- Array API header for the Common UNIX Printing System (CUPS).
+ Array API header for CUPS.
- Copyright 2008 by Apple Inc.
+ Copyright 2008-2011 by Apple Inc.
These coded instructions, statements, and computer programs are the
property of Apple Inc. and are protected by Federal copyright
file is missing or damaged, see the license at "http://www.cups.org/".
-->
-<h1 class="title">Array API</h1>
+<h1 class='title'>Array API</h1>
<div class='summary'><table summary='General Information'>
<thead>
</table></div>
<h2 class="title">Contents</h2>
<ul class="contents">
-</li>
<li><a href="#OVERVIEW">Overview</a><ul class="subcontents">
-<li><a href="#MANAGING_ARRAYS">Managing Arrays</a></li>
-<li><a href="#FINDING_AND_ENUMERATING">Finding and Enumerating Elements</a></li>
+
<li><a href="#MANAGING_ARRAYS">Managing Arrays</a></li>
+
<li><a href="#FINDING_AND_ENUMERATING">Finding and Enumerating Elements</a></li>
</ul></li>
<li><a href="#FUNCTIONS">Functions</a><ul class="code">
-<li><a href="#cupsArrayAdd" title="Add an element to the array.">cupsArrayAdd</a></li>
-<li><a href="#cupsArrayClear" title="Clear the array.">cupsArrayClear</a></li>
-<li><a href="#cupsArrayCount" title="Get the number of elements in the array.">cupsArrayCount</a></li>
-<li><a href="#cupsArrayCurrent" title="Return the current element in the array.">cupsArrayCurrent</a></li>
-<li><a href="#cupsArrayDelete" title="Free all memory used by the array.">cupsArrayDelete</a></li>
-<li><a href="#cupsArrayDup" title="Duplicate the array.">cupsArrayDup</a></li>
-<li><a href="#cupsArrayFind" title="Find an element in the array.">cupsArrayFind</a></li>
-<li><a href="#cupsArrayFirst" title="Get the first element in the array.">cupsArrayFirst</a></li>
-<li><a href="#cupsArrayGetIndex" title="Get the index of the current element.">cupsArrayGetIndex</a></li>
-<li><a href="#cupsArrayGetInsert" title="Get the index of the last inserted element.">cupsArrayGetInsert</a></li>
-<li><a href="#cupsArrayIndex" title="Get the N-th element in the array.">cupsArrayIndex</a></li>
-<li><a href="#cupsArrayInsert" title="Insert an element in the array.">cupsArrayInsert</a></li>
-<li><a href="#cupsArrayLast" title="Get the last element in the array.">cupsArrayLast</a></li>
-<li><a href="#cupsArrayNew" title="Create a new array.">cupsArrayNew</a></li>
-<li><a href="#cupsArrayNew2" title="Create a new array with hash.">cupsArrayNew2</a></li>
-<li><a href="#cupsArrayNext" title="Get the next element in the array.">cupsArrayNext</a></li>
-<li><a href="#cupsArrayPrev" title="Get the previous element in the array.">cupsArrayPrev</a></li>
-<li><a href="#cupsArrayRemove" title="Remove an element from the array.">cupsArrayRemove</a></li>
-<li><a href="#cupsArrayRestore" title="Reset the current element to the last cupsArraySave.">cupsArrayRestore</a></li>
-<li><a href="#cupsArraySave" title="Mark the current element for a later cupsArrayRestore.">cupsArraySave</a></li>
-<li><a href="#cupsArrayUserData" title="Return the user data for an array.">cupsArrayUserData</a></li>
-</ul>
+ <li><a href="#cupsArrayAdd" title="Add an element to the array.">cupsArrayAdd</a></li>
+ <li><a href="#cupsArrayClear" title="Clear the array.">cupsArrayClear</a></li>
+ <li><a href="#cupsArrayCount" title="Get the number of elements in the array.">cupsArrayCount</a></li>
+ <li><a href="#cupsArrayCurrent" title="Return the current element in the array.">cupsArrayCurrent</a></li>
+ <li><a href="#cupsArrayDelete" title="Free all memory used by the array.">cupsArrayDelete</a></li>
+ <li><a href="#cupsArrayDup" title="Duplicate the array.">cupsArrayDup</a></li>
+ <li><a href="#cupsArrayFind" title="Find an element in the array.">cupsArrayFind</a></li>
+ <li><a href="#cupsArrayFirst" title="Get the first element in the array.">cupsArrayFirst</a></li>
+ <li><a href="#cupsArrayGetIndex" title="Get the index of the current element.">cupsArrayGetIndex</a></li>
+ <li><a href="#cupsArrayGetInsert" title="Get the index of the last inserted element.">cupsArrayGetInsert</a></li>
+ <li><a href="#cupsArrayIndex" title="Get the N-th element in the array.">cupsArrayIndex</a></li>
+ <li><a href="#cupsArrayInsert" title="Insert an element in the array.">cupsArrayInsert</a></li>
+ <li><a href="#cupsArrayLast" title="Get the last element in the array.">cupsArrayLast</a></li>
+ <li><a href="#cupsArrayNew" title="Create a new array.">cupsArrayNew</a></li>
+ <li><a href="#cupsArrayNew2" title="Create a new array with hash.">cupsArrayNew2</a></li>
+ <li><a href="#cupsArrayNew3" title="Create a new array with hash and/or free function.">cupsArrayNew3</a></li>
+ <li><a href="#cupsArrayNext" title="Get the next element in the array.">cupsArrayNext</a></li>
+ <li><a href="#cupsArrayPrev" title="Get the previous element in the array.">cupsArrayPrev</a></li>
+ <li><a href="#cupsArrayRemove" title="Remove an element from the array.">cupsArrayRemove</a></li>
+ <li><a href="#cupsArrayRestore" title="Reset the current element to the last cupsArraySave.">cupsArrayRestore</a></li>
+ <li><a href="#cupsArraySave" title="Mark the current element for a later cupsArrayRestore.">cupsArraySave</a></li>
+ <li><a href="#cupsArrayUserData" title="Return the user data for an array.">cupsArrayUserData</a></li>
+</ul></li>
<li><a href="#TYPES">Data Types</a><ul class="code">
+ <li><a href="#cups_acopy_func_t" title="Array element copy function">cups_acopy_func_t</a></li>
+ <li><a href="#cups_afree_func_t" title="Array element free function">cups_afree_func_t</a></li>
<li><a href="#cups_ahash_func_t" title="Array hash function">cups_ahash_func_t</a></li>
<li><a href="#cups_array_func_t" title="Array comparison function">cups_array_func_t</a></li>
<li><a href="#cups_array_t" title="CUPS array type">cups_array_t</a></li>
</ul></li>
</ul>
<!--
- "$Id: api-array.shtml 7266 2008-01-29 02:15:29Z mike $"
+ Array API introduction for CUPS.
- Array API introduction for the Common UNIX Printing System (CUPS).
-
- Copyright 2007-2008 by Apple Inc.
+ Copyright 2007-2011 by Apple Inc.
Copyright 1997-2006 by Easy Software Products, all rights reserved.
These coded instructions, statements, and computer programs are the
<h3><a name='MANAGING_ARRAYS'>Managing Arrays</a></h3>
<p>Arrays are created using either the
-<a href='#cupsArrayNew'><code>cupsArrayNew</code></a> or
-<a href='#cupsArrayNew2'><code>cupsArrayNew2</code></a> functions. The
+<a href='#cupsArrayNew'><code>cupsArrayNew</code></a>,
+<a href='#cupsArrayNew2'><code>cupsArrayNew2</code></a>, or
+<a href='#cupsArrayNew2'><code>cupsArrayNew3</code></a> functions. The
first function creates a new array with the specified callback function
and user data pointer:</p>
static int hash_func(void *element, void *user_data);
void *user_data;
-<a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew2'>cupsArrayNew2</a>(compare_func, user_data, hash_func, HASH_SIZE);
+<a href='#cups_array_t'>cups_array_t</a> *
hash_array = <a href='#cupsArrayNew2'>cupsArrayNew2</a>(compare_func, user_data, hash_func, HASH_SIZE);
</pre>
<p>The hash function (type
-<a href="#cups_ahash_func_t"><code>cups_ahash_func_t</code></a>) returns a
+<a href="#cups_ahash_func_t"><code>cups_ahash_func_t</code></a>) should return a
number from 0 to (hash_size-1) that (hopefully) uniquely identifies the
element and is called whenever you look up an element in the array with
<a href='#cupsArrayFind'><code>cupsArrayFind</code></a>. The hash size is
only limited by available memory, but generally should not be larger than
16384 to realize any performance improvement.</p>
+<p>The <a href='#cupsArrayNew3'><code>cupsArrayNew3</code></a> function adds
+copy and free callbacks to support basic memory management of elements:</p>
+
+<pre class='example'>
+#include <cups/array.h>
+
+#define HASH_SIZE 512 /* Size of hash table */
+
+static int compare_func(void *first, void *second, void *user_data);
+static void *copy_func(void *element, void *user_data);
+static void free_func(void *element, void *user_data);
+static int hash_func(void *element, void *user_data);
+
+void *user_data;
+<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);
+
+<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);
+</pre>
+
<p>Once you have created the array, you add elements using the
<a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a>
<a href='#cupsArrayInsert'><code>cupsArrayInsert</code></a> functions.
The first function adds an element to the array, adding the new element
after any elements that have the same order, while the second inserts the
element before others with the same order. For unsorted arrays,
-<a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a> appends the elemnt to
+<a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a> appends the element to
the end of the array while
<a href='#cupsArrayInsert'><code>cupsArrayInsert</code></a> inserts the
element at the beginning of the array. For example, the following code
<p>Finally, you free the memory used by the array using the
<a href='#cupsArrayDelete'><code>cupsArrayDelete</code></a> function. All
of the memory for the array and hash table (if any) is freed, however <em>CUPS
-does not free the elements</em> - if necessary, you must allocate and free the
-elements yourself.</p>
+does not free the elements unless you provide copy and free functions</em>.</p>
<h3><a name='FINDING_AND_ENUMERATING'>Finding and Enumerating Elements</a></h3>
<dl>
<dt><a href='#cupsArrayFind'><code>cupsArrayFind</code></a></dt>
- <dd>Returns the first matching element .</dd>
+ <dd>Returns the first matching element.</dd>
<dt><a href='#cupsArrayFirst'><code>cupsArrayFirst</code></a></dt>
<dd>Returns the first element in the array.</dd>
<dt><a href='#cupsArrayIndex'><code>cupsArrayIndex</code></a></dt>
- <dd>Returns the Nth element in the array.</dd>
+ <dd>Returns the Nth element in the array, starting at 0.</dd>
<dt><a href='#cupsArrayLast'><code>cupsArrayLast</code></a></dt>
<dd>Returns the last element in the array.</dd>
<dt><a href='#cupsArrayNext'><code>cupsArrayNext</code></a></dt>
puts(s);
</pre>
<h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayAdd">cupsArrayAdd</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsArrayAdd">cupsArrayAdd</a></h3>
<p class="description">Add an element to the array.</p>
<p class="code">
int cupsArrayAdd (<br>
<p class="description">1 on success, 0 on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">When adding an element to a sorted array, non-unique elements are
-appended at the end of the run. For unsorted arrays, the element
-is inserted at the end of the array.
+appended at the end of the run of identical elements. For unsorted arrays,
+the element is appended to the end of the array.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayClear">cupsArrayClear</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsArrayClear">cupsArrayClear</a></h3>
<p class="description">Clear the array.</p>
<p class="code">
void cupsArrayClear (<br>
<dt>a</dt>
<dd class="description">Array</dd>
</dl>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayCount">cupsArrayCount</a></h3>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function is equivalent to removing all elements in the array.
+The caller is responsible for freeing the memory used by the
+elements themselves.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayCount">cupsArrayCount</a></h3>
<p class="description">Get the number of elements in the array.</p>
<p class="code">
int cupsArrayCount (<br>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Number of elements</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayCurrent">cupsArrayCurrent</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsArrayCurrent">cupsArrayCurrent</a></h3>
<p class="description">Return the current element in the array.</p>
<p class="code">
void *cupsArrayCurrent (<br>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Element</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayDelete">cupsArrayDelete</a></h3>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
+<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayDelete">cupsArrayDelete</a></h3>
<p class="description">Free all memory used by the array.</p>
<p class="code">
void cupsArrayDelete (<br>
<dt>a</dt>
<dd class="description">Array</dd>
</dl>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayDup">cupsArrayDup</a></h3>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The caller is responsible for freeing the memory used by the
+elements themselves.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayDup">cupsArrayDup</a></h3>
<p class="description">Duplicate the array.</p>
<p class="code">
<a href="#cups_array_t">cups_array_t</a> *cupsArrayDup (<br>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Duplicate array</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayFind">cupsArrayFind</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsArrayFind">cupsArrayFind</a></h3>
<p class="description">Find an element in the array.</p>
<p class="code">
void *cupsArrayFind (<br>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Element found or <code>NULL</code></p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayFirst">cupsArrayFirst</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsArrayFirst">cupsArrayFirst</a></h3>
<p class="description">Get the first element in the array.</p>
<p class="code">
void *cupsArrayFirst (<br>
<dd class="description">Array</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">First element or <code>NULL</code></p>
-<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsArrayGetIndex">cupsArrayGetIndex</a></h3>
+<p class="description">First element or <code>NULL</code> if the array is empty</p>
+<h3 class="function"><span class="info"> CUPS 1.3
/OS X 10.5 </span><a name="cupsArrayGetIndex">cupsArrayGetIndex</a></h3>
<p class="description">Get the index of the current element.</p>
<p class="code">
int cupsArrayGetIndex (<br>
<dd class="description">Array</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">Index of the current element</p>
-<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsArrayGetInsert">cupsArrayGetInsert</a></h3>
+<p class="description">Index of the current element, starting at 0</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
+<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsArrayGetInsert">cupsArrayGetInsert</a></h3>
<p class="description">Get the index of the last inserted element.</p>
<p class="code">
int cupsArrayGetInsert (<br>
<dd class="description">Array</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">Index of the last inserted element</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayIndex">cupsArrayIndex</a></h3>
+<p class="description">Index of the last inserted element, starting at 0</p>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsArrayIndex">cupsArrayIndex</a></h3>
<p class="description">Get the N-th element in the array.</p>
<p class="code">
void *cupsArrayIndex (<br>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">N-th element or <code>NULL</code></p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayInsert">cupsArrayInsert</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsArrayInsert">cupsArrayInsert</a></h3>
<p class="description">Insert an element in the array.</p>
<p class="code">
int cupsArrayInsert (<br>
<p class="description">0 on failure, 1 on success</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">When inserting an element in a sorted array, non-unique elements are
-inserted at the beginning of the run. For unsorted arrays, the element
-is inserted at the beginning of the array.
+inserted at the beginning of the run of identical elements. For unsorted
+arrays, the element is inserted at the beginning of the array.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayLast">cupsArrayLast</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsArrayLast">cupsArrayLast</a></h3>
<p class="description">Get the last element in the array.</p>
<p class="code">
void *cupsArrayLast (<br>
<dd class="description">Array</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">Last element or <code>NULL</code></p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayNew">cupsArrayNew</a></h3>
+<p class="description">Last element or <code>NULL</code> if the array is empty</p>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsArrayNew">cupsArrayNew</a></h3>
<p class="description">Create a new array.</p>
<p class="code">
<a href="#cups_array_t">cups_array_t</a> *cupsArrayNew (<br>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>f</dt>
-<dd class="description">Comparison function</dd>
+<dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd>
<dt>d</dt>
-<dd class="description">User data</dd>
+<dd class="description">User data pointer or <code>NULL</code></dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Array</p>
-<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsArrayNew2">cupsArrayNew2</a></h3>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The comparison function ("f") is used to create a sorted array. The function
+receives pointers to two elements and the user data pointer ("d") - the user
+data pointer argument can safely be omitted when not required so functions
+like <code>strcmp</code> can be used for sorted string arrays.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsArrayNew2">cupsArrayNew2</a></h3>
<p class="description">Create a new array with hash.</p>
<p class="code">
<a href="#cups_array_t">cups_array_t</a> *cupsArrayNew2 (<br>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>f</dt>
-<dd class="description">Comparison function</dd>
+<dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd>
<dt>d</dt>
-<dd class="description">User data</dd>
+<dd class="description">User data or <code>NULL</code></dd>
<dt>h</dt>
-<dd class="description">Hash function</dd>
+<dd class="description">Hash function or <code>NULL</code> for unhashed lookups</dd>
<dt>hsize</dt>
-<dd class="description">Hash size</dd>
+<dd class="description">Hash size (>= 0)</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Array</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayNext">cupsArrayNext</a></h3>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The comparison function ("f") is used to create a sorted array. The function
+receives pointers to two elements and the user data pointer ("d") - the user
+data pointer argument can safely be omitted when not required so functions
+like <code>strcmp</code> can be used for sorted string arrays.<br>
+<br>
+The hash function ("h") is used to implement cached lookups with the
+specified hash size ("hsize").
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.5/OS X 10.7 </span><a name="cupsArrayNew3">cupsArrayNew3</a></h3>
+<p class="description">Create a new array with hash and/or free function.</p>
+<p class="code">
+<a href="#cups_array_t">cups_array_t</a> *cupsArrayNew3 (<br>
+ <a href="#cups_array_func_t">cups_array_func_t</a> f,<br>
+ void *d,<br>
+ <a href="#cups_ahash_func_t">cups_ahash_func_t</a> h,<br>
+ int hsize,<br>
+ <a href="#cups_acopy_func_t">cups_acopy_func_t</a> cf,<br>
+ <a href="#cups_afree_func_t">cups_afree_func_t</a> ff<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>f</dt>
+<dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd>
+<dt>d</dt>
+<dd class="description">User data or <code>NULL</code></dd>
+<dt>h</dt>
+<dd class="description">Hash function or <code>NULL</code> for unhashed lookups</dd>
+<dt>hsize</dt>
+<dd class="description">Hash size (>= 0)</dd>
+<dt>cf</dt>
+<dd class="description">Copy function</dd>
+<dt>ff</dt>
+<dd class="description">Free function</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Array</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The comparison function ("f") is used to create a sorted array. The function
+receives pointers to two elements and the user data pointer ("d") - the user
+data pointer argument can safely be omitted when not required so functions
+like <code>strcmp</code> can be used for sorted string arrays.<br>
+<br>
+The hash function ("h") is used to implement cached lookups with the
+specified hash size ("hsize").<br>
+<br>
+The copy function ("cf") is used to automatically copy/retain elements when
+added or the array is copied.<br>
+<br>
+The free function ("cf") is used to automatically free/release elements when
+removed or the array is deleted.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayNext">cupsArrayNext</a></h3>
<p class="description">Get the next element in the array.</p>
<p class="code">
void *cupsArrayNext (<br>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Next element or <code>NULL</code></p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayPrev">cupsArrayPrev</a></h3>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function is equivalent to "cupsArrayIndex(a, cupsArrayGetIndex(a) + 1)".<br>
+<br>
+The next element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
+<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>
+to set the current element.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayPrev">cupsArrayPrev</a></h3>
<p class="description">Get the previous element in the array.</p>
<p class="code">
void *cupsArrayPrev (<br>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Previous element or <code>NULL</code></p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayRemove">cupsArrayRemove</a></h3>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function is equivalent to "cupsArrayIndex(a, cupsArrayGetIndex(a) - 1)".<br>
+<br>
+The previous element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
+<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>
+to set the current element.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayRemove">cupsArrayRemove</a></h3>
<p class="description">Remove an element from the array.</p>
<p class="code">
int cupsArrayRemove (<br>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">1 on success, 0 on failure</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayRestore">cupsArrayRestore</a></h3>
-<p class="description">Reset the current element to the last cupsArraySave.</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">If more than one element matches "e", only the first matching element is
+removed.<br>
+<br>
+The caller is responsible for freeing the memory used by the
+removed element.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayRestore">cupsArrayRestore</a></h3>
+<p class="description">Reset the current element to the last <a href="#cupsArraySave"><code>cupsArraySave</code></a>.</p>
<p class="code">
void *cupsArrayRestore (<br>
<a href="#cups_array_t">cups_array_t</a> *a<br>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">New current element</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArraySave">cupsArraySave</a></h3>
-<p class="description">Mark the current element for a later cupsArrayRestore.</p>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsArraySave">cupsArraySave</a></h3>
+<p class="description">Mark the current element for a later <a href="#cupsArrayRestore"><code>cupsArrayRestore</code></a>.</p>
<p class="code">
int cupsArraySave (<br>
<a href="#cups_array_t">cups_array_t</a> *a<br>
<h4 class="returnvalue">Return Value</h4>
<p class="description">1 on success, 0 on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The save/restore stack is guaranteed to be at least 32 elements deep.
+<p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
+<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>
+to set the current element.<br>
+<br>
+The save/restore stack is guaranteed to be at least 32 elements deep.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayUserData">cupsArrayUserData</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsArrayUserData">cupsArrayUserData</a></h3>
<p class="description">Return the user data for an array.</p>
<p class="code">
void *cupsArrayUserData (<br>
<h4 class="returnvalue">Return Value</h4>
<p class="description">User data</p>
<h2 class="title"><a name="TYPES">Data Types</a></h2>
+<h3 class="typedef"><a name="cups_acopy_func_t">cups_acopy_func_t</a></h3>
+<p class="description">Array element copy function</p>
+<p class="code">
+typedef void *(*cups_acopy_func_t)(void *element, void *data);
+</p>
+<h3 class="typedef"><a name="cups_afree_func_t">cups_afree_func_t</a></h3>
+<p class="description">Array element free function</p>
+<p class="code">
+typedef void (*cups_afree_func_t)(void *element, void *data);
+</p>
<h3 class="typedef"><a name="cups_ahash_func_t">cups_ahash_func_t</a></h3>
<p class="description">Array hash function</p>
<p class="code">
projects / thirdparty / cups.git / blobdiff