diff --git a/ccc/buffer.h b/ccc/buffer.h index f6abeb6..1c9031b 100644 --- a/ccc/buffer.h +++ b/ccc/buffer.h @@ -39,6 +39,10 @@ Then, the `ccc_` prefix can be dropped from all types and functions. */ #include "impl/impl_buffer.h" #include "types.h" +/** @name Container Types +Types available in the container interface. */ +/**@{*/ + /** @brief A contiguous block of storage for elements of the same type. @warning it is undefined behavior to use an uninitialized buffer. @@ -46,6 +50,8 @@ A buffer may be initialized on the stack, heap, or data segment at compile time or runtime. */ typedef struct ccc_buf_ ccc_buffer; +/**@}*/ + /** @name Initialization Interface Initialize the container with memory, callbacks, and permissions. */ /**@{*/ diff --git a/ccc/doubly_linked_list.h b/ccc/doubly_linked_list.h index 66e2dcf..08aa9fe 100644 --- a/ccc/doubly_linked_list.h +++ b/ccc/doubly_linked_list.h @@ -32,6 +32,10 @@ All types and functions can then be written without the `ccc_` prefix. */ #include "impl/impl_doubly_linked_list.h" #include "types.h" +/** @name Container Types +Types available in the container interface. */ +/**@{*/ + /** @brief A container offering bidirectional, insert, removal, and iteration. @warning it is undefined behavior to use an uninitialized container. @@ -50,6 +54,8 @@ the container will handle copying the data wrapping the element to allocations and deallocating when necessary. */ typedef struct ccc_dll_elem_ ccc_dll_elem; +/**@}*/ + /** @name Initialization Interface Initialize the container with memory, callbacks, and permissions. */ /**@{*/ diff --git a/ccc/flat_double_ended_queue.h b/ccc/flat_double_ended_queue.h index b9fd98e..02429fa 100644 --- a/ccc/flat_double_ended_queue.h +++ b/ccc/flat_double_ended_queue.h @@ -33,6 +33,10 @@ All types and functions can then be written without the `ccc_` prefix. */ #include "impl/impl_flat_double_ended_queue.h" #include "types.h" +/** @name Container Types +Types available in the container interface. */ +/**@{*/ + /** @brief A contiguous buffer for O(1) push and pop from front and back. @warning it is undefined behavior to use an uninitialized flat double ended queue. @@ -41,6 +45,8 @@ A flat double ended queue can be initialized on the stack, heap, or data segment at compile time or runtime. */ typedef struct ccc_fdeq_ ccc_flat_double_ended_queue; +/**@}*/ + /** @name Initialization Interface Initialize and create containers with memory, callbacks, and permissions. */ /**@{*/ diff --git a/ccc/flat_hash_map.h b/ccc/flat_hash_map.h index 964c8ae..f9688b7 100644 --- a/ccc/flat_hash_map.h +++ b/ccc/flat_hash_map.h @@ -31,6 +31,10 @@ All types and functions can then be written without the `ccc_` prefix. */ #include "impl/impl_flat_hash_map.h" #include "types.h" +/** @name Container Types +Types available in the container interface. */ +/**@{*/ + /** @brief A container for storing key-value structures defined by the user in a contiguous buffer. @@ -50,6 +54,8 @@ The Entry Interface offers efficient search and subsequent insertion, deletion, or value update based on the needs of the user. */ typedef union ccc_fhmap_entry_ ccc_fhmap_entry; +/**@}*/ + /** @name Initialization Interface Initialize the container with memory, callbacks, and permissions. */ /**@{*/ @@ -77,6 +83,7 @@ equality operator (i.e. ccc_flat_hash_map fh = ccc_fhm_init(...);) */ /** @brief Copy the map at source to destination. @param [in] dst the initialized destination for the copy of the src map. @param [in] src the initialized source of the map. +@param [in] fn the optional allocation function if resizing is needed. @return the result of the copy operation. If the destination capacity is less than the source capacity and no allocation function is provided an input error is returned. If resizing is required and resizing of dst fails a memory error diff --git a/ccc/flat_ordered_map.h b/ccc/flat_ordered_map.h index 52d2fac..0e95c70 100644 --- a/ccc/flat_ordered_map.h +++ b/ccc/flat_ordered_map.h @@ -39,6 +39,10 @@ All types and functions can then be written without the `ccc_` prefix. */ #include "impl/impl_flat_ordered_map.h" #include "types.h" +/** @name Container Types +Types available in the container interface. */ +/**@{*/ + /** @brief A self-optimizing data structure offering amortized O(lg N) search, insert, and erase. @warning it is undefined behavior to access an uninitialized container. @@ -62,6 +66,8 @@ The Entry Interface offers efficient search and subsequent insertion, deletion, or value update based on the needs of the user. */ typedef union ccc_fomap_entry_ ccc_fomap_entry; +/**@}*/ + /** @name Initialization Interface Initialize the container with memory, callbacks, and permissions. */ /**@{*/ diff --git a/ccc/flat_priority_queue.h b/ccc/flat_priority_queue.h index ee5ce38..2f37085 100644 --- a/ccc/flat_priority_queue.h +++ b/ccc/flat_priority_queue.h @@ -24,6 +24,10 @@ All types and functions can then be written without the `ccc_` prefix. */ #include "impl/impl_flat_priority_queue.h" #include "types.h" +/** @name Container Types +Types available in the container interface. */ +/**@{*/ + /** @brief A container offering direct storage and sorting of user data by heap order. @warning it is undefined behavior to access an uninitialized container. @@ -32,6 +36,8 @@ A flat priority queue can be initialized on the stack, heap, or data segment at runtime or compile time.*/ typedef struct ccc_fpq_ ccc_flat_priority_queue; +/**@}*/ + /** @name Initialization Interface Initialize the container with memory, callbacks, and permissions. */ /**@{*/ diff --git a/ccc/flat_realtime_ordered_map.h b/ccc/flat_realtime_ordered_map.h index 45bc5ce..dea0b33 100644 --- a/ccc/flat_realtime_ordered_map.h +++ b/ccc/flat_realtime_ordered_map.h @@ -33,6 +33,10 @@ All types and functions can then be written without the `ccc_` prefix. */ #include "impl/impl_flat_realtime_ordered_map.h" #include "types.h" +/** @name Container Types +Types available in the container interface. */ +/**@{*/ + /** @brief A flat realtime ordered map offers O(lg N) search and erase, and amortized O(lg N) insert. @warning it is undefined behavior to access an uninitialized container. @@ -54,6 +58,8 @@ The Entry Interface offers efficient search and subsequent insertion, deletion, or value update based on the needs of the user. */ typedef union ccc_fromap_entry_ ccc_fromap_entry; +/**@}*/ + /** @name Initialization Interface Initialize the container with memory, callbacks, and permissions. */ /**@{*/ diff --git a/ccc/ordered_map.h b/ccc/ordered_map.h index 9a3a36c..ebb363f 100644 --- a/ccc/ordered_map.h +++ b/ccc/ordered_map.h @@ -29,6 +29,10 @@ All types and functions can then be written without the `ccc_` prefix. */ #include "impl/impl_ordered_map.h" #include "types.h" +/** @name Container Types +Types available in the container interface. */ +/**@{*/ + /** @brief A self-optimizing data structure offering amortized O(lg N) search, insert, and erase and pointer stability. @warning it is undefined behavior to access an uninitialized container. @@ -52,6 +56,8 @@ The Entry Interface offers efficient search and subsequent insertion, deletion, or value update based on the needs of the user. */ typedef union ccc_omap_entry_ ccc_omap_entry; +/**@}*/ + /** @name Initialization Interface Initialize the container with memory, callbacks, and permissions. */ /**@{*/ diff --git a/ccc/ordered_multimap.h b/ccc/ordered_multimap.h index 629bcd0..4d08089 100644 --- a/ccc/ordered_multimap.h +++ b/ccc/ordered_multimap.h @@ -40,6 +40,10 @@ All types and functions can then be written without the `ccc_` prefix. */ #include "impl/impl_ordered_multimap.h" #include "types.h" +/** @name Container Types +Types available in the container interface. */ +/**@{*/ + /** @brief A container for membership testing by key field, allowing duplicate keys. @warning it is undefined behavior to use an uninitialized container. @@ -66,6 +70,8 @@ further operations to be performed once they are obtained without a second search, insert, or remove query. */ typedef union ccc_ommap_entry_ ccc_ommap_entry; +/**@}*/ + /** @name Initialization Interface Initialize the container with memory, callbacks, and permissions. */ /**@{*/ diff --git a/ccc/priority_queue.h b/ccc/priority_queue.h index 3c1a1d0..1f397b8 100644 --- a/ccc/priority_queue.h +++ b/ccc/priority_queue.h @@ -26,6 +26,10 @@ All types and functions can then be written without the `ccc_` prefix. */ #include "impl/impl_priority_queue.h" #include "types.h" +/** @name Container Types +Types available in the container interface. */ +/**@{*/ + /** @brief A container for pointer stability and an O(1) push and amortized o(lg N) increase/decrease key. @warning it is undefined behavior to access an uninitialized container. @@ -44,6 +48,8 @@ the container will handle copying the data wrapping the element to allocations and deallocating when necessary. */ typedef struct ccc_pq_elem_ ccc_pq_elem; +/**@}*/ + /** @name Initialization Interface Initialize the container with memory, callbacks, and permissions. */ /**@{*/ diff --git a/ccc/realtime_ordered_map.h b/ccc/realtime_ordered_map.h index 536a77a..05f1f5f 100644 --- a/ccc/realtime_ordered_map.h +++ b/ccc/realtime_ordered_map.h @@ -24,6 +24,10 @@ All types and functions can then be written without the `ccc_` prefix. */ #include "impl/impl_realtime_ordered_map.h" #include "types.h" +/** @name Container Types +Types available in the container interface. */ +/**@{*/ + /** @brief A container for amortized O(lg N) search, insert, erase, ranges, and pointer stability. @warning it is undefined behavior to access an uninitialized container. @@ -49,6 +53,8 @@ The Entry Interface offers efficient search and subsequent insertion, deletion, or value update based on the needs of the user. */ typedef union ccc_romap_entry_ ccc_romap_entry; +/**@}*/ + /** @name Initialization Interface Initialize the container with memory, callbacks, and permissions. */ /**@{*/ diff --git a/ccc/singly_linked_list.h b/ccc/singly_linked_list.h index 0e06d24..20f04ba 100644 --- a/ccc/singly_linked_list.h +++ b/ccc/singly_linked_list.h @@ -33,6 +33,10 @@ All types and functions can then be written without the `ccc_` prefix. */ #include "impl/impl_singly_linked_list.h" #include "types.h" +/** @name Container Types +Types available in the container interface. */ +/**@{*/ + /** @brief A low overhead front tracking container with efficient push and pop. A singly linked list may be stored in the stack, heap, or data segment. Once @@ -50,6 +54,8 @@ the container will handle copying the data wrapping the element to allocations and deallocating when necessary. */ typedef struct ccc_sll_elem_ ccc_sll_elem; +/**@}*/ + /** @name Initialization Interface Initialize the container with memory, callbacks, and permissions. */ /**@{*/ diff --git a/ccc/types.h b/ccc/types.h index 2618ddf..6be587d 100644 --- a/ccc/types.h +++ b/ccc/types.h @@ -17,6 +17,10 @@ the allocation function interface. */ #include "impl/impl_types.h" +/** @name Container Types +Types used across many containers. */ +/**@{*/ + /** @brief The result of a range query on iterable containers. A range provides a view all elements that fit the equals range criteria @@ -248,6 +252,12 @@ A reference to any aux data provided on initialization is also available. Return the complete hash value as determined by the user hashing algorithm. */ typedef uint64_t ccc_hash_fn(ccc_user_key to_hash); +/**@}*/ + +/** @name Entry Interface +The generic interface for associative container entries. */ +/**@{*/ + /** @brief Determine if an entry is Occupied in the container. @param [in] e the pointer to the entry obtained from a container. @return true if Occupied false if Vacant. */ @@ -280,6 +290,12 @@ container being used to understand what to expect from this function once an entry is obtained. */ void *ccc_entry_unwrap(ccc_entry const *e); +/**@}*/ + +/** @name Range Interface +The generic range interface for associative containers. */ +/**@{*/ + /** @brief Obtain a reference to the beginning user element stored in a container in the provided range. @param [in] r a pointer to the range. @@ -321,6 +337,12 @@ NULL. Functions that obtain ranges treat the reverse end as an exclusive bound and therefore it is undefined to access this element. */ void *ccc_rend_rrange(ccc_rrange const *r); +/**@}*/ + +/** @name Status Interface +Functions for obtaining more descriptive status information. */ +/**@{*/ + /** @brief Obtain a string message with a description of the error returned from a container operation, possible causes, and possible fixes to such error. @param [in] res the result obtained from a container operation. @@ -351,6 +373,8 @@ the provided interface gives all the functions needed to check status but these strings can be used when more details are required. */ char const *ccc_entry_status_msg(ccc_entry_status status); +/**@}*/ + /** Define this directive at the top of a translation unit if shorter names are desired. By default the ccc prefix is used to avoid namespace clashes. */ #ifdef TYPES_USING_NAMESPACE_CCC