Sequence

Sequence — Ordered sequence of items.

Types and Values

typedef raptor_sequence

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.

Functions

raptor_new_sequence ()

raptor_sequence *
raptor_new_sequence (raptor_data_free_handler free_handler,
                     raptor_data_print_handler print_handler);

Constructor - create a new sequence with the given handlers.

This creates a sequence over objects that need only the item data pointers in order to print or free the objects.

For example sequences of strings could use handlers (free, NULL) and sequences of raptor_uri could use (raptor_free_uri, raptor_print_uri)

Parameters

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_with_context ()

raptor_sequence *
raptor_new_sequence_with_context (raptor_data_context_free_handler free_handler,
                                  raptor_data_context_print_handler print_handler,
                                  void *handler_context);

Constructor - create a new sequence with the given handlers and handler context.

This creates a sequence over objects that need context + item data pointers in order to print or free the objects.

Parameters

free_handler

handler to free a sequence item

 

print_handler

handler to print a sequence item to a FILE*

 

handler_context

context information to pass to free/print handlers

 

Returns

a new raptor_sequence or NULL on failure


raptor_free_sequence ()

void
raptor_free_sequence (raptor_sequence *seq);

Destructor - free a raptor_sequence

Parameters

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.

Parameters

seq

sequence object

 

idx

index into sequence to operate at

 

Returns

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

Parameters

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

Parameters

dest

raptor_sequence destination sequence

 

src

raptor_sequence source sequence

 

Returns

non-0 on failure


raptor_sequence_next_permutation ()

int
raptor_sequence_next_permutation (raptor_sequence *seq,
                                  raptor_data_compare_handler compare);

Get the next permutation of a sequence in lexicographic order

Assumes the initial order of the items is lexicographically increasing. This function alters the order of the items until the last permuatation is done at which point the contents is reset to the intial order.

Algorithm used is described in http://en.wikipedia.org/wiki/Permutation

The comparison function compare 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.

Parameters

seq

int seq

 

compare

comparison function

 

Returns

non-0 at the last permutation


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.

Parameters

seq

sequence to use

 

Returns

the object or NULL if the sequence is empty


raptor_sequence_print ()

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

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

Parameters

seq

sequence to sort

 

fh

file handle

 

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.

Parameters

seq

sequence to add to

 

data

item to add

 

Returns

non-0 on failure


raptor_sequence_reverse ()

int
raptor_sequence_reverse (raptor_sequence *seq,
                         int start_index,
                         int length);

Reverse a range of elements

Parameters

seq

sequence

 

start_index

starting index

 

length

number of elements to reverse

 

Returns

non-0 if arguments are out of range


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.

Parameters

seq

sequence object

 

idx

index into sequence to operate at

 

data

new data item.

 

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.

Parameters

seq

sequence to add to

 

data

item to add

 

Returns

non-0 on failure


raptor_sequence_size ()

int
raptor_sequence_size (raptor_sequence *seq);

Get the number of items in a sequence.

Parameters

seq

sequence object

 

Returns

the sequence size (>=0)


raptor_sequence_sort ()

void
raptor_sequence_sort (raptor_sequence *seq,
                      raptor_data_compare_handler compare);

Sort a sequence inline

The comparison function compare 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.

Parameters

seq

sequence to sort

 

compare

comparison function with args (a, b)

 

raptor_sequence_sort_r ()

void
raptor_sequence_sort_r (raptor_sequence *seq,
                        raptor_data_compare_arg_handler compare,
                        void *user_data);

Sort a sequence inline with user data

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

Parameters

seq

sequence to sort

 

compare

comparison function with args (a, b, user data)

 

user_data

User data argument for compare

 

raptor_sequence_swap ()

int
raptor_sequence_swap (raptor_sequence *seq,
                      int i,
                      int j);

Swap a pair of elements in a sequence

Parameters

seq

sequence

 

i

first data index

 

j

second data index

 

Returns

non-0 if arguments are out of range


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.

Parameters

seq

sequence to use

 

Returns

the object or NULL if the sequence is empty

Types and Values

raptor_sequence

raptor_sequence* raptor_sequence;

Raptor sequence class



Navigation: Redland Home Page

Copyright 2000-2023 Dave Beckett