--- a/docs/Writerside/topics/collection.h.md Sat Feb 08 14:24:22 2025 +0100
+++ b/docs/Writerside/topics/collection.h.md Sat Feb 08 20:38:05 2025 +0100
@@ -1,24 +1,77 @@
# Collections
-<warning>
-Outdated - Rewrite!
-</warning>
-
-Collections in UCX 3 have several common features.
+UCX defines common attributes for collections.
If you want to implement an own collection data type that uses the same features, you can use the
`CX_COLLECTION_BASE` macro at the beginning of your struct to roll out all members a usual UCX collection has.
+
+This macro will embed a structure in your collection that can be accessed with the member name `collection`.
+
```c
struct my_fancy_collection_s {
- CX_COLLECTION_BASE;
+ CX_COLLECTION_BASE; // adds a member named 'collection'
struct my_collection_data_s *data;
};
```
-Based on this structure, this header provides some convenience macros for invoking the destructor functions
-that are part of the basic collection members.
-The idea of having destructor functions within a collection is that you can destroy the collection _and_ the
-contents with one single function call.
-When you are implementing a collection, you are responsible for invoking the destructors at the right places, e.g.
-when removing (and deleting) elements in the collection, clearing the collection, or - the most prominent case -
-destroying the collection.
+
+> You can always look at the UCX list and map implementations if you need some inspiration.
+
+## Base Attributes of a Collection
+
+The following attributes are declared by the `CX_COLLECTION_BASE` macro:
+
+| Attribute | Description |
+|-----------------------|----------------------------------------------------------------------------------------------------------------|
+| `allocator` | The [allocator](allocator.h.md) that shall be used for the collection data. |
+| `cmpfunc` | A function to [compare](compare.h.md) two elements. |
+| `elem_size` | The size of one element in bytes. |
+| `size` | The size, meaning the number of elements, currently stored. |
+| `simple_destructor` | An optional simple [destructor function](allocator.h.md#destructor-functions). |
+| `advanced_destructor` | An optional advanced destructor function. |
+| `destructor_data` | A pointer to the custom data that shall be passed to the advanced destructor. |
+| `store_pointer` | A `bool` indicating whether this collection stores pointers instead of the element's data. |
+| `sorted` | A `bool` indicating whether the elements are currently guaranteed sorted with respect to the compare function. |
+
+The attributes can be accessed directly via the `collection` member of your struct, or with the following convenience macros.
+
+```C
+cxCollectionSize(c)
+cxCollectionElementSize(c)
+cxCollectionStoresPointers(c)
+cxCollectionSorted(c)
+```
+
+In each case the argument `c` is a pointer to your collection. The macro will then access the base data with `c->collection`.
+
+For working with destructors, the following macros are defined:
-You can always look at the UCX list and map implementations if you need some inspiration.
+```C
+cxDefineDestructor(c, destr)
+cxDefineAdvancedDestructor(c, destr, data)
+
+// use in your collection's implementation
+cx_invoke_destructor(c, elem)
+
+// the following two should not be used
+cx_invoke_simple_destructor(c, elem)
+cx_invoke_advanced_destructor(c, elem)
+```
+
+With `cxDefineDestructor()` you can assign a simple [destructor function](allocator.h.md#destructor-functions)
+to an _instance_ of your collection.
+Similarly, you can assign an advanced destructor with custom `data` by using `cxDefineAdvancedDestructor`.
+
+Your collection _should_ be supporting destructors by invoking `cx_invoke_destructor()` whenever an element
+is removed from your collection _without_ being returned to the caller.
+This macro will invoke a simple destructor, if one is assigned, first, and then the advanced destructor (again, if assigned).
+
+> Destructor functions are always invoked with a pointer to the element in your collection.
+> If your collection is storing pointers (i.e. `cxCollectionStorePointers()` returns `true`)
+> the `cx_invoke_destructor()` will make sure that the pointer to the element is dereferenced first,
+> so that the destructor functions are _always_ invoked with pointer to the actual element.
+{style="note"}
+
+<seealso>
+<category ref="apidoc">
+<a href="https://ucx.sourceforge.io/api/collection_8h.html">collection.h</a>
+</category>
+</seealso>