universe@720: ---
universe@720: title: UCX Features
universe@720: ---
universe@720:
universe@720:
universe@720:
universe@720: ------------------------ ------------------------- ------------------- ---------------------------------
universe@720: [Allocator](#allocator) [String](#string) [Buffer](#buffer) [Memory Pool](#memory-pool)
universe@720: [Iterator](#iterator) [Collection](#collection) [List](#list) [Map](#map)
universe@720: [Utilities](#utilities)
universe@720: ------------------------ ------------------------- ------------------- ---------------------------------
universe@720:
universe@720:
universe@720:
universe@720: ## Allocator
universe@720:
universe@720: *Header file:* [allocator.h](api/allocator_8h.html)
universe@720:
universe@722: The UCX allocator provides an interface for implementing an own memory allocation mechanism.
universe@722: Various function in UCX provide an additional alternative signature that takes an allocator as
universe@722: argument. A default allocator implementation using the stdlib memory management functions is
universe@722: available via the global symbol `cxDefaultAllocator`.
universe@722:
universe@722: If you want to define your own allocator, you need to initialize the `CxAllocator` structure
universe@722: with a pointer to an allocator class (containing function pointers for the memory management
universe@722: functions) and an optional pointer to an arbitrary memory region that can be used to store
universe@722: state information for the allocator. An example is shown below:
universe@722:
universe@722: ```c
universe@722: struct my_allocator_state {
universe@722: size_t total;
universe@722: size_t avail;
universe@722: char[] mem;
universe@722: };
universe@722:
universe@722: static cx_allocator_class my_allocator_class = {
universe@722: my_malloc_impl,
universe@722: my_realloc_impl, // all these functions are somewhere defined
universe@722: my_calloc_impl,
universe@722: my_free_impl
universe@722: };
universe@722:
universe@722: CxAllocator create_my_allocator(size_t n) {
universe@722: CxAllocator alloc;
universe@722: alloc.cl = &my_allocator_class;
universe@722: alloc.data = calloc(1, sizeof(struct my_allocator_state) + n);
universe@722: return alloc;
universe@722: }
universe@722:
universe@722: void free_my_allocator(CxAllocator *alloc) {
universe@722: free(alloc.data);
universe@722: free(alloc);
universe@722: }
universe@722: ```
universe@722:
universe@720: ## String
universe@720:
universe@720: *Header file:* [string.h](api/string_8h.html)
universe@720:
universe@723: UCX strings come in two variants: immutable (`cxstring`) and mutable (`cxmutstr`).
universe@723: The functions of UCX are designed to work with immutable strings by default but in situations where it is necessary,
universe@723: the API also provides alternative functions that work directly with mutable strings.
universe@723: Functions that change a string in-place are, of course, only accepting mutable strings.
universe@723:
universe@723: When you are using UCX functions, or defining your own functions, you are sometimes facing the "problem",
universe@723: that the function only accepts arguments of type `cxstring` but you only have a `cxmutstr` at hand.
universe@723: In this case you _should not_ introduce a wrapper function that accepts the `cxmutstr`,
universe@723: but instead you should use the `cx_strcast()` function to cast the argument to the correct type.
universe@723:
universe@723: In general, UCX strings are **not** necessarily zero-terminated. If a function guarantees to return zero-terminated
universe@723: string, it is explicitly mentioned in the documentation of the respective function.
universe@723: As a rule of thumb, you _should not_ pass the strings of a UCX string structure to another API without explicitly
universe@723: ensuring that the string is zero-terminated.
universe@723:
universe@720: ## Buffer
universe@720:
universe@720: *Header file:* [buffer.h](api/buffer_8h.html)
universe@720:
universe@720: ## Memory Pool
universe@720:
universe@720: *Header file:* [mempool.h](api/mempool_8h.html)
universe@720:
universe@720: ### Basic Memory Pool
universe@720:
universe@720: *Header file:* [basic_mempool.h](api/basic__mempool_8h.html)
universe@720:
universe@720: ## Iterator
universe@720:
universe@720: *Header file:* [iterator.h](api/iterator_8h.html)
universe@720:
universe@720: ## Collection
universe@720:
universe@720: *Header file:* [collection.h](api/collection_8h.html)
universe@720:
universe@720: ## List
universe@720:
universe@720: *Header file:* [list.h](api/list_8h.html)
universe@720:
universe@720: ### Linked List
universe@720:
universe@720: *Header file:* [linked_list.h](api/linked__list_8h.html)
universe@720:
universe@720: ### Array List
universe@720:
universe@720: *Header file:* [array_list.h](api/array__list_8h.html)
universe@720:
universe@720: ## Map
universe@720:
universe@720: *Header file:* [map.h](api/map_8h.html)
universe@720:
universe@720: ### Hash Map
universe@720:
universe@720: *Header file:* [hash_map.h](api/hash__map_8h.html)
universe@720:
universe@720: ## Utilities
universe@720:
universe@720: *Header file:* [utils.h](api/utils_8h.html)
universe@720:
universe@720: ### Printf Functions
universe@720:
universe@720: *Header file:* [printf.h](api/printf_8h.html)
universe@720:
universe@720: ### Compare Functions
universe@720:
universe@720: *Header file:* [compare.h](api/compare_8h.html)