Reference prick_vec in prick_darr

This is an SBO'd stable dynamic array.

prick_darr.h

@@ -19,6 +19,9 @@
  area on the heap and copy over the data.  Therefore, if you're expecting the
  array to grow during the runtime of your program, you should ensure any
  pointers to components of it are updated as they will otherwise be dangling.
+
+ You may want to consider prick_vec.h if you want to more explicit control of
+ the dynamic array, and would like a stable pointer to the container itself.
  */
 
 #ifndef PRICK_DARR_H

prick_vec.h

@@ -0,0 +1,163 @@
+/* prick_vec.h: A dynamically sized array with SBO.
+ * Created: 2026-01-22
+ * Author: Aryadev Chavali
+ * License: See end of file
+ * Commentary:
+
+ To utilise this library, please put:
+    #define PRICK_VEC_IMPL
+    #include "prick_vec.h"
+ in one of your code units.
+
+ This library defines another form of dynamically sized array as opposed to
+ prick_darr.h.  This one is closer to the one classically implemented by most; a
+ structure with some metadata and a pointer to the raw buffer.  This way,
+ pointers to the dynamic array are stable (as the structure itself is never
+ reallocated) and the array can still grow as required.
+
+ We use a trick, called Small Buffer Optimisation (SBO), to inline elements
+ directly into the structure when there are a small number of them (see
+ PRICK_VEC_INLINE_CAPACITY).  This makes lookup _even faster_ (no derefence and
+ possibility of the entire vector existing in the CPU cache) and allows us to
+ avoid allocation for smaller use cases.  If the number of elements exceeds
+ PRICK_VEC_INLINE_CAPACITY, we utilise the allocator.
+ */
+
+#ifndef PRICK_VEC_H
+#define PRICK_VEC_H
+
+#include <assert.h>
+#include <stdint.h>
+
+#define PRICK_VEC_INLINE_CAPACITY 32
+#define PRICK_VEC_MULT            2
+
+typedef struct
+{
+  uint64_t size, capacity;
+  uint8_t not_inlined;
+  union
+  {
+    void *ptr;
+    alignas(max_align_t) uint8_t inlined[PRICK_VEC_INLINE_CAPACITY];
+  };
+} prick_vec_t;
+
+static_assert(sizeof(prick_vec_t) == 64,
+              "Expected sizeof(prick_vec_t) to be 64");
+
+void prick_vec_append(prick_vec_t *vec, const void *const ptr, uint64_t size);
+void prick_vec_append_byte(prick_vec_t *vec, uint8_t byte);
+void *prick_vec_data(prick_vec_t *vec);
+void prick_vec_ensure_capacity(prick_vec_t *vec, uint64_t capacity);
+void prick_vec_ensure_free(prick_vec_t *vec, uint64_t size);
+void prick_vec_free(prick_vec_t *vec);
+void prick_vec_clone(prick_vec_t *v2, prick_vec_t *v1);
+
+#define PRICK_VEC_GET(VEC, INDEX, TYPE) (((TYPE *)prick_vec_data(VEC))[INDEX])
+
+#ifdef PRICK_VEC_IMPL
+#define MAX(A, B) ((A) > (B) ? (A) : (B))
+
+#include <stdlib.h>
+#include <string.h>
+
+void prick_vec_append(prick_vec_t *vec, const void *const ptr, uint64_t size)
+{
+  if (!vec || !ptr || !size)
+    return;
+  prick_vec_ensure_free(vec, size);
+  memcpy(&PRICK_VEC_GET(vec, vec->size, uint8_t), ptr, size);
+  vec->size += size;
+}
+
+void prick_vec_append_byte(prick_vec_t *vec, uint8_t byte)
+{
+  if (!vec)
+    return;
+  prick_vec_ensure_free(vec, 1);
+  PRICK_VEC_GET(vec, vec->size, uint8_t) = byte;
+  ++vec->size;
+}
+
+void *prick_vec_data(prick_vec_t *vec)
+{
+  if (!vec)
+    return NULL;
+
+  if (vec->not_inlined)
+  {
+    return vec->ptr;
+  }
+  else
+  {
+    return vec->inlined;
+  }
+}
+
+void prick_vec_ensure_capacity(prick_vec_t *vec, uint64_t capacity)
+{
+  if (!vec)
+    return;
+  if (vec->capacity == 0)
+    vec->capacity = PRICK_VEC_INLINE_CAPACITY;
+  if (vec->capacity < capacity)
+  {
+    vec->capacity = MAX(vec->capacity * PRICK_VEC_MULT, capacity);
+    if (!vec->not_inlined)
+    {
+      // We were a small buffer, and now we cannot be i.e. we need to allocate
+      // on the heap.
+      vec->not_inlined = 1;
+      void *buffer     = calloc(1, vec->capacity);
+      memcpy(buffer, vec->inlined, vec->size);
+      memset(vec->inlined, 0, sizeof(vec->inlined));
+      vec->ptr = buffer;
+    }
+    else
+    {
+      // We're already on the heap, just reallocate.
+      vec->ptr = realloc(vec->ptr, vec->capacity);
+    }
+  }
+}
+
+void prick_vec_ensure_free(prick_vec_t *vec, uint64_t size)
+{
+  if (!vec)
+    return;
+  prick_vec_ensure_capacity(vec, vec->size + size);
+}
+
+void prick_vec_free(prick_vec_t *vec)
+{
+  if (!vec)
+    return;
+  if (vec->not_inlined)
+    free(vec->ptr);
+  memset(vec, 1, sizeof(*vec));
+}
+
+void prick_vec_clone(prick_vec_t *v2, prick_vec_t *v1)
+{
+  if (!v1 || !v2)
+    return;
+  prick_vec_append(v2, prick_vec_data(v1), v1->size);
+}
+
+#undef MAX
+#endif
+
+#endif
+
+/* Copyright (C) 2026 Aryadev Chavali
+
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE.  See the Unlicense for details.
+
+ * You may distribute and modify this code under the terms of the Unlicense,
+ * which you should have received a copy of along with this program.  If not,
+ * please go to <https://unlicense.org/>.
+
+ */