array_allocate(3)

array_allocate(3) 💖

okay bestie, welcome to the libowfat manual, Library Functions Manual section, and today's main character is array_allocate — she makes sure your array has at least n elements allocated. no cap. let's get into it ✨

---

✨ NAME ✨

array_allocate — make sure array has at least n elements allocated 🫶

---

🎀 SYNTAX 🎀

#include <libowfat/array.h>

void* array_allocate(array* x, uint64 membersize, int64 pos);

and like, here's how she shows up in the wild:

array x;
int64 pos;
t* p = array_allocate(&x,sizeof(t),pos);

---

💅 DESCRIPTION 💅

so array_allocate makes absolutely sure that enough bytes are allocated in x for at least pos+1 objects of type t. 🦋

⚠️ the size of t must be positive — otherwise the effects are undefined. not "kinda weird", literally undefined. do not test her.

if not enough bytes are allocated (or x is unallocated), array_allocate allocates more bytes, moving the dynamically allocated region if necessary. and she's generous about it: array_allocate often allocates somewhat more bytes than necessary, to save time later. foresight? iconic. 👑

then array_allocate makes sure the number of bytes initialized covers at least those pos+1 objects. if not enough bytes are initialized, she initializes more bytes — setting them to 0 — up to exactly the end of the pos+1st object.

after all that, array_allocate returns a pointer to the pos+1st object; i.e., object number pos, with objects numbered starting at 0. this pointer can be used to change or inspect the object. 💫

the pointer can keep being used through subsequent calls to array_get, array_start, array_length, and array_bytes — but it must not be used after any other operations on this array. it's giving temporary VIP pass, not a forever key. 🙈

if something goes wrong, array_allocate returns 0, setting errno appropriately, without touching x. in particular, array_allocate returns 0 if:

• x has failed, or
• pos is negative, or
• not enough memory is available.

and important: array_allocate does not change x to have failed. if you want that, use array_fail. she's not gonna put that on your array without your say-so, bestie. 🌸

---

🔥 PERFORMANCE 🔥

this function can call realloc when the array needs to be enlarged. under exceptional circumstances, this can lead to blocking the current thread. 😭

it will also zero-fill the newly enlarged part of the array, which leads to all pages being mapped in by the operating system. and if a small array gets enlarged to a very large array, this can lead to swapping and blocking. 💀 so like, yes she's convenient, but she's not free.

---

👑 SEE ALSO 👑

• array_get(3)
• array_start(3)
• array_fail(3)

---

and that's the whole page, fr fr — array_allocate(3) from the Library Functions Manual, out here serving you the libowfat array lore. go forth and allocate responsibly, bestie 🎀💜⭐