list

The list data type implements a fast generic doubly-linked list. More...

## Typedefs

typedef struct stp_list_item | stp_list_item_t
| The list item opaque data type. More...
typedef struct stp_list | stp_list_t
| The list opaque data type. More...
typedef void(* | stp_node_freefunc) (void *)
| A callback function to free the data a node contains. More...
typedef void *(* | stp_node_copyfunc) (const void *)
| A callback function to copy the data a node contains. More...
typedef const char *(* | stp_node_namefunc) (const void *)
| A callback function to get the name of a node. More...
typedef int(* | stp_node_sortfunc) (const void *, const void *)
| A callback function to compare two nodes. More...

## Functions

void | stp_list_node_free_data (void *item)
| Free node data allocated with stp_malloc. More...
stp_list_t * | stp_list_create (void)
| Create a new list object. More...
stp_list_t * | stp_list_copy (const stp_list_t *list)
| Copy and allocate a list object. More...
int | stp_list_destroy (stp_list_t *list)
| Destroy a list object. More...
stp_list_item_t * | stp_list_get_start (const stp_list_t *list)
| Find the first item in a list. More...
stp_list_item_t * | stp_list_get_end (const stp_list_t *list)
| Find the last item in a list. More...
stp_list_item_t * | stp_list_get_item_by_index (const stp_list_t *list, int idx)
| Find an item in a list by its index. More...
stp_list_item_t * | stp_list_get_item_by_name (const stp_list_t *list, const char *name)
| Find an item in a list by its name. More...
stp_list_item_t * | stp_list_get_item_by_long_name (const stp_list_t *list, const char *long_name)
| Find an item in a list by its long name. More...
int | stp_list_get_length (const stp_list_t *list)
| Get the length of a list. More...
void | stp_list_set_freefunc (stp_list_t *list, stp_node_freefunc freefunc)
| Set a list node free function. More...
stp_node_freefunc | stp_list_get_freefunc (const stp_list_t *list)
| Get a list node free function. More...
void | stp_list_set_copyfunc (stp_list_t *list, stp_node_copyfunc copyfunc)
| Set a list node copy function. More...
stp_node_copyfunc | stp_list_get_copyfunc (const stp_list_t *list)
| Get a list node copy function. More...
void | stp_list_set_namefunc (stp_list_t *list, stp_node_namefunc namefunc)
| Set a list node name function. More...
stp_node_namefunc | stp_list_get_namefunc (const stp_list_t *list)
| Get a list node name function. More...
void | stp_list_set_long_namefunc (stp_list_t *list, stp_node_namefunc long_namefunc)
| Set a list node long name function. More...
stp_node_namefunc | stp_list_get_long_namefunc (const stp_list_t *list)
| Get a list node long name function. More...
void | stp_list_set_sortfunc (stp_list_t *list, stp_node_sortfunc sortfunc)
| Set a list node sort function. More...
stp_node_sortfunc | stp_list_get_sortfunc (const stp_list_t *list)
| Get a list node sort function. More...
int | stp_list_item_create (stp_list_t *list, stp_list_item_t *next, const void *data)
| Create a new list item. More...
int | stp_list_item_destroy (stp_list_t *list, stp_list_item_t *item)
| Destroy a list item. More...
stp_list_item_t * | stp_list_item_prev (const stp_list_item_t *item)
| Get the previous item in the list. More...
stp_list_item_t * | stp_list_item_next (const stp_list_item_t *item)
| Get the next item in the list. More...
void * | stp_list_item_get_data (const stp_list_item_t *item)
| Get the data associated with a list item. More...
int | stp_list_item_set_data (stp_list_item_t *item, void *data)
| Set the data associated with a list item. More...

## Detailed Description

The list data type implements a fast generic doubly-linked list.

It supports all of the operations you might want in a list (insert, remove, iterate over the list, copy whole lists), plus some (optional) less common features: finding items by index, name or long name, and sorting. These should also be fairly fast, due to caching in the list head.

## Typedef Documentation

## stp_list_item_t

typedef struct stp_list_item stp_list_item_t

The list item opaque data type.

This object is a node in the list.

## stp_list_t

typedef struct stp_list stp_list_t

The list opaque data type.

This object represents the list as a whole.

## stp_node_copyfunc

typedef void*(* stp_node_copyfunc) (const void *)

A callback function to copy the data a node contains.

The parameter is a pointer to the node data. The return value is a pointer to the new copy of the data.

## stp_node_freefunc

typedef void(* stp_node_freefunc) (void *)

A callback function to free the data a node contains.

The parameter is a pointer to the node data.

## stp_node_namefunc

typedef const char*(* stp_node_namefunc) (const void *)

A callback function to get the name of a node.

The parameter is a pointer to the node data. The return value is a pointer to the name of the node, or NULL if there is no name.

## stp_node_sortfunc

typedef int(* stp_node_sortfunc) (const void *, const void *)

A callback function to compare two nodes.

The two parameters are pointers to node data. The return value is <0 if the first sorts before the second, 0 if they sort identically, and >0 if the first sorts after the second.

## Function Documentation

## stp_list_copy()

stp_list_t* stp_list_copy | ( | const stp_list_t * | list | ) |

Copy and allocate a list object.

list must be a valid list object previously created with stp_list_create().

Parameters

  list | the list to copy.

Returns
  a pointer to the new copy of the list.

## stp_list_create()

stp_list_t* stp_list_create | ( | void |  | ) |

Create a new list object.

Returns
  the newly created list object.

## stp_list_destroy()

int stp_list_destroy | ( | stp_list_t * | list | ) |

Destroy a list object.

It is an error to destroy the list more than once.

Parameters

  list | the list to destroy.

Returns
  0 on success, 1 on failure.

## stp_list_get_copyfunc()

stp_node_copyfunc stp_list_get_copyfunc | ( | const stp_list_t * | list | ) |

Get a list node copy function.

Parameters

  list | the list to use.

Returns
  the function previously set with stp_list_set_copyfunc, or NULL if no function has been set.

## stp_list_get_end()

stp_list_item_t* stp_list_get_end | ( | const stp_list_t * | list | ) |

Find the last item in a list.

Parameters

  list | the list to use.

Returns
  a pointer to the last list item, or NULL if the list is empty.

## stp_list_get_freefunc()

stp_node_freefunc stp_list_get_freefunc | ( | const stp_list_t * | list | ) |

Get a list node free function.

Parameters

  list | the list to use.

Returns
  the function previously set with stp_list_set_freefunc, or NULL if no function has been set.

## stp_list_get_item_by_index()

stp_list_item_t* stp_list_get_item_by_index | ( | const stp_list_t * | list,
|  | int | idx
| ) |  |

Find an item in a list by its index.

Parameters

  list | the list to use.
  idx | the index to find.

Returns
  a pointer to the list item, or NULL if the index is invalid or the list is empty.

## stp_list_get_item_by_long_name()

stp_list_item_t* stp_list_get_item_by_long_name | ( | const stp_list_t * | list,
|  | const char * | long_name
| ) |  |

Find an item in a list by its long name.

Parameters

  list | the list to use.
  long_name | the long name to find.

Returns
  a pointer to the list item, or NULL if the long name is invalid or the list is empty.

## stp_list_get_item_by_name()

stp_list_item_t* stp_list_get_item_by_name | ( | const stp_list_t * | list,
|  | const char * | name
| ) |  |

Find an item in a list by its name.

Parameters

  list | the list to use.
  name | the name to find.

Returns
  a pointer to the list item, or NULL if the name is invalid or the list is empty.

## stp_list_get_length()

int stp_list_get_length | ( | const stp_list_t * | list | ) |

Get the length of a list.

Parameters

  list | the list to use.

Returns
  the list length (number of list items).

## stp_list_get_long_namefunc()

stp_node_namefunc stp_list_get_long_namefunc | ( | const stp_list_t * | list | ) |

Get a list node long name function.

Parameters

  list | the list to use.

Returns
  the function previously set with stp_list_set_long_namefunc, or NULL if no function has been set.

## stp_list_get_namefunc()

stp_node_namefunc stp_list_get_namefunc | ( | const stp_list_t * | list | ) |

Get a list node name function.

Parameters

  list | the list to use.

Returns
  the function previously set with stp_list_set_namefunc, or NULL if no function has been set.

## stp_list_get_sortfunc()

stp_node_sortfunc stp_list_get_sortfunc | ( | const stp_list_t * | list | ) |

Get a list node sort function.

Parameters

  list | the list to use.

Returns
  the function previously set with stp_list_set_sortfunc, or NULL if no function has been set.

## stp_list_get_start()

stp_list_item_t* stp_list_get_start | ( | const stp_list_t * | list | ) |

Find the first item in a list.

Parameters

  list | the list to use.

Returns
  a pointer to the first list item, or NULL if the list is empty.

## stp_list_item_create()

int stp_list_item_create | ( | stp_list_t * | list,
|  | stp_list_item_t * | next,
|  | const void * | data
| ) |  |

Create a new list item.

Parameters

  list | the list to use.
  next | the next item in the list, or NULL to insert at the end of the list.
  data | the data the list item will contain.

Returns
  0 on success, 1 on failure (if data is NULL, for example).

## stp_list_item_destroy()

int stp_list_item_destroy | ( | stp_list_t * | list,
|  | stp_list_item_t * | item
| ) |  |

Destroy a list item.

Parameters

  list | the list to use.
  item | the item to destroy.

Returns
  0 on success, 1 on failure.

## stp_list_item_get_data()

void* stp_list_item_get_data | ( | const stp_list_item_t * | item | ) |

Get the data associated with a list item.

Parameters

  item | the list item to use.

Returns
  the data associated with item.

## stp_list_item_next()

stp_list_item_t* stp_list_item_next | ( | const stp_list_item_t * | item | ) |

Get the next item in the list.

Parameters

  item | the item to start from.

Returns
  a pointer to the list item following from item, or NULL if item is the end of the list.

## stp_list_item_prev()

stp_list_item_t* stp_list_item_prev | ( | const stp_list_item_t * | item | ) |

Get the previous item in the list.

Parameters

  item | the item to start from.

Returns
  a pointer to the list item prior to item, or NULL if item is the start of the list.

## stp_list_item_set_data()

int stp_list_item_set_data | ( | stp_list_item_t * | item,
|  | void * | data
| ) |  |

Set the data associated with a list item.

Warning
  Note that if a sortfunc is in use, changing the data will NOT re-sort the list!

Parameters

  item | the list item to use.
  data | the data to set.

Returns
  0 on success, 1 on failure (if data is NULL).

## stp_list_node_free_data()

void stp_list_node_free_data | ( | void * | item | ) |

Free node data allocated with stp_malloc.

This function is indended for use as an stp_node_freefunc, which uses stp_free to free the node data.

Parameters

  item | the node data to free

## stp_list_set_copyfunc()

void stp_list_set_copyfunc | ( | stp_list_t * | list,
|  | stp_node_copyfunc | copyfunc
| ) |  |

Set a list node copy function.

This callback function will be called whenever a list item is copied. Its intended use is for automatic object copying (since C lacks a copy constructor).

Parameters

  list | the list to use.
  copyfunc | the function to set.

## stp_list_set_freefunc()

void stp_list_set_freefunc | ( | stp_list_t * | list,
|  | stp_node_freefunc | freefunc
| ) |  |

Set a list node free function.

This callback function will be called whenever a list item is destroyed. Its intended use is for automatic object destruction and any other cleanup required.

Parameters

  list | the list to use.
  freefunc | the function to set.

## stp_list_set_long_namefunc()

void stp_list_set_long_namefunc | ( | stp_list_t * | list,
|  | stp_node_namefunc | long_namefunc
| ) |  |

Set a list node long name function.

This callback function will be called whenever the long name of a list item needs to be determined. This is used to find list items by long name.

Parameters

  list | the list to use.
  long_namefunc | the function to set.

## stp_list_set_namefunc()

void stp_list_set_namefunc | ( | stp_list_t * | list,
|  | stp_node_namefunc | namefunc
| ) |  |

Set a list node name function.

This callback function will be called whenever the name of a list item needs to be determined. This is used to find list items by name.

Parameters

  list | the list to use.
  namefunc | the function to set.

## stp_list_set_sortfunc()

void stp_list_set_sortfunc | ( | stp_list_t * | list,
|  | stp_node_sortfunc | sortfunc
| ) |  |

Set a list node sort function.

This callback function will be called to determine the sort order for list items in sorted lists.

Parameters

  list | the list to use.
  sortfunc | the function to set.