Tue, 20 Aug 2024 18:02:39 +0200
merge feature/tree_add branch
relates to #390
606 | 1 | /* |
2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. | |
3 | * | |
4 | * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved. | |
5 | * | |
6 | * Redistribution and use in source and binary forms, with or without | |
7 | * modification, are permitted provided that the following conditions are met: | |
8 | * | |
9 | * 1. Redistributions of source code must retain the above copyright | |
10 | * notice, this list of conditions and the following disclaimer. | |
11 | * | |
12 | * 2. Redistributions in binary form must reproduce the above copyright | |
13 | * notice, this list of conditions and the following disclaimer in the | |
14 | * documentation and/or other materials provided with the distribution. | |
15 | * | |
16 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" | |
17 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
18 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
19 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE | |
20 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | |
21 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | |
22 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
23 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |
24 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
25 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE | |
26 | * POSSIBILITY OF SUCH DAMAGE. | |
27 | */ | |
28 | /** | |
29 | * \file array_list.h | |
30 | * \brief Array list implementation. | |
31 | * \details Also provides several low-level functions for custom array list implementations. | |
32 | * \author Mike Becker | |
33 | * \author Olaf Wintermann | |
34 | * \copyright 2-Clause BSD License | |
35 | */ | |
36 | ||
37 | ||
38 | #ifndef UCX_ARRAY_LIST_H | |
39 | #define UCX_ARRAY_LIST_H | |
40 | ||
617
cec11387c1be
fix include in array_list.h
Olaf Wintermann <olaf.wintermann@gmail.com>
parents:
612
diff
changeset
|
41 | #include "list.h" |
606 | 42 | |
43 | #ifdef __cplusplus | |
44 | extern "C" { | |
45 | #endif | |
46 | ||
47 | /** | |
807
c8d692131b1e
remove flags to disable SBO in tests - fix #343 fix #358
Mike Becker <universe@uap-core.de>
parents:
804
diff
changeset
|
48 | * The maximum item size in an array list that fits into stack buffer when swapped. |
804
5136f2fc32ec
add CX_DISABLE_ARRAY_LIST_SWAP_SBO flag
Mike Becker <universe@uap-core.de>
parents:
795
diff
changeset
|
49 | */ |
807
c8d692131b1e
remove flags to disable SBO in tests - fix #343 fix #358
Mike Becker <universe@uap-core.de>
parents:
804
diff
changeset
|
50 | extern unsigned cx_array_swap_sbo_size; |
804
5136f2fc32ec
add CX_DISABLE_ARRAY_LIST_SWAP_SBO flag
Mike Becker <universe@uap-core.de>
parents:
795
diff
changeset
|
51 | |
5136f2fc32ec
add CX_DISABLE_ARRAY_LIST_SWAP_SBO flag
Mike Becker <universe@uap-core.de>
parents:
795
diff
changeset
|
52 | /** |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
53 | * Declares variables for an array that can be used with the convenience macros. |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
54 | * |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
55 | * @see cx_array_simple_add() |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
56 | * @see cx_array_simple_copy() |
834
04c53b3c8378
capitalize cx_array_declare()
Mike Becker <universe@uap-core.de>
parents:
832
diff
changeset
|
57 | * @see cx_array_initialize() |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
58 | */ |
834
04c53b3c8378
capitalize cx_array_declare()
Mike Becker <universe@uap-core.de>
parents:
832
diff
changeset
|
59 | #define CX_ARRAY_DECLARE(type, name) \ |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
60 | type * name; \ |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
61 | size_t name##_size; \ |
844
3270ea9e41ef
fix another superfluous semicolon...
Mike Becker <universe@uap-core.de>
parents:
843
diff
changeset
|
62 | size_t name##_capacity |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
63 | |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
64 | /** |
834
04c53b3c8378
capitalize cx_array_declare()
Mike Becker <universe@uap-core.de>
parents:
832
diff
changeset
|
65 | * Initializes an array declared with CX_ARRAY_DECLARE(). |
832
97df2e4c68fb
make cx_array_simple_add() automatically take the address of the element
Mike Becker <universe@uap-core.de>
parents:
831
diff
changeset
|
66 | * |
97df2e4c68fb
make cx_array_simple_add() automatically take the address of the element
Mike Becker <universe@uap-core.de>
parents:
831
diff
changeset
|
67 | * The memory for the array is allocated with stdlib malloc(). |
97df2e4c68fb
make cx_array_simple_add() automatically take the address of the element
Mike Becker <universe@uap-core.de>
parents:
831
diff
changeset
|
68 | * @param array the array |
97df2e4c68fb
make cx_array_simple_add() automatically take the address of the element
Mike Becker <universe@uap-core.de>
parents:
831
diff
changeset
|
69 | * @param capacity the initial capacity |
97df2e4c68fb
make cx_array_simple_add() automatically take the address of the element
Mike Becker <universe@uap-core.de>
parents:
831
diff
changeset
|
70 | */ |
97df2e4c68fb
make cx_array_simple_add() automatically take the address of the element
Mike Becker <universe@uap-core.de>
parents:
831
diff
changeset
|
71 | #define cx_array_initialize(array, capacity) \ |
97df2e4c68fb
make cx_array_simple_add() automatically take the address of the element
Mike Becker <universe@uap-core.de>
parents:
831
diff
changeset
|
72 | array##_capacity = capacity; \ |
97df2e4c68fb
make cx_array_simple_add() automatically take the address of the element
Mike Becker <universe@uap-core.de>
parents:
831
diff
changeset
|
73 | array##_size = 0; \ |
843
7d2959b7fff2
fix superfluous semicolon
Mike Becker <universe@uap-core.de>
parents:
834
diff
changeset
|
74 | array = malloc(sizeof(array[0]) * capacity) |
832
97df2e4c68fb
make cx_array_simple_add() automatically take the address of the element
Mike Becker <universe@uap-core.de>
parents:
831
diff
changeset
|
75 | |
97df2e4c68fb
make cx_array_simple_add() automatically take the address of the element
Mike Becker <universe@uap-core.de>
parents:
831
diff
changeset
|
76 | /** |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
77 | * Defines a reallocation mechanism for arrays. |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
78 | */ |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
79 | struct cx_array_reallocator_s { |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
80 | /** |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
81 | * Reallocates space for the given array. |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
82 | * |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
83 | * Implementations are not required to free the original array. |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
84 | * This allows reallocation of static memory by allocating heap memory |
795
00ba1bfa4ab4
fix documentation of reallocator struct
Mike Becker <universe@uap-core.de>
parents:
763
diff
changeset
|
85 | * and copying the array contents. The information in the custom fields of |
00ba1bfa4ab4
fix documentation of reallocator struct
Mike Becker <universe@uap-core.de>
parents:
763
diff
changeset
|
86 | * the referenced allocator can be used to track the state of the memory |
00ba1bfa4ab4
fix documentation of reallocator struct
Mike Becker <universe@uap-core.de>
parents:
763
diff
changeset
|
87 | * or to transport other additional data. |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
88 | * |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
89 | * @param array the array to reallocate |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
90 | * @param capacity the new capacity (number of elements) |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
91 | * @param elem_size the size of each element |
609
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
92 | * @param alloc a reference to this allocator |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
93 | * @return a pointer to the reallocated memory or \c NULL on failure |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
94 | */ |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
95 | void *(*realloc)( |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
96 | void *array, |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
97 | size_t capacity, |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
98 | size_t elem_size, |
609
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
99 | struct cx_array_reallocator_s *alloc |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
100 | ); |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
101 | |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
102 | /** |
609
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
103 | * Custom data pointer. |
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
104 | */ |
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
105 | void *ptr1; |
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
106 | /** |
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
107 | * Custom data pointer. |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
108 | */ |
609
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
109 | void *ptr2; |
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
110 | /** |
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
111 | * Custom data integer. |
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
112 | */ |
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
113 | size_t int1; |
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
114 | /** |
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
115 | * Custom data integer. |
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
116 | */ |
6ae8146d9f62
more custom data for array re-allocator
Mike Becker <universe@uap-core.de>
parents:
608
diff
changeset
|
117 | size_t int2; |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
118 | }; |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
119 | |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
120 | /** |
817
949908c97474
add cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
807
diff
changeset
|
121 | * A default stdlib-based array reallocator. |
949908c97474
add cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
807
diff
changeset
|
122 | */ |
818
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
123 | extern struct cx_array_reallocator_s *cx_array_default_reallocator; |
817
949908c97474
add cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
807
diff
changeset
|
124 | |
949908c97474
add cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
807
diff
changeset
|
125 | /** |
819
5da2ead43077
rename cx_array_copy_result to just cx_array_result
Mike Becker <universe@uap-core.de>
parents:
818
diff
changeset
|
126 | * Return codes for array functions. |
610
de5d3ee6435f
#219 array list: implement add and at
Mike Becker <universe@uap-core.de>
parents:
609
diff
changeset
|
127 | */ |
819
5da2ead43077
rename cx_array_copy_result to just cx_array_result
Mike Becker <universe@uap-core.de>
parents:
818
diff
changeset
|
128 | enum cx_array_result { |
5da2ead43077
rename cx_array_copy_result to just cx_array_result
Mike Becker <universe@uap-core.de>
parents:
818
diff
changeset
|
129 | CX_ARRAY_SUCCESS, |
5da2ead43077
rename cx_array_copy_result to just cx_array_result
Mike Becker <universe@uap-core.de>
parents:
818
diff
changeset
|
130 | CX_ARRAY_REALLOC_NOT_SUPPORTED, |
5da2ead43077
rename cx_array_copy_result to just cx_array_result
Mike Becker <universe@uap-core.de>
parents:
818
diff
changeset
|
131 | CX_ARRAY_REALLOC_FAILED, |
610
de5d3ee6435f
#219 array list: implement add and at
Mike Becker <universe@uap-core.de>
parents:
609
diff
changeset
|
132 | }; |
de5d3ee6435f
#219 array list: implement add and at
Mike Becker <universe@uap-core.de>
parents:
609
diff
changeset
|
133 | |
de5d3ee6435f
#219 array list: implement add and at
Mike Becker <universe@uap-core.de>
parents:
609
diff
changeset
|
134 | /** |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
135 | * Copies elements from one array to another. |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
136 | * |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
137 | * The elements are copied to the \p target array at the specified \p index, |
637
ceadf0792ded
remove the untrue restriction for the index parameter of cx_array_copy() from the documentation
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
138 | * overwriting possible elements. The \p index does not need to be in range of |
ceadf0792ded
remove the untrue restriction for the index parameter of cx_array_copy() from the documentation
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
139 | * the current array \p size. If the new index plus the number of elements added |
ceadf0792ded
remove the untrue restriction for the index parameter of cx_array_copy() from the documentation
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
140 | * would extend the array's size, and \p capacity is not \c NULL, the remaining |
ceadf0792ded
remove the untrue restriction for the index parameter of cx_array_copy() from the documentation
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
141 | * capacity is used. |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
142 | * |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
143 | * If the capacity is insufficient to hold the new data, a reallocation |
818
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
144 | * attempt is made, unless the \p reallocator is set to \c NULL, in which case |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
145 | * this function ultimately returns a failure. |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
146 | * |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
147 | * @param target a pointer to the target array |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
148 | * @param size a pointer to the size of the target array |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
149 | * @param capacity a pointer to the target array's capacity - |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
150 | * \c NULL if only the size shall be used to bound the array |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
151 | * @param index the index where the copied elements shall be placed |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
152 | * @param src the source array |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
153 | * @param elem_size the size of one element |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
154 | * @param elem_count the number of elements to copy |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
155 | * @param reallocator the array reallocator to use, or \c NULL |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
156 | * if reallocation shall not happen |
610
de5d3ee6435f
#219 array list: implement add and at
Mike Becker <universe@uap-core.de>
parents:
609
diff
changeset
|
157 | * @return zero on success, non-zero error code on failure |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
158 | */ |
819
5da2ead43077
rename cx_array_copy_result to just cx_array_result
Mike Becker <universe@uap-core.de>
parents:
818
diff
changeset
|
159 | enum cx_array_result cx_array_copy( |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
160 | void **target, |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
161 | size_t *size, |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
162 | size_t *capacity, |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
163 | size_t index, |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
164 | void const *src, |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
165 | size_t elem_size, |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
166 | size_t elem_count, |
610
de5d3ee6435f
#219 array list: implement add and at
Mike Becker <universe@uap-core.de>
parents:
609
diff
changeset
|
167 | struct cx_array_reallocator_s *reallocator |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
168 | ) __attribute__((__nonnull__(1, 2, 5))); |
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
169 | |
818
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
170 | /** |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
171 | * Convenience macro that uses cx_array_copy() with a default layout and the default reallocator. |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
172 | * |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
173 | * @param array the name of the array (NOT a pointer to the array) |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
174 | * @param index the index where the copied elements shall be placed |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
175 | * @param src the source array |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
176 | * @param count the number of elements to copy |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
177 | */ |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
178 | #define cx_array_simple_copy(array, index, src, count) \ |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
179 | cx_array_copy((void**)&(array), &(array##_size), &(array##_capacity), \ |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
180 | index, src, sizeof((array)[0]), count, cx_array_default_reallocator) |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
181 | |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
182 | /** |
818
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
183 | * Adds an element to an array with the possibility of allocating more space. |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
184 | * |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
185 | * The element \p elem is added to the end of the \p target array which containing |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
186 | * \p size elements, already. The \p capacity must not be \c NULL and point a |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
187 | * variable holding the current maximum number of elements the array can hold. |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
188 | * |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
189 | * If the capacity is insufficient to hold the new element, and the optional |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
190 | * \p reallocator is not \c NULL, an attempt increase the \p capacity is made |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
191 | * and the new capacity is written back. |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
192 | * |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
193 | * @param target a pointer to the target array |
818
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
194 | * @param size a pointer to the size of the target array |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
195 | * @param capacity a pointer to the target array's capacity - must not be \c NULL |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
196 | * @param elem_size the size of one element |
832
97df2e4c68fb
make cx_array_simple_add() automatically take the address of the element
Mike Becker <universe@uap-core.de>
parents:
831
diff
changeset
|
197 | * @param elem a pointer to the element to add |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
198 | * @param reallocator the array reallocator to use, or \c NULL if reallocation shall not happen |
818
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
199 | * @return zero on success, non-zero error code on failure |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
200 | */ |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
201 | #define cx_array_add(target, size, capacity, elem_size, elem, reallocator) \ |
2be8fe3d5a2d
add cx_array_add() + fix type of cx_array_default_reallocator
Mike Becker <universe@uap-core.de>
parents:
817
diff
changeset
|
202 | cx_array_copy((void**)(target), size, capacity, *(size), elem, elem_size, 1, reallocator) |
623
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
203 | |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
204 | /** |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
205 | * Convenience macro that uses cx_array_add() with a default layout and the default reallocator. |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
206 | * |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
207 | * @param array the name of the array (NOT a pointer to the array) |
832
97df2e4c68fb
make cx_array_simple_add() automatically take the address of the element
Mike Becker <universe@uap-core.de>
parents:
831
diff
changeset
|
208 | * @param elem the element to add (NOT a pointer, address is automatically taken) |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
209 | */ |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
210 | #define cx_array_simple_add(array, elem) \ |
832
97df2e4c68fb
make cx_array_simple_add() automatically take the address of the element
Mike Becker <universe@uap-core.de>
parents:
831
diff
changeset
|
211 | cx_array_simple_copy(array, array##_size, &(elem), 1) |
831
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
212 | |
7970eac1c598
add convenience macros for cx_array_*
Mike Becker <universe@uap-core.de>
parents:
819
diff
changeset
|
213 | /** |
623
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
214 | * Swaps two array elements. |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
215 | * |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
216 | * @param arr the array |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
217 | * @param elem_size the element size |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
218 | * @param idx1 index of first element |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
219 | * @param idx2 index of second element |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
220 | */ |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
221 | void cx_array_swap( |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
222 | void *arr, |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
223 | size_t elem_size, |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
224 | size_t idx1, |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
225 | size_t idx2 |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
226 | ) __attribute__((__nonnull__)); |
21082350a590
#219 array list: implement reverse
Mike Becker <universe@uap-core.de>
parents:
617
diff
changeset
|
227 | |
608
2e93521145ac
proposal for a low level array copy
Mike Becker <universe@uap-core.de>
parents:
606
diff
changeset
|
228 | /** |
855
35bcb3216c0d
fix inconsistent use of item_size and elem_size
Mike Becker <universe@uap-core.de>
parents:
844
diff
changeset
|
229 | * Allocates an array list for storing elements with \p elem_size bytes each. |
606 | 230 | * |
855
35bcb3216c0d
fix inconsistent use of item_size and elem_size
Mike Becker <universe@uap-core.de>
parents:
844
diff
changeset
|
231 | * If \p elem_size is CX_STORE_POINTERS, the created list will be created as if |
763
741a2040fa33
make cx_cmp_ptr default comparator for pointer lists - relates to #340
Mike Becker <universe@uap-core.de>
parents:
759
diff
changeset
|
232 | * cxListStorePointers() was called immediately after creation and the compare |
741a2040fa33
make cx_cmp_ptr default comparator for pointer lists - relates to #340
Mike Becker <universe@uap-core.de>
parents:
759
diff
changeset
|
233 | * function will be automatically set to cx_cmp_ptr(), if none is given. |
669
dce9b8450656
add docs for CX_STORE_POINTERS and remove cxHashMapCreateForPointers()
Mike Becker <universe@uap-core.de>
parents:
662
diff
changeset
|
234 | * |
606 | 235 | * @param allocator the allocator for allocating the list memory |
670
4ad8ea3aee49
allow NULL for allocator and comparator
Mike Becker <universe@uap-core.de>
parents:
669
diff
changeset
|
236 | * (if \c NULL the cxDefaultAllocator will be used) |
606 | 237 | * @param comparator the comparator for the elements |
763
741a2040fa33
make cx_cmp_ptr default comparator for pointer lists - relates to #340
Mike Becker <universe@uap-core.de>
parents:
759
diff
changeset
|
238 | * (if \c NULL, and the list is not storing pointers, sort and find |
741a2040fa33
make cx_cmp_ptr default comparator for pointer lists - relates to #340
Mike Becker <universe@uap-core.de>
parents:
759
diff
changeset
|
239 | * functions will not work) |
855
35bcb3216c0d
fix inconsistent use of item_size and elem_size
Mike Becker <universe@uap-core.de>
parents:
844
diff
changeset
|
240 | * @param elem_size the size of each element in bytes |
606 | 241 | * @param initial_capacity the initial number of elements the array can store |
242 | * @return the created list | |
243 | */ | |
244 | CxList *cxArrayListCreate( | |
245 | CxAllocator const *allocator, | |
677
b09aae58bba4
refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
670
diff
changeset
|
246 | cx_compare_func comparator, |
855
35bcb3216c0d
fix inconsistent use of item_size and elem_size
Mike Becker <universe@uap-core.de>
parents:
844
diff
changeset
|
247 | size_t elem_size, |
606 | 248 | size_t initial_capacity |
670
4ad8ea3aee49
allow NULL for allocator and comparator
Mike Becker <universe@uap-core.de>
parents:
669
diff
changeset
|
249 | ); |
606 | 250 | |
662
d0d95740071b
add simple functions for creating lists
Mike Becker <universe@uap-core.de>
parents:
637
diff
changeset
|
251 | /** |
855
35bcb3216c0d
fix inconsistent use of item_size and elem_size
Mike Becker <universe@uap-core.de>
parents:
844
diff
changeset
|
252 | * Allocates an array list for storing elements with \p elem_size bytes each. |
662
d0d95740071b
add simple functions for creating lists
Mike Becker <universe@uap-core.de>
parents:
637
diff
changeset
|
253 | * |
d0d95740071b
add simple functions for creating lists
Mike Becker <universe@uap-core.de>
parents:
637
diff
changeset
|
254 | * The list will use the cxDefaultAllocator and \em NO compare function. |
d0d95740071b
add simple functions for creating lists
Mike Becker <universe@uap-core.de>
parents:
637
diff
changeset
|
255 | * If you want to call functions that need a compare function, you have to |
d0d95740071b
add simple functions for creating lists
Mike Becker <universe@uap-core.de>
parents:
637
diff
changeset
|
256 | * set it immediately after creation or use cxArrayListCreate(). |
d0d95740071b
add simple functions for creating lists
Mike Becker <universe@uap-core.de>
parents:
637
diff
changeset
|
257 | * |
855
35bcb3216c0d
fix inconsistent use of item_size and elem_size
Mike Becker <universe@uap-core.de>
parents:
844
diff
changeset
|
258 | * If \p elem_size is CX_STORE_POINTERS, the created list will be created as if |
763
741a2040fa33
make cx_cmp_ptr default comparator for pointer lists - relates to #340
Mike Becker <universe@uap-core.de>
parents:
759
diff
changeset
|
259 | * cxListStorePointers() was called immediately after creation and the compare |
741a2040fa33
make cx_cmp_ptr default comparator for pointer lists - relates to #340
Mike Becker <universe@uap-core.de>
parents:
759
diff
changeset
|
260 | * function will be automatically set to cx_cmp_ptr(). |
669
dce9b8450656
add docs for CX_STORE_POINTERS and remove cxHashMapCreateForPointers()
Mike Becker <universe@uap-core.de>
parents:
662
diff
changeset
|
261 | * |
855
35bcb3216c0d
fix inconsistent use of item_size and elem_size
Mike Becker <universe@uap-core.de>
parents:
844
diff
changeset
|
262 | * @param elem_size the size of each element in bytes |
662
d0d95740071b
add simple functions for creating lists
Mike Becker <universe@uap-core.de>
parents:
637
diff
changeset
|
263 | * @param initial_capacity the initial number of elements the array can store |
d0d95740071b
add simple functions for creating lists
Mike Becker <universe@uap-core.de>
parents:
637
diff
changeset
|
264 | * @return the created list |
d0d95740071b
add simple functions for creating lists
Mike Becker <universe@uap-core.de>
parents:
637
diff
changeset
|
265 | */ |
855
35bcb3216c0d
fix inconsistent use of item_size and elem_size
Mike Becker <universe@uap-core.de>
parents:
844
diff
changeset
|
266 | #define cxArrayListCreateSimple(elem_size, initial_capacity) \ |
35bcb3216c0d
fix inconsistent use of item_size and elem_size
Mike Becker <universe@uap-core.de>
parents:
844
diff
changeset
|
267 | cxArrayListCreate(NULL, NULL, elem_size, initial_capacity) |
606 | 268 | |
269 | #ifdef __cplusplus | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
623
diff
changeset
|
270 | } // extern "C" |
606 | 271 | #endif |
272 | ||
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
623
diff
changeset
|
273 | #endif // UCX_ARRAY_LIST_H |