libtools Documentation

Transcription

1 libtools Documentation Release 0.1 Thibaut DIRLIK January 26, 2017

2

3 Contents 1 Documentation Compiling and installing Arrays Lists i

4 ii

5 The libtools library is a user-focused, easy to use and well documented C library which provides simple containers (lists, arrays and hash), string manipulating functions, and much more. Performance is not our main goal. We really want libtools to be easy to use so you can start using it in a few minutes, and enjoy its simplicity. If you are looking for a full-featured and performance oriented library, take a look at GLib, but it s really bigger and more complicated. Note: Currently, libtools only supports Linux. It should compile correctly with any recent version of gcc or clang. We are open to contributions on the Github page of the project. Contents 1

6 2 Contents

7 CHAPTER 1 Documentation 1.1 Compiling and installing Installing scons To build libtools, you need to install SCons, which is a simple build system based on Python. Most linux distributions provides a package for it (like sudo apt-get install scons on Ubuntu). Please read the scons documentation if you need more informations about installing scons Getting the source code You can download a specific release on github, or you can clone the repository to get the last version: $ git clone This will create a directory libtools in your current directory Compiling To compile libtools in release mode, just type: $ scons The library is then avaiable in the build directory. Compiling options You can pass some options to scons: tests=1 - Build unit tests, in build/tests debug=1 - Build libtools in debug mode, enabling assertions and debugging symbols. static=1 - Creates a static version of libtools. Example: $ scons tests=1 debug=1 static=1 3

8 1.1.4 Cleaning If you need to clean the build, you can either delete the build directory, or run the scons -c command, with the same options you used for building. 1.2 Arrays In libtools, the array_t is a basic array of void*. Unlike basic C arrays, it will dynamically resize when you add elements to it (doubling its size every time it s resized): /* Creates a new array. You can use array_new_sized() method if you * want to specify the initial size, else a default value is used. */ array_t *a = array_new(); /* You can use array_append() or array_insert() to add elements in the * array. The array_set() method let you update an existing index. */ array_append(a, "Hello"); array_append(a, "World"); array_set(a, 1, "people!"); /* The array_size() method returns the number of elements in the array. */ for (size_t i = 0; i < array_size(a); i++) { printf("elem %zu: %s\n", i, array_get(a, i)); } /* Finally, free the array (not its data!) */ array_destroy(a); Arrays are very fast containers if you need to access elements by index. Resizing the array have a cost, which is amortized by doubling its size each time. Using array_new_sized() is a good idea to avoid resizing, when you know how much elements your array might contains (approximatively). However, removing or inserting elements inside the array will move all elements, and is an expensive operation. If you plan to do a lot of insertion or removal, you should think about using a linked list. Note: Like C arrays, libtools arrays are 0-indexed. Warning: When compiled in debug mode, their is an assert call to check that the positions passed to array function are valid (which means you don t try to access data outside the array). However, there is absolutely no check in release mode, and you could corrupt memory The array_t type Warning: You should not access these struct members directly. Use available functions to manipulate arrays. They are documented for general purpose. array_t You will never have to access these struct members, but they are documented for general purpose. Use functions (most are inlined, so it s fast). 4 Chapter 1. Documentation

9 void** data This C array will contain the data. size_t data_size This is the current size of the data array. size_t len This is the number of elements currently in the array Creates a new array with array_new() or array_new_sized() array_t* array_new() Creates a new array and returns a pointer to the allocated structure. This functions returns NULL in case of failure (if malloc() fails). array_t* array_new_sized(size_t size) Same as array_new() except that you can specify the initial size of the array. This is useful if you already know how much elements will be stored, so it won t have to reallocate memory Insert new elements with array_append() or array_insert() int array_append(array_t* array, const void* element) This function appends element at the end of the array, resizing the array if needed. If the array is resized, this function could return -1 because of realloc() failure. int array_insert(array_t* array, size_t position, const void* element) This function let you insert an element at any position. All the elements after position will move to the right, and the new element will be inserted at the position. If the array is resized, this function could return -1 because of realloc() failure Remove elements with array_remove() void array_remove(array_t* array, size_t position) Removes the element at the given position Retrieve and update elements with array_get() and array_set() void array_set(array_t *array, size_t position, const void *element) Sets the element at the position to element. The position must contains an existing element. You can t use this function to insert a new element. void* array_get(array_t *array, size_t position) Returns the element at the specified position Get the number of elements with array_size() size_t array_size(array_t *array) Returns the number of elements in the array Arrays 5

10 1.2.7 Destroy an array with array_destroy() and array_destroy_free() void array_destroy(array_t *array) Destroy the specified array. void array_destroy_free(array_t *array) Destroy the specified array and also call free() on all its element. 1.3 Lists Libtools provides a list_t type, which is an easy-to-use doubly linked list implementation. Unlike arrays, inserting an elements in a list is a fast and constant O(1) operation. Accessing first or last element is also fast and constant operation. However, accessing an element by index requires to iterate over the list, and is a O(n) operation. Searching an element is also a O(n) operation. Here is a simple example: /* Creates a new list. */ list_t* list = list_new(); /* Append elements at the end of the list. */ list_append(list, "elem1"); list_append(list, "elem2"); /* Insert an element at the begin of the list. */ list_prepend(list, "elem0"); /* Iterates over the list, and print the value. */ list_each(char, elem, list) { printf("%s\n", elem); } /* Destroy the list */ list_destroy(list); Internally, each element of a list is a list_node_t, containing a list_node_t.data pointer. When you add an element to a list, a new list_node_t object containing a pointer to your data is allocated and added to the list. Multiple nodes can reference the same data. The list_t structure contains a reference to the first and last list_node_t of the list list_t and list_node_t types Warning: You should not access these struct members directly. Use available functions to manipulate lists. They are documented for general purpose. list_t list_node_t* first A pointer to the first node of the list. 6 Chapter 1. Documentation

11 list_node_t* last A pointer to the last node of the list. size_t size The number of elements in the list. compare_fn_t compare_fn A pointer to the function used to compare elements. This function is used when you search the node containing a specified data. The default function just compare data address. list_node_t void* data A pointer to the data associated to a node. list_node_t* next A pointer to the next element in the list. The is NULL if it s the last node. list_node_t* prev A pointer to the previous element in the list. The is NULL if it s the first node Comparaison function Because you can store void* pointers as data in the list, we can t know how to compare you data. But some list function needs to compare them. For example, when you call list_find(), you pass the data you are looking for, and list_find() will iterate over the list and call the comparaison function on every item until one which is equal to the one you passed is found. The comparaison function must be a function with the following signature: int some_comparaison_function(const void* data1, const void* data2); Exactly like the well known strcmp(), it must returns -1 if data1 is lesser than data2, 0 if they are equal, and 1 if data1 is greater than data2. The default comparaison function simply compares the pointer address of your objects. Warning: Nothing prevent you from storing objects of differents types in your list. If you do so, make sure your comparaison function can handle this correctly Creates a new list with list_new() and friends list_t* list_new() Creates a new list and returns a pointer to the allocated structure. This functions returns NULL in case of failure (if malloc() fails). list_t* list_new_str() Same as list_new() except that it uses strcmp() as a comparaison function. This is a useful shortcut if you use lists of strings (char*). list_t* list_new_custom(compare_fn_t func) Same as list_new() except you can explicitly set the comparaison function Lists 7

12 1.3.4 Add elements with list_append(), list_insert() and list_prepend() These functions return NULL if malloc() failed, or the internal list_node_t which has been created to store your data. In most case you won t need it. list_node_t* list_append(list_t *list, const void *data) Appends the specified data at the end of the list. list_node_t* list_insert(list_t* list, size_t position, const void* data) Insert the specified data at the specified position. This function iterates over the list up to the specified position, so inserting near the end is longer than inserting near the begin. list_node_t* list_prepend(list_t* list, const void *data) Insert the specified data at the begin of you list Remove elements with list_remove(), list_remove_node() and list_remove_at() int list_remove(list_t *list, const void *data) This function will search your data in the list using list_find() and remove the first matching element from the list. Returns -1 if the element is not found in the list, 0 otherwise. void list_remove_node(list_t *list, list_node_t *node) Removes the specified node from the list. int list_remove_at(list_t *list, size_t position) Removes the element at the specified position. Returns -1 if the position is invalid, 0 otherwise Find elements with list_find() and list_find_node() ssize_t list_find(list_t *list, const void *data) This function will iterate over the list until it finds a node which contains the specified data. It uses the comparaison function to determine the equality of the data. Returns the data position in the list, or -1 if it s not found. list_node_t* list_find_node(list_t *list, const void *data) Same as list_find() except that it returns the data s list_node_t (or NULL) Retrieve elements with list_at(), list_node_at() and list_pop() These functions will return NULL if you pass an invalid position. void* list_at(list_t *list, size_t position) Returns the data associated to the node at position. list_node_t* list_node_at(list_t *list, size_t position) Returns the internal node at the specified position. void* list_pop(list_t* list) Remove the first node of the list, and returns its data. 8 Chapter 1. Documentation

13 1.3.8 Update elements with list_set() and list_node_set() int list_set(list_t* list, size_t position, const void* data) Sets the data of the node at the specified position to data. Returns 0 on succes or -1 if the position is invalid. void list_node_set(list_t* list, list_node_t* node, const void* data) Sets the data of the specified node to data Get the size of the list with list_size() size_t list_size(list_t* list) Returns the number of elements in the list Destroy a list with list_destroy() and list_destroy_free() size_t list_destroy(list_t* list) Destroy the list, freeing all nodes and the associated list_t structure. size_t list_destroy_free(list_t* list) Same as list_destroy() but also call free() on the data. Warning: You have to be sure that all your data has been allocated on the heap Lists 9

14 10 Chapter 1. Documentation

15 Index A array_append (C function), 5 array_destroy (C function), 6 array_destroy_free (C function), 6 array_get (C function), 5 array_insert (C function), 5 array_new (C function), 5 array_new_sized (C function), 5 array_remove (C function), 5 array_set (C function), 5 array_size (C function), 5 array_t (C type), 4 array_t.data (C member), 4 array_t.data_size (C member), 5 array_t.len (C member), 5 L list_append (C function), 8 list_at (C function), 8 list_destroy (C function), 9 list_destroy_free (C function), 9 list_find (C function), 8 list_find_node (C function), 8 list_insert (C function), 8 list_new (C function), 7 list_new_custom (C function), 7 list_new_str (C function), 7 list_node_at (C function), 8 list_node_set (C function), 9 list_node_t (C type), 7 list_node_t.data (C member), 7 list_node_t.next (C member), 7 list_node_t.prev (C member), 7 list_pop (C function), 8 list_prepend (C function), 8 list_remove (C function), 8 list_remove_at (C function), 8 list_remove_node (C function), 8 list_set (C function), 9 list_size (C function), 9 list_t (C type), 6 list_t.compare_fn (C member), 7 list_t.first (C member), 6 list_t.last (C member), 6 list_t.size (C member), 7 11