fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type

A contiguous, growable list of arbitrarily aligned items in memory. This is a wrapper around an array of T values aligned to alignment-byte addresses. If the specified alignment is null, then @alignOf(T) is used. Initialize with init.

This struct internally stores a std.mem.Allocator for memory management. To manually specify an allocator with each method call see ArrayListAlignedUnmanaged.

Parameters

T: type,
alignment: ?u29,

Fields

items: Slice,

Contents of the list. Pointers to elements in this slice are invalid after resizing operations on the ArrayList unless the operation explicitly either: (1) states otherwise or (2) lists the invalidated pointers.

The allocator used determines how element pointers are invalidated, so the behavior may vary between lists. To avoid illegal behavior, take into account the above paragraph plus the explicit statements given in each method.

capacity: usize,

How many T values this list can hold without allocating additional memory.

allocator: Allocator,

Functions

fn addManyAsArray(self: *Self, comptime n: usize) Allocator.Error!*[n]T

Resize the array, adding n new elements, which have undefined values. The r…

Resize the array, adding n new elements, which have undefined values. The return value is an array pointing to the newly allocated elements. The returned pointer becomes invalid when the list is resized. Resizes list if self.capacity is not large enough.

fn addManyAsArrayAssumeCapacity(self: *Self, comptime n: usize) *[n]T

Resize the array, adding n new elements, which have undefined values. The r…

Resize the array, adding n new elements, which have undefined values. The return value is an array pointing to the newly allocated elements. Asserts that there is already space for the new item without allocating more. Does not invalidate element pointers. The returned pointer becomes invalid when the list is resized.

fn addManyAsSlice(self: *Self, n: usize) Allocator.Error![]T

Resize the array, adding n new elements, which have undefined values. The r…

Resize the array, adding n new elements, which have undefined values. The return value is a slice pointing to the newly allocated elements. The returned pointer becomes invalid when the list is resized. Resizes list if self.capacity is not large enough.

fn addManyAsSliceAssumeCapacity(self: *Self, n: usize) []T

Resize the array, adding n new elements, which have undefined values. The r…

Resize the array, adding n new elements, which have undefined values. The return value is a slice pointing to the newly allocated elements. Asserts that there is already space for the new item without allocating more. Does not invalidate element pointers. The returned pointer becomes invalid when the list is resized.

fn addOne(self: *Self) Allocator.Error!*T

Increase length by 1, returning pointer to the new item. The returned pointer b…

Increase length by 1, returning pointer to the new item. The returned pointer becomes invalid when the list resized.

fn addOneAssumeCapacity(self: *Self) *T

Increase length by 1, returning pointer to the new item. Asserts that there is …

Increase length by 1, returning pointer to the new item. Asserts that there is already space for the new item without allocating more. The returned pointer becomes invalid when the list is resized. Does not invalidate element pointers.

fn allocatedSlice(self: Self) Slice

Returns a slice of all the items plus the extra capacity, whose memory contents…

Returns a slice of all the items plus the extra capacity, whose memory contents are undefined.

fn append(self: *Self, item: T) Allocator.Error!void

Extend the list by 1 element. Allocates more memory as necessary. Invalidates p…

Extend the list by 1 element. Allocates more memory as necessary. Invalidates pointers if additional memory is needed.

fn appendAssumeCapacity(self: *Self, item: T) void

Extend the list by 1 element, but assert self.capacity is sufficient to hold …

Extend the list by 1 element, but assert self.capacity is sufficient to hold an additional item. Does not invalidate pointers.

inline fn appendNTimes(self: *Self, value: T, n: usize) Allocator.Error!void

Append a value to the list n times. Allocates more memory as necessary. Inva…

Append a value to the list n times. Allocates more memory as necessary. Invalidates pointers if additional memory is needed. The function is inline so that a comptime-known value parameter will have a more optimal memset codegen in case it has a repeated byte pattern.

inline fn appendNTimesAssumeCapacity(self: *Self, value: T, n: usize) void

Append a value to the list n times. Asserts the capacity is enough. **Does no…

Append a value to the list n times. Asserts the capacity is enough. Does not invalidate pointers. The function is inline so that a comptime-known value parameter will have a more optimal memset codegen in case it has a repeated byte pattern.

fn appendSlice(self: *Self, items: []const T) Allocator.Error!void

Append the slice of items to the list. Allocates more memory as necessary. Inv…

Append the slice of items to the list. Allocates more memory as necessary. Invalidates pointers if additional memory is needed.

fn appendSliceAssumeCapacity(self: *Self, items: []const T) void

Append the slice of items to the list, asserting the capacity is already enough…

Append the slice of items to the list, asserting the capacity is already enough to store the new items. Does not invalidate pointers.

fn appendUnalignedSlice(self: *Self, items: []const align(1) T) Allocator.Error!void

Append an unaligned slice of items to the list. Allocates more memory as necess…

Append an unaligned slice of items to the list. Allocates more memory as necessary. Only call this function if calling appendSlice instead would be a compile error. Invalidates pointers if additional memory is needed.

fn appendUnalignedSliceAssumeCapacity(self: *Self, items: []const align(1) T) void

Append the slice of items to the list, asserting the capacity is already enough…

Append the slice of items to the list, asserting the capacity is already enough to store the new items. Does not invalidate pointers. Only call this function if calling appendSliceAssumeCapacity instead would be a compile error.

fn clearAndFree(self: *Self) void

Invalidates all element pointers.

fn clearRetainingCapacity(self: *Self) void

Invalidates all element pointers.

fn clone(self: Self) Allocator.Error!Self

Creates a copy of this ArrayList, using the same allocator.

fn deinit(self: Self) void

Release all allocated memory.

fn ensureTotalCapacity(self: *Self, new_capacity: usize) Allocator.Error!void

Modify the array so that it can hold at least new_capacity items. Invalidates…

Modify the array so that it can hold at least new_capacity items. Invalidates pointers if additional memory is needed.

fn ensureTotalCapacityPrecise(self: *Self, new_capacity: usize) Allocator.Error!void

Modify the array so that it can hold new_capacity items. Like `ensureTotalCap…

Modify the array so that it can hold new_capacity items. Like ensureTotalCapacity, but the resulting capacity is guaranteed to be equal to new_capacity. Invalidates pointers if additional memory is needed.

fn ensureUnusedCapacity(self: *Self, additional_count: usize) Allocator.Error!void

Modify the array so that it can hold at least additional_count more items….

Modify the array so that it can hold at least additional_count more items. Invalidates pointers if additional memory is needed.

fn expandToCapacity(self: *Self) void

Increases the array’s length to match the full capacity that is already allocate…

Increases the array’s length to match the full capacity that is already allocated. The new elements have undefined values. Does not invalidate pointers.

fn fromOwnedSlice(allocator: Allocator, slice: Slice) Self

ArrayList takes ownership of the passed in slice. The slice must have been allo…

ArrayList takes ownership of the passed in slice. The slice must have been allocated with allocator. Deinitialize with deinit or use toOwnedSlice.

fn fromOwnedSliceSentinel(allocator: Allocator, comptime sentinel: T, slice: [:sentinel]T) Self

ArrayList takes ownership of the passed in slice. The slice must have been allo…

ArrayList takes ownership of the passed in slice. The slice must have been allocated with allocator. Deinitialize with deinit or use toOwnedSlice.

fn getLast(self: Self) T

Return the last element from the list. Asserts the list has at least one item.

fn getLastOrNull(self: Self) ?T

Return the last element from the list, or return null if list is empty.

fn init(allocator: Allocator) Self

Deinitialize with deinit or use toOwnedSlice.

fn initCapacity(allocator: Allocator, num: usize) Allocator.Error!Self

Initialize with capacity to hold num elements. The resulting capacity will eq…

Initialize with capacity to hold num elements. The resulting capacity will equal num exactly. Deinitialize with deinit or use toOwnedSlice.

fn insert(self: *Self, n: usize, item: T) Allocator.Error!void

Insert item at index n. Moves list[n .. list.len] to higher indices to mak…

Insert item at index n. Moves list[n .. list.len] to higher indices to make room. If n is equal to the length of the list this operation is equivalent to append. This operation is O(N). Invalidates pointers if additional memory is needed.

fn insertAssumeCapacity(self: *Self, n: usize, item: T) void

Insert item at index n. Moves list[n .. list.len] to higher indices to mak…

Insert item at index n. Moves list[n .. list.len] to higher indices to make room. If n is equal to the length of the list this operation is equivalent to append. This operation is O(N). Asserts that there is enough capacity for the new item.

fn insertSlice(self: *Self, i: usize, items: []const T) Allocator.Error!void

Insert slice items at index i by moving list[i .. list.len] to make room. …

Insert slice items at index i by moving list[i .. list.len] to make room. This operation is O(N). Invalidates pointers if additional memory is needed.

fn moveToUnmanaged(self: *Self) ArrayListAlignedUnmanaged(T, alignment)

Initializes an ArrayListUnmanaged with the items and capacity fields of thi…

Initializes an ArrayListUnmanaged with the items and capacity fields of this ArrayList. Empties this ArrayList.

fn orderedRemove(self: *Self, i: usize) T

Remove the element at index i, shift elements after index i forward, and re…

Remove the element at index i, shift elements after index i forward, and return the removed element. Asserts the array has at least one item. Invalidates pointers to end of list. This operation is O(N). This preserves item order. Use swapRemove if order preservation is not important.

fn pop(self: *Self) T

Remove and return the last element from the list. Asserts the list has at least…

Remove and return the last element from the list. Asserts the list has at least one item. Invalidates pointers to the removed element.

fn popOrNull(self: *Self) ?T

Remove and return the last element from the list, or return null if list is e…

Remove and return the last element from the list, or return null if list is empty. Invalidates pointers to the removed element, if any.

fn replaceRange(self: *Self, start: usize, len: usize, new_items: []const T) Allocator.Error!void

Replace range of elements list[start..][0..len] with new_items. Grows list …

Replace range of elements list[start..][0..len] with new_items. Grows list if len < new_items.len. Shrinks list if len > new_items.len. Invalidates pointers if this ArrayList is resized.

fn resize(self: *Self, new_len: usize) Allocator.Error!void

Adjust the list’s length to new_len. Does not initialize added items if any. …

Adjust the list’s length to new_len. Does not initialize added items if any. Invalidates pointers if additional memory is needed.

fn shrinkAndFree(self: *Self, new_len: usize) void

Reduce allocated capacity to new_len. May invalidate element pointers.

fn shrinkRetainingCapacity(self: *Self, new_len: usize) void

Reduce length to new_len. Invalidates pointers for the elements `items[new_le…

Reduce length to new_len. Invalidates pointers for the elements items[new_len..].

fn swapRemove(self: *Self, i: usize) T

Removes the element at the specified index and returns it. The empty slot is fi…

Removes the element at the specified index and returns it. The empty slot is filled from the end of the list. This operation is O(1). This may not preserve item order. Use orderedRemove if you need to preserve order.

fn toOwnedSlice(self: *Self) Allocator.Error!Slice

The caller owns the returned memory. Empties this ArrayList, Its capacity is cl…

The caller owns the returned memory. Empties this ArrayList, Its capacity is cleared, making deinit() safe but unnecessary to call.

fn toOwnedSliceSentinel(self: *Self, comptime sentinel: T) Allocator.Error!SentinelSlice(sentinel)

The caller owns the returned memory. Empties this ArrayList.

fn unusedCapacitySlice(self: Self) Slice

Returns a slice of only the extra capacity after items. This can be useful for …

Returns a slice of only the extra capacity after items. This can be useful for writing directly into an ArrayList. Note that such an operation must be followed up with a direct modification of self.items.len.

fn writer(self: *Self) Writer

Initializes a Writer which will append to the list.

Values

Slice
type
Writer
type