Update doc
This commit is contained in:
1 parent
ab3aa33fac
commit
c8354aa6ed
1 file changed
+45
-1
@@ -662,6 +662,13 @@ Example:
|
|||||||
|
|
||||||
This can simplify a lot OPLIST usage and it is recommended.
|
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
|
### 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).
|
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.
|
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:
|
You can also describe the exact transformation to perform for calling the method:
|
||||||
this is called Generic API Interface Adaptation (or GAIA).
|
this is called Generic API Interface Adaptation (or GAIA).
|
||||||
With this, you can add constant values to parameter of the method,
|
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\_INIT\_MOVE(oplist, dest, src)
|
||||||
##### M\_DO\_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.
|
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)
|
##### M\_GLOBAL\_OPLIST(a)
|
||||||
|
|
||||||
If 'a' is a type that has registered a global oplist, it returns the registered oplist,
|
If 'a' is a type that has registered a global oplist, it returns the registered oplist,
|
||||||
|
|||||||
Reference in new issue
Block a user