Remove all of the Subversion keywords from various source files.

[thirdparty/cups.git] / cups / api-array.shtml

diff --git a/cups/api-array.shtml b/cups/api-array.shtml
index ae2787fec3c7635909ff84a6b92eef71f9cf2c9f..374ef5bfb56f5de67c5e4200115ca4ebdc7b95c9 100644 (file)
--- a/cups/api-array.shtml
+++ b/cups/api-array.shtml
@@ -1,9 +1,7 @@
 <!--
-  "$Id: api-array.shtml 6649 2007-07-11 21:46:42Z 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
@@ -31,8 +29,9 @@ data.</p>
 <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>
 
@@ -69,7 +68,7 @@ static int compare_func(void *first, void *second, 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='#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
@@ -80,6 +79,25 @@ element and is called whenever you look up an element in the array with
 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 &lt;cups/array.h&gt;
+
+#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.
@@ -128,8 +146,7 @@ example:</p>
 <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>