Maintenance:

* update comments
* simplify code.

m-array.h

@@ -618,15 +618,9 @@
   {                                                                           \
     M_ARRA4_CONTRACT(v1);                                                     \
     M_ARRA4_CONTRACT(v2);                                                     \
-    size_t tmp = v1->size;                                                    \
-    v1->size = v2->size;                                                      \
-    v2->size = tmp;                                                           \
-    tmp = v1->alloc;                                                          \
-    v1->alloc = v2->alloc;                                                    \
-    v2->alloc = tmp;                                                          \
-    type *p = v1->ptr;                                                        \
-    v1->ptr = v2->ptr;                                                        \
-    v2->ptr = p;                                                              \
+    M_SWAP(size_t, v1->size, v2->size);                                       \
+    M_SWAP(size_t, v1->alloc, v2->alloc);                                     \
+    M_SWAP(type *, v1->ptr, v2->ptr);                                         \
     M_ARRA4_CONTRACT(v1);                                                     \
     M_ARRA4_CONTRACT(v2);                                                     \
   }                                                                           \

m-bitset.h

@@ -394,7 +394,6 @@ bitset_capacity(bitset_t v)
 static inline void
 bitset_swap_at (bitset_t v, size_t i, size_t j)
 {
-  M_B1TSET_CONTRACT (v);
   M_ASSERT_INDEX(i, v->size);
   M_ASSERT_INDEX(j, v->size);
 
@@ -402,7 +401,6 @@ bitset_swap_at (bitset_t v, size_t i, size_t j)
   bool j_val = bitset_get(v, j);
   bitset_set_at (v, i, j_val);
   bitset_set_at (v, j, i_val);
-  M_B1TSET_CONTRACT (v);
 }
 
 /* Swap the bitsets */
@@ -414,6 +412,8 @@ bitset_swap (bitset_t v1, bitset_t v2)
   M_SWAP (size_t, v1->size, v2->size);
   M_SWAP (size_t, v1->alloc, v2->alloc);
   M_SWAP (bitset_limb_ct *, v1->ptr, v2->ptr);
+  M_B1TSET_CONTRACT (v1);
+  M_B1TSET_CONTRACT (v2);
 }
 
 /* (INTERNAL) Left shift of the bitset (ptr+size) by 1 bit,
@@ -446,7 +446,8 @@ m_b1tset_rshift(bitset_limb_ct ptr[], size_t n, bitset_limb_ct carry)
   return carry;
 }
 
-/* Insert a new bit at position 'key' of value 'value' in the bitset */
+/* Insert a new bit at position 'key' of value 'value' in the bitset 'set'
+  shifting the set accordingly */
 static inline void
 bitset_push_at(bitset_t set, size_t key, bool value)
 {
@@ -467,7 +468,7 @@ bitset_push_at(bitset_t set, size_t key, bool value)
   size_t size = (set->size + M_B1TSET_LIMB_BIT - 1) / M_B1TSET_LIMB_BIT;
   M_ASSERT (size >= offset + 1);
   v = m_b1tset_lshift(&set->ptr[offset+1], size - offset - 1, carry);
-  // v is unused.
+  // v is unused as it should be zero.
   M_ASSERT(v == 0);
   (void) v;
   M_B1TSET_CONTRACT (set);
@@ -866,7 +867,8 @@ M_END_PROTECTED_CODE
 
 M_BEGIN_PROTECTED_CODE
 
-/* Output to a string_t the formatted text representation of a bitset */
+/* Output to a string_t 'str' the formatted text representation of the bitset 'set'
+   or append it to the strinf (append=true) */
 static inline void
 bitset_get_str(string_t str, const bitset_t set, bool append)
 {

m-i-list.h

@@ -622,6 +622,8 @@ typedef struct m_ilist_head_s {
     M_IL1ST_CONTRACT(name, e);                                                \
     struct m_ilist_head_s *d_item = d->name.next;                             \
     struct m_ilist_head_s *e_item = e->name.next;                             \
+    /* it is more complicated than other swap functions since                 \
+       we need to detect "cyclic" loop */                                     \
     d->name.next = e_item == &e->name ? &d->name : e_item;                    \
     e->name.next = d_item == &d->name ? &e->name : d_item;                    \
     d_item = d->name.prev;                                                    \

m-list.h

@@ -343,9 +343,7 @@
   {                                                                           \
     M_L1ST_CONTRACT(l);                                                       \
     M_L1ST_CONTRACT(v);                                                       \
-    struct M_C(name, _s) *tmp = *l;                                           \
-    *l = *v;                                                                  \
-    *v = tmp;                                                                 \
+    M_SWAP(struct M_C(name, _s) *, *l, *v);                                   \
     M_L1ST_CONTRACT(l);                                                       \
     M_L1ST_CONTRACT(v);                                                       \
   }                                                                           \

m-string.h

@@ -92,7 +92,14 @@ typedef enum string_fgets_e {
   STRING_READ_LINE = 0, STRING_READ_PURE_LINE = 1, STRING_READ_FILE = 2
 } string_fgets_t;
 
-/* Internal method to test if the string is stack based or heap based */
+/* Internal method to test if the string is stack based or heap based
+   We test if the ptr field points to the heap allocated buffer or not.
+   This is no particularly efficient from a memory point of view
+   (as we may reuse the pointer field to store some data)
+   but it should be enough for most of "small" strings as most
+   of the strings are less than 14 characters.
+   Moreover it generates quite efficient code.
+ */
 static inline bool
 m_str1ng_stack_p(const string_t s)
 {
@@ -107,6 +114,7 @@ m_str1ng_set_size(string_t s, size_t size)
   // Function can be called when contract is not fullfilled
   if (m_str1ng_stack_p(s)) {
     M_ASSERT (size < sizeof (string_heap_ct) - 1);
+    // The size of the string is stored as the last char of the buffer.
     s->u.stack.buffer[sizeof (string_heap_ct) - 1] = (char) size;
   } else
     s->u.heap.size = size;
@@ -416,7 +424,7 @@ string_init_move(string_t v1, string_t v2)
   M_STR1NG_CONTRACT (v1);
 }
 
-/* Swap the string */
+/* Swap the two strings v1 and v2 */
 static inline void
 string_swap(string_t v1, string_t v2)
 {
@@ -439,7 +447,7 @@ string_move(string_t v1, string_t v2)
   string_init_move(v1,v2);
 }
 
-/* Push a character in a string */
+/* Push the character 'c' in the string 'v' */
 static inline void
 string_push_back (string_t v, char c)
 {
@@ -484,7 +492,7 @@ string_cat(string_t v, const string_t v2)
 }
 
 /* Compare the string to the C string and
-  return the sort order (-1 if less, 0 if equal, 1 if greater) */
+  return the sort order (negative if less, 0 if equal, positive if greater) */
 static inline int
 string_cmp_str(const string_t v1, const char str[])
 {
@@ -494,7 +502,7 @@ string_cmp_str(const string_t v1, const char str[])
 }
 
 /* Compare the string to the other string and
-  return the sort order (-1 if less, 0 if equal, 1 if greater) */
+  return the sort order (negative if less, 0 if equal, positive if greater) */
 static inline int
 string_cmp(const string_t v1, const string_t v2)
 {
@@ -516,9 +524,11 @@ string_equal_str_p(const string_t v1, const char str[])
 static inline bool
 string_equal_p(const string_t v1, const string_t v2)
 {
-  /* string_equal_p can be called with one string which is an OOR value.
-     In case of OOR value, .ptr is NULL and .size is maximum.
-     It will detect a heap based string, and read size from heap structure.
+  /* string_equal_p can be called with (at most) one string which is an OOR value.
+     In case of OOR value, .ptr is NULL and .alloc is the maximum or the maximum-1.
+     As it will detect a stack based string, it will read the size from the alloc fied
+     as 0xFF or 0xFE. In both cases, the size cannot be equal to a normal string
+     so the test string_size(v1) == string_size(v2) is false in this case.
   */
   M_ASSERT(v1 != NULL);
   M_ASSERT(v2 != NULL);
@@ -583,9 +593,10 @@ string_search_rchar (const string_t v, char c, size_t start)
 {
   M_STR1NG_CONTRACT (v);
   M_ASSERT_INDEX (start, string_size(v)+1);
-  // NOTE: Can implement it in a faster way than the libc function
+  // NOTE: Can be implemented in a faster way than the libc function
   // by scanning backward from the bottom of the string (which is
-  // possible since we know the size)
+  // possible since we know the size).
+  // However, does it worth the effort?
   const char *p = M_ASSIGN_CAST(const char*,
                                 strrchr(string_get_cstr(v)+start, c));
   return p == NULL ? STRING_FAILURE : (size_t) (p-string_get_cstr(v));