Ruby: darray.h Source File

Ruby 3.4.4p34 (2025-05-14 revision a38531fd3f617bf734ef7d6c595325f69985ea1d)

darray.h
1#ifndef RUBY_DARRAY_H
2#define RUBY_DARRAY_H
3
4#include <stdint.h>
5#include <stddef.h>
6#include <stdlib.h>
7
8// Type for a dynamic array. Use to declare a dynamic array.
9// It is a pointer so it fits in st_table nicely. Designed
10// to be fairly type-safe.
11//
12// NULL is a valid empty dynamic array.
13//
14// Example:
15// rb_darray(char) char_array = NULL;
16// rb_darray_append(&char_array, 'e');
17// printf("pushed %c\n", *rb_darray_ref(char_array, 0));
18// rb_darray_free(char_array);
19//
20#define rb_darray(T) struct { rb_darray_meta_t meta; T data[]; } *
21
22// Copy an element out of the array. Warning: not bounds checked.
23//
24// T rb_darray_get(rb_darray(T) ary, size_t idx);
25//
26#define rb_darray_get(ary, idx) ((ary)->data[(idx)])
27
28// Assign to an element. Warning: not bounds checked.
29//
30// void rb_darray_set(rb_darray(T) ary, size_t idx, T element);
31//
32#define rb_darray_set(ary, idx, element) ((ary)->data[(idx)] = (element))
33
34// Get a pointer to an element. Warning: not bounds checked.
35//
36// T *rb_darray_ref(rb_darray(T) ary, size_t idx);
37//
38#define rb_darray_ref(ary, idx) (&((ary)->data[(idx)]))
39
40/* Copy a new element into the array. ptr_to_ary is evaluated multiple times.
41 *
42 * void rb_darray_append(rb_darray(T) *ptr_to_ary, T element);
43 */
44#define rb_darray_append(ptr_to_ary, element) do { \
45 rb_darray_ensure_space((ptr_to_ary), \
46 sizeof(**(ptr_to_ary)), \
47 sizeof((*(ptr_to_ary))->data[0])); \
48 rb_darray_set(*(ptr_to_ary), \
49 (*(ptr_to_ary))->meta.size, \
50 (element)); \
51 (*(ptr_to_ary))->meta.size++; \
52} while (0)
53
54#define rb_darray_insert(ptr_to_ary, idx, element) do { \
55 rb_darray_ensure_space((ptr_to_ary), \
56 sizeof(**(ptr_to_ary)), \
57 sizeof((*(ptr_to_ary))->data[0])); \
58 MEMMOVE( \
59 rb_darray_ref(*(ptr_to_ary), idx + 1), \
60 rb_darray_ref(*(ptr_to_ary), idx), \
61 (*(ptr_to_ary))->data[0], \
62 rb_darray_size(*(ptr_to_ary)) - idx); \
63 rb_darray_set(*(ptr_to_ary), idx, element); \
64 (*(ptr_to_ary))->meta.size++; \
65} while (0)
66
67// Iterate over items of the array in a for loop
68//
69#define rb_darray_foreach(ary, idx_name, elem_ptr_var) \
70 for (size_t idx_name = 0; idx_name < rb_darray_size(ary) && ((elem_ptr_var) = rb_darray_ref(ary, idx_name)); ++idx_name)
71
72// Iterate over valid indices in the array in a for loop
73//
74#define rb_darray_for(ary, idx_name) \
75 for (size_t idx_name = 0; idx_name < rb_darray_size(ary); ++idx_name)
76
77/* Make a dynamic array of a certain size. All bytes backing the elements are set to zero.
78 * Return 1 on success and 0 on failure.
79 *
80 * Note that NULL is a valid empty dynamic array.
81 *
82 * void rb_darray_make(rb_darray(T) *ptr_to_ary, size_t size);
83 */
84#define rb_darray_make(ptr_to_ary, size) \
85 rb_darray_make_impl((ptr_to_ary), size, sizeof(**(ptr_to_ary)), sizeof((*(ptr_to_ary))->data[0]))
86
87/* Resize the darray to a new capacity. The new capacity must be greater than
88 * or equal to the size of the darray.
89 *
90 * void rb_darray_resize_capa(rb_darray(T) *ptr_to_ary, size_t capa);
91 */
92#define rb_darray_resize_capa(ptr_to_ary, capa) \
93 rb_darray_resize_capa_impl((ptr_to_ary), capa, sizeof(**(ptr_to_ary)), sizeof((*(ptr_to_ary))->data[0]))
94
95#define rb_darray_data_ptr(ary) ((ary)->data)
96
97 typedef struct rb_darray_meta {
98 size_t size;
99 size_t capa;
100} rb_darray_meta_t;
101
102/* Set the size of the array to zero without freeing the backing memory.
103 * Allows reusing the same array. */
104static inline void
105rb_darray_clear(void *ary)
106{
107 rb_darray_meta_t *meta = ary;
108 if (meta) {
109 meta->size = 0;
110 }
111}
112
113// Get the size of the dynamic array.
114//
115static inline size_t
116rb_darray_size(const void *ary)
117{
118 const rb_darray_meta_t *meta = ary;
119 return meta ? meta->size : 0;
120}
121
122
123static inline void
124rb_darray_pop(void *ary, size_t count)
125{
126 rb_darray_meta_t *meta = ary;
127 meta->size -= count;
128}
129
130// Get the capacity of the dynamic array.
131//
132static inline size_t
133rb_darray_capa(const void *ary)
134{
135 const rb_darray_meta_t *meta = ary;
136 return meta ? meta->capa : 0;
137}
138
139/* Free the dynamic array. */
140static inline void
141rb_darray_free(void *ary)
142{
143 xfree(ary);
144}
145
146/* Internal function. Resizes the capacity of a darray. The new capacity must
147 * be greater than or equal to the size of the darray. */
148static inline void
149rb_darray_resize_capa_impl(void *ptr_to_ary, size_t new_capa, size_t header_size, size_t element_size)
150{
151 rb_darray_meta_t **ptr_to_ptr_to_meta = ptr_to_ary;
152 rb_darray_meta_t *meta = *ptr_to_ptr_to_meta;
153
154 rb_darray_meta_t *new_ary = xrealloc(meta, new_capa * element_size + header_size);
155
156 if (meta == NULL) {
157 /* First allocation. Initialize size. On subsequence allocations
158 * realloc takes care of carrying over the size. */
159 new_ary->size = 0;
160 }
161
162 RUBY_ASSERT(new_ary->size <= new_capa);
163
164 new_ary->capa = new_capa;
165
166 // We don't have access to the type of the dynamic array in function context.
167 // Write out result with memcpy to avoid strict aliasing issue.
168 memcpy(ptr_to_ary, &new_ary, sizeof(new_ary));
169}
170
171// Internal function
172// Ensure there is space for one more element.
173// Note: header_size can be bigger than sizeof(rb_darray_meta_t) when T is __int128_t, for example.
174static inline void
175rb_darray_ensure_space(void *ptr_to_ary, size_t header_size, size_t element_size)
176{
177 rb_darray_meta_t **ptr_to_ptr_to_meta = ptr_to_ary;
178 rb_darray_meta_t *meta = *ptr_to_ptr_to_meta;
179 size_t current_capa = rb_darray_capa(meta);
180 if (rb_darray_size(meta) < current_capa) return;
181
182 // Double the capacity
183 size_t new_capa = current_capa == 0 ? 1 : current_capa * 2;
184
185 rb_darray_resize_capa_impl(ptr_to_ary, new_capa, header_size, element_size);
186}
187
188static inline void
189rb_darray_make_impl(void *ptr_to_ary, size_t array_size, size_t header_size, size_t element_size)
190{
191 rb_darray_meta_t **ptr_to_ptr_to_meta = ptr_to_ary;
192 if (array_size == 0) {
193 *ptr_to_ptr_to_meta = NULL;
194 return;
195 }
196
197 rb_darray_meta_t *meta = xcalloc(array_size * element_size + header_size, 1);
198
199 meta->size = array_size;
200 meta->capa = array_size;
201
202 // We don't have access to the type of the dynamic array in function context.
203 // Write out result with memcpy to avoid strict aliasing issue.
204 memcpy(ptr_to_ary, &meta, sizeof(meta));
205}
206
207#endif /* RUBY_DARRAY_H */
RUBY_ASSERT
#define RUBY_ASSERT(...)
Asserts that the given expression is truthy if and only if RUBY_DEBUG is truthy.
Definition assert.h:219
xfree
#define xfree
Old name of ruby_xfree.
Definition xmalloc.h:58
xrealloc
#define xrealloc
Old name of ruby_xrealloc.
Definition xmalloc.h:56
xcalloc
#define xcalloc
Old name of ruby_xcalloc.
Definition xmalloc.h:55
rb_darray_meta
Definition darray.h:97