Extended readme

README.md

@@ -0,0 +1,44 @@
+# RingBuf
+
+RingBuf is an allocator-agnostic, non-overwriting circular/ring buffer
+implementation in C99.  
+See: [Circular Buffer (Wikipedia)](https://en.wikipedia.org/wiki/Circular_buffer)
+
+## Features
+- Space Efficiency
+The code is designed to be portable and flexible. The inspiration initially
+came to me when designing a network driver. When operating in memory
+constrained environments, every byte is of upmost importance. Traditional
+metaprogramming such as templating in C++ and template metaprogramming in C,
+although generic has the side effect of expanding into discrete machine code
+specific for the specialization applied, essentially scaling (spatially) linear
+with the amount of different datatypes we specialize on. This implementation
+circumvents this by treating all data as a void pointer with a length. This
+implies **no deep copies**.
+
+- Allocator Agnostic
+Another common characteristic of memory constrained environments are
+custom malloc implementations and/or variations.
+    - Signatures
+    - Arena
+
+## Design considerations
+- Holding a reference to malloc internally would make a tidier interface
+- Passing a user-defined function for deep-copies would enable certain applications
+
+## Usage
+In essence:
+```c
+int value = 42;
+struct RingBuf rb;
+rb_init(&rb, 10, malloc, sizeof(int));
+rb_push_back(&rb, (void *)&data, memcpy);
+rb_pop_front(&rb, &value, memcpy);
+```
+Most of these functions return Enum result types. See:
+[ringbuf.h](./ringbuf.h).
+
+## Future Improvements
+- Trim the code
+- Reduce boilerplate in tests
+- Reduce the number of tests in exchange for better test fit