Add more comments

example/ex-algo03.c

@@ -3,20 +3,31 @@
 #include "m-algo.h"
 #include "m-string.h"
 
+/* Define a dictionnary (or hash_map or undordered_map)
+ * from a string_t to int */
 DICT_DEF2(dict, string_t, int)
+/* Register the oplist of this dictionnary globally */
 #define M_OPL_dict_t() DICT_OPLIST(dict, STRING_OPLIST, M_DEFAULT_OPLIST)
 
+/* Define an array of integer */
 ARRAY_DEF(vector_int, int)
+/* Register the oplist of this array of integer globally */
 #define M_OPL_vector_int_t() ARRAY_OPLIST(vector_int)
 
+/* Micro macro to detect if a string starts with the given pattern */
 #define start_with(pattern, item)                \
   string_start_with_str_p((item).key, (pattern))
+
+/* Micro macro to get the value of a pair of (key, value) */
 #define get_value(out, item) ((out) = (item).value)
 
 int main(void)
 {
   int s;
+  // Init keys as a vector_int_t, initialize it (and prepare its destruction)
   M_LET(keys, vector_int_t)
+    // Initialize m as a dictionnary and initialize it with the given database
+    // Initialize tmp as a dictionanry
     M_LET( (m, (STRING_CTE("foo"), 1), (STRING_CTE("bar"), 42), (STRING_CTE("bluez"), 7), (STRING_CTE("stop"), 789) ), tmp, dict_t) {
  
     /* Extract all elements of 'm' that starts with 'b' */

example/ex-algo04.c

@@ -2,20 +2,31 @@
 #include "m-array.h"
 #include "m-string.h"
 
+/* Define an array of int */
 ARRAY_DEF(vector_int, int)
+/* Register the oplist of this array of int globally */
 #define M_OPL_vector_int_t() ARRAY_OPLIST(vector_int)
 
+/* Set s (string_t) to the integer i */
 #define str_ui(s, i) string_printf(s, "%d", i)
+
+/* Concat two strings by insertion a '-' within them */
 #define str_cat(s1, s2) (string_cat_str(s1, "-"), string_cat(s1, s2))
 
 int main(void)
 {
+  // Let s be a string_t and initilize it.
   M_LET(s, string_t)
+    // Let v be a vector of integer and initialize it.
     M_LET( (v, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10), vector_int_t) {
     int sum, product;
     
+    // Compute the sum of theses integers.
     ALGO_REDUCE(sum, v, vector_int_t, add);
+
+    // Compute the product of theses integers.
     ALGO_REDUCE(product, v, vector_int_t, mul);
+
     /* Example of reduction with a transformation of the type from int to string_t */
     ALGO_REDUCE( (s, string_t), v, vector_int_t, str_cat, str_ui);
 

example/ex-array03.c

@@ -1,14 +1,14 @@
 #include <stdlib.h>
 #include "m-array.h"
 
-// Let's define an array of 'int' named 'int'
+// Let's define an array of 'int' named 'array_int'
 ARRAY_DEF(array_int, int)
 
 const int n = 100000;
 
 int main(void)
 {
-  // Declare and initilize the array
+  // Declare and initialize the array
   array_int_t x;
   array_int_init(x);
 

example/ex-bptree01.c

@@ -1,12 +1,16 @@
 #include "m-bptree.h"
 #include "m-string.h"
 
-// Define a map int -> string
+// Define a map int -> string named map_employee_id
+// The number 5 is the number of elements in a node of the B+TREE
 BPTREE_DEF2(map_employee_id, 5, int, string_t)
+// Register the oplist of this map globally.
 #define M_OPL_map_employee_id_t() BPTREE_OPLIST2(map_employee_id, M_DEFAULT_OPLIST, STRING_OPLIST)
 
-// Define a map string -> int
+// Define a map string -> int named map_employee_name
+// The number 5 is the number of elements in a node of the B+TREE
 BPTREE_DEF2(map_employee_name, 5, string_t, int)
+// Register the oplist of this map globally.
 #define M_OPL_map_employee_name_t() BPTREE_OPLIST2(map_employee_name, STRING_OPLIST, M_DEFAULT_OPLIST)
 
 int main(void)
@@ -14,7 +18,7 @@ int main(void)
   map_employee_id_t Employees;
   map_employee_id_init(Employees);
 
-  // Assign
+  // Assign the map with some data
   map_employee_id_set_at(Employees, 17425, STRING_CTE("Mike"));
   map_employee_id_set_at(Employees, 7147, STRING_CTE("Tango"));
   map_employee_id_set_at(Employees, 841, STRING_CTE("Charlie"));
@@ -35,6 +39,8 @@ int main(void)
     printf ("%d: %s\n", *(e->key_ptr), string_get_cstr(*(e->value_ptr)));
   }
 
+  // Now, let's go using some macros!
+
   // Let's create a reverse map
   M_LET(Employees_r, map_employee_name_t) {
 
@@ -51,9 +57,8 @@ int main(void)
       }
 
     // Print
-    printf("\nElisabeth has id = %d\n", *map_employee_name_get(Employees_r, STRING_CTE("Elisabeth")));
-    
-  }
+    printf("\nElisabeth has id = %d\n", *map_employee_name_get(Employees_r, STRING_CTE("Elisabeth")));    
+  } /* Employees_r is cleared beyond this point */
 
   map_employee_id_clear(Employees);
   return 0;

example/ex-dict01.c

@@ -5,7 +5,7 @@
 #include "m-string.h"
 
 // Define a dictionnary of string --> int
-// named 'str'
+// named 'dict_str'
 DICT_DEF2(dict_str, string_t, STRING_OPLIST, int, M_DEFAULT_OPLIST)
 
 int main(void)

example/ex-dict03.c

@@ -5,8 +5,9 @@
 #include "m-dict.h"
 #include "m-string.h"
 
-DICT_DEF2(dict_map, char, M_DEFAULT_OPLIST, int, M_DEFAULT_OPLIST)
-              
+// Define a dictionary (hashmap) from 'char' to 'int'
+DICT_DEF2(dict_map, char, int)
+             
 int main(void)
 {
   dict_map_t mp;
@@ -92,4 +93,3 @@ int main(void)
         }     
     }
 }
-    

example/ex-dict04.c

@@ -5,14 +5,23 @@
 /* program that reads text from standard-input, 
    and prints the total number of distinct words found in the text. 
 */
+
+/* Definition of a set (hashset) of unique string_t */
 DICT_SET_DEF(dict_str, string_t, STRING_OPLIST)
 
 int main(void)
 {
+  // Define word as a string_t
   M_LET(word, STRING_OPLIST)
-    M_LET(wordcount, DICT_SET_OPLIST(dict_str, STRING_OPLIST)) {
-    while (string_fget_word(word, " \t\n,.!;:?", stdin))
+  // Define wordcount as a set of string_t
+  M_LET(wordcount, DICT_SET_OPLIST(dict_str, STRING_OPLIST)) {
+    // Read a word from the standard input
+    while (string_fget_word(word, " \t\n,.!;:?", stdin)) {
+      // Push this word in the set.
+      // Do nothing if it already exists.
       dict_str_push(wordcount, word);
+    }
+    // Print the number of words of the standard input.
     printf ("Words: %zu\n", dict_str_size(wordcount));
   }
 }

example/ex-grep01.c

@@ -3,30 +3,50 @@
 #include "m-array.h"
 #include "m-dict.h"
 
+// Define an array of size_t
 ARRAY_DEF(array_size, size_t)
+// Register the oplist of this array globaly
 #define M_OPL_array_size_t() ARRAY_OPLIST(array_size)
+
+// Define a dictionary (hashmap) of string_t to array of size_t
 DICT_DEF2(map_pos, string_t, array_size_t)
+// Register the oplist of this dictionary (hashmap)
 #define M_OPL_map_pos_t() DICT_OPLIST(map_pos, STRING_OPLIST, ARRAY_OPLIST(array_size))
 
 int main(int argc, const char *argv[])
 {
-   if (argc == 2) {
-     M_LET(word, string_t)
-     M_LET(positions, map_pos_t) {
-        FILE *f = fopen(argv[1], "rt");
-        if (!f) return 1;
-        while (string_fget_word(word, " \t\n\r\"(),=", f)) {
-          array_size_t *array = map_pos_get_at(positions, word);
-          array_size_push_back(*array, (size_t)ftell(f) - string_size(word));
-        }
-        fclose(f);
+   if (argc != 2) {
+      printf("USAGE: %s filename\n", argv[0]);
+      exit(0);
+   }
 
-        for M_EACH(pair, positions, map_pos_t) {
+   // Define word as a string_t
+   M_LET(word, string_t)
+   // Define positions as a map of string_t-->array of size_t
+   M_LET(positions, map_pos_t) {
+      // Open the file
+      FILE *f = fopen(argv[1], "rt");
+      if (!f) return 1;
+
+      // While it reads some word from the file
+      while (string_fget_word(word, " \t\n\r\"(),=", f)) {
+         // Get the reference to this word in the dictionnary (or create it if needed)
+         array_size_t *array = map_pos_get_at(positions, word);
+         // Push the new offset to this word in the associated array
+         array_size_push_back(*array, (size_t)ftell(f) - string_size(word));
+      }
+
+      // Close the file
+      fclose(f);
+
+      // Print the words and where they are:
+      for M_EACH(pair, positions, map_pos_t) {
          string_fputs(stdout, pair->key);
          for M_EACH(pos, pair->value, array_size_t)
             printf(" %zu", *pos);
          printf("\n");
-        }
-     }
-   }
+         }
+      } // All created objects are destroyed beyond this point
+
+   return 0;
 }

example/ex-json01.c

@@ -11,10 +11,12 @@ TUPLE_DEF2(person,
            (age, int),
            (present, bool)
            )
+// Register the oplist of this tuple globaly
 #define M_OPL_person_t() TUPLE_OPLIST(person, M_DEFAULT_OPLIST, STRING_OPLIST, M_DEFAULT_OPLIST )
 
 // Let's define an array of person
 ARRAY_DEF(base, person_t)
+// Register the oplist of this array globaly
 #define M_OPL_base_t() ARRAY_OPLIST(base, M_OPL_person_t())
 
 // Let's read an array of person from the given JSON file
@@ -29,6 +31,7 @@ static void read(base_t base, const char filename[])
     fprintf(stderr, "ERROR: Cannot open file '%s'.\n", filename);
     exit(2);
   }
+
   // Initialize the serializer with the file
   m_serial_json_read_init(in, f);
   // Read the array
@@ -44,14 +47,17 @@ static void read(base_t base, const char filename[])
 
 int main(void)
 {
+  // Let's have base as a base_t
   M_LET(base, base_t) {
+    // Read the JSON file and fill-in base
     read(base, "ex-json01.json");
+    // Print the contents of base:
     printf ("List of presents:\n");
     for M_EACH(el, base, base_t) {
-        if ((*el)->present) {
-          printf("%s\n", string_get_cstr((*el)->surname));
-        }
+      if ((*el)->present) {
+        printf("%s\n", string_get_cstr((*el)->surname));
       }
+    }
   }
   exit(0);    
 }