Sequence 3 RAPTOR Library
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);
    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 (*compare) (const 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_sequence

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

### raptor_free_sequence ()

    void        raptor_free_sequence            (raptor_sequence *seq);

Destructor - free a raptor_sequence

seq :

  sequence to destroy

raptor_free_sequence

### raptor_sequence_size ()

    int         raptor_sequence_size            (raptor_sequence *seq);

Get the size of a sequence.

seq :

  sequence object

Returns :

  the sequence size (>=0)

raptor_sequence_size

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

seq :

  sequence object

idx :

  index into sequence to operate at

data :

  new data item.

Returns :

  non-0 on failure

raptor_sequence_set_at

### raptor_sequence_push ()

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

Add an item to the end of the sequence.

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

seq :

  sequence to add to

data :

  item to add

Returns :

  non-0 on failure

raptor_sequence_push

### raptor_sequence_shift ()

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

Add an item to the start of the sequence.

This is in-efficient to perform. raptor_sequence is optimised to append to the end of the sequence.

seq :

  sequence to add to

data :

  item to add

Returns :

  non-0 on failure

raptor_sequence_shift

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

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_get_at

### raptor_sequence_pop ()

    void*       raptor_sequence_pop             (raptor_sequence *seq);

Retrieve the item at the end of the sequence.

This is efficient to perform.

seq :

  sequence to use

Returns :

  the object or NULL if the sequence is empty

raptor_sequence_pop

### raptor_sequence_unshift ()

    void*       raptor_sequence_unshift         (raptor_sequence *seq);

Retrieve the item at the start of the sequence.

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

seq :

  sequence to use

Returns :

  the object or NULL if the sequence is empty

raptor_sequence_unshift

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

### raptor_sequence_sort ()

    void        raptor_sequence_sort            (raptor_sequence *seq,
                                                 int (*compare) (const 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_sort

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

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

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

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

raptor_sequence_join