Another C library usable for creation and management of generic linked lists.
Once downloaded you have to compile it, so:
- open a shell (like the bash)
- enter in the directory just downloaded (
cd /path_to_gll/gll) - compile the sources (
make install) - optional: test the library (
make test) and report any issue ;)
If you want to remove the binaries generated just do make clean.
Now, if you want to use it in your projects copy the library (gll.o) in the /lib folder and move it where you need.
Remember to link it when you compile your programs!
For example: if you want to use it in your /foo.c program you have to tell gcc where it can find the library:
gcc foo.c -o executable -L /path_to_gll_library -lgll
n.b For now there is no possibility to use this library in "dynamic loading" as a shared .so object, but only in default "static mode". In the next versions I'll try to add this feature.
n.b. Indexes starts from 0.
Here you can find a short description of the functions this library offers and their signatures
##list
Create a brand new list.
list_t* list (int(*comp)(void*,void*), void(*mdea)(void*));
arguments:
- comp: pointer to an user defined integer function used to compare two elements
- mdea: pointer to an user defined void function used to deallocate an element
returns the pointer to the newly created (empty) list, on error returns NULL and sets errno to:
- EINVAL if one of the argumens is null
- ENOMEM if memory errors occour
In order to use this function properly you have first to define a structure that contains the data you want to use, for example:
typedef struct _item {
/*here goes your data fields*/
} item;
Then you have to provide a function to compare two different items and one to deallocate your items from the heap, here are two examples:
int compare (void *itm1, void *itm2) {
int i1 = itm1-> field1;
int i2 = itm2-> field1;
/* do your comparing stuff here */
return result;
}
int memory_deallocation (void *itm) {
item* it = (item*) itm;
/*free eventually heap allocated fields*/
free(it);
}
Return the length of a list.
int length (list_t* list);
arguments:
- list: pointer to the list
returns the length of the list, on error returns -1 and sets errno to EINVAL if the argument is null
Insert an element in the head of a list.
int push (list_t* list, void* data, int size);
arguments:
- list: pointer to the list
- data: pointer to the element
- size: size of the element
returns 0 if the function ends correctly, on error returns 1 and sets errno to:
- ENOMEM if memory error occours
- EINVAL if one of the arguments is null or zero
Append an element to the tail of a list.
int append (list_t* list, void* data, int size);
arguments:
- list: pointer to the list
- data: pointer to the element
- size: size of the element
returns 0 if the function terminates correctly, on error returns 1 and sets errno to:
- ENOMEM if memory error occours
- EINVAL if one of the arguments is null or zero
Return and remove the first element of a list.
void* pop (list_t*);
arguments:
- list: pointer to the list
returns the pointer to the first element of the list, on error returns NULL and sets errno to:
- ENODATA if the list is empty
- EINVAL if the argument is null
Return and remove the tail of a list.
void* cut (list_t* list);
arguments:
- list: pointer to the list
returns the pointer to the tail of the list, on error returns NULL and sets errno to:
- ENODATA if the list is empty
- EINVAL if the argument is null
Remove an element at the specified position from a list.
int remove_element (list_t* list, int pos);
arguments:
- list: pointer to the list
- pos: position of the element
returns 0 if the function ends correctly, on error returns 1 and sets errno to:
- EINVAL if one of the arguments is null or if pos < 0 or pos >= length(list)
- ENODATA if the list is empty
Returns a copy of the element at the specified position.
void* get (list_t* list, int pos);
arguments:
- list: pointer to the list
- pos: position of the element
returns the pointer to a copy of the element, on error returns NULL and sets errno to:
- EINVAL if one of the arguments is null or if pos < 0 or pos >= length(list)
- ENODATA if the list is empty
- ENOMEM if memory error occours
Set the element at the specified position.
int set (list_t* list, void* data, int pos);
arguments:
- list: pointer to the list
- data: pointer to the new element
- pos: position of the element
returns 0 if the function ends correctly, on error returns 1 and sets errno to:
- EINVAL if one of the arguments is null or if pos < 0 or pos >= length(list)
- ENODATA if the list is empty
Return the position of the first occourrence of an element.
int index_of (list_t* list, void* data);
arguments:
- list: pointer to the list
- data: pointer to the elements
returns the index of the element (count start from 0), on error returns -1 and sets errno to:
- ENODATA if the list is empty
- EINVAL if one of the arguments is null
n.b. this function performs a deep test so it will compare the data, not the pointers.
Destroy a list and all its elements.
void destroy (list_t* list);
arguments:
- list: pointer to the list
returns: void, errors are not checked like null arguments or errors while freeing memory
Return a new list where its elements are the result of an user provided function applied to all the elements of another list.
list_t* map (list_t* list, void*(*fun)(void*));
arguments:
- list: pointer to the list
- fun: pointer to the function
returns: the pointer fo the newly "mapped" list, on error returns NULL and sets errno to:
- EINVAL if one of the arguments is null
- ENODATA if the list is empty
In order to use this function you have to provide a special function that performs the requested operation on the elements: it have to takes an item, select the field, performs an operation on the data and return a new item with the data processed. For example: if you have an "int list" with your elements structured like this:
typedef struct _item {
int value;
} item;
...and you want to make a new list where all its elements have the same values of another list plus 10, then you have to define a function like this one:
void* plus10 (void* itm) {
item* i = (item*) itm;
item* new_i = (item*) malloc(sizeof(item));
/* error check ... */
new_i->value = i->value + 10;
return new_i;
}
Return a new list where its elements are the result of "filtering" another list using a function provided by the user.
list_t* filter (list_t*, int(*fun)(void*));
arguments:
- list: pointer to the list
- fun: pointer to the function
returns: the pointer fo the newly "filtered" list, on error returns NULL and sets errno to:
- EINVAL if one of the arguments is null
- ENODATA if the list is empty
In order to use this function you have to provide a special function that takes an item, examinates a field and choose if mantain that element or not. For example: if you have an "int list" with your elements structured like in the example above and you want to make a new list where all its elements are only the odd elements contained into another list, then you have to define a function like this one:
int isOdd (void* itm) {
item* i = (item*) itm;
/* error check ... */
return i->value % 2 != 0;
}
Currently under construction! Stay tuned!