<commit_before>M\*LIB: a Generic type-safe Container Library in C language
==========================================================

Overview
--------

M\*LIB (M star lib) is a meta library allowing the programmer to use **generic but
type safe container** in pure C language, aka handling generic containers.
The objects within the containers can have proper constructor, destructor
(and other methods):
this will be handled by the library. This allows to construct fully
recursive objects (using container of container of objects).

This is more or less an equivalent to the C++ STL.

M\*LIB should be portable to any systems that support C99 (or C11
for some rare features).
Compatibility with C++ was not aimed (as the library is totally 
useless in C++ - use the STL instead) but is more or less kept.

M\*LIB is **only** composed of a set of headers.
There is no C file. Just put the header in the search path of your compiler,
and it will work.
So there is no dependency (except some other headers of M\*LIB).

One of M\*LIB's design key is to ensure safety. This is done by multiple means:

* in debug mode, the contracts of the function are checked, ensuring
that the data are not corrupted.
* very few casts are used within the library. Still the library can be used
with the greatest level of warnings by the compiler without
any aliasing warning.
* the genericity is not done directly by macro, but indirectly by making them
define inline functions with the proper prototypes: this allows
the calls to have proper warning checks and proper debugging.

M\*LIB should still be quite-efficient: even if the implementation may not always be state
of the art, there is no overhead in using this library rather than using
direct C low-level access: the compiler is able to **fully** optimize
the library calls
since all the functions are declared as inline and the library gives
the compiler some hints on how to optimize even further.

M\*LIB uses internally the 'malloc', 'realloc' and 'free' functions to handle
the memory pool. This behavior can be overridden.
M\*LIB default policy is to abort the 
program if there is a memory error. However, this behavior
can also be customized.

M\*LIB may use a lot of assertions in its implementation to ensure safety: 
it is highly recommended to properly define NDEBUG for released programs. 
Otherwise you may have a noticeable slow-down (up to a factor x10 in some cases).

M\*LIB is distributed under BSD-2 simplified license.

It is strongly advised not to read the source to know how to use the library
but rather read the examples or the tests.

Components
----------

The available containers which doesn't require the user structure to be modified are:

* m-array.h: header for creating array of generic type and of variable size,
* m-list.h: header for creating single-linked list of generic type,
* m-dict.h: header for creating generic dictionary of generic types,
* m-tuple.h: header for creating arbitrary tuple of generic type,
* m-rbtree.h: header for creating binary sorted tree (RED-BLACK),
* m-variant.h: header for creating arbitrary variant of generic type TODO,
* m-set.h: header for creating set TODO,
* m-btree.h: header for creating B-TREE TODO,

The available containers of M\*LIB for thread synchronization are:

* m-buffer.h: header for creating fixed-size queue (or stack) of generic type,
* m-pbuffer.h: header for creating fixed-size priority queue of generic type TODO,
* m-mbuffer.h: header for creating fixed-size merge queue of generic type TODO,
* m-snapshot: header for creating 'snapshot' buffer for passing data between a producer and multiple consumers running at different rates (thread safe). It ensures that the consumer only sees complete data with minimal lag, but the consumer doesn't expect to see every piece of data.
* m-shared.h: header for creating shared pointer of generic type.

The following containers are intrusive (You need to modify your structure):

* m-i-list.h: header for creating dual-linked intrusive list of generic type,
* m-i-shared.h: header for creating intrusive shared pointer of generic type (Thread Safe),


Other headers offering other functionality are:

* m-bitset.h: header for creating bit set,
* m-string.h: header for creating variable-length string,
* m-core.h: header for meta-programming with the C preprocessor.
* m-mutex.h: header for providing a very thin layer accross multiple implementation of mutex/threads.
* m-algo.h: header for providing various generic algorithms to the previous containers.
* m-register.h: header for static polymorphic TODO

Each containers define their iterators.


External Reference
------------------

Many other implementation of generic container libraries exist in C.
For example, a non exhaustive list can be:

* [KLIB](https://github.com/attractivechaos/klib)
* [SGLIB](http://sglib.sourceforge.net/)
* [GLIB](https://wiki.gnome.org/Projects/GLib)
* [GDB internal library](https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob;f=gdb/common/vec.h;h=41e41b5b22c9f5ec14711aac35ce4ae6bceab1e7;hb=HEAD)
* [UTHASH](http://troydhanson.github.io/uthash/index.html)
* [LIBNIH](https://github.com/keybuk/libnih)
* [CCL](http://www.cs.virginia.edu/~lcc-win32/ccl/ccl.html)
* [Generic-Container-Lib](https://github.com/Siapran/Generic-Container-Lib)
* [qlibc](http://wolkykim.github.io/qlibc/)
* [cello](http://libcello.org/)
* [Red-black tree implementation](http://www.canonware.com/rb/)
* [BSD tree.h](http://fxr.watson.org/fxr/source/sys/tree.h)
* [GDSL - The Generic Data Structures Library](http://home.gna.org/gdsl/)
* [LIBCONTAINER](http://www.agottem.com/libcontainer)
* [LIBCOLLECTION](https://bitbucket.org/manvscode/libcollections)

Each of theses can be classified into:

* Everything is a pointer to void,
* Macros are used to access structures in a generic way,
* Macros are used to generate C code.

M\*LIB's category is the last one. Some macros are also defined to access structure in a generic way, but they are optional.
M\*LIB main added value compared to other libraries is its op-list support allowing for proper recursive definition of function
(list of array of dictionary are perfectly supported by M\*LIB).

For the macro-preprocessing part, other libraries also exist, like:

* [P99](http://p99.gforge.inria.fr/p99-html/)
* [C99 Lambda](https://github.com/Leushenko/C99-Lambda)
* [MAP MACRO](https://github.com/swansontec/map-macro)
* [C Preprocessor Tricks, Tips and Idioms](https://github.com/pfultz2/Cloak/wiki/C-Preprocessor-tricks,-tips,-and-idioms)
* [CPP MAGIC](http://jhnet.co.uk/articles/cpp_magic)
 

How to use
----------

To use these data structures, you include the desired header,
instantiate the definition of the structure and its associated methods by using a macro _DEF.<commit_msg>Add new C generic container library reference.<commit_after>M\*LIB: a Generic type-safe Container Library in C language
==========================================================

Overview
--------

M\*LIB (M star lib) is a meta library allowing the programmer to use **generic but
type safe container** in pure C language, aka handling generic containers.
The objects within the containers can have proper constructor, destructor
(and other methods):
this will be handled by the library. This allows to construct fully
recursive objects (using container of container of objects).

This is more or less an equivalent to the C++ STL.

M\*LIB should be portable to any systems that support C99 (or C11
for some rare features).
Compatibility with C++ was not aimed (as the library is totally 
useless in C++ - use the STL instead) but is more or less kept.

M\*LIB is **only** composed of a set of headers.
There is no C file. Just put the header in the search path of your compiler,
and it will work.
So there is no dependency (except some other headers of M\*LIB).

One of M\*LIB's design key is to ensure safety. This is done by multiple means:

* in debug mode, the contracts of the function are checked, ensuring
that the data are not corrupted.
* very few casts are used within the library. Still the library can be used
with the greatest level of warnings by the compiler without
any aliasing warning.
* the genericity is not done directly by macro, but indirectly by making them
define inline functions with the proper prototypes: this allows
the calls to have proper warning checks and proper debugging.

M\*LIB should still be quite-efficient: even if the implementation may not always be state
of the art, there is no overhead in using this library rather than using
direct C low-level access: the compiler is able to **fully** optimize
the library calls
since all the functions are declared as inline and the library gives
the compiler some hints on how to optimize even further.

M\*LIB uses internally the 'malloc', 'realloc' and 'free' functions to handle
the memory pool. This behavior can be overridden.
M\*LIB default policy is to abort the 
program if there is a memory error. However, this behavior
can also be customized.

M\*LIB may use a lot of assertions in its implementation to ensure safety: 
it is highly recommended to properly define NDEBUG for released programs. 
Otherwise you may have a noticeable slow-down (up to a factor x10 in some cases).

M\*LIB is distributed under BSD-2 simplified license.

It is strongly advised not to read the source to know how to use the library
but rather read the examples or the tests.

Components
----------

The available containers which doesn't require the user structure to be modified are:

* m-array.h: header for creating array of generic type and of variable size,
* m-list.h: header for creating single-linked list of generic type,
* m-dict.h: header for creating generic dictionary of generic types,
* m-tuple.h: header for creating arbitrary tuple of generic type,
* m-rbtree.h: header for creating binary sorted tree (RED-BLACK),
* m-variant.h: header for creating arbitrary variant of generic type TODO,
* m-set.h: header for creating set TODO,
* m-btree.h: header for creating B-TREE TODO,

The available containers of M\*LIB for thread synchronization are:

* m-buffer.h: header for creating fixed-size queue (or stack) of generic type,
* m-pbuffer.h: header for creating fixed-size priority queue of generic type TODO,
* m-mbuffer.h: header for creating fixed-size merge queue of generic type TODO,
* m-snapshot: header for creating 'snapshot' buffer for passing data between a producer and multiple consumers running at different rates (thread safe). It ensures that the consumer only sees complete data with minimal lag, but the consumer doesn't expect to see every piece of data.
* m-shared.h: header for creating shared pointer of generic type.

The following containers are intrusive (You need to modify your structure):

* m-i-list.h: header for creating dual-linked intrusive list of generic type,
* m-i-shared.h: header for creating intrusive shared pointer of generic type (Thread Safe),


Other headers offering other functionality are:

* m-bitset.h: header for creating bit set,
* m-string.h: header for creating variable-length string,
* m-core.h: header for meta-programming with the C preprocessor.
* m-mutex.h: header for providing a very thin layer accross multiple implementation of mutex/threads.
* m-algo.h: header for providing various generic algorithms to the previous containers.
* m-register.h: header for static polymorphic TODO

Each containers define their iterators.


External Reference
------------------

Many other implementation of generic container libraries exist in C.
For example, a non exhaustive list can be:

* [KLIB](https://github.com/attractivechaos/klib)
* [SGLIB](http://sglib.sourceforge.net/)
* [GLIB](https://wiki.gnome.org/Projects/GLib)
* [GDB internal library](https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob;f=gdb/common/vec.h;h=41e41b5b22c9f5ec14711aac35ce4ae6bceab1e7;hb=HEAD)
* [UTHASH](http://troydhanson.github.io/uthash/index.html)
* [LIBNIH](https://github.com/keybuk/libnih)
* [CCL](http://www.cs.virginia.edu/~lcc-win32/ccl/ccl.html)
* [Generic-Container-Lib](https://github.com/Siapran/Generic-Container-Lib)
* [qlibc](http://wolkykim.github.io/qlibc/)
* [cello](http://libcello.org/)
* [Red-black tree implementation](http://www.canonware.com/rb/)
* [BSD tree.h](http://fxr.watson.org/fxr/source/sys/tree.h)
* [GDSL - The Generic Data Structures Library](http://home.gna.org/gdsl/)
* [LIBCONTAINER](http://www.agottem.com/libcontainer)
* [LIBCOLLECTION](https://bitbucket.org/manvscode/libcollections)
* [C GENERIC CONTAINER LIBRARY](https://github.com/ta5578/C-Generic-Container-Library)

Each of theses can be classified into:

* Everything is a pointer to void,
* Macros are used to access structures in a generic way,
* Macros are used to generate C code.

M\*LIB's category is the last one. Some macros are also defined to access structure in a generic way, but they are optional.
M\*LIB main added value compared to other libraries is its op-list support allowing for proper recursive definition of function
(list of array of dictionary are perfectly supported by M\*LIB).

For the macro-preprocessing part, other libraries also exist. For example:

* [P99](http://p99.gforge.inria.fr/p99-html/)
* [C99 Lambda](https://github.com/Leushenko/C99-Lambda)
* [MAP MACRO](https://github.com/swansontec/map-macro)
* [C Preprocessor Tricks, Tips and Idioms](https://github.com/pfultz2/Cloak/wiki/C-Preprocessor-tricks,-tips,-and-idioms)
* [CPP MAGIC](http://jhnet.co.uk/articles/cpp_magic)
 

How to use
----------

To use these data structures, you include the desired header,
instantiate the definition of the structure and its associated methods by using a macro _DEF.
{'fraction_non_alphanumeric': 0.09721109735673196, 'fraction_numerical': 0.006116653316828078, 'mean_word_length': 4.3795534665099884, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 19, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1477234', 'n_tokens_mistral': 3947, 'n_tokens_neox': 3769, 'n_words': 1756}