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.
The CUPS scheduler (cupsd) and many of the CUPS API functions use the array API to efficiently manage large lists of data.
The <cups/array.h> header file must be included to use the cupsArray functions.
Programs using these functions must be linked to the CUPS library: libcups.a, libcups.so.2, libcups.2.dylib, libcups_s.a, or libcups2.lib depending on the platform. The following command compiles myprogram.c using GCC and the CUPS library:
gcc -o myprogram myprogram.c -lcups
All of these functions require CUPS 1.2 or higher.
Add an element to the array.
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.
int
cupsArrayAdd(
cups_array_t * a,
void * e);
| Name | Description |
|---|---|
| a | Array |
| e | Element |
1 on success, 0 on failure
Clear the array.
void
cupsArrayClear(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
Nothing.
Get the number of elements in the array.
int
cupsArrayCount(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
Number of elements
Return the current element in the array.
void *
cupsArrayCurrent(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
Element
Free all memory used by the array.
void
cupsArrayDelete(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
Nothing.
Duplicate the array.
cups_array_t *
cupsArrayDup(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
Duplicate array
Find an element in the array.
void *
cupsArrayFind(
cups_array_t * a,
void * e);
| Name | Description |
|---|---|
| a | Array |
| e | Element |
Element found or NULL
Get the first element in the array.
void *
cupsArrayFirst(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
First element or NULL
Get the index of the current element.
int
cupsArrayGetIndex(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
Index of the current element
Get the index of the last inserted element.
int
cupsArrayGetInsert(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
Index of the last inserted element
Get the N-th element in the array.
void *
cupsArrayIndex(
cups_array_t * a,
int n);
| Name | Description |
|---|---|
| a | Array |
| n | Index into array, starting at 0 |
N-th element or NULL
Insert an element in the array.
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.
int
cupsArrayInsert(
cups_array_t * a,
void * e);
| Name | Description |
|---|---|
| a | Array |
| e | Element |
0 on failure, 1 on success
Get the last element in the array.
void *
cupsArrayLast(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
Last element or NULL
Create a new array.
cups_array_t *
cupsArrayNew(
cups_array_func_t f,
void * d);
| Name | Description |
|---|---|
| f | Comparison function |
| d | User data |
Array
Create a new array with hash.
cups_array_t *
cupsArrayNew2(
cups_array_func_t f,
void * d,
cups_ahash_func_t h,
int hsize);
| Name | Description |
|---|---|
| f | Comparison function |
| d | User data |
| h | Hash function |
| hsize | Hash size |
Array
Get the next element in the array.
void *
cupsArrayNext(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
Next element or NULL
Get the previous element in the array.
void *
cupsArrayPrev(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
Previous element or NULL
Remove an element from the array.
int
cupsArrayRemove(
cups_array_t * a,
void * e);
| Name | Description |
|---|---|
| a | Array |
| e | Element |
1 on success, 0 on failure
Reset the current element to the last cupsArraySave.
void *
cupsArrayRestore(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
New current element
Mark the current element for a later cupsArrayRestore.
The save/restore stack is guaranteed to be at least 32 elements deep.
int
cupsArraySave(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
1 on success, 0 on failure
Return the user data for an array.
void *
cupsArrayUserData(
cups_array_t * a);
| Name | Description |
|---|---|
| a | Array |
User data
Array hash function
typedef int (*cups_ahash_func_t)(void *element, void *data);
Array comparison function
typedef int (*cups_array_func_t)(void *first, void *second, void *data);
CUPS array type
typedef struct _cups_array_s cups_array_t;