Update doc

This commit is contained in:
Patrick Pelissier committed 2023-03-18 08:08:33 +01:00
1 parent ab3aa33fac
commit c8354aa6ed
1 file changed
+45 -1
+45 -1
View File
@@ -662,6 +662,13 @@ Example:
This can simplify a lot OPLIST usage and it is recommended.
Each type a macro expects an oplist, you can give instead its type.
This make the code much easier to read.
There is one exception however: the macros that are used to build oplist
(like ARRAY\_OPLIST) don't perform this simplification and the oplist of
the basic type shall be given instead.
This is due to limitation in the C preprocessing.
### API Interface Adaptation
@@ -691,6 +698,28 @@ For example:
The default adaptation is API\_0 (i.e. no adaptation between operator interface and method interface).
If an adaptation gives an oplist to the method, the method shall be implemented as macro.
Let's take the interface of a pseudo library:
```C
typedef struct { ... } obj_t;
obj_t *obj_init(void); // Constructor of the object z
obj_t *obj_init_str(const char *str); // Constructor of the object z
obj_t *obj_clone(const obj_t *s); // Copy Constructor of the object z
void obj_clear(obj_t *z); // Destructor of the object z
```
The library returns a pointer to the object, so we need API_4 for these methods.
There is no method for the SET operator available. However, we can use the macro M_SET_THROUGH_INIT_SET
to emulate a SET semantics by using a combinaison of CLEAR+INIT_SET. This enables to support
the type for array containers in particular. Or we can avoid this definition if we don't need it.
A basic oplist will be:
```C
(INIT(API_4(obj_init)),SET(API_1(M_SET_THROUGH_INIT_SET)),INIT_SET(API_4(obj_clone)),CLEAR(obj_clear),TYPE(obj_t *))
```
### Generic API Interface Adaptation
You can also describe the exact transformation to perform for calling the method:
this is called Generic API Interface Adaptation (or GAIA).
With this, you can add constant values to parameter of the method,
@@ -6373,9 +6402,24 @@ If the operator has not this property or it is set to 0, it means that it may ra
##### M\_DO\_INIT\_MOVE(oplist, dest, src)
##### M\_DO\_MOVE(oplist, dest, src)
Perform an INIT\_MOVE/MOVE if present, or emulate it otherwise.
Perform an INIT\_MOVE/MOVE if present, or emulate it otherwise (Internal macros).
Note: default methods for INIT\_MOVE/MOVE are not robust enough yet.
##### M\_INIT\_WITH\_THROUGH\_EMPLACE\_TYPE(oplist, dest, src)
Use the provided EMPLACE\_TYPE of the oplist to emulate an INIT\_WITH operator.
It transforms the different emplace types by a C11 _Generic switch in order to call the
right initialization function in function of the type of argument.
The EMPLACE\_TYPE shall use a LIST based format for listing the different emplace types.
This method is compatible with C11 or above.
This method shall be used with API\_1 adaptator.
##### M\_SET\_THROUGH\_INIT\_SET(oplist, dest, src)
Emulate the SET semantics using a combinaison of CLEAR and INIT\_SET of the given oplist.
This method shall be used with API\_1 adaptator.
##### M\_GLOBAL\_OPLIST(a)
If 'a' is a type that has registered a global oplist, it returns the registered oplist,