2 ** @file mruby/array.h - Array class
4 ** See Copyright Notice in mruby.h
18 typedef struct mrb_shared_array {
24 #define MRB_ARY_EMBED_LEN_MAX ((mrb_int)(sizeof(void*)*3/sizeof(mrb_value)))
32 mrb_shared_array *shared;
40 #define mrb_ary_ptr(v) ((struct RArray*)(mrb_ptr(v)))
41 #define mrb_ary_value(p) mrb_obj_value((void*)(p))
42 #define RARRAY(v) ((struct RArray*)(mrb_ptr(v)))
44 #define MRB_ARY_EMBED_MASK 7
45 #define ARY_EMBED_P(a) ((a)->flags & MRB_ARY_EMBED_MASK)
46 #define ARY_UNSET_EMBED_FLAG(a) ((a)->flags &= ~(MRB_ARY_EMBED_MASK))
47 #define ARY_EMBED_LEN(a) ((mrb_int)(((a)->flags & MRB_ARY_EMBED_MASK) - 1))
48 #define ARY_SET_EMBED_LEN(a,len) ((a)->flags = ((a)->flags&~MRB_ARY_EMBED_MASK) | ((uint32_t)(len) + 1))
49 #define ARY_EMBED_PTR(a) ((mrb_value*)(&(a)->as.ary))
51 #define ARY_LEN(a) (ARY_EMBED_P(a)?ARY_EMBED_LEN(a):(a)->as.heap.len)
52 #define ARY_PTR(a) (ARY_EMBED_P(a)?ARY_EMBED_PTR(a):(a)->as.heap.ptr)
53 #define RARRAY_LEN(a) ARY_LEN(RARRAY(a))
54 #define RARRAY_PTR(a) ARY_PTR(RARRAY(a))
55 #define ARY_SET_LEN(a,n) do {\
56 if (ARY_EMBED_P(a)) {\
57 mrb_assert((n) <= MRB_ARY_EMBED_LEN_MAX); \
58 ARY_SET_EMBED_LEN(a,n);\
61 (a)->as.heap.len = (n);\
63 #define ARY_CAPA(a) (ARY_EMBED_P(a)?MRB_ARY_EMBED_LEN_MAX:(a)->as.heap.aux.capa)
64 #define MRB_ARY_SHARED 256
65 #define ARY_SHARED_P(a) ((a)->flags & MRB_ARY_SHARED)
66 #define ARY_SET_SHARED_FLAG(a) ((a)->flags |= MRB_ARY_SHARED)
67 #define ARY_UNSET_SHARED_FLAG(a) ((a)->flags &= ~MRB_ARY_SHARED)
69 void mrb_ary_decref(mrb_state*, mrb_shared_array*);
70 MRB_API void mrb_ary_modify(mrb_state*, struct RArray*);
71 MRB_API mrb_value mrb_ary_new_capa(mrb_state*, mrb_int);
74 * Initializes a new array.
80 * @param mrb The mruby state reference.
81 * @return The initialized array.
83 MRB_API mrb_value mrb_ary_new(mrb_state *mrb);
86 * Initializes a new array with initial values
90 * Array[value1, value2, ...]
92 * @param mrb The mruby state reference.
93 * @param size The numer of values.
94 * @param vals The actual values.
95 * @return The initialized array.
97 MRB_API mrb_value mrb_ary_new_from_values(mrb_state *mrb, mrb_int size, const mrb_value *vals);
100 * Initializes a new array with two initial values
106 * @param mrb The mruby state reference.
107 * @param car The first value.
108 * @param cdr The second value.
109 * @return The initialized array.
111 MRB_API mrb_value mrb_assoc_new(mrb_state *mrb, mrb_value car, mrb_value cdr);
114 * Concatenate two arrays. The target array will be modified
119 * @param mrb The mruby state reference.
120 * @param self The target array.
121 * @param other The array that will be concatenated to self.
123 MRB_API void mrb_ary_concat(mrb_state *mrb, mrb_value self, mrb_value other);
126 * Create an array from the input. It tries calling to_a on the
127 * value. If value does not respond to that, it creates a new
128 * array with just this value.
130 * @param mrb The mruby state reference.
131 * @param value The value to change into an array.
132 * @return An array representation of value.
134 MRB_API mrb_value mrb_ary_splat(mrb_state *mrb, mrb_value value);
137 * Pushes value into array.
143 * @param mrb The mruby state reference.
144 * @param ary The array in which the value will be pushed
145 * @param value The value to be pushed into array
147 MRB_API void mrb_ary_push(mrb_state *mrb, mrb_value array, mrb_value value);
150 * Pops the last element from the array.
156 * @param mrb The mruby state reference.
157 * @param ary The array from which the value will be popped.
158 * @return The popped value.
160 MRB_API mrb_value mrb_ary_pop(mrb_state *mrb, mrb_value ary);
163 * Returns a reference to an element of the array on the given index.
169 * @param mrb The mruby state reference.
170 * @param ary The target array.
171 * @param n The array index being referenced
172 * @return The referenced value.
174 MRB_API mrb_value mrb_ary_ref(mrb_state *mrb, mrb_value ary, mrb_int n);
177 * Sets a value on an array at the given index
183 * @param mrb The mruby state reference.
184 * @param ary The target array.
185 * @param n The array index being referenced.
186 * @param val The value being setted.
188 MRB_API void mrb_ary_set(mrb_state *mrb, mrb_value ary, mrb_int n, mrb_value val);
191 * Replace the array with another array
197 * @param mrb The mruby state reference
198 * @param self The target array.
199 * @param other The array to replace it with.
201 MRB_API void mrb_ary_replace(mrb_state *mrb, mrb_value self, mrb_value other);
202 MRB_API mrb_value mrb_ensure_array_type(mrb_state *mrb, mrb_value self);
203 MRB_API mrb_value mrb_check_array_type(mrb_state *mrb, mrb_value self);
206 * Unshift an element into the array
212 * @param mrb The mruby state reference.
213 * @param self The target array.
214 * @param item The item to unshift.
216 MRB_API mrb_value mrb_ary_unshift(mrb_state *mrb, mrb_value self, mrb_value item);
219 * Get nth element in the array
225 * @param ary The target array.
226 * @param offset The element position (negative counts from the tail).
228 MRB_API mrb_value mrb_ary_entry(mrb_value ary, mrb_int offset);
231 * Replace subsequence of an array.
237 * @param mrb The mruby state reference.
238 * @param self The array from which the value will be shifted.
239 * @param head Beginning position of a replacement subsequence.
240 * @param len Length of a replacement subsequence.
241 * @param rpl The array of replacement elements.
242 * It is possible to pass `mrb_undef_value()` instead of an empty array.
243 * @return The receiver array.
245 MRB_API mrb_value mrb_ary_splice(mrb_state *mrb, mrb_value self, mrb_int head, mrb_int len, mrb_value rpl);
248 * Shifts the first element from the array.
254 * @param mrb The mruby state reference.
255 * @param self The array from which the value will be shifted.
256 * @return The shifted value.
258 MRB_API mrb_value mrb_ary_shift(mrb_state *mrb, mrb_value self);
261 * Removes all elements from the array
267 * @param mrb The mruby state reference.
268 * @param self The target array.
271 MRB_API mrb_value mrb_ary_clear(mrb_state *mrb, mrb_value self);
274 * Join the array elements together in a string
280 * @param mrb The mruby state reference.
281 * @param ary The target array
282 * @param sep The separater, can be NULL
284 MRB_API mrb_value mrb_ary_join(mrb_state *mrb, mrb_value ary, mrb_value sep);
287 * Update the capacity of the array
289 * @param mrb The mruby state reference.
290 * @param ary The target array.
291 * @param new_len The new capacity of the array
293 MRB_API mrb_value mrb_ary_resize(mrb_state *mrb, mrb_value ary, mrb_int new_len);
295 /* helper functions */
296 mrb_value mrb_ary_subseq(mrb_state *mrb, mrb_value ary, mrb_int beg, mrb_int len);
300 #endif /* MRUBY_ARRAY_H */