docs/src/features.md

Sun, 22 Dec 2024 21:57:53 +0100

author
Mike Becker <universe@uap-core.de>
date
Sun, 22 Dec 2024 21:57:53 +0100
changeset 1046
fe2c842fce4b
parent 998
bb196054f3fd
permissions
-rw-r--r--

fix datatype in long long variants

issue #532

720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
1 ---
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
2 title: UCX Features
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
3 ---
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
4
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
5 <div id="modules">
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
6
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
7 ------------------------ ------------------------- ------------------- ---------------------------------
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
8 [Allocator](#allocator) [String](#string) [Buffer](#buffer) [Memory&nbsp;Pool](#memory-pool)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
9 [Iterator](#iterator) [Collection](#collection) [List](#list) [Map](#map)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
10 [Utilities](#utilities)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
11 ------------------------ ------------------------- ------------------- ---------------------------------
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
12
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
13 </div>
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
14
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
15 ## Allocator
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
16
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
17 *Header file:* [allocator.h](api/allocator_8h.html)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
18
722
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
19 The UCX allocator provides an interface for implementing an own memory allocation mechanism.
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
20 Various function in UCX provide an additional alternative signature that takes an allocator as
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
21 argument. A default allocator implementation using the stdlib memory management functions is
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
22 available via the global symbol `cxDefaultAllocator`.
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
23
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
24 If you want to define your own allocator, you need to initialize the `CxAllocator` structure
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
25 with a pointer to an allocator class (containing function pointers for the memory management
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
26 functions) and an optional pointer to an arbitrary memory region that can be used to store
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
27 state information for the allocator. An example is shown below:
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
28
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
29 ```c
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
30 struct my_allocator_state {
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
31 size_t total;
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
32 size_t avail;
727
d92a59f5d261 improve mempool implementation
Mike Becker <universe@uap-core.de>
parents: 725
diff changeset
33 char mem[];
722
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
34 };
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
35
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
36 static cx_allocator_class my_allocator_class = {
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
37 my_malloc_impl,
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
38 my_realloc_impl, // all these functions are somewhere defined
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
39 my_calloc_impl,
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
40 my_free_impl
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
41 };
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
42
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
43 CxAllocator create_my_allocator(size_t n) {
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
44 CxAllocator alloc;
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
45 alloc.cl = &my_allocator_class;
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
46 alloc.data = calloc(1, sizeof(struct my_allocator_state) + n);
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
47 return alloc;
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
48 }
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
49 ```
adc3c48dd3af add allocator example
Mike Becker <universe@uap-core.de>
parents: 720
diff changeset
50
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
51 ## String
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
52
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
53 *Header file:* [string.h](api/string_8h.html)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
54
723
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
55 UCX strings come in two variants: immutable (`cxstring`) and mutable (`cxmutstr`).
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
56 The functions of UCX are designed to work with immutable strings by default but in situations where it is necessary,
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
57 the API also provides alternative functions that work directly with mutable strings.
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
58 Functions that change a string in-place are, of course, only accepting mutable strings.
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
59
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
60 When you are using UCX functions, or defining your own functions, you are sometimes facing the "problem",
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
61 that the function only accepts arguments of type `cxstring` but you only have a `cxmutstr` at hand.
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
62 In this case you _should not_ introduce a wrapper function that accepts the `cxmutstr`,
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
63 but instead you should use the `cx_strcast()` function to cast the argument to the correct type.
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
64
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
65 In general, UCX strings are **not** necessarily zero-terminated. If a function guarantees to return zero-terminated
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
66 string, it is explicitly mentioned in the documentation of the respective function.
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
67 As a rule of thumb, you _should not_ pass the strings of a UCX string structure to another API without explicitly
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
68 ensuring that the string is zero-terminated.
c33e0ac069dd add web documentation for strings
Mike Becker <universe@uap-core.de>
parents: 722
diff changeset
69
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
70 ## Buffer
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
71
724
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
72 *Header file:* [buffer.h](api/buffer_8h.html)
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
73
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
74 Instances of this buffer implementation can be used to read from or write to memory like you would do with a stream.
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
75 This allows the use of `cx_stream_copy()` (see [Utilities](#utilities)) to copy contents from one buffer to another,
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
76 or from a file or network streams to the buffer and vice-versa.
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
77
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
78 More features for convenient use of the buffer can be enabled, like automatic memory management and automatic
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
79 resizing of the buffer space.
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
80
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
81 Since UCX 3.0, the buffer also supports automatic flushing of contents to another stream (or buffer) as an alternative
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
82 to automatically resizing the buffer space.
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
83 Please refer to the API doc for the fields prefixed with `flush_` to learn more.
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
84
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
85 ## Memory Pool
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
86
725
c9b882bef838 add docs for the compare.h and printf.h utilities
Mike Becker <universe@uap-core.de>
parents: 724
diff changeset
87 *Header file:* [mempool.h](api/mempool_8h.html)
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
88
729
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
89 A memory pool is providing an allocator implementation that automatically deallocates the memory upon its destruction.
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
90 It also allows you to register destructor functions for the allocated memory, which are automatically called before
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
91 the memory is deallocated.
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
92 Additionally, you may also register _independent_ destructor functions within a pool in case some external library
993
b642eca4b956 make names of destroy and free functions consistent - fixes #484
Mike Becker <universe@uap-core.de>
parents: 962
diff changeset
93 allocated memory for you, which should be freed together with this pool.
729
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
94
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
95 Many UCX features support the use of an allocator.
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
96 The [strings](#string), for instance, provide several functions suffixed with `_a` that allow specifying an allocator.
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
97 You can use this to keep track of the memory occupied by dynamically allocated strings and cleanup everything with
993
b642eca4b956 make names of destroy and free functions consistent - fixes #484
Mike Becker <universe@uap-core.de>
parents: 962
diff changeset
98 just a single call to `cxMempoolFree()`.
729
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
99
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
100 The following code illustrates this on the example of reading a CSV file into memory.
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
101 ```C
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
102 #include <stdio.h>
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
103 #include <cx/mempool.h>
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
104 #include <cx/linked_list.h>
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
105 #include <cx/string.h>
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
106 #include <cx/buffer.h>
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
107 #include <cx/utils.h>
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
108
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
109 typedef struct {
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
110 cxstring column_a;
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
111 cxstring column_b;
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
112 cxstring column_c;
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
113 } CSVData;
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
114
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
115 int main(void) {
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
116 CxMempool* pool = cxBasicMempoolCreate(128);
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
117
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
118 FILE *f = fopen("test.csv", "r");
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
119 if (!f) {
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
120 perror("Cannot open file");
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
121 return 1;
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
122 }
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
123 // close the file automatically at pool destruction
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
124 cxMempoolRegister(pool, f, (cx_destructor_func) fclose);
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
125
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
126 // create a buffer using the memory pool for destruction
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
127 CxBuffer *content = cxBufferCreate(NULL, 256, pool->allocator, CX_BUFFER_AUTO_EXTEND);
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
128
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
129 // read the file into the buffer and turn it into a string
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
130 cx_stream_copy(f, content, (cx_read_func) fread, (cx_write_func) cxBufferWrite);
745
c99abca90d21 some fixes in example code
Mike Becker <universe@uap-core.de>
parents: 733
diff changeset
131 fclose(f);
729
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
132 cxstring contentstr = cx_strn(content->space, content->size);
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
133
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
134 // split the string into lines - use the mempool for allocating the target array
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
135 cxstring* lines;
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
136 size_t lc = cx_strsplit_a(pool->allocator, contentstr,
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
137 CX_STR("\n"), SIZE_MAX, &lines);
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
138
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
139 // skip the header and parse the remaining data into a linked list
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
140 // the nodes of the linked list shall also be allocated by the mempool
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
141 CxList* datalist = cxLinkedListCreate(pool->allocator, NULL, sizeof(CSVData));
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
142 for (size_t i = 1 ; i < lc ; i++) {
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
143 if (lines[i].length == 0) continue;
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
144 cxstring fields[3];
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
145 size_t fc = cx_strsplit(lines[i], CX_STR(";"), 3, fields);
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
146 if (fc != 3) {
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
147 fprintf(stderr, "Syntax error in line %zu.\n", i);
993
b642eca4b956 make names of destroy and free functions consistent - fixes #484
Mike Becker <universe@uap-core.de>
parents: 962
diff changeset
148 cxMempoolFree(pool);
729
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
149 return 1;
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
150 }
746
b4bd0155f03f improve the CSV example
Mike Becker <universe@uap-core.de>
parents: 745
diff changeset
151 CSVData data;
b4bd0155f03f improve the CSV example
Mike Becker <universe@uap-core.de>
parents: 745
diff changeset
152 data.column_a = fields[0];
b4bd0155f03f improve the CSV example
Mike Becker <universe@uap-core.de>
parents: 745
diff changeset
153 data.column_b = fields[1];
b4bd0155f03f improve the CSV example
Mike Becker <universe@uap-core.de>
parents: 745
diff changeset
154 data.column_c = fields[2];
b4bd0155f03f improve the CSV example
Mike Becker <universe@uap-core.de>
parents: 745
diff changeset
155 cxListAdd(datalist, &data);
729
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
156 }
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
157
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
158 // iterate through the list and output the data
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
159 CxIterator iter = cxListIterator(datalist);
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
160 cx_foreach(CSVData*, data, iter) {
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
161 printf("Column A: %.*s | "
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
162 "Column B: %.*s | "
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
163 "Column C: %.*s\n",
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
164 (int)data->column_a.length, data->column_a.ptr,
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
165 (int)data->column_b.length, data->column_b.ptr,
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
166 (int)data->column_c.length, data->column_c.ptr
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
167 );
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
168 }
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
169
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
170 // cleanup everything, no manual free() needed
993
b642eca4b956 make names of destroy and free functions consistent - fixes #484
Mike Becker <universe@uap-core.de>
parents: 962
diff changeset
171 cxMempoolFree(pool);
729
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
172
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
173 return 0;
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
174 }
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
175 ```
600d72644919 add mempool example
Mike Becker <universe@uap-core.de>
parents: 727
diff changeset
176
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
177 ## Iterator
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
178
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
179 *Header file:* [iterator.h](api/iterator_8h.html)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
180
733
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
181 In UCX 3 a new feature has been introduced to write own iterators, that work with the `cx_foreach` macro.
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
182 In previous UCX releases there were different hard-coded foreach macros for lists and maps that were not customizable.
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
183 Now, creating an iterator is as simple as creating a `CxIterator` struct and setting the fields in a meaningful way.
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
184
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
185 You do not always need all fields in the iterator structure, depending on your use case.
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
186 Sometimes you only need the `index` (for example when iterating over simple lists), and other times you will need the
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
187 `slot` and `kv_data` fields (for example when iterating over maps).
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
188
853
d4baf4dd55c3 simplify iterator structures
Mike Becker <universe@uap-core.de>
parents: 834
diff changeset
189 If the predefined fields are insufficient for your use case, you can alternatively create your own iterator structure
854
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 853
diff changeset
190 and place the `CX_ITERATOR_BASE` macro as first member of that structure.
853
d4baf4dd55c3 simplify iterator structures
Mike Becker <universe@uap-core.de>
parents: 834
diff changeset
191
733
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
192 Usually an iterator is not mutating the collection it is iterating over.
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
193 In some programming languages it is even disallowed to change the collection while iterating with foreach.
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
194 But sometimes it is desirable to remove an element from the collection while iterating over it.
853
d4baf4dd55c3 simplify iterator structures
Mike Becker <universe@uap-core.de>
parents: 834
diff changeset
195 For this purpose, most collections allow the creation of a _mutating_ iterator.
733
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
196 The only differences are, that the `mutating` flag is `true` and the `src_handle` is not const.
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
197 On mutating iterators it is allowed to call the `cxFlagForRemoval()` function, which instructs the iterator to remove
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
198 the current element from the collection on the next call to `cxIteratorNext()` and clear the flag afterward.
853
d4baf4dd55c3 simplify iterator structures
Mike Becker <universe@uap-core.de>
parents: 834
diff changeset
199 If you are implementing your own iterator, it is up to you to implement this behavior.
733
2ed01495f838 add iterator documentation
Mike Becker <universe@uap-core.de>
parents: 732
diff changeset
200
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
201 ## Collection
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
202
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
203 *Header file:* [collection.h](api/collection_8h.html)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
204
730
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
205 Collections in UCX 3 have several common features.
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
206 If you want to implement an own collection data type that uses the same features, you can use the
854
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 853
diff changeset
207 `CX_COLLECTION_BASE` macro at the beginning of your struct to roll out all members a usual UCX collection has.
730
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
208 ```c
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
209 struct my_fancy_collection_s {
854
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 853
diff changeset
210 CX_COLLECTION_BASE;
730
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
211 struct my_collection_data_s *data;
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
212 };
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
213 ```
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
214 Based on this structure, this header provides some convenience macros for invoking the destructor functions
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
215 that are part of the basic collection members.
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
216 The idea of having destructor functions within a collection is that you can destroy the collection _and_ the
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
217 contents with one single function call.
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
218 When you are implementing a collection, you are responsible for invoking the destructors at the right places, e.g.
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
219 when removing (and deleting) elements in the collection, clearing the collection, or - the most prominent case -
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
220 destroying the collection.
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
221
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
222 You can always look at the UCX list and map implementations if you need some inspiration.
9fecb2769d32 add documentation for collection.h
Mike Becker <universe@uap-core.de>
parents: 729
diff changeset
223
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
224 ## List
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
225
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
226 *Header file:* [list.h](api/list_8h.html)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
227
854
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 853
diff changeset
228 This header defines a common interface for all list implementations.
731
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
229
854
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 853
diff changeset
230 UCX already comes with two common list implementations (linked list and array list) that should cover most use cases.
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 853
diff changeset
231 But if you feel the need to implement an own list, the only thing you need to do is to define a struct with a
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 853
diff changeset
232 `struct cx_list_s` as first member, and set an appropriate list class that implements the functionality.
731
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
233 It is strongly recommended that this class is shared among all instances of the same list type, because otherwise
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
234 the `cxListCompare` function cannot use the optimized implementation of your class and will instead fall back to
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
235 using iterators to compare the contents element-wise.
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
236
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
237 ### Linked List
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
238
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
239 *Header file:* [linked_list.h](api/linked__list_8h.html)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
240
731
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
241 On top of implementing the list interface, this header also defines several low-level functions that
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
242 work with arbitrary structures.
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
243 Low-level functions, in contrast to the high-level list interface, can easily be recognized by their snake-casing.
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
244 The function `cx_linked_list_at`, for example, implements a similar functionality like `cxListAt`, but operates
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
245 on arbitrary structures.
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
246 The following snippet shows how it is used.
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
247 All other low-level functions work similarly.
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
248 ```c
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
249 struct node {
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
250 node *next;
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
251 node *prev;
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
252 int data;
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
253 };
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
254
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
255 const ptrdiff_t loc_prev = offsetof(struct node, prev);
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
256 const ptrdiff_t loc_next = offsetof(struct node, next);
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
257 const ptrdiff_t loc_data = offsetof(struct node, data);
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
258
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
259 struct node a = {0}, b = {0}, c = {0}, d = {0};
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
260 cx_linked_list_link(&a, &b, loc_prev, loc_next);
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
261 cx_linked_list_link(&b, &c, loc_prev, loc_next);
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
262 cx_linked_list_link(&c, &d, loc_prev, loc_next);
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
263
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
264 cx_linked_list_at(&a, 0, loc_next, 2); // returns pointer to c
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
265 ```
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
266
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
267 ### Array List
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
268
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
269 *Header file:* [array_list.h](api/array__list_8h.html)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
270
731
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
271 Since low-level array lists are just plain arrays, there is no need for such many low-level functions as for linked
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
272 lists.
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
273 However, there is one extremely powerful function that can be used for several complex tasks: `cx_array_copy`.
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
274 The full signature is shown below:
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
275 ```c
998
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
276 int cx_array_copy(
731
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
277 void **target,
998
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
278 void *size,
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
279 void *capacity,
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
280 unsigned width,
731
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
281 size_t index,
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 854
diff changeset
282 const void *src,
731
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
283 size_t elem_size,
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
284 size_t elem_count,
998
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
285 struct cx_array_reallocator_s *reallocator
731
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
286 );
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
287 ```
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
288 The `target` argument is a pointer to the target array pointer.
998
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
289 The reason for this additional indirection is that this function writes
731
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
290 back the pointer to the possibly reallocated array.
998
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
291 The next two arguments are pointers to the `size` and `capacity` of the target array for which the width
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
292 (in bits) is specified in the `width` argument.
731
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
293
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
294 On a successful invocation, the function copies `elem_count` number of elements, each of size `elem_size` from
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
295 `src` to `*target` and uses the `reallocator` to extend the array when necessary.
998
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
296 Finally, the size, capacity, and the pointer to the array are all updated and the function returns zero.
731
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
297
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
298 A few things to note:
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
299 * `*target` and `src` can point to the same memory region, effectively copying elements within the array with `memmove`
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
300 * `*target` does not need to point to the start of the array, but `size` and `capacity` always start counting from the
998
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
301 position, `*target` points to - in this scenario, the need for reallocation must be avoided for obvious reasons
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
302 * `index` does not need to be within size of the current array
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
303 * `index` does not even need to be within the capacity of the array
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
304 * `width` must be one of 8, 16, 32, 64 (only on 64-bit systems), or zero (in which case the native word width is used)
731
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
305
819
5da2ead43077 rename cx_array_copy_result to just cx_array_result
Mike Becker <universe@uap-core.de>
parents: 746
diff changeset
306 If you just want to add one single element to an existing array, you can use the macro `cx_array_add()`.
834
04c53b3c8378 capitalize cx_array_declare()
Mike Becker <universe@uap-core.de>
parents: 831
diff changeset
307 You can use `CX_ARRAY_DECLARE()` to declare the necessary fields within a structure and then use the
831
7970eac1c598 add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents: 819
diff changeset
308 `cx_array_simple_*()` convenience macros to reduce code overhead.
998
bb196054f3fd make cx_array_copy() support different types for size/capacity - fixes #492
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
309 The convenience macros automatically determine the width of the size/capacity variables.
731
9c097dabba2c add documentation for the lists
Mike Becker <universe@uap-core.de>
parents: 730
diff changeset
310
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
311 ## Map
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
312
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
313 *Header file:* [map.h](api/map_8h.html)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
314
732
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
315 Similar to the list interface, the map interface provides a common API for implementing maps.
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
316 There are some minor subtle differences, though.
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
317
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
318 First, the `remove` method is not always a destructive removal.
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
319 Instead, the last argument is a Boolean that indicates whether the element shall be destroyed or returned.
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
320 ```c
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
321 void *(*remove)(CxMap *map, CxHashKey key, bool destroy);
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
322 ```
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
323 When you implement this method, you are either supposed to invoke the destructors and return `NULL`,
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
324 or just remove the element from the map and return it.
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
325
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
326 Secondly, the iterator method is a bit more complete. The signature is as follows:
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
327 ```c
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 854
diff changeset
328 CxIterator (*iterator)(const CxMap *map, enum cx_map_iterator_type type);
732
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
329 ```
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
330 There are three map iterator types: for values, for keys, for pairs.
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
331 Depending on the iterator type requested, you need to create an iterator with the correct methods that
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
332 return the requested thing.
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
333 There are no automatic checks to enforce this - it's completely up to you.
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
334 If you need inspiration on how to do that, check the hash map implementation that comes with UCX.
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
335
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
336 ### Hash Map
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
337
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
338 *Header file:* [hash_map.h](api/hash__map_8h.html)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
339
732
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
340 UCX provides a basic hash map implementation with a configurable amount of buckets.
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
341 If you do not specify the number of buckets, a default of 16 buckets will be used.
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
342 You can always rehash the map with `cxMapRehash()` to change the number of buckets to something more efficient,
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
343 but you need to be careful, because when you use this function you are effectively locking into using this
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
344 specific hash map implementation, and you would need to remove all calls to this function when you want to
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
345 exchange the concrete map implementation with something different.
a3b5f27ad956 add map documentation
Mike Becker <universe@uap-core.de>
parents: 731
diff changeset
346
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
347 ## Utilities
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
348
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
349 *Header file:* [utils.h](api/utils_8h.html)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
350
962
cd418898af5c remove cx_for_n() macro - fixes #467
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
351 UCX provides some utilities for routine tasks.
724
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
352
962
cd418898af5c remove cx_for_n() macro - fixes #467
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
353 The most useful utilities are the *stream copy* functions, which provide a simple way to copy all - or a
724
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
354 bounded amount of - data from one stream to another. Since the read/write functions of a UCX buffer are
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
355 fully compatible with stream read/write functions, you can easily transfer data from file or network streams to
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
356 a UCX buffer or vice-versa.
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
357
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
358 The following example shows, how easy it is to read the contents of a file into a buffer:
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
359 ```c
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
360 FILE *inputfile = fopen(infilename, "r");
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
361 if (inputfile) {
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
362 CxBuffer fbuf;
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
363 cxBufferInit(&fbuf, NULL, 4096, NULL, CX_BUFFER_AUTO_EXTEND);
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
364 cx_stream_copy(inputfile, &fbuf,
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
365 (cx_read_func) fread,
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
366 (cx_write_func) cxBufferWrite);
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
367 fclose(inputfile);
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
368
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
369 // ... do something meaningful with the contents ...
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
370
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
371 cxBufferDestroy(&fbuf);
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
372 } else {
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
373 perror("Error opening input file");
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
374 if (fout != stdout) {
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
375 fclose(fout);
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
376 }
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
377 }
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
378 ```
5e7b1951dc80 add web docs for buffer and stream copy
Mike Becker <universe@uap-core.de>
parents: 723
diff changeset
379
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
380 ### Printf Functions
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
381
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
382 *Header file:* [printf.h](api/printf_8h.html)
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
383
725
c9b882bef838 add docs for the compare.h and printf.h utilities
Mike Becker <universe@uap-core.de>
parents: 724
diff changeset
384 In this utility header you can find `printf()`-like functions that can write the formatted output to an arbitrary
c9b882bef838 add docs for the compare.h and printf.h utilities
Mike Becker <universe@uap-core.de>
parents: 724
diff changeset
385 stream (or UCX buffer, resp.), or to memory allocated by an allocator within a single function call.
c9b882bef838 add docs for the compare.h and printf.h utilities
Mike Becker <universe@uap-core.de>
parents: 724
diff changeset
386 With the help of these convenience functions, you do not need to `snprintf` your string to a temporary buffer anymore,
c9b882bef838 add docs for the compare.h and printf.h utilities
Mike Becker <universe@uap-core.de>
parents: 724
diff changeset
387 plus you do not need to worry about too small buffer sizes, because the functions will automatically allocate enough
c9b882bef838 add docs for the compare.h and printf.h utilities
Mike Becker <universe@uap-core.de>
parents: 724
diff changeset
388 memory to contain the entire formatted string.
c9b882bef838 add docs for the compare.h and printf.h utilities
Mike Becker <universe@uap-core.de>
parents: 724
diff changeset
389
720
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
390 ### Compare Functions
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
391
f73adc75e50a add empty sections to features.md
Mike Becker <universe@uap-core.de>
parents: 716
diff changeset
392 *Header file:* [compare.h](api/compare_8h.html)
725
c9b882bef838 add docs for the compare.h and printf.h utilities
Mike Becker <universe@uap-core.de>
parents: 724
diff changeset
393
c9b882bef838 add docs for the compare.h and printf.h utilities
Mike Becker <universe@uap-core.de>
parents: 724
diff changeset
394 This header file contains a collection of compare functions for various data types.
c9b882bef838 add docs for the compare.h and printf.h utilities
Mike Becker <universe@uap-core.de>
parents: 724
diff changeset
395 Their signatures are designed to be compatible with the `cx_compare_func` function pointer type.

mercurial