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 On the other hand, the following macros can be used to set the properties of a collection: 48 49 ```C 50 cxSetCompareFunc(c, func) 51 cxSetDestructor(c, destr) 52 cxSetAdvancedDestructor(c, destr, data) 53 ``` 54 55 More details on the destructor functions follow in the next section. 56 57 ## Destructor Functions 58 59 For working with destructors, the following macros are defined: 60 61 ```C 62 cxSetDestructor(c, destr) 63 cxSetAdvancedDestructor(c, destr, data) 64 65 // use in your collection's implementation 66 cx_invoke_destructor(c, elem) 67 68 // the following two should not be used 69 cx_invoke_simple_destructor(c, elem) 70 cx_invoke_advanced_destructor(c, elem) 71 ``` 72 73 With `cxSetDestructor()` you can assign a simple [destructor function](allocator.h.md#destructor-functions) 74 to an _instance_ of your collection. 75 Similarly, you can assign an advanced destructor with custom `data` by using `cxSetAdvancedDestructor`. 76 77 Your collection _should_ be supporting destructors by invoking `cx_invoke_destructor()` whenever an element 78 is removed from your collection _without_ being returned to the caller. 79 This macro will invoke a simple destructor, if one is assigned, first, and then the advanced destructor (again, if assigned). 80 81 > Destructor functions are always invoked with a pointer to the element in your collection. 82 > If your collection is storing pointers (i.e. `cxCollectionStoresPointers()` returns `true`) 83 > the `cx_invoke_destructor()` will make sure that the pointer to the element is dereferenced first, 84 > so that the destructor functions are _always_ invoked with a pointer to the actual element. 85 {style="note"} 86 87 <seealso> 88 <category ref="apidoc"> 89 <a href="https://ucx.sourceforge.io/api/collection_8h.html">collection.h</a> 90 </category> 91 </seealso> 92