## Doubly-Linked Lists

Doubly-Linked Lists — linked lists

## Functions

lt_list_t * | lt_list_new ()
lt_list_t * | lt_list_ref ()
void | lt_list_unref ()
void | lt_list_free ()
lt_list_t * | lt_list_first ()
lt_list_t * | lt_list_last ()
lt_list_t * | lt_list_previous ()
lt_list_t * | lt_list_next ()
lt_pointer_t | lt_list_value ()
size_t | lt_list_length ()
lt_list_t * | lt_list_append ()
lt_list_t * | lt_list_prepend ()
lt_list_t * | lt_list_remove ()
lt_list_t * | lt_list_delete ()
lt_list_t * | lt_list_delete_link ()
lt_list_t * | lt_list_find ()
lt_list_t * | lt_list_find_custom ()
lt_list_t * | lt_list_sort ()
lt_list_t * | lt_list_pop ()

## Types and Values

| lt_list_t

## Description

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

## Functions

### 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_ref ()

    lt_list_t *
    lt_list_ref (lt_list_t *list);

Increases the reference count of `list` .

#### Parameters

list | a lt_list_t. |

#### Returns

the same `list` object.

[transfer none]

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

#### Parameters

list | a lt_list_t. |

### lt_list_free ()

    void
    lt_list_free (lt_pointer_t data);

Frees all of the memory used by a lt_list_t.

#### Parameters

data | a lt_list_t. |

### lt_list_first ()

    lt_list_t *
    lt_list_first (lt_list_t *list);

Gets the first element in a lt_list_t.

#### Parameters

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

    lt_list_t *
    lt_list_last (lt_list_t *list);

Gets the last element in a lt_list_t.

#### Parameters

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

    lt_list_t *
    lt_list_previous (const lt_list_t *list);

Gets the previous element in a lt_list_t.

#### Parameters

list | a lt_list_t. |

#### Returns

the previous element, or `NULL` if there are no previous elements.

[transfer none]

### lt_list_next ()

    lt_list_t *
    lt_list_next (const lt_list_t *list);

Gets the next element in a lt_list_t.

#### Parameters

list | a lt_list_t. |

#### Returns

the next element, or `NULL` if there are no more elements.

[transfer none]

### lt_list_value ()

    lt_pointer_t
    lt_list_value (const lt_list_t *list);

Gets a value in a lt_list_t.

#### Parameters

list | a lt_list_t. |

#### Returns

a pointer to be set to the lt_list_t.

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

#### Parameters

list | a lt_list_t. |

#### Returns

the number of elements in the lt_list_t.

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

    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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

list | a lt_list_t |
data | a pointer to set the data in the first element |

#### Returns

the new head of `list` .

## Types and Values

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