feat(vec): support head and last

include/wheel/containers/vec/header.h

@@ -40,6 +40,42 @@ void vec_destroy(vec* v);
  */
 void vec_destroy_ptr(vec** v);
 
+#ifdef LIBWHEEL_TRAIT_SHALLOW_COPY
+/**
+ * retrieve the first element in a vector.
+ * @param v the vector to get the value from.
+ * @return a shallow copy of the first element in the vector, or
+ * `optional_empty` if it doesn't exist.
+ * @note this function requires the `LIBWHEEL_TRAIT_SHALLOW_COPY` trait.
+ */
+optional vec_head(const vec* v);
+#endif // LIBWHEEL_TRAIT_SHALLOW_COPY
+
+/**
+ * Retrieve the first element in a vector.
+ * @param v The vector to get the value from.
+ * @return A pointer to the first element in the vector, or null if it doesn't exist.
+ */
+LIBWHEEL_TYPE* vec_head_ptr(const vec* v);
+
+#ifdef LIBWHEEL_TRAIT_SHALLOW_COPY
+/**
+ * Retrieve the last element in a vector.
+ * @param v The vector to get the value from.
+ * @return A shallow copy of the last element in the vector, or
+ * `optional_empty` if it doesn't exist.
+ * @note This function requires the `LIBWHEEL_TRAIT_SHALLOW_COPY` trait.
+ */
+optional vec_last(const vec* v);
+#endif // LIBWHEEL_TRAIT_SHALLOW_COPY
+
+/**
+ * Retrieve the last element in a vector.
+ * @param v The vector to get the value from.
+ * @return A pointer to the last element in the vector, or null if it doesn't exist.
+ */
+LIBWHEEL_TYPE* vec_last_ptr(const vec* v);
+
 #ifdef LIBWHEEL_TRAIT_SHALLOW_COPY
 /**
  * Shallow copy the value at the given index in a vector.

include/wheel/containers/vec/impl.h

@@ -350,4 +350,48 @@ bool vec_next(vec_iter* it) {
     }
 }
 
+#ifdef LIBWHEEL_TRAIT_SHALLOW_COPY
+optional vec_head(const vec* v) {
+    for (uint64_t i = 0; i < v->size; ++i) {
+        if (vec_bit_get(&v->present, i)) {
+            return optional_of(trait_shallow_copy(v->values[i]));
+        }
+    }
+
+    return optional_empty();
+}
+#endif // LIBWHEEL_TRAIT_SHALLOW_COPY
+
+LIBWHEEL_TYPE* vec_head_ptr(const vec* v) {
+    for (uint64_t i = 0; i < v->size; ++i) {
+        if (vec_bit_get(&v->present, i)) {
+            return v->values + i;
+        }
+    }
+
+    return NULL;
+}
+
+#ifdef LIBWHEEL_TRAIT_SHALLOW_COPY
+optional vec_last(const vec* v) {
+    for (int64_t i = v->size - 1; i >= 0; --i) {
+        if (vec_bit_get(&v->present, i)) {
+            return optional_of(trait_shallow_copy(v->values[i]));
+        }
+    }
+
+    return optional_empty();
+}
+#endif // LIBWHEEL_TRAIT_SHALLOW_COPY
+
+LIBWHEEL_TYPE* vec_last_ptr(const vec* v) {
+    for (int64_t i = v->size - 1; i >= 0; --i) {
+        if (vec_bit_get(&v->present, i)) {
+            return v->values + i;
+        }
+    }
+
+    return NULL;
+}
+
 #include "wheel/wheel/undef.h"

tests/vec/vec_int_head.c

@@ -0,0 +1,19 @@
+#include <wheel/std/int.h>
+
+int main() {
+    vec_int v = vec_int_init();
+    optional_int result = vec_int_head(&v);
+    assert(!result.present);
+
+    vec_int_set(&v, 0, 1);
+    result = vec_int_head(&v);
+    assert(result.present);
+    assert(result.value == 1);
+
+    vec_int_set(&v, 1, 2);
+    result = vec_int_head(&v);
+    assert(result.present);
+    assert(result.value == 1);
+
+    vec_int_destroy(&v);
+}

tests/vec/vec_int_head_ptr.c

@@ -0,0 +1,19 @@
+#include <wheel/std/int.h>
+
+int main() {
+    vec_int v = vec_int_init();
+    int* result = vec_int_head_ptr(&v);
+    assert(result == NULL);
+
+    vec_int_set(&v, 0, 1);
+    result = vec_int_head_ptr(&v);
+    assert(result != NULL);
+    assert(*result == 1);
+
+    vec_int_set(&v, 1, 2);
+    result = vec_int_head_ptr(&v);
+    assert(result != NULL);
+    assert(*result == 1);
+
+    vec_int_destroy(&v);
+}

tests/vec/vec_int_last.c

@@ -0,0 +1,19 @@
+#include <wheel/std/int.h>
+
+int main() {
+    vec_int v = vec_int_init();
+    optional_int result = vec_int_last(&v);
+    assert(!result.present);
+
+    vec_int_set(&v, 0, 1);
+    result = vec_int_last(&v);
+    assert(result.present);
+    assert(result.value == 1);
+
+    vec_int_set(&v, 1, 2);
+    result = vec_int_last(&v);
+    assert(result.present);
+    assert(result.value == 2);
+
+    vec_int_destroy(&v);
+}

tests/vec/vec_int_last_ptr.c

@@ -0,0 +1,19 @@
+#include <wheel/std/int.h>
+
+int main() {
+    vec_int v = vec_int_init();
+    int* result = vec_int_last_ptr(&v);
+    assert(result == NULL);
+
+    vec_int_set(&v, 0, 1);
+    result = vec_int_last_ptr(&v);
+    assert(result != NULL);
+    assert(*result == 1);
+
+    vec_int_set(&v, 1, 2);
+    result = vec_int_last_ptr(&v);
+    assert(result != NULL);
+    assert(*result == 2);
+
+    vec_int_destroy(&v);
+}