Doubly-Linked Lists

Doubly-Linked Lists — linked lists

Synopsis

lt_list_t *         lt_list_append                      (lt_list_t *list,
                                                         lt_pointer_t data,
                                                         lt_destroy_func_t func);
lt_list_t *         lt_list_delete                      (lt_list_t *list,
                                                         lt_pointer_t data);
lt_list_t *         lt_list_delete_link                 (lt_list_t *list,
                                                         lt_list_t *link_);
lt_list_t *         lt_list_find                        (lt_list_t *list,
                                                         const lt_pointer_t data);
lt_list_t *         lt_list_find_custom                 (lt_list_t *list,
                                                         const lt_pointer_t data,
                                                         lt_compare_func_t func);
lt_list_t *         lt_list_first                       (lt_list_t *list);
void                lt_list_free                        (lt_pointer_t data);
lt_list_t *         lt_list_last                        (lt_list_t *list);
size_t              lt_list_length                      (const lt_list_t *list);
lt_list_t *         lt_list_new                         (void);
lt_list_t *         lt_list_next                        (const lt_list_t *list);
lt_list_t *         lt_list_pop                         (lt_list_t *list,
                                                         lt_pointer_t *data);
lt_list_t *         lt_list_prepend                     (lt_list_t *list,
                                                         lt_pointer_t data,
                                                         lt_destroy_func_t func);
lt_list_t *         lt_list_previous                    (const lt_list_t *list);
lt_list_t *         lt_list_ref                         (lt_list_t *list);
lt_list_t *         lt_list_remove                      (lt_list_t *list,
                                                         lt_pointer_t data);
lt_list_t *         lt_list_sort                        (lt_list_t *list,
                                                         lt_compare_func_t func);
                    lt_list_t;
void                lt_list_unref                       (lt_list_t *list);
lt_pointer_t        lt_list_value                       (const lt_list_t *list);

Description

The lt_list_t object and its associated functions provide a standard doubly-linked list data structure.

Details

lt_list_append ()

lt_list_t *         lt_list_append                      (lt_list_t *list,
                                                         lt_pointer_t data,
                                                         lt_destroy_func_t func);

Adds a new element on to the end of the list.

list :

a lt_list_t.

data :

the data for the new element

func :

the call back function to destroy data or NULL. [scope async]

Returns :

the new start of the lt_list_t.

lt_list_delete ()

lt_list_t *         lt_list_delete                      (lt_list_t *list,
                                                         lt_pointer_t data);

Removes an element from a lt_list_t. If two elements contain the same data, only the first is removed. If none of the elements contain the data, the lt_list_t is unchanged.

list :

a lt_list_t.

data :

the data of the element to remove.

Returns :

the new start of the lt_list_t.

lt_list_delete_link ()

lt_list_t *         lt_list_delete_link                 (lt_list_t *list,
                                                         lt_list_t *link_);

Removes the node link_ from the list and frees it.

list :

a lt_list_t

link_ :

node to delete from list

Returns :

the new head of list

lt_list_find ()

lt_list_t *         lt_list_find                        (lt_list_t *list,
                                                         const lt_pointer_t data);

Finds the element in a lt_list_t which contains the given data.

list :

a lt_list_t

data :

the element data to find

Returns :

the found lt_list_t element, or NULL if it's not found

lt_list_find_custom ()

lt_list_t *         lt_list_find_custom                 (lt_list_t *list,
                                                         const lt_pointer_t data,
                                                         lt_compare_func_t func);

Finds an element in a lt_list_t, using a supplied function to find the desired element. It iterates over the list, calling the given function which should return 0 when the desired element is found. The function takes two const lt_pointer_t arguments, the lt_list_t element's data as the first argument and the given data.

list :

a lt_list_t

data :

the data passed to the function

func :

the function to call for each element. It should return 0 when the desired element is found. [scope call]

Returns :

the found lt_list_t element, or NULL if it's not found

lt_list_first ()

lt_list_t *         lt_list_first                       (lt_list_t *list);

Gets the first element in a lt_list_t.

list :

a lt_list_t.

Returns :

the first element in the lt_list_t or NULL if the lt_list_t has no elements. [transfer none]

lt_list_free ()

void                lt_list_free                        (lt_pointer_t data);

Frees all of the memory used by a lt_list_t.

data :

a lt_list_t.

lt_list_last ()

lt_list_t *         lt_list_last                        (lt_list_t *list);

Gets the last element in a lt_list_t.

list :

a lt_list_t.

Returns :

the last element in the lt_list_t or NULL if the lt_list_t has no elements. [transfer none]

lt_list_length ()

size_t              lt_list_length                      (const lt_list_t *list);

Gets the number of elements in a lt_list_t.

list :

a lt_list_t.

Returns :

the number of elements in the lt_list_t.

lt_list_new ()

lt_list_t *         lt_list_new                         (void);

Creates lt_list_t object. this function is protected and not supposed to use in applications directly. Use lt_list_append() or lt_list_prepend() with NULL as the first argument to newly allocate the object.

Returns :

a newly allocated lt_list_t. it has to be freed with lt_list_unref(). [transfer full]

lt_list_next ()

lt_list_t *         lt_list_next                        (const lt_list_t *list);

Gets the next element in a lt_list_t.

list :

a lt_list_t.

Returns :

the next element, or NULL if there are no more elements. [transfer none]

lt_list_pop ()

lt_list_t *         lt_list_pop                         (lt_list_t *list,
                                                         lt_pointer_t *data);

Sets the data in the first element to data and drop the element.

list :

a lt_list_t

data :

a pointer to set the data in the first element

Returns :

the new head of list.

lt_list_prepend ()

lt_list_t *         lt_list_prepend                     (lt_list_t *list,
                                                         lt_pointer_t data,
                                                         lt_destroy_func_t func);

Adds a new element on to the start of the list.

list :

a lt_list_t

data :

the data for the new element

func :

the call back function to destroy data or NULL. [scope async]

Returns :

the new start of the lt_list_t.

lt_list_previous ()

lt_list_t *         lt_list_previous                    (const lt_list_t *list);

Gets the previous element in a lt_list_t.

list :

a lt_list_t.

Returns :

the previous element, or NULL if there are no previous elements. [transfer none]

lt_list_ref ()

lt_list_t *         lt_list_ref                         (lt_list_t *list);

Increases the reference count of list.

list :

a lt_list_t.

Returns :

the same list object. [transfer none]

lt_list_remove ()

lt_list_t *         lt_list_remove                      (lt_list_t *list,
                                                         lt_pointer_t data);

Removes an element from a lt_list_t. If two elements contain the same data, only the first is removed. If none of the elements contain the data, the lt_list_t is unchanged. This works similar to lt_list_delete() though, the difference is this won't calls the finalizer to destroy the data in the element.

list :

a lt_list_t.

data :

the data of the element to remove.

Returns :

the new start of the lt_list_t.

lt_list_sort ()

lt_list_t *         lt_list_sort                        (lt_list_t *list,
                                                         lt_compare_func_t func);

Sorts a lt_list_t using the given comparison function.

list :

a lt_list_t

func :

the comparison function used to sort the lt_list_t. This function is passed the data from 2 elements of the lt_list_t and should return 0 if they are equal, a negative value if the first element comes before the second, or a positive value if the first element comes after the second. [scope call]

Returns :

the start of the sorted lt_list_t

lt_list_t

typedef struct _lt_list_t lt_list_t;

All the fields in the lt_list_t structure are private to the lt_list_t implementation.


lt_list_unref ()

void                lt_list_unref                       (lt_list_t *list);

Decreases the reference count of list. when its reference count drops to 0, the object is finalized (i.e. its memory is freed).

list :

a lt_list_t.

lt_list_value ()

lt_pointer_t        lt_list_value                       (const lt_list_t *list);

Gets a value in a lt_list_t.

list :

a lt_list_t.

Returns :

a pointer to be set to the lt_list_t. [transfer none]