diff --git a/README.md b/README.md index b6c67b62..7d6afe7e 100644 --- a/README.md +++ b/README.md @@ -594,6 +594,7 @@ Other documented operators are: * SEPARATOR() --> character: Return the character used to separate items for I/O methods (default is ',') (for internal use only). * EXT\_ALGO(name, container oplist, object oplist): Define additional algorithms functions specialized for the containers (for internal use only). * PROPERTIES() --> ( properties): Return internal properties of a container (for internal use only) in an oplist format. +* EMPLACE\_TYPE( ... ) : Specify the types usable for "emplacing" the object. See chapter 'emplace'. The operator names listed above shall not be defined as macro. @@ -820,6 +821,29 @@ All bench codes are available in the bench directory. The results are available [in a separate page](https://github.com/P-p-H-d/mlib/wiki/performance). +Emplace +------- + +For M\*LIB, 'emplace' means pushing a new object in the container, +while not giving it the new object, but the parameters needed +to construct this object. +This is a shortcut to the pattern of creating the object with the arguments, +pushing it in the container, and deleting the created object +(even if using PUSH\_MOVE could simplify the design). + +The containers taggued as emplace support generate the emplace functions +based on the provided EMPLACE\_TYPE of the oplist. If EMPLACE\_TYPE doesn't exist or is disabled, no emplace function is generated. Otherwise: + +* EMPLACE\_TYPE( typeA ) means that the object can be constructed from 'typeA' using the method of the INIT_WITH operator. An emplace function without suffix will be generated. +* EMPLACE\_TYPE( (typeA, typeB, ...) ) means that the object can be constructed from the lists of types 'typeA, typeB, ...' using the method of the INIT_WITH operator. An emplace function without suffix will be generated. +* EMPLACE\_TYPE( LIST( (suffix, function, typeA, typeB, ...), (suffix, function, typeA, typeB, ...), ...) means that the object can be constructed from all the provided lists of types 'typeA, typeB, ...' using the provided method 'function'. The 'function' is the method to call to construct the object from the list of types. It supports API transformation if needed. As many emplace function will be generated as there are constructor function. Each generated function will be generated by suffixing it with the provided 'suffix'. + +For example, for an ARRAY definition named vec, if there is such a definition of EMPLACE\_TYPE(const char *), it will generate a function vec_emplace_back(const char *). This function will take a const char * parameter, construct the object from it (for example a string\_t) then push the result back on the array. + +Another example, for an ARRAY definition named vec, if there is such a definition of EMPLACE\_TYPE( LIST( (_ui, mpz\_init\_set\_ui, unsigned int), (_si, mpz\_init\_set\_si, int) ) ), it will generate two functions vec_emplace_back_ui(unsigned int) and vec_emplace_back_si(int). Theses functions will take the (unsigned) int parameter, construct the object from it then push the result back on the array. + + + External Reference ------------------ @@ -1089,6 +1113,12 @@ Push a new element within the list 'list' with the value '\*value' contained wit by stealing as much resources from '\*value' than possible. Afterward '\*value' is cleared and cannot longer be used. +##### void name\_emplace\_back[\_suffix](name\_t list, args...) + +Push a new element by initializing it with the provided arguments, +at the back of the list. +This method is created if the EMPLACE\_TYPE operator is provided. See emplace chapter. + ##### void name\_pop\_back(type *data, name\_t list) Pop a element from the list 'list', and set *data to this value @@ -1416,6 +1446,12 @@ into the back of the list. Afterwards, *value is cleared and cannot be used anymore. value cannot be NULL. +##### void name\_emplace\_back[\_suffix](name\_t list, args...) + +Push a new element by initializing it with the provided arguments, +at the back of the list. +This method is created if the EMPLACE\_TYPE operator is provided. See emplace chapter. + ##### const type *name\_front(const name\_t list) Return a constant pointer to the data stored in the front of the list. @@ -1451,6 +1487,12 @@ into the front of the list. Afterwards, *value is cleared and cannot be used anymore. value cannot be NULL. +##### void name\_emplace\_front[\_suffix](name\_t list, args...) + +Push a new element by initializing it with the provided arguments, +at the front of the list. +This method is created if the EMPLACE\_TYPE operator is provided. See emplace chapter. + ##### void name\_pop\_back(type *data, name\_t list) Pop a element from the list 'list' and set *data to this value @@ -1734,6 +1776,12 @@ Push a new element into the position 'key' of the array 'array' with the value ' 'key' shall be a valid position of the array: from 0 to the size of array (included). This method is created if the INIT\_SET operator is provided. +##### void name\_emplace\_back[\_suffix](name\_t array, args...) + +Push a new element by initializing it with the provided arguments, +at the back of the array. +This method is created if the EMPLACE\_TYPE operator is provided. See emplace chapter. + ##### void name\_pop\_back(type *data, name\_t array) Pop a element from the back of the array 'array' and set *data to this value @@ -2081,6 +2129,12 @@ Return a pointer to the **non-initialized** data. Push at the back a new element within the deque 'deque' and initialize it with the default constructor of the type. Return a pointer to the initialized object. +##### void name\_emplace\_back[\_suffix](name\_t list, args...) + +Push a new element by initializing it with the provided arguments, +at the back of the queue. +This method is created if the EMPLACE\_TYPE operator is provided. See emplace chapter. + ##### void name\_pop\_back(type *data, name\_t deque) Pop a element from the deque 'deque' and set *data to this value. @@ -2106,6 +2160,12 @@ Return a pointer to the **non-initialized** data. Push at the front a new element within the deque 'deque' and initialize it with the default constructor of the type. Return a pointer to the initialized object. +##### void name\_emplace\_front[\_suffix](name\_t list, args...) + +Push a new element by initializing it with the provided arguments, +at the front of the queue. +This method is created if the EMPLACE\_TYPE operator is provided. See emplace chapter. + ##### void name\_pop\_front(type *data, name\_t deque) Pop a element from the deque 'deque' and set *data to this value.