Array API
Keywords: Programming

## 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()`
- `cupsArrayIndex()`
- `cupsArrayInsert()`
- `cupsArrayLast()`
- `cupsArrayNew()`
- `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

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

### 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_array_func_t`
- `cups_array_t`

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