From d1bb6515965bc06da5ffac3ead70694557055866 Mon Sep 17 00:00:00 2001 From: Patrick Pelissier Date: Sat, 14 Jul 2018 14:03:17 +0200 Subject: [PATCH] Update doc. --- README.md | 40 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6fc9d93e..ae6c84af 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,13 @@ Other key designs are: * do not make users pay the cost of what they don't need. +Due to the nature of the C language, 'type safe' means that a proper warning +shall be generated by the compiler in case of wrong type passed as +arguments to the functions (and not errors). You can also request +the compiler to transform all warnings into errors to get proper errors +too if you want. + + 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 @@ -174,6 +181,13 @@ good type for the list of the defined type and to all the necessary functions needed to handle such type. It is heavily context dependent and can generate different code depending on it. You can use it as many times as needed to defined as many lists as you want. +The first argument of the macro is the name to use, e.g. the prefix which +shall be added to all generated functions and types. +The second argument of the macro is the type to embed within the container. +It can be any C type. +The third argument of the macro is optionnal and is the oplist to use. +See below for more information. + You could replace LIST\_DEF by ARRAY\_DEF to change the kind of container (an array instead of a linked list) @@ -217,7 +231,7 @@ This has the following advantages: * you pass automatically the variable per reference for function calls, * you can not copy the variable by an affectation (you have to use the API instead). -You can also condense the M\*LIB code by using the EACH & LET macros if you are not afraid of using syntactic macros: +You can also condense the M\*LIB code by using the M\_EACH & M\_LET macros if you are not afraid of using syntactic macros: #include #include "m-list.h" @@ -234,7 +248,7 @@ You can also condense the M\*LIB code by using the EACH & LET macros if you are } /* Clear of list will be done now */ } -Another example with a complete type (with proper initialization & clear function) by using the [GMP](https://gmplib.org/) library: +Here is another example with a complete type (with proper initialization & clear function) by using the [GMP](https://gmplib.org/) library: #include #include @@ -262,7 +276,18 @@ Another example with a complete type (with proper initialization & clear functio array_mpz_clear(array); /* Clear all the array */ } -or the equivalent: +As the mpz\_t type needs proper initialization, copy and destroy functions +we need to tell to the container how to handle such a type. +This is done by giving it the oplist associated to the type. +An oplist is an associative array where the operators are associated to methods. +In the example, we tell to the container to use +the mpz\_init function for the INIT operator of the type, +the mpz\_clear function for the CLEAR operator of the type, +the mpz\_set function for the SET operator of the type, +the mpz\_init\_set function for the INIT\_SET operator of the type. +See oplist chapter for more information. + +We can also write the same example shorter: #include #include @@ -293,9 +318,18 @@ or the equivalent: } +There are two ways a container can known what is the oplist of a type: + +* either the oplist is passed explictly for each definition of container and for the LET & EACH macros, +* or the oplist is registered globally by defining a new macro starting with the prefix M\_OPL\_ and finishing with the name of type (don't forget the parenthesis). The macros performing the definition of container and the LET & EACH will test if such macro is defined. If it is defined, it will be used. Otherwise default methods are used. + Here we can see that we register the mpz\_t type into the container with the minimum information of its interface needed. +We can also see in this example so the container ARRAY provides also +a macro to define the oplist of the array itself. This is true for +all containers and this allows to define proper recursive container. + Other examples are available in the example folder. Internal fields of the structure are subject to change even for small revision