# HG changeset patch # User Mike Becker # Date 1688214556 -7200 # Node ID 9fecb2769d32e9fe7f0d93fd74a9808e07a6a8b0 # Parent 600d72644919eaf6e96618b7d57a8fd8a57c9415 add documentation for collection.h diff -r 600d72644919 -r 9fecb2769d32 docs/src/features.md --- a/docs/src/features.md Sat Jul 01 14:05:52 2023 +0200 +++ b/docs/src/features.md Sat Jul 01 14:29:16 2023 +0200 @@ -186,6 +186,25 @@ *Header file:* [collection.h](api/collection_8h.html) +Collections in UCX 3 have several common features. +If you want to implement an own collection data type that uses the same features, you can use the +`CX_COLLECTION_MEMBERS` macro at the beginning of your struct to roll out all members a usual UCX collection has. +```c +struct my_fancy_collection_s { + CX_COLLECTION_MEMBERS + 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. + ## List *Header file:* [list.h](api/list_8h.html)