README.md

1 files changed, 130 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cf956f8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,130 @@
+# cminus
+Librarie utilitaire pour de la programmation de jeux ergonomique en C23.
+
+Conçu pour être utilisé appairé avec mon framework [TZR](https://kdx.re/cgit/tzr).
+
+## utilisation
+Ajoutez _.c et _.h à votre projet.
+
+Utilisez l'option `-include_.h` pour inclure _.h dans tous vos fichiers automatiquement.
+
+Vous aurez besoin du flag `-std=c2x`, cminus étant écrit pour le dernier standard C disponible.
+
+## types
+Les types suivants sont définis :
+```
+u8    -> uint8_t
+u16   -> uint16_t
+u32   -> uint32_t
+u64   -> uint64_t
+usize -> size_t
+i8    -> int8_t
+i16   -> int16_t
+i32   -> int32_t
+i64   -> int64_t
+isize -> ssize_t
+f32   -> float
+f64   -> double
+```
+
+## mémoire
+cminus redéfinit `malloc`, `calloc`, `realloc` et `free`
+afin de gérer les leaks et erreurs automatiquement.
+
+Appelez `void wdeinit()` pour automatiquement libérer toute la mémoire utilisée.
+
+```c
+int main() {
+    defer(wdeinit);
+
+    for (;;)
+        realloc(malloc(1000), 10000); // pas de gestion d'erreur !
+
+    // pas de leak !
+    return 0;
+}
+```
+
+## logging
+cminus ajoute les fonctions utilitaires `plog`, `perr`, `pwrn` pour du "debug printf" maintenable.
+`panic` est également disponible, affichant un message avant d'`exit(1)`.
+
+```c
+int main() {
+    plog("début de l'exécution");
+    if (SDL_Init(SDL_INIT_VIDEO) < 0)
+        panic("SDL_Init a fail"); // l'exécution se termine ici
+    defer(SDL_Quit);
+    plog("fin de l'exécution");
+    return 0;
+}
+```
+
+## assert
+Si la condition donnée à assert est fausse, une erreur est affichée et l'exécution se termine.
+
+```c
+FILE *fp = fopen("salut", "rb");
+assert(fp != nullptr);
+fclose(fp);
+```
+
+## defer
+Donnez une fonction avec signature `void fn(void)` à `defer`
+et elle sera automatiquement appelée à la sortie du programme
+(`return` du `main` ou `exit`).
+
+```c
+int main() {
+    defer(wdeinit);
+    assert(SDL_Init(SDL_INIT_VIDEO) == 0);
+    defer(SDL_Quit);
+
+    // faites votre vie...
+
+    return 0; // le cleanup est automatique ! wow
+}
+```
+
+## boucles
+
+### foreach
+`foreach` peut être utilisé afin de parcourir facilement des listes chainées
+
+```c
+foreach (e, root)
+    plog("%p", e->data);
+// s'étend en :
+for (auto e = root; e != nullptr; e = e->next)
+    plog("%p", e->data);
+```
+
+### rfor
+`rfor` est une manière courte d'écrire une boucle `for` à incrémentation basique.
+```c
+rfor (i, 4u, 42)
+    plog("%u", i);
+// s'étend en :
+for (auto i = 0u; i < 42; i++)
+    plog("%u", i);
+```
+
+### repeat
+`repeat` est une version courte du commun `for (int i = 0; i < X; i++)`
+```c
+repeat (i, 100u)
+    plog("%u", i);
+// s'étend en :
+for (unsigned i = 0; i < 100u; i++)
+     plog("%u", i);
+```
+
+### with
+Dangereux, lisez les sources si vous voulez le comprendre.
+Je veux pas être responsable de son utilisation.
+
+## mathématiques
+cminus ajoute quelques macros utilitaires
+(`max`, `min` et `appr` parmis d'autres)
+ainsi que des vecteurs et matrices,
+lisez `_.h` pour des détails.