axl main logo
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Modules Pages
axlList* axl_list_new ( axlEqualFunc  are_equal,
axlDestroyFunc  destroy_data 
)

Creates a new axlList, using provided handlers.

An axlList is a double linked list, with the hability to recognize elements inside its list by providing the are_equal function and the ability to release memory allocated by the data stored by providing a destroy_data handler.

The destroy handler is a optional value. If not provided, any automatic deallocation function will not provided.

The "are equal" handler is not optinal. You must provide it to make the list work. In the case you don't like a ordering feature you can provide an are equal that just return 0 when elements are equal and always -1 for the rest of the cases if element should be appended or 1 if the element should be prepended.

The list is not prepared to be managed at the same type by several threads. If the list is created and then used by several threads it will work properly. However, if several threads add and removes elements at the same time rainy days will come and you'll get funny behaviours.

To create the list you must provide two function that performs some minimal functions required by the list o properly order the data inside the list and how this data is deallocated (this is optional).

For example, to create a list that will hold strings dinamically allocated you can use:

1 axlList * list = axl_list_new (axl_list_equal_string, axl_free);

For a list that will holds integer values you can use: axl_list_equal_int.

Previous list will cause all strings inside to be deallocated once called to axl_list_free. If you don't like this, do not provide the deallocation function.

You can always use the following function to make the list to allways add all data at the end of the list: axl_list_always_return_1, which, as its names indicates, allways return 1, causing the item to be added at the end of the list. See axlEqualFunc documentation to know more about creating ordenation functions.

Now you have your list created, you can use the following functions to add items:

Once you have inserted some data, you can use the following piece of code to perform an iteration:

1 int iterator = 0;
2 while (iterator < axl_list_length (list)) {
3  // get the data at the given position
4  data = axl_list_get_nth (list, iterator);
5 
6  // update the iterator
7  iterator++;
8 }

However, it is preferred to use the axlListCursor, which is far more efficient. See the following function to get more information: axl_list_cursor_new.

In general, if you are going to perform a lookup for a single item you can use axl_list_lookup (by providing a handler) or axl_list_get_nth if you know the position.

Parameters
are_equalThe equal function to be used by the list to find and order elements inside the list. This function isn't optional. If you do not provide it, the list will not be created.
destroy_dataAn optional handler to destroy nodes in the case the list is unrefered.
Returns
A newly allocated list, that must be destroy by calling to axl_list_free.

Creating an equal element function (are_equal) or reusing one

The list created by this function needs an are_equal function. You can use one of the already available functions:

But also, you can build your own equal function by checking the implementation of these (above) functions and/or checking. All these functions uses the prototype defined by axlEqualFunc.

References axl_new, and axl_return_val_if_fail.

Referenced by axl_doc_get_list(), axl_dtd_validate(), axl_list_copy(), axl_node_get_childs(), axl_node_get_pi_target_list(), and axl_stream_link_full().