summaryrefslogtreecommitdiff
path: root/ds.h
diff options
context:
space:
mode:
authorpommicket <pommicket@gmail.com>2023-02-28 19:39:06 -0500
committerpommicket <pommicket@gmail.com>2023-02-28 19:39:06 -0500
commit52ba910a48a4dd2abb798c3c998ecb0e006c1895 (patch)
tree5fa4b3fb1e28ee1027aaa02a78ddf9b9bd7b59f5 /ds.h
parent5e92dac7b8ff9d60bfa3dcc69c3f77663a01aea4 (diff)
doxygen documentation
Diffstat (limited to 'ds.h')
-rw-r--r--ds.h56
1 files changed, 32 insertions, 24 deletions
diff --git a/ds.h b/ds.h
index a588be7..dde3496 100644
--- a/ds.h
+++ b/ds.h
@@ -1,8 +1,7 @@
-#ifndef DS_H_
-#define DS_H_
+/*!
+\file
+\brief VARIOUS DATA STRUCTURES
-/*
-VARIOUS DATA STRUCTURES
- dynamic array
- string builder
- string hash table
@@ -13,7 +12,7 @@ any reasonable compiler will ignore the unused code.
functions in this file suffixed with _ are not meant to be used outside here, unless you
know what you're doing
-NOTE: even on 64-bit platforms, dynamic arrays can only hold ~2^32 elements.
+NOTE: even on 64-bit platforms, dynamic arrays can only hold ~2<sup>32</sup> elements.
IMPORTANT NOTE: If you are using this with structures containing `long double`s, do
#define ARR_LONG_DOUBLE
@@ -23,6 +22,9 @@ IMPORTANT NOTE: If you are using this with structures containing `long double`s,
which isnt important unless you're making a lot of arrays.)
*/
+#ifndef DS_H_
+#define DS_H_
+
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
@@ -208,19 +210,18 @@ static void *arr_copy_(const void *arr, size_t member_size) {
#endif
#define arr__join2(a,b) a##b
-#define arr__join(a,b) arr__join2(a,b) // macro used internally
-// if the array is not NULL, free it and set it to NULL
+/// macro used internally
+#define arr__join(a,b) arr__join2(a,b)
+/// if the array is not NULL, free it and set it to NULL
#define arr_free(a) do { if (a) { free(arr_hdr_(a)); (a) = NULL; } } while (0)
-// a nice alias
+/// a nice alias
#define arr_clear(a) arr_free(a)
-// add an item to the array - if allocation fails, the array will be freed and set to NULL.
-// (how this works: if we can successfully grow the array, increase the length and add the item.)
+/// add an item to the array - if allocation fails, the array will be freed and set to NULL.
+/// (how this works: if we can successfully grow the array, increase the length and add the item.)
#define arr_add(a, x) do { if (((a) = arr_cast_typeof(a) arr_grow1_((a), sizeof *(a)))) ((a)[arr_hdr_(a)->len++] = (x)); } while (0)
-// like arr_add, but instead of passing it the value, it returns a pointer to the value. returns NULL if allocation failed.
-// the added item will be zero-initialized.
+/// like arr_add, but instead of passing it the value, it returns a pointer to the value. returns NULL if allocation failed.
+/// the added item will be zero-initialized.
#define arr_addp(a) arr_cast_typeof(a) arr_add_ptr_((void **)&(a), sizeof *(a))
-// set the length of `a` to `n`, increasing the capacity if necessary.
-// the newly-added elements are zero-initialized.
#define arr_qsort(a, cmp) qsort((a), arr_len(a), sizeof *(a), (cmp))
#define arr_remove_last(a) do { assert(a); if (--arr_hdr_(a)->len == 0) arr_free(a); } while (0)
#define arr_remove(a, i) (void)((a) = arr_remove_((a), sizeof *(a), (i)))
@@ -234,15 +235,21 @@ static void *arr_copy_(const void *arr, size_t member_size) {
#define arr_copy(a) arr_cast_typeof(a) arr_copy_((a), sizeof *(a))
#define arr_foreach_ptr_end(a, type, var, end) type *end = (a) + arr_len(a); \
for (type *var = (a); var != end; ++var)
-// Iterate through each element of the array, setting var to a pointer to the element.
-// You can't use this like, e.g.:
-// if (something)
-// arr_foreach_ptr(a, int, i);
-// You'll get an error. You will need to use braces because it expands to multiple statements.
-// (we need to name the end pointer something unique, which is why there's that arr__join thing
-// we can't just declare it inside the for loop, because type could be something like char *.)
+/// Iterate through each element of the array, setting `var` to a pointer to the element.
+///
+/// You can't use this like, e.g.:
+/// ```
+/// if (something)
+/// arr_foreach_ptr(a, int, i)
+/// thing(*i);
+/// ```
+/// You'll get an error. You will need to use braces because it expands to multiple statements.
+/// (we need to name the end pointer something unique, which is why there's that `arr__join` thing
+/// we can't just declare it inside the for loop, because type could be something like `char *`.)
#define arr_foreach_ptr(a, type, var) arr_foreach_ptr_end(a, type, var, arr__join(_foreach_end,__LINE__))
-
+/// Reverse array.
+///
+/// You need to pass in the type because we don't have `typeof` in C yet (coming in C23 supposedly!)
#define arr_reverse(a, type) do { \
u64 _i, _len = arr_len(a); \
for (_i = 0; 2*_i < _len; ++_i) { \
@@ -255,9 +262,10 @@ static void *arr_copy_(const void *arr, size_t member_size) {
} \
} while (0)
-// Ensure that enough space is allocated for n elements.
+/// Ensure that enough space is allocated for `n` elements.
#define arr_reserve(a, n) arr_reserve_((void **)&(a), sizeof *(a), (n))
-// Similar to arr_reserve, but also sets the length of the array to n.
+/// set the length of `a` to `n`, increasing the capacity if necessary.
+/// the newly-added elements are zero-initialized.
#define arr_set_len(a, n) arr_set_len_((void **)&(a), sizeof *(a), (n))
#ifndef NDEBUG