comparison: docs/Writerside/topics/array_list.h.md
docs/Writerside/topics/array_list.h.md
- changeset 1425
- 83284b289430
- parent 1424
- 563033aa998c
equal
deleted
inserted
replaced
| 1424:563033aa998c | 1425:83284b289430 |
|---|---|
| 94 | 94 |
| 95 typedef struct { | 95 typedef struct { |
| 96 void *(*realloc)(void *array, | 96 void *(*realloc)(void *array, |
| 97 size_t old_capacity, size_t new_capacity, | 97 size_t old_capacity, size_t new_capacity, |
| 98 size_t elem_size, CxArrayReallocator *alloc); | 98 size_t elem_size, CxArrayReallocator *alloc); |
| 99 void *ptr1; | 99 const CxAllocator *allocator; |
| 100 void *ptr2; | 100 const void *stack_ptr; |
| 101 size_t int1; | |
| 102 size_t int2; | |
| 103 } CxArrayReallocator; | 101 } CxArrayReallocator; |
| 104 | 102 |
| 105 CxArrayReallocator cx_array_reallocator( | 103 CxArrayReallocator cx_array_reallocator( |
| 106 const struct cx_allocator_s *allocator, | 104 const struct cx_allocator_s *allocator, |
| 107 const void *stackmem | 105 const void *stack_ptr |
| 108 ); | 106 ); |
| 109 | 107 |
| 110 extern CxArrayReallocator* cx_array_default_reallocator; | 108 extern CxArrayReallocator* cx_array_default_reallocator; |
| 111 ``` | 109 ``` |
| 112 | 110 |
| 118 The default `cx_array_default_reallocator` simply defers to the [default allocator](allocator.h.md#default-allocator). | 116 The default `cx_array_default_reallocator` simply defers to the [default allocator](allocator.h.md#default-allocator). |
| 119 | 117 |
| 120 A reallocator created with the `cx_array_reallocator()` function uses a more sophisticated approach. | 118 A reallocator created with the `cx_array_reallocator()` function uses a more sophisticated approach. |
| 121 On the one hand, it can use an arbitrary UCX [allocator](allocator.h.md) for the reallocation, | 119 On the one hand, it can use an arbitrary UCX [allocator](allocator.h.md) for the reallocation, |
| 122 and on the other hand, it can optionally keep track of a stack memory pointer. | 120 and on the other hand, it can optionally keep track of a stack memory pointer. |
| 123 If you pass a non-`NULL` pointer to `stackmem`, the reallocator will _always_ allocate _new_ memory for the array, | 121 If you pass a non-`NULL` pointer to `stack_ptr`, the reallocator will _always_ allocate _new_ memory for the array, |
| 124 if the current location equals the `stackmem` address. | 122 if the current location equals the `stack_ptr` address. |
| 125 | 123 |
| 126 This allows you to allocate an array on the stack and instruct UCX to automatically move it to heap memory when the capacity is exceeded. | 124 This allows you to allocate an array on the stack and instruct UCX to automatically move it to heap memory when the capacity is exceeded. |
| 127 Combined with a UCX [memory pool](mempool.h.md) this can be a powerful tool for local arrays | 125 Combined with a UCX [memory pool](mempool.h.md) this can be a powerful tool. |
| 128 which are expected to stay within the bounds of the stack memory most of the time, but are also allowed to sometimes grow their capacity. | 126 For example, you can add small arrays to your structs plus a memory pool and then use that memory pool to reallocate the arrays on the heap when needed. |
| 127 When you are done with the arrays, you can then use the memory pool to free the memory for those arrays that needed to be moved to the heap. | |
| 129 | 128 |
| 130 ## Reserve | 129 ## Reserve |
| 131 | 130 |
| 132 ```C | 131 ```C |
| 133 #include <cx/array_list.h> | 132 #include <cx/array_list.h> |
| 310 except that they return the index of the closest element if the searched element is not found. | 309 except that they return the index of the closest element if the searched element is not found. |
| 311 The former function returns the closest element that is less or equal (the greatest lower bound / infimum), | 310 The former function returns the closest element that is less or equal (the greatest lower bound / infimum), |
| 312 and the latter function returns the closest element that is larger or equal (the least upper bound / supremum) | 311 and the latter function returns the closest element that is larger or equal (the least upper bound / supremum) |
| 313 than the searched element. | 312 than the searched element. |
| 314 | 313 |
| 315 > Note that all of the above functions are only well-defined on arrays which are sorted with respect to the given compare function. | 314 > Note that all the above functions are only well-defined on arrays which are sorted with respect to the given compare function. |
| 316 > | 315 > |
| 317 > This can, for example, easily be achieved by calling the standard library's `qsort()` function. | 316 > This can, for example, easily be achieved by calling the standard library's `qsort()` function. |
| 318 >{style="note"} | 317 >{style="note"} |
| 319 | 318 |
| 320 > Despite the name, neither C nor POSIX standards require the standard library's `bsearch()` function to be implemented using binary search. | 319 > Despite the name, neither C nor POSIX standards require the standard library's `bsearch()` function to be implemented using binary search. |
