# Array API

Header | cups/array.h
--- | ---
Library | -lcups
See Also | Programming: Introduction to CUPS Programming

## Contents

- Overview
  - Managing Arrays
  - Finding and Enumerating Elements
- Functions
  - cupsArrayAdd
  - cupsArrayClear
  - cupsArrayCount
  - cupsArrayCurrent
  - cupsArrayDelete
  - cupsArrayDup
  - cupsArrayFind
  - cupsArrayFirst
  - cupsArrayGetIndex
  - cupsArrayGetInsert
  - cupsArrayIndex
  - cupsArrayInsert
  - cupsArrayLast
  - cupsArrayNew
  - cupsArrayNew2
  - cupsArrayNew3
  - cupsArrayNext
  - cupsArrayPrev
  - cupsArrayRemove
  - cupsArrayRestore
  - cupsArraySave
  - cupsArrayUserData
- Data Types
  - cups_acopy_func_t
  - cups_afree_func_t
  - cups_ahash_func_t
  - cups_array_func_t
  - cups_array_t

## Overview

The CUPS array API provides a high-performance generic array container. The contents of the array container can be sorted and the container itself is designed for optimal speed and memory usage under a wide variety of conditions. Sorted arrays use a binary search algorithm from the last found or inserted element to quickly find matching elements in the array. Arrays created with the optional hash function can often find elements with a single lookup. The `cups_array_t` type is used when referring to a CUPS array.

The CUPS scheduler (`cupsd`) and many of the CUPS API functions use the array API to efficiently manage large lists of data.

### Managing Arrays

Arrays are created using either the `cupsArrayNew`, `cupsArrayNew2`, or `cupsArrayNew3` functions. The first function creates a new array with the specified callback function and user data pointer:

    #include <cups/array.h>

    static int compare_func(void *first, void *second, void *user_data);

    void *user_data;
    cups_array_t *array = cupsArrayNew(compare_func, user_data);

The comparison function (type `cups_arrayfunc_t`) is called whenever an element is added to the array and can be `NULL` to create an unsorted array. The function returns -1 if the first element should come before the second, 0 if the first and second elements should have the same ordering, and 1 if the first element should come after the second.

The "user_data" pointer is passed to your comparison function. Pass `NULL` if you do not need to associate the elements in your array with additional information.

The `cupsArrayNew2` function adds two more arguments to support hashed lookups, which can potentially provide instantaneous ("O(1)") lookups in your array:

    #include <cups/array.h>

    #define HASH_SIZE 512 /* Size of hash table */

    static int compare_func(void *first, void *second, void *user_data);
    static int hash_func(void *element, void *user_data);

    void *user_data;
    cups_array_t *hash_array = cupsArrayNew2(compare_func, user_data, hash_func, HASH_SIZE);

The hash function (type `cups_ahash_func_t`) 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 `cupsArrayFind`. The hash size is only limited by available memory, but generally should not be larger than 16384 to realize any performance improvement.

The `cupsArrayNew3` function adds copy and free callbacks to support basic memory management of elements:

    #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;
    cups_array_t *array = cupsArrayNew3(compare_func, user_data, NULL, 0, copy_func, free_func);

    cups_array_t *hash_array = cupsArrayNew3(compare_func, user_data, hash_func, HASH_SIZE, copy_func, free_func);

Once you have created the array, you add elements using the `cupsArrayAdd` `cupsArrayInsert` 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, `cupsArrayAdd` appends the element to the end of the array while `cupsArrayInsert` inserts the element at the beginning of the array. For example, the following code creates a sorted array of character strings:

    #include <cups/array.h>

    /* Use strcmp() to compare strings - it will ignore the user_data pointer */
    cups_array_t *array = cupsArrayNew((cups_array_func_t)strcmp, NULL);

    /* Add four strings to the array */
    cupsArrayAdd(array, "One Fish");
    cupsArrayAdd(array, "Two Fish");
    cupsArrayAdd(array, "Red Fish");
    cupsArrayAdd(array, "Blue Fish");

Elements are removed using the `cupsArrayRemove` function, for example:

    #include <cups/array.h>

    /* Use strcmp() to compare strings - it will ignore the user_data pointer */
    cups_array_t *array = cupsArrayNew((cups_array_func_t)strcmp, NULL);

    /* Add four strings to the array */
    cupsArrayAdd(array, "One Fish");
    cupsArrayAdd(array, "Two Fish");
    cupsArrayAdd(array, "Red Fish");
    cupsArrayAdd(array, "Blue Fish");

    /* Remove "Red Fish" */
    cupsArrayRemove(array, "Red Fish");

Finally, you free the memory used by the array using the `cupsArrayDelete` function. All of the memory for the array and hash table (if any) is freed, however CUPS does not free the elements unless you provide copy and free functions.

### Finding and Enumerating Elements

CUPS provides several functions to find and enumerate elements in an array. Each one sets or updates a "current index" into the array, such that future lookups will start where the last one left off:

`cupsArrayFind`
  Returns the first matching element.
`cupsArrayFirst`
  Returns the first element in the array.
`cupsArrayIndex`
  Returns the Nth element in the array, starting at 0.
`cupsArrayLast`
  Returns the last element in the array.
`cupsArrayNext`
  Returns the next element in the array.
`cupsArrayPrev`
  Returns the previous element in the array.

Each of these functions returns `NULL` when there is no corresponding element. For example, a simple `for` loop using the `cupsArrayFirst` and `cupsArrayNext` functions will enumerate all of the strings in our previous example:

    #include <cups/array.h>

    /* Use strcmp() to compare strings - it will ignore the user_data pointer */
    cups_array_t *array = cupsArrayNew((cups_array_func_t)strcmp, NULL);

    /* Add four strings to the array */
    cupsArrayAdd(array, "One Fish");
    cupsArrayAdd(array, "Two Fish");
    cupsArrayAdd(array, "Red Fish");
    cupsArrayAdd(array, "Blue Fish");

    /* Show all of the strings in the array */
    char *s;
    for (s = (char *)cupsArrayFirst(array); s != NULL; s = (char *)cupsArrayNext(array))
      puts(s);

## Functions

### CUPS 1.2/OS X 10.5 cupsArrayAdd

Add an element to the array.

int cupsArrayAdd (
cups_array_t *a,
void *e
);

#### Parameters

a
  Array
e
  Element

#### Return Value

1 on success, 0 on failure

#### Discussion

When adding an element to a sorted array, non-unique elements are appended at the end of the run of identical elements. For unsorted arrays, the element is appended to the end of the array.

### CUPS 1.2/OS X 10.5 cupsArrayClear

Clear the array.

void cupsArrayClear (
cups_array_t *a
);

#### Parameters

a
  Array

#### 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.

### CUPS 1.2/OS X 10.5 cupsArrayCount

Get the number of elements in the array.

int cupsArrayCount (
cups_array_t *a
);

#### Parameters

a
  Array

#### Return Value

Number of elements

### CUPS 1.2/OS X 10.5 cupsArrayCurrent

Return the current element in the array.

void *cupsArrayCurrent (
cups_array_t *a
);

#### Parameters

a
  Array

#### Return Value

Element

#### Discussion

The current element is undefined until you call `cupsArrayFind`, `cupsArrayFirst`, or `cupsArrayIndex`, or `cupsArrayLast`.

### CUPS 1.2/OS X 10.5 cupsArrayDelete

Free all memory used by the array.

void cupsArrayDelete (
cups_array_t *a
);

#### Parameters

a
  Array

#### Discussion

The caller is responsible for freeing the memory used by the elements themselves.

### CUPS 1.2/OS X 10.5 cupsArrayDup

Duplicate the array.

cups_array_t *cupsArrayDup (
cups_array_t *a
);

#### Parameters

a
  Array

#### Return Value

Duplicate array

### CUPS 1.2/OS X 10.5 cupsArrayFind

Find an element in the array.

void *cupsArrayFind (
cups_array_t *a,
void *e
);

#### Parameters

a
  Array
e
  Element

#### Return Value

Element found or `NULL`

### CUPS 1.2/OS X 10.5 cupsArrayFirst

Get the first element in the array.

void *cupsArrayFirst (
cups_array_t *a
);

#### Parameters

a
  Array

#### Return Value

First element or `NULL` if the array is empty

### CUPS 1.3/OS X 10.5 cupsArrayGetIndex

Get the index of the current element.

int cupsArrayGetIndex (
cups_array_t *a
);

#### Parameters

a
  Array

#### Return Value

Index of the current element, starting at 0

#### Discussion

The current element is undefined until you call `cupsArrayFind`, `cupsArrayFirst`, or `cupsArrayIndex`, or `cupsArrayLast`.

### CUPS 1.3/OS X 10.5 cupsArrayGetInsert

Get the index of the last inserted element.

int cupsArrayGetInsert (
cups_array_t *a
);

#### Parameters

a
  Array

#### Return Value

Index of the last inserted element, starting at 0

### CUPS 1.2/OS X 10.5 cupsArrayIndex

Get the N-th element in the array.

void *cupsArrayIndex (
cups_array_t *a,
int n
);

#### Parameters

a
  Array
n
  Index into array, starting at 0

#### Return Value

N-th element or `NULL`

### CUPS 1.2/OS X 10.5 cupsArrayInsert

Insert an element in the array.

int cupsArrayInsert (
cups_array_t *a,
void *e
);

#### Parameters

a
  Array
e
  Element

#### Return Value

0 on failure, 1 on success

#### Discussion

When inserting an element in a sorted array, non-unique elements are inserted at the beginning of the run of identical elements. For unsorted arrays, the element is inserted at the beginning of the array.

### CUPS 1.2/OS X 10.5 cupsArrayLast

Get the last element in the array.

void *cupsArrayLast (
cups_array_t *a
);

#### Parameters

a
  Array

#### Return Value

Last element or `NULL` if the array is empty

### CUPS 1.2/OS X 10.5 cupsArrayNew

Create a new array.

cups_array_t *cupsArrayNew (
cups_array_func_t f,
void *d
);

#### Parameters

f
  Comparison function or `NULL` for an unsorted array
d
  User data pointer or `NULL`

#### Return Value

Array

#### 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 `strcmp` can be used for sorted string arrays.

### CUPS 1.3/OS X 10.5 cupsArrayNew2

Create a new array with hash.

cups_array_t *cupsArrayNew2 (
cups_array_func_t f,
void *d,
cups_ahash_func_t h,
int hsize
);

#### Parameters

f
  Comparison function or `NULL` for an unsorted array
d
  User data or `NULL`
h
  Hash function or `NULL` for unhashed lookups
hsize
  Hash size (>= 0)

#### Return Value

Array

#### 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 `strcmp` can be used for sorted string arrays.
The hash function ("h") is used to implement cached lookups with the specified hash size ("hsize").

### CUPS 1.5/OS X 10.7 cupsArrayNew3

Create a new array with hash and/or free function.

cups_array_t *cupsArrayNew3 (
cups_array_func_t f,
void *d,
cups_ahash_func_t h,
int hsize,
cups_acopy_func_t cf,
cups_afree_func_t ff
);

#### Parameters

f
  Comparison function or `NULL` for an unsorted array
d
  User data or `NULL`
h
  Hash function or `NULL` for unhashed lookups
hsize
  Hash size (>= 0)
cf
  Copy function
ff
  Free function

#### Return Value

Array

#### 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 `strcmp` can be used for sorted string arrays.
The hash function ("h") is used to implement cached lookups with the specified hash size ("hsize").
The copy function ("cf") is used to automatically copy/retain elements when added or the array is copied.
The free function ("cf") is used to automatically free/release elements when removed or the array is deleted.

### CUPS 1.2/OS X 10.5 cupsArrayNext

Get the next element in the array.

void *cupsArrayNext (
cups_array_t *a
);

#### Parameters

a
  Array

#### Return Value

Next element or `NULL`

#### Discussion

This function is equivalent to "cupsArrayIndex(a, cupsArrayGetIndex(a) + 1)".
The next element is undefined until you call `cupsArrayFind`, `cupsArrayFirst`, or `cupsArrayIndex`, or `cupsArrayLast` to set the current element.

### CUPS 1.2/OS X 10.5 cupsArrayPrev

Get the previous element in the array.

void *cupsArrayPrev (
cups_array_t *a
);

#### Parameters

a
  Array

#### Return Value

Previous element or `NULL`

#### Discussion

This function is equivalent to "cupsArrayIndex(a, cupsArrayGetIndex(a) - 1)".
The previous element is undefined until you call `cupsArrayFind`, `cupsArrayFirst`, or `cupsArrayIndex`, or `cupsArrayLast` to set the current element.

### CUPS 1.2/OS X 10.5 cupsArrayRemove

Remove an element from the array.

int cupsArrayRemove (
cups_array_t *a,
void *e
);

#### Parameters

a
  Array
e
  Element

#### Return Value

1 on success, 0 on failure

#### Discussion

If more than one element matches "e", only the first matching element is removed.
The caller is responsible for freeing the memory used by the removed element.

### CUPS 1.2/OS X 10.5 cupsArrayRestore

Reset the current element to the last `cupsArraySave`.

void *cupsArrayRestore (
cups_array_t *a
);

#### Parameters

a
  Array

#### Return Value

New current element

### CUPS 1.2/OS X 10.5 cupsArraySave

Mark the current element for a later `cupsArrayRestore`.

int cupsArraySave (
cups_array_t *a
);

#### Parameters

a
  Array

#### Return Value

1 on success, 0 on failure

#### Discussion

The current element is undefined until you call `cupsArrayFind`, `cupsArrayFirst`, or `cupsArrayIndex`, or `cupsArrayLast` to set the current element.
The save/restore stack is guaranteed to be at least 32 elements deep.

### CUPS 1.2/OS X 10.5 cupsArrayUserData

Return the user data for an array.

void *cupsArrayUserData (
cups_array_t *a
);

#### Parameters

a
  Array

#### Return Value

User data

## Data Types

### cups_acopy_func_t

Array element copy function

typedef void *(*cups_acopy_func_t)(void *element, void *data);

### cups_afree_func_t

Array element free function

typedef void (*cups_afree_func_t)(void *element, void *data);

### cups_ahash_func_t

Array hash function

typedef int (*cups_ahash_func_t)(void *element, void *data);

### cups_array_func_t

Array comparison function

typedef int (*cups_array_func_t)(void *first, void *second, void *data);

### cups_array_t

CUPS array type

typedef struct _cups_array_s cups_array_t;