Slice

API

#include <ds/slice.h>

Handle

struct slice

Managed array with autoscaling capabilities. Building block for array-based data structures that should not be used directly.

Slices keep track of the size of their elements, their current capacity and the first free spot on their underlying array. Array based data structures use slices to conveniently manipulate their underlying memory. Slices may be used directly but, it is likely that you are looking for a higher level data structure.

Public Members

byte *data

Pointer to the underlying array.

size_t len

Number of elements currently on the slice.

Functions

struct slice *slice_make(size_t el_size, size_t el_no)

Initializes a slice and allocates its memory.

Every call to slice_make must have a matching call to slice_del to release the managed memory.

Parameters:

• el_size – Size of each element.

• el_no – Number of elements for the initial allocation.

Returns:

Handle to the slice.

void slice_del(struct slice *p)

Deallocates the memory managed by a slice created by slice_make.

Parameters:

• p – Handle to the slice.

bool slice_empty(struct slice *p)

Returns whether the given slice is empty.

Parameters:

• p – Handle to the slice.

Returns:

Whether the given slice is empty.

bool slice_full(struct slice *p)

Returns whether the given slice is full.

Parameters:

• p – Handle to the slice.

Returns:

Whether the given slice is full.

void slice_rwd(struct slice *p, size_t rwd)

Discards elements at the end of the slice.

Decrements the length of the slice by rwd elements. Further appends will override the elements that got rewinded. Does not check the size of the slice, rwd must be smaller than or equal to the number of elements currently on the slice.

Parameters:

• p – Handle to the slice.

• rwd – Number of elements to rewind.

void slice_resize(struct slice *p)

Grows the underlying array by _SLICE_SCALE_FACTOR.

Parameters:

• p – Handle to the slice.

void slice_append(struct slice *p, data *el)

Appends a value to the end of the slice without checking its capacity.

Copies the element stored at el to the end of the slice. Does not check if there is enough space on the slice. For a safe version that grows the slice when it’s out of space, use slice_sappend.

Parameters:

• p – Handle to the slice.

• el – Pointer to the element to append.

void slice_sappend(struct slice *p, data *el)

Appends a value to the end of the slice checking its capacity.

Copies the element stored at el to the end of the slice. If the slice is out of space, grows the allocated memory before appending. When certain that the slice has enough space, use slice_append instead.

See also

slice_resize

Parameters:

• p – Handle to the slice.

• el – Pointer to the element to append.

void slice_insert(struct slice *p, data *el, size_t idx)

Inserts a value into the given position of the slice.

Copies the element stored at el into the given position of the slice, shifting existing elements to the right. Does not check if there is enough space on the slice. For a safe version that grows the slice when it’s out of space, use slice_sinsert.

Parameters:

• p – Handle to the slice.

• el – Pointer to the element to insert.

• idx – Index to insert the element at.

void slice_sinsert(struct slice *p, data *el, size_t idx)

Inserts a value into the given position of the slice checking its capacity.

Copies the element stored at el into the given position of the slice, shifting existing elements to the right. If the slice is out of space, grows the allocated memory before appending. When certain that the slice has enough space, use slice_insert instead.

See also

slice_resize

Parameters:

• p – Handle to the slice.

• el – Pointer to the element to insert.

• idx – Index to insert the element at.

void slice_replace(struct slice *p, data *el, size_t idx)

Replaces the value at the given position of the slice.

Copies the element stored at el into the given position of the slice, overriding the existing element. Does not check if the index is out of bounds.

Parameters:

• p – Handle to the slice.

• el – Pointer to the element to insert.

• idx – Index of the element to be replaced.

void slice_delete_at(struct slice *p, size_t idx)

Deletes the element at a given position.

Shifts existing elements to the right, overwriting the element to be deleted. When preserving the order of elements is not important, use slice_delete_at_fast instead.

Parameters:

• p – Handle to the slice.

• idx – Index of the element to retrieve.

void slice_delete_at_fast(struct slice *p, size_t idx)

Deletes the element at a given position without preserving element order.

Copies the last element of the slice to the given position, then decrements the length. Faster but does not preserve element order. If preserving the order is important, use slice_delete_at instead.

Parameters:

• p – Handle to the slice.

• idx – Index of the element to retrieve.

void slice_clear(struct slice *p)

Sets the length to zero, clearing the slice.

Sets the length to zero makikng it so further appends will override the previous elements.

Parameters:

• p – Handle to the slice.

data *slice_at(struct slice *p, size_t idx)

Returns a pointer to the element at the given index.

Returns a view into the slice without copying the data. Indexing is done by element type instead of bytes, so idx does not need to be multiplied by the size of the elements.

Parameters:

• p – Handle to the slice.

• idx – Index of the element to retrieve.

data *slice_first(struct slice *p)

Returns the first element of the slice.

Does not check if the slice is empty.

Parameters:

• p – Handle to the slice.

Returns:

Pointer to the first element of the slice.

data *slice_last(struct slice *p)

Returns the last element of the slice.

Does not check if the slice is empty.

Parameters:

• p – Handle to the slice.

Returns:

Pointer to the last element of the slice.

Macros

slice_foreach(type, iterator, p)

Loop through each element of the array.

Loops through each element of the array, assigning the current element to an iterator of the given type.

Parameters:

• type – Type of the iterator.

• iterator – Where to store the current element.

• p – Handle to the slice.

Definitions

_SLICE_SCALE_FACTOR

How much a slice should grow if it runs out of space.

If a slice is out of space when appending values with slice_sappend, the underlying array will grow by this factor.

See also

slice_resize