## Sequence

Sequence — Ordered sequence of items.

## Synopsis

    typedef             raptor_sequence;
    raptor_sequence*    raptor_new_sequence                 (raptor_sequence_free_handler *free_handler,
                                                             raptor_sequence_print_handler *print_handler);
    void                raptor_free_sequence                (raptor_sequence *seq);
    void*               raptor_sequence_delete_at           (raptor_sequence *seq,
                                                             int idx);
    int                 raptor_sequence_size                (raptor_sequence *seq);
    int                 raptor_sequence_set_at              (raptor_sequence *seq,
                                                             int idx,
                                                             void *data);
    int                 raptor_sequence_push                (raptor_sequence *seq,
                                                             void *data);
    int                 raptor_sequence_shift               (raptor_sequence *seq,
                                                             void *data);
    void*               raptor_sequence_get_at              (raptor_sequence *seq,
                                                             int idx);
    void*               raptor_sequence_pop                 (raptor_sequence *seq);
    void*               raptor_sequence_unshift             (raptor_sequence *seq);
    int                 raptor_compare_strings              (const void *a,
                                                             const void *b);
    void                raptor_sequence_sort                (raptor_sequence *seq,
                                                             int (compareconst void *, const void *) ());
    void                raptor_sequence_print_string        (char *data,
                                                             FILE *fh);
    void                raptor_sequence_print_uri           (char *data,
                                                             FILE *fh);
    void                raptor_sequence_set_print_handler   (raptor_sequence *seq,
                                                             raptor_sequence_print_handler *print_handler);
    void                raptor_sequence_print               (raptor_sequence *seq,
                                                             FILE *fh);
    int                 raptor_sequence_join                (raptor_sequence *dest,
                                                             raptor_sequence *src);

## Description

A utility class that provides access to small sequence of items that grow at the end and require quick ordered and indexed access. Can be used as a queue/FIFO but less efficiently than a stack where the items are added and removed from the end.

## Details

### raptor_sequence

    raptor_sequence* raptor_sequence;

Raptor sequence class

### raptor_new_sequence ()

    raptor_sequence*    raptor_new_sequence                 (raptor_sequence_free_handler *free_handler,
                                                             raptor_sequence_print_handler *print_handler);

Constructor - create a new sequence with the given handlers.

`free_handler` : | handler to free a sequence item
`print_handler` : | handler to print a sequence item to a FILE*
Returns : | a new raptor_sequence or NULL on failure

### raptor_free_sequence ()

    void                raptor_free_sequence                (raptor_sequence *seq);

Destructor - free a raptor_sequence

`seq` : | sequence to destroy

### raptor_sequence_delete_at ()

    void*               raptor_sequence_delete_at           (raptor_sequence *seq,
                                                             int idx);

Remove an item from a position a sequence, returning it

The item at the offset `idx` in the sequence is replaced with a NULL pointer and any existing item is returned. The caller owns the resulting item.

`seq` : | sequence object
`idx` : | index into sequence to operate at
Returns : | NULL on failure

### raptor_sequence_size ()

    int                 raptor_sequence_size                (raptor_sequence *seq);

Get the number of items in a sequence.

`seq` : | sequence object
Returns : | the sequence size (>=0)

### raptor_sequence_set_at ()

    int                 raptor_sequence_set_at              (raptor_sequence *seq,
                                                             int idx,
                                                             void *data);

Replace/set an item in a sequence.

The item at the offset `idx` in the sequence is replaced with the new item `data` (which may be NULL). Any existing item is freed with the sequence's free_handler. If necessary the sequence is extended (with NULLs) to handle a larger offset.

The sequence takes ownership of the new data item. On failure, the item is freed immediately.

`seq` : | sequence object
`idx` : | index into sequence to operate at
`data` : | new data item.
Returns : | non-0 on failure

### raptor_sequence_push ()

    int                 raptor_sequence_push                (raptor_sequence *seq,
                                                             void *data);

Add an item to the end of the sequence.

The sequence takes ownership of the pushed item and frees it with the free_handler. On failure, the item is freed immediately.

`seq` : | sequence to add to
`data` : | item to add
Returns : | non-0 on failure

### raptor_sequence_shift ()

    int                 raptor_sequence_shift               (raptor_sequence *seq,
                                                             void *data);

Add an item to the start of the sequence.

The sequence takes ownership of the shifted item and frees it with the free_handler. On failure, the item is freed immediately.

`seq` : | sequence to add to
`data` : | item to add
Returns : | non-0 on failure

### raptor_sequence_get_at ()

    void*               raptor_sequence_get_at              (raptor_sequence *seq,
                                                             int idx);

Retrieve an item at offset `index` in the sequence.

This is efficient to perform. raptor_sequence is optimised to append/remove from the end of the sequence.

After this call the item is still owned by the sequence.

`seq` : | sequence to use
`idx` : | index of item to get
Returns : | the object or NULL if `index` is out of range (0... sequence size-1)

### raptor_sequence_pop ()

    void*               raptor_sequence_pop                 (raptor_sequence *seq);

Retrieve the item at the end of the sequence.

Ownership of the item is transferred to the caller, i.e. caller is responsible of freeing the item.

`seq` : | sequence to use
Returns : | the object or NULL if the sequence is empty

### raptor_sequence_unshift ()

    void*               raptor_sequence_unshift             (raptor_sequence *seq);

Retrieve the item at the start of the sequence.

Ownership of the item is transferred to the caller, i.e. caller is responsible of freeing the item.

`seq` : | sequence to use
Returns : | the object or NULL if the sequence is empty

### raptor_compare_strings ()

    int                 raptor_compare_strings              (const void *a,
                                                             const void *b);

Utility function for `raptor_sequence_sort()` to compare a sequence of strings.

`a` : | pointer first string
`b` : | pointer to second string
Returns : | comparison of `a` to `b` as strings

### raptor_sequence_sort ()

    void                raptor_sequence_sort                (raptor_sequence *seq,
                                                             int (compareconst void *, const void *) ());

The comparison function is compatible with that used for `qsort()` and provides the addresses of pointers to the data that must be dereferenced to get to the stored sequence data.

`seq` : | sequence to sort
`compare` : | comparison function

### raptor_sequence_print_string ()

    void                raptor_sequence_print_string        (char *data,
                                                             FILE *fh);

Helper function for printing a sequence of strings.

Intended for use as a raptor_sequence_print_handler passed into `raptor_new_sequence()`.

`data` : | data item (a char*)
`fh` : | file handle to print to

### raptor_sequence_print_uri ()

    void                raptor_sequence_print_uri           (char *data,
                                                             FILE *fh);

Helper function for printing a sequence of URIs.

Intended for use as a raptor_sequence_print_handler passed into `raptor_new_sequence()`.

`data` : | data item (a raptor_uri)
`fh` : | file handle to print to

### raptor_sequence_set_print_handler ()

    void                raptor_sequence_set_print_handler   (raptor_sequence *seq,
                                                             raptor_sequence_print_handler *print_handler);

Set the print handler for the sequence.

This is set in the `raptor_new_sequence()` constructor and can be overridden here.

`seq` : | sequence
`print_handler` : | print handler

### raptor_sequence_print ()

    void                raptor_sequence_print               (raptor_sequence *seq,
                                                             FILE *fh);

Print the sequence contents using the print_handler to print the data items.

`seq` : | sequence to sort
`fh` : | file handle

### raptor_sequence_join ()

    int                 raptor_sequence_join                (raptor_sequence *dest,
                                                             raptor_sequence *src);

Join two sequences moving all items from one sequence to the end of another.

After this operation, sequence src will be empty (zero size) but will have the same item capacity as before.

`dest` : | raptor_sequence destination sequence
`src` : | raptor_sequence source sequence
Returns : | non-0 on failure