UNIXworkcode

1 # Collections 2 3 UCX defines common attributes for collections. 4 If you want to implement an own collection data type that uses the same features, you can use the 5 `CX_COLLECTION_BASE` macro at the beginning of your struct to roll out all members a usual UCX collection has. 6 7 This macro will embed a structure in your collection that can be accessed with the member name `collection`. 8 9 ```c 10 #include <cx/collection.h> 11 12 struct my_fancy_collection_s { 13 CX_COLLECTION_BASE; // adds a member named 'collection' 14 struct my_collection_data_s *data; 15 }; 16 ``` 17 18 > You can always look at the UCX list and map implementations if you need some inspiration. 19 20 ## Base Attributes of a Collection 21 22 The following attributes are declared by the `CX_COLLECTION_BASE` macro: 23 24 | Attribute | Description | 25 |-----------------------|----------------------------------------------------------------------------------------------------------------| 26 | `allocator` | The [allocator](allocator.h.md) that shall be used for the collection data. | 27 | `cmpfunc` | A function to [compare](compare.h.md) two elements. | 28 | `elem_size` | The size of one element in bytes. | 29 | `size` | The size, meaning the number of elements, currently stored. | 30 | `simple_destructor` | An optional simple [destructor function](allocator.h.md#destructor-functions). | 31 | `advanced_destructor` | An optional advanced destructor function. | 32 | `destructor_data` | A pointer to the custom data that shall be passed to the advanced destructor. | 33 | `store_pointer` | A `bool` indicating whether this collection stores pointers instead of the element's data. | 34 | `sorted` | A `bool` indicating whether the elements are currently guaranteed sorted with respect to the compare function. | 35 36 The attributes can be accessed directly via the `collection` member of your struct, or with the following convenience macros. 37 38 ```C 39 cxCollectionSize(c) 40 cxCollectionElementSize(c) 41 cxCollectionStoresPointers(c) 42 cxCollectionSorted(c) 43 ``` 44 45 In each case the argument `c` is a pointer to your collection. The macro will then access the base data with `c->collection`. 46 47 Similar to the above macros, the `cxCollectionCompareFunc(c,f)` macro can be used to set the compare function. 48 49 ## Destructor Functions 50 51 For working with destructors, the following macros are defined: 52 53 ```C 54 cxDefineDestructor(c, destr) 55 cxDefineAdvancedDestructor(c, destr, data) 56 57 // use in your collection's implementation 58 cx_invoke_destructor(c, elem) 59 60 // the following two should not be used 61 cx_invoke_simple_destructor(c, elem) 62 cx_invoke_advanced_destructor(c, elem) 63 ``` 64 65 With `cxDefineDestructor()` you can assign a simple [destructor function](allocator.h.md#destructor-functions) 66 to an _instance_ of your collection. 67 Similarly, you can assign an advanced destructor with custom `data` by using `cxDefineAdvancedDestructor`. 68 69 Your collection _should_ be supporting destructors by invoking `cx_invoke_destructor()` whenever an element 70 is removed from your collection _without_ being returned to the caller. 71 This macro will invoke a simple destructor, if one is assigned, first, and then the advanced destructor (again, if assigned). 72 73 > Destructor functions are always invoked with a pointer to the element in your collection. 74 > If your collection is storing pointers (i.e. `cxCollectionStoresPointers()` returns `true`) 75 > the `cx_invoke_destructor()` will make sure that the pointer to the element is dereferenced first, 76 > so that the destructor functions are _always_ invoked with a pointer to the actual element. 77 {style="note"} 78 79 <seealso> 80 <category ref="apidoc"> 81 <a href="https://ucx.sourceforge.io/api/collection_8h.html">collection.h</a> 82 </category> 83 </seealso> 84