documentation (#56)

documentation

README.md

@@ -6,10 +6,14 @@
 
 Portable, stand-alone C libraries and data structures. (C99)    
 
-Each folder is stand-alone and contains a single .h .c pair.  
-There is no build, copy .h .c files you want.
+This repo contains common libraries you may need when writing C applications.  
+Most of them are optimized for performance. e.g array, hashmap, queue, timer.
 
-Although I use on Linux mostly, CI runs on
+Each folder is stand-alone with a single header/source pair in it.  
+There is no build for libraries, just copy files you want.  
+e.g If you want array, copy sc_array.h and sc_array.c to your project.
+
+I use on Linux mostly but libraries are portable, CI runs on
 
 <pre>
 OS         : Linux, MacOS, FreeBSD and Windows  

array/README.md

@@ -83,4 +83,21 @@ int main(int argc, char *argv[])
     sc_array_destroy(p);
 }
 
+```
+
+Most probably you will hold array pointer in a struct anyway, so you have a  
+stable address of the pointer, "*numbers" might change but "numbers" is stable :
+
+```c
+struct my_app {
+    int *numbers;
+};
+
+void func(struct my_app* app)
+{
+    sc_array_add(app->numbers, 0);
+    sc_array_add(app->numbers, 1);
+    sc_array_add(app->numbers, 2);
+}
+
 ```

map/sc_map.h

@@ -108,10 +108,10 @@
     uint32_t sc_map_size_##name(struct sc_map_##name *map);                    \
                                                                                \
     /**                                                                        \
-     * Get map element count                                                   \
+     * Clear map                                                               \
      *                                                                         \
      * struct sc_map_str map;                                                  \
-     * uint32_t count = sc_map_size_str(&map);                                 \
+     * sc_map_clear_str(&map);                                                 \
      *                                                                         \
      * @param map map                                                          \
      */                                                                        \

queue/README.md

@@ -65,4 +65,19 @@ int main(int argc, char *argv[])
     some_function_to_add_elems(&q);
     sc_array_destroy(q);
 }
-```
+```
+
+Most probably you will hold queue pointer in a struct anyway, so you have a  
+stable address of the pointer, "*numbers" might change but "numbers" is stable :
+
+```c
+struct my_app {
+    int *numbers;
+};
+
+void func(struct my_app* app)
+{
+    sc_queue_add_last(app->numbers, 300);
+    sc_queue_add_last(app->numbers, 400);
+    sc_queue_add_last(app->numbers, 500);
+}

sc/sc.c

@@ -30,16 +30,9 @@
 #include <stdlib.h>
 #include <string.h>
 
-#if (SIZE_MAX == 0xFFFF)
-    #define SIZE_T_BITS 16
-#elif (SIZE_MAX == 0xFFFFFFFF)
-    #define SIZE_T_BITS 32
-#elif (SIZE_MAX == 0xFFFFFFFFFFFFFFFF)
-    #define SIZE_T_BITS 64
-#else
-    #error unknown size_t bits
-#endif
-
+/**
+ * RC4 random is based on https://sqlite.org/src/file?name=src/random.c
+ */
 void sc_rand_init(struct sc_rand *r, const unsigned char *init)
 {
     unsigned char t;