libflint/docs/vector.md

175 lines
4.1 KiB
Markdown
Raw Normal View History

2023-10-25 15:54:53 +00:00
# vector
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
Simple type-agnostic dynamic array
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
## Structs
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
### Vector
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
Vector struct
2023-10-25 15:42:38 +00:00
```c
2023-10-25 15:54:53 +00:00
typedef struct Vector {
size_t capacity;
size_t length;
void **elements;
void (*destroy)(void *data);
} Vector;
2023-10-25 15:42:38 +00:00
```
2023-10-25 15:54:53 +00:00
Members:
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
- `capacity`: The size of `elements` in memory
- `length`: The number of real elements stored in the backing `elements` array
- `elements`: The dynamic array of `void *` that holds the vector's members
- `destroy`: Optional deallocation function for data inside a node. Typical usage is `NULL` for stack allocated data and `free()` for data created with `malloc()`
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
## Functions
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
### vec_init
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
Initialize the vector with a default capacity of 2. User is responsible for freeing elements of the vector with `vec_destroy()`. Returns a non-zero integer if there is an error
2023-10-25 15:42:38 +00:00
```c
2023-10-25 15:54:53 +00:00
int vec_init(Vector *vec, void (*destroy)(void *data));
2023-10-25 15:42:38 +00:00
```
2023-10-25 15:54:53 +00:00
### vec_init_with_capacity
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
Initialize the vector with a user-specified capacity. User is responsible for freeing elements of the vector with `vec_destroy()`. Returns a non-zero integer if there is an error
2023-10-25 15:42:38 +00:00
```c
2023-10-25 15:54:53 +00:00
int vec_init_with_capacity(Vector *vec, void (*destroy)(void *data), size_t cap);
2023-10-25 15:42:38 +00:00
```
2023-10-25 15:54:53 +00:00
### vec_destroy
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
Frees the underlying array inside a `Vector`. If `destroy` was provided when creating the vector, then it is called against each element in the array before the array is freed. Does not destroy the vector itself, that is left up to the user
2023-10-25 15:42:38 +00:00
```c
2023-10-25 15:54:53 +00:00
void vec_destroy(Vector *vec);
/* Usage */
vec_destroy(vec);
free(vec);
2023-10-25 15:42:38 +00:00
```
2023-10-25 15:54:53 +00:00
### vec_insert
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
Insert `data` into the vector at a specified index. Any elements at that array and beyond will be moved up to make room. Returns a non-zero integer if there is an error
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
```c
int vec_insert(Vector *vec, void *data, size_t index);
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
/* Usage */
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
// vec: 1 2 3 4
int i = 99;
vec_insert(vec, &i, 2);
// vec: 1 2 99 3 4
2023-10-25 15:42:38 +00:00
```
2023-10-25 15:54:53 +00:00
### vec_push
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
Insert `data` at the end of the vector. Returns a non-zero integer if there is an error
2023-10-25 15:42:38 +00:00
```c
2023-10-25 15:54:53 +00:00
int vec_push(Vector *vec, void *data);
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
/* Usage */
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
// vec: 1 2 3
int *i = malloc(sizeof(int));
*i = 4;
vec_push(vec, i);
// vec: 1 2 3 4
2023-10-25 15:42:38 +00:00
```
2023-10-25 15:54:53 +00:00
### vec_safe_at
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
Gets the stored data at a specified index. Uses safety checks to make sure `index` is not out of bounds. Returns `NULL` if there is an error
2023-10-25 15:42:38 +00:00
```c
2023-10-25 15:54:53 +00:00
void *vec_safe_at(Vector *vec, size_t index);
2023-10-25 15:42:38 +00:00
```
2023-10-25 15:54:53 +00:00
### vec_remove
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
Removes an element from the array and returns the pointer, then moves elements to shrink the array accordingly. Returns `NULL` if the index is not valid
2023-10-25 15:42:38 +00:00
```c
2023-10-25 15:54:53 +00:00
void *vec_remove(Vector *vec, size_t index);
/* Usage */
// vec: 1 2 3 4
int *t = NULL;
t = (int*)vec_remove(vec, 2);
assert(*t == 3);
// vec: 1 2 4
2023-10-25 15:42:38 +00:00
```
2023-10-25 15:54:53 +00:00
### vec_shrink
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
Shrinks the capacity of the vector down to the current length. Returns a non-zero integer if there is an error
2023-10-25 15:42:38 +00:00
```c
2023-10-25 15:54:53 +00:00
int vec_shrink(Vector *vec);
2023-10-25 15:42:38 +00:00
```
### vec_max
2023-11-29 22:39:59 +00:00
Finds the largest value in the vector and returns a void pointer to the underlying data. Requires a
comparison function to compare the data in the vector. This function must return `1` if `a > b`, `-1` if
`a < b`, or `0` if `a == b`. See the supplied comparison functions below for reference
```c
const void *vec_min(const Vector *vec, int(*cmp)(const void *a, const void *b));
```
### vec_min
2023-11-29 22:39:59 +00:00
Finds the smallest value in the vector and returns a void pointer to the underlying data. Requires a
comparison function to compare the data in the vector. This function must return `1` if `a > b`, `-1` if
`a < b`, or `0` if `a == b`. See the supplied comparison functions below for reference
```c
const void *vec_max(const Vector *vec, int(*cmp)(const void *a, const void *b));
```
## Comparison Functions
Comparison functions to compare data in a vector. These functions must return `1` if `a > b`, `-1` if
`a < b`, or `0` if `a == b`.
```c
int vec_cmp_int(const void *a, const void *b);
int vec_cmp_char(const void *a, const void *b);
```
2023-10-25 15:54:53 +00:00
## Macros
### vec_at
2023-10-25 15:42:38 +00:00
2023-11-29 22:39:59 +00:00
Grabs the element at index `i` without safety checks for better performance. Use with caution
2023-10-25 15:42:38 +00:00
```c
2023-10-25 15:54:53 +00:00
#define vec_at(v, i) (v)->elements[(i)]
2023-10-25 15:42:38 +00:00
```
2023-10-25 15:54:53 +00:00
### vec_len
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
Returns the length of the vector
2023-10-25 15:42:38 +00:00
```c
2023-10-25 15:54:53 +00:00
#define vec_len(v) (v)->length
2023-10-25 15:42:38 +00:00
```
2023-10-25 15:54:53 +00:00
### vec_cap
2023-10-25 15:42:38 +00:00
2023-10-25 15:54:53 +00:00
Returns the capacity of the vector
2023-10-25 15:42:38 +00:00
```c
2023-10-25 15:54:53 +00:00
#define vec_cap(v) (v)->capacity
2023-10-25 15:42:38 +00:00
```