wl_list man page

wl_list — Doubly-linked list.  

Synopsis

#include <wayland-util.h>

Public Member Functions

void wl_list_init (struct wl_list *list)
void wl_list_insert (struct wl_list *list, struct wl_list *elm)
void wl_list_remove (struct wl_list *elm)
int wl_list_length (const struct wl_list *list)
int wl_list_empty (const struct wl_list *list)
void wl_list_insert_list (struct wl_list *list, struct wl_list *other)

Data Fields

struct wl_list * prev
struct wl_list * next

Detailed Description

Doubly-linked list.

On its own, an instance of struct wl_list represents the sentinel head of a doubly-linked list, and must be initialized using wl_list_init(). When empty, the list head's next and prev members point to the list head itself, otherwise next references the first element in the list, and prev refers to the last element in the list.

Use the struct wl_list type to represent both the list head and the links between elements within the list. Use wl_list_empty() to determine if the list is empty in O(1).

All elements in the list must be of the same type. The element type must have a struct wl_list member, often named link by convention. Prior to insertion, there is no need to initialize an element's link - invoking wl_list_init() on an individual list element's struct wl_list member is unnecessary if the very next operation is wl_list_insert(). However, a common idiom is to initialize an element's link prior to removal - ensure safety by invoking wl_list_init() before wl_list_remove().

Consider a list reference struct wl_list foo_list, an element type as struct element, and an element's link member as struct wl_list link.

The following code initializes a list and adds three elements to it.

struct wl_list foo_list;

struct element {
        int foo;
        struct wl_list link;
};
struct element e1, e2, e3;

wl_list_init(&foo_list);
wl_list_insert(&foo_list, &e1.link);   // e1 is the first element
wl_list_insert(&foo_list, &e2.link);   // e2 is now the first element
wl_list_insert(&e2.link, &e3.link); // insert e3 after e2

The list now looks like [e2, e3, e1].

The wl_list API provides some iterator macros. For example, to iterate a list in ascending order:

struct element *e;
wl_list_for_each(e, foo_list, link) {
        do_something_with_element(e);
}

See the documentation of each iterator for details.

See also:

Member Function Documentation

int wl_list_empty (const struct wl_list * list)

Determines if the list is empty.

Parameters:

list List whose emptiness is to be determined

Returns:

1 if empty, or 0 if not empty

void wl_list_init (struct wl_list * list)

Initializes the list.

Parameters:

list List to initialize

void wl_list_insert (struct wl_list * list, struct wl_list * elm)

Inserts an element into the list, after the element represented by list. When list is a reference to the list itself (the head), set the containing struct of elm as the first element in the list.

Note:

If elm is already part of a list, inserting it again will lead to list corruption.

Parameters:

list List element after which the new element is inserted
elm Link of the containing struct to insert into the list

void wl_list_insert_list (struct wl_list * list, struct wl_list * other)

Inserts all of the elements of one list into another, after the element represented by list.

Note:

This leaves other in an invalid state.

Parameters:

list List element after which the other list elements will be inserted
other List of elements to insert

int wl_list_length (const struct wl_list * list)

Determines the length of the list.

Note:

This is an O(n) operation.

Parameters:

list List whose length is to be determined

Returns:

Number of elements in the list

void wl_list_remove (struct wl_list * elm)

Removes an element from the list.

Note:

This operation leaves elm in an invalid state.

Parameters:

elm Link of the containing struct to remove from the list

Field Documentation

struct wl_list* wl_list::next

Next list element

struct wl_list* wl_list::prev

Previous list element

Author

Generated automatically by Doxygen for Wayland from the source code.

Referenced By

The man pages wl_list_empty(3), wl_list_for_each(3), wl_list_for_each_reverse(3), wl_list_for_each_reverse_safe(3), wl_list_for_each_safe(3), wl_list_init(3), wl_list_insert(3), wl_list_insert_list(3), wl_list_length(3) and wl_list_remove(3) are aliases of wl_list(3).

Wed Aug 9 2017 Version 1.14.0 Wayland