This section defines a resizable array class, similar to C++’s std::vector or Java’s ArrayList classes. Our arrays can store any fixed-size element. The arrays automatically resize themselves as necessary to store the elements that you add.
A resizable array that contains elements of type element_type.
Initializes a new array. You should allocate array yourself, presumably on the stack or directly within some other data type. The array will start empty.
Finalizes an array, freeing any storage that was allocated to hold the arrays elements.
Returns a pointer to the underlying array of elements in array. The elements are guaranteed to be contiguous, just like in a normal C array, but the particular pointer that is returned in not guaranteed to be consistent across function calls that modify the contents of the array.
Returns the element in array at the given index. Like accessing a normal C array, we don’t do any bounds checking. The result is a valid lvalue, so it can be directly assigned to:
cork_array(int64_t) array; cork_array_append(array, 5, err); cork_array_at(array, 0) = 12;
Appends element to the end of array, reallocating the array’s storage if necessary. If you have an init or reset callback for array, it will be used to initialize the space that was allocated for the new element, and then element will be directly copied into that space (using memcpy or an equivalent). If that is not the right copy behavior for the elements of array, then you should use cork_array_append_get() instead, and fill in the allocated element directly.
Appends a new element to the end of array, reallocating the array’s storage if necessary, returning a pointer to the new element.
Ensures that array has enough allocated space to store desired_count elements, reallocating the array’s storage if needed. The actual size and existing contents of the array aren’t changed.
Copy elements from src to dest. If you provide a copy function, it will be called on each element to perform the copy. If not, we’ll use memcpy to bulk-copy the elements.
If you’ve provided callbacks for dest, then those callbacks will be called appropriately. We’ll call the remove callback for any existing entries (will be overwritten by the copy). We’ll call init or reuse on each element entry before it’s copied.
Returns the size of the elements that are stored in array. You won’t normally need to call this, since you can just use sizeof(T).
You can provide callback functions that will be used to automatically initialize and finalize the elements of a resizable array.
Set one of the callback functions for array. There are two pairs of callbacks: init and done, and reuse and remove. Within each pair, one callback is used to initialize an element of the array, while the other is used to finalize it.
The init callback is used to initialize an element when its array entry is used for the first time. If you then shrink the array (via cork_array_clear(), for instance), and then append elements again, you will reuse array entries; in this case, the reset callback is used instead. (Having separate init and reuse callbacks can be useful when the elements are complex objects with deep memory requirements. If you use the init callback to allocate that memory, and use the reset callback to “clear” it, then you can reduce some of the memory allocation overhead.)
Similarly, the remove callback is used when an element is removed from the array, but the space that the element used isn’t being reclaimed yet. The done callback, on the other hand, is used when the array entry is reclaimed and freed.
All of the callbacks take in an additional user_data parameter, in addition to the array entries themselves. You provide that parameter by calling the cork_array_set_callback_data() function. If you pass in a free_user_data function, then we will use that function to free the user_data when the array itself is finalized.