## Introduction

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.

## General Usage

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

## Compatibility

All of these functions require CUPS 1.2 or higher.

## Contents

- Functions
- Types

## Functions

- `cupsArrayAdd()`
- `cupsArrayClear()`
- `cupsArrayCount()`
- `cupsArrayCurrent()`
- `cupsArrayDelete()`
- `cupsArrayDup()`
- `cupsArrayFind()`
- `cupsArrayFirst()`
- `cupsArrayGetIndex()` CUPS 1.3
- `cupsArrayGetInsert()` CUPS 1.3
- `cupsArrayIndex()`
- `cupsArrayInsert()`
- `cupsArrayLast()`
- `cupsArrayNew()`
- `cupsArrayNew2()` CUPS 1.3
- `cupsArrayNext()`
- `cupsArrayPrev()`
- `cupsArrayRemove()`
- `cupsArrayRestore()`
- `cupsArraySave()`
- `cupsArrayUserData()`

### cupsArrayAdd()

#### Description

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.

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`a` | Array
`e` | Element

#### Returns

1 on success, 0 on failure

### cupsArrayClear()

#### Description

Clear the array.

#### Syntax

`void
cupsArrayClear( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

Nothing.

### cupsArrayCount()

#### Description

Get the number of elements in the array.

#### Syntax

`int
cupsArrayCount( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

Number of elements

### cupsArrayCurrent()

#### Description

Return the current element in the array.

#### Syntax

`void *
cupsArrayCurrent( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

Element

### cupsArrayDelete()

#### Description

Free all memory used by the array.

#### Syntax

`void
cupsArrayDelete( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

Nothing.

### cupsArrayDup()

#### Description

Duplicate the array.

#### Syntax

`cups_array_t *
cupsArrayDup( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

Duplicate array

### cupsArrayFind()

#### Description

Find an element in the array.

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`a` | Array
`e` | Element

#### Returns

Element found or NULL

### cupsArrayFirst()

#### Description

Get the first element in the array.

#### Syntax

`void *
cupsArrayFirst( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

First element or NULL

### CUPS 1.3 cupsArrayGetIndex()

#### Description

Get the index of the current element.

#### Syntax

`int
cupsArrayGetIndex( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

Index of the current element

### CUPS 1.3 cupsArrayGetInsert()

#### Description

Get the index of the last inserted element.

#### Syntax

`int
cupsArrayGetInsert( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

Index of the last inserted element

### cupsArrayIndex()

#### Description

Get the N-th element in the array.

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`a` | Array
`n` | Index into array, starting at 0

#### Returns

N-th element or NULL

### cupsArrayInsert()

#### Description

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.

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`a` | Array
`e` | Element

#### Returns

0 on failure, 1 on success

### cupsArrayLast()

#### Description

Get the last element in the array.

#### Syntax

`void *
cupsArrayLast( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

Last element or NULL

### cupsArrayNew()

#### Description

Create a new array.

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`f` | Comparison function
`d` | User data

#### Returns

Array

### CUPS 1.3 cupsArrayNew2()

#### Description

Create a new array with hash.

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`f` | Comparison function
`d` | User data
`h` | Hash function
`hsize` | Hash size

#### Returns

Array

### cupsArrayNext()

#### Description

Get the next element in the array.

#### Syntax

`void *
cupsArrayNext( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

Next element or NULL

### cupsArrayPrev()

#### Description

Get the previous element in the array.

#### Syntax

`void *
cupsArrayPrev( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

Previous element or NULL

### cupsArrayRemove()

#### Description

Remove an element from the array.

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`a` | Array
`e` | Element

#### Returns

1 on success, 0 on failure

### cupsArrayRestore()

#### Description

Reset the current element to the last cupsArraySave.

#### Syntax

`void *
cupsArrayRestore( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

New current element

### cupsArraySave()

#### Description

Mark the current element for a later cupsArrayRestore.

The save/restore stack is guaranteed to be at least 32 elements deep.

#### Syntax

`int
cupsArraySave( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

1 on success, 0 on failure

### cupsArrayUserData()

#### Description

Return the user data for an array.

#### Syntax

`void *
cupsArrayUserData( cups_array_t * a);`

#### Arguments

Name | Description
--- | ---
`a` | Array

#### Returns

User data

## Types

- `cups_ahash_func_t`
- `cups_array_func_t`
- `cups_array_t`

### cups_ahash_func_t

#### Description

Array hash function

#### Definition

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

### cups_array_func_t

#### Description

Array comparison function

#### Definition

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

### cups_array_t

#### Description

CUPS array type

#### Definition

`typedef struct _cups_array_s cups_array_t;`