comparison: docs/src/features.md
docs/src/features.md
- changeset 854
- fe0d69d72bcd
- parent 853
- d4baf4dd55c3
- child 890
- 54565fd74e74
equal
deleted
inserted
replaced
| 853:d4baf4dd55c3 | 854:fe0d69d72bcd |
|---|---|
| 185 You do not always need all fields in the iterator structure, depending on your use case. | 185 You do not always need all fields in the iterator structure, depending on your use case. |
| 186 Sometimes you only need the `index` (for example when iterating over simple lists), and other times you will need the | 186 Sometimes you only need the `index` (for example when iterating over simple lists), and other times you will need the |
| 187 `slot` and `kv_data` fields (for example when iterating over maps). | 187 `slot` and `kv_data` fields (for example when iterating over maps). |
| 188 | 188 |
| 189 If the predefined fields are insufficient for your use case, you can alternatively create your own iterator structure | 189 If the predefined fields are insufficient for your use case, you can alternatively create your own iterator structure |
| 190 and place the `CX_ITERATOR_BASE` macro inside. | 190 and place the `CX_ITERATOR_BASE` macro as first member of that structure. |
| 191 | 191 |
| 192 Usually an iterator is not mutating the collection it is iterating over. | 192 Usually an iterator is not mutating the collection it is iterating over. |
| 193 In some programming languages it is even disallowed to change the collection while iterating with foreach. | 193 In some programming languages it is even disallowed to change the collection while iterating with foreach. |
| 194 But sometimes it is desirable to remove an element from the collection while iterating over it. | 194 But sometimes it is desirable to remove an element from the collection while iterating over it. |
| 195 For this purpose, most collections allow the creation of a _mutating_ iterator. | 195 For this purpose, most collections allow the creation of a _mutating_ iterator. |
| 202 | 202 |
| 203 *Header file:* [collection.h](api/collection_8h.html) | 203 *Header file:* [collection.h](api/collection_8h.html) |
| 204 | 204 |
| 205 Collections in UCX 3 have several common features. | 205 Collections in UCX 3 have several common features. |
| 206 If you want to implement an own collection data type that uses the same features, you can use the | 206 If you want to implement an own collection data type that uses the same features, you can use the |
| 207 `CX_COLLECTION_MEMBERS` macro at the beginning of your struct to roll out all members a usual UCX collection has. | 207 `CX_COLLECTION_BASE` macro at the beginning of your struct to roll out all members a usual UCX collection has. |
| 208 ```c | 208 ```c |
| 209 struct my_fancy_collection_s { | 209 struct my_fancy_collection_s { |
| 210 CX_COLLECTION_MEMBERS | 210 CX_COLLECTION_BASE; |
| 211 struct my_collection_data_s *data; | 211 struct my_collection_data_s *data; |
| 212 }; | 212 }; |
| 213 ``` | 213 ``` |
| 214 Based on this structure, this header provides some convenience macros for invoking the destructor functions | 214 Based on this structure, this header provides some convenience macros for invoking the destructor functions |
| 215 that are part of the basic collection members. | 215 that are part of the basic collection members. |
| 223 | 223 |
| 224 ## List | 224 ## List |
| 225 | 225 |
| 226 *Header file:* [list.h](api/list_8h.html) | 226 *Header file:* [list.h](api/list_8h.html) |
| 227 | 227 |
| 228 This header defines a common interface for all list implementations, which is basically as simple as the following | 228 This header defines a common interface for all list implementations. |
| 229 structure. | 229 |
| 230 ```c | 230 UCX already comes with two common list implementations (linked list and array list) that should cover most use cases. |
| 231 struct cx_list_s { | 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 |
| 232 CX_COLLECTION_MEMBERS // size, capacity, etc. | 232 `struct cx_list_s` as first member, and set an appropriate list class that implements the functionality. |
| 233 cx_list_class const *cl; // The list class definition | |
| 234 }; | |
| 235 ``` | |
| 236 The actual structure contains one more class pointer that is used when wrapping a list into a pointer-aware list | |
| 237 with `cxListStorePointers()`. What this means, is that - if you want to implement your own list structure - you | |
| 238 only need to cover the case where the list is storing copies of your objects. | |
| 239 | |
| 240 UCX comes with two common list implementations (linked list and array list) that should cover most use cases. | |
| 241 But if you feel the need to implement an own list, the only thing you need to do is to define a struct where | |
| 242 `struct cx_list_s`, and set an appropriate list class that implements the functionality. | |
| 243 It is strongly recommended that this class is shared among all instances of the same list type, because otherwise | 233 It is strongly recommended that this class is shared among all instances of the same list type, because otherwise |
| 244 the `cxListCompare` function cannot use the optimized implementation of your class and will instead fall back to | 234 the `cxListCompare` function cannot use the optimized implementation of your class and will instead fall back to |
| 245 using iterators to compare the contents element-wise. | 235 using iterators to compare the contents element-wise. |
| 246 | 236 |
| 247 ### Linked List | 237 ### Linked List |
