From 4b37ab93b7c5e2b29e6718042311550b14c168aa Mon Sep 17 00:00:00 2001 From: Patrick Pelissier Date: Sat, 23 Dec 2017 00:03:34 +0100 Subject: [PATCH] Add some comments to better explain the source. --- example/ex-array01.c | 50 ++++++++++++++++++++++++++++++++++++++------ example/ex-array02.c | 36 ++++++++++++++++++++++++++----- 2 files changed, 75 insertions(+), 11 deletions(-) diff --git a/example/ex-array01.c b/example/ex-array01.c index 824e4b9d..b6eb793e 100644 --- a/example/ex-array01.c +++ b/example/ex-array01.c @@ -1,16 +1,35 @@ +/* + * All the definition are included in the file m-array.h + * You don't need to link with any library. + */ #include "m-array.h" -// Let's define an array of 'char *' named 'charp' +// First you need to instanciate your code for the type you want. +// This is done by calling the ARRAY_DEF macro with the name +// of the instance (here array_charp) and the type of the instance +// (here a pointer to char). +// This will create all types and functions to handle an +// array of char pointers. +// So let's define an array of 'char *' named 'array_charp' ARRAY_DEF (array_charp, char *) +// Ok everything has been defined. We can use everything like +// standard C function. int main(void) { - // Create an array list + // Declare an array of 'char *'. + // The used name for the container is the name concatened with '_t'. array_charp_t al; - // Initialize it + + // Like a good POD it needs to be explicitly initialized. + // Notice that we don't to pass the address of the variable as input + // to the function, but the variable. + // In fact, the array is automatically passed by reference to any + // function. array_charp_init(al); - // add elements to the array list + // Let's do some basic stuff: + // add some elements to the array list array_charp_push_back (al,"C"); array_charp_push_back (al,"A"); array_charp_push_back (al,"E"); @@ -20,14 +39,29 @@ int main(void) // Use iterator to display contents of al printf("Original contents of al: "); + // The iterator has also been defined with the ARRAY_DEF macro. + // All iterators of all containers follow the same logic, + // so that you can change the type of the container without + // changing your code. array_charp_it_t itr; + // You initialized the iterator to the first element of the container, + // iterate until not the end of the container is reached, + // while moving the iterator to the next element of the array. + // This is pretty overkill for an array, but this works for any container. for (array_charp_it(itr, al) ; !array_charp_end_p (itr); array_charp_next(itr)) { + // Let's get a reference to the data pointed by the iterator. + // You'll always get a pointer to this data, not the data itself. + // So you need an extra '*' to read the data. char *element = *array_charp_ref(itr); printf ("%s ", element); } printf("\n"); // Now, display the list backwards + // As the iterator as reached the end of the array, + // let's go back by one element, + // iterate until not the end of the container is reached, + // while moving the iterator to the previous element of the array. printf("Array backwards: "); for (array_charp_previous (itr) ; !array_charp_end_p (itr); array_charp_previous(itr)) { char *element = *array_charp_ref(itr); @@ -35,15 +69,19 @@ int main(void) } printf("\n"); - // For array, we can also iterate over the integer + // As it is an array, we can also iterate using a standard integer: printf("Array Direct: "); for(size_t i = 0 ; i < array_charp_size(al); ++i) { + // Like for getting a reference of an iterator + // the get operator returns a pointer to the data. + // This allows handling non-copying type within the container + // (like array). char *element = *array_charp_get(al, i); printf ("%s ", element); } printf("\n"); - // Clear the array + // Like POD, we need to clear the array explicitly array_charp_clear(al); return 0; } diff --git a/example/ex-array02.c b/example/ex-array02.c index 75d0746a..b0801dd5 100644 --- a/example/ex-array02.c +++ b/example/ex-array02.c @@ -1,14 +1,31 @@ +// This is the same example as ex-array01.c +// It uses some macros to simplify the writing of the code. +// So it is a shorter version of the first example. #include "m-array.h" -// Let's define an array of 'char *' named 'charp' +// Let's define an array of 'char *' named 'array_charp' ARRAY_DEF (array_charp, char *) -// Let's register globaly the oplist of array_charp -#define M_OPL_array_charp_t() ARRAY_OPLIST(array_charp) +// Let's register globaly the oplist of array_charp +// This is done by defining a macro named M_OPL_ and the type +// of the containern, like this: +#define M_OPL_array_charp_t() ARRAY_OPLIST(array_charp) +// An oplist is the interface published by the type. +// It contains all exported methods of the type +// (and which functions shall be called to handle them). +// It is both an input of the ARRAY_DEF macro (the last argument) +// if the type used to create the container has non-standard +// requirements (like pretty much any C structure) and an output +// (using ARRAY_OPLIST) which provides the updated oplist +// which will handle the container itself. int main(void) { - // Create an array list 'al' of type array_charp_t + // Create an array list 'al' of type 'array_charp_t' + // M_LET will check if a global oplist has been registered + // with the name array_charp_t, and if it finds it, will + // define the type, initializes it and clears it after + // it disappears from the bracket: M_LET (al, array_charp_t) { // add elements to the array list array_charp_push_back (al,"C"); @@ -20,7 +37,16 @@ int main(void) // Display contents of al printf("Original contents of al: "); - // For each element of the array al + // M_EACH is a macro which iterates over a container. + // It first argument is the name of the created variable + // which will be a pointer to one element of the container, + // al is the container to iterate, + // the last argument is either the type of the container + // (if a global oplist has been registered) or is the oplist + // of the container (if none). + // Indeed the macro needs to access the methods of the container + // to iterate over the container. + // So for each element of the array al for M_EACH(element, al, array_charp_t) { printf ("%s ", *element); }