This is a basic single linked list library that provides all the functionalities that you will ever need on a list. You can also use this library to simulate stacks and queues. The philosofy behind this project is that the user should not deal with the internals of it. Thus the interface is a very easy one to use.
You should be aware of the fact that this library uses the C99
standard.
The documentation of the library is here:
http://cristid9.github.io/cd9list/annotated.html
In order to build the library on your local machine, you have to clone the project first. After that go in to the directory where the library resides and run the following commands:
make
sudo make install
make clean
The commands above will copy the library into the /usr/lib/
and the header
files of the library in the directory /usr/include/cd9/
.
In order to run the tests you must have the most recent version of the library installed(if you want the tests to be meaningful). After that run the following command:
make check
- Creating and deleting lists
The function that you will use in order to create a list is
cd9list_createList
. After you have done working with the list you will delete
the list using the function cd9list_deleteList
. The following snippet
ilutrates the concepts:
// creating_and_deleting_lists.c
#include <cd9/cd9list.h>
int main()
{
// This is how you initialize a list.
CD9List *list = cd9list_createList();
// This is how you destroy a list
cd9list_deleteList(list);
return 0;
}
To compile the source abouve run the following command:
gcc -Wall -std=c99 creating_and_deleting_lists.c -lcd9list
- Adding elements
The 2 main functions used for adding elements to an existing list are
append
and prepend
. There are also some other functions, but they work
similarly. You will pass to both of this functions a pointer to the value
you want to store in the list. Take a look at the following snippet:
// append_prepend_and_get.c
#include <stdio.h>
#include <cd9/cd9list.h>
int main()
{
CD9List *list = cd9list_createList();
// prepend adds an element at the end of the list.
list->append(list, "cat");
list->append(list, "dog");
list->append(list, "fish");
// So far, the list should look like this: ["cat", "dog", "fish"]
// Let's print the elements.
for(int i = 0; i < 3; i++) {
// Since the liste stores pointers to the elemnts as void pointers,
// it is necessary to typecast them before using it.
printf("%s ", (char *)list->get(list, i));
}
printf("\n");
// Now we will prepend an item.
list->prepend(list, "bunny");
printf("%s \n", (char *)list->get(list, 0));
// This is how we get the last element in the list.
printf("%s \n", (char *)list->get(list, list->length - 1));
cd9list_deleteList(list);
return 0;
}
To compile the above source file run the following command:
gcc -Wall append_prepend_and_get.c -std=c99 -lcd9list
- CD9FOREACH loop
The list provides a loop that will make your life easier while dealing with the datastructures in the library. Take a look at the following example that prints the elements in a list and then prints the elemnts in a reversed copy of the list(we used the copy functions just to ilustrate how functions similar to it works):
// foreach_example.c
#include <stdio.h>
#include <cd9/cd9list.h>
int main()
{
CD9List *list = cd9list_createList();
// Add some values to the list.
list->append(list, "car");
list->append(list, "pen");
list->append(list, "laptop");
// The simplest form of the CD9FOREACH loop will pass you at every
// iteration each value in the list. It is usefull when you want to iterate
// over a ist.
CD9FOREACH(list, value) {
printf("%s ", (char *)value);
}
printf("\n");
// The copy function returns a copy of the list.
// Be careful to delete the returned value.
CD9List *reversed = list->copy(list);
// Now we eill reverse the copy.
reversed->reverse(reversed);
// The second version of CD9FOREACH will pass the valu and the index of
// that value at each iteration. This process will be repeated at every
// iteration.
CD9FOREACH(reversed, value, index) {
printf("at index %zu we find %s\n", index, (char *)value);
}
cd9list_deleteList(reversed);
cd9list_deleteList(list);
return 0;
}
To compile the source above run:
gcc -Wall -std=c99 foreach_example.c -lcd9list
- *Copy functions
You maybe have noticed that there are some functions that have the Copy
suffix. In order to understand them it is very important to understand that
when you append/prepend/insert something into a list you actually add the
address of that value, not the value itself. There are no problems if the
lifetime of the list is no longer than the lifetime of that value. But, when
the lifetime of a value that you added to the list is over the reference
stored in the list will point to an irelevant value. Functions from *Copy
family will make a copy of the value you want to append and will store in the
list the address of that copy, thus you do not have to care about the lifetime
of the values anymore.