fn ArrayListUnmanaged(comptime T: type) type

An ArrayList, but the allocator is passed as a parameter to the relevant functions rather than stored in the struct itself. The same allocator must be used throughout the entire lifetime of an ArrayListUnmanaged. Initialize directly or with initCapacity, and deinitialize with deinit or use toOwnedSlice.

Parameters

T: type,

Fields

items: Slice = ref,

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 = 0,

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

Functions

fn addManyAsArray(self: *Self, allocator: Allocator, 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.

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 pointers. The returned pointer becomes invalid when the list is resized.

fn addManyAsSlice(self: *Self, allocator: Allocator, 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: Allocator) 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. Does not invalidate pointers. The returned pointer becomes invalid when the list resized.

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, allocator: Allocator, 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 asserting self.capacity is sufficient to ho…

Extend the list by 1 element, but asserting self.capacity is sufficient to hold an additional item.

inline fn appendNTimes(self: *Self, allocator: Allocator, 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. Does not invalidate pointers. Assert…

Append a value to the list n times. Does not invalidate pointers. Asserts the capacity is enough. 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, allocator: Allocator, 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 enough to stor…

Append the slice of items to the list, asserting the capacity is enough to store the new items.

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

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

Append the slice of items to the list. Allocates more memory as necessary. Only call this function if a call to 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 an unaligned slice of items to the list, asserting the capacity is enough…

Append an unaligned slice of items to the list, asserting the capacity is enough to store the new items. Only call this function if a call to appendSliceAssumeCapacity instead would be a compile error.

fn clearAndFree(self: *Self, allocator: Allocator) void

Invalidates all element pointers.

fn clearRetainingCapacity(self: *Self) void

Invalidates all element pointers.

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

Creates a copy of this ArrayList.

fn deinit(self: *Self, allocator: Allocator) void

Release all allocated memory.

fn ensureTotalCapacity(self: *Self, allocator: Allocator, 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, allocator: Allocator, 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, allocator: Allocator, 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(slice: Slice) Self

ArrayListUnmanaged takes ownership of the passed in slice. The slice must have b…

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

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

ArrayListUnmanaged takes ownership of the passed in slice. The slice must have b…

ArrayListUnmanaged 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 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, allocator: Allocator, 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, allocator: Allocator, i: usize, items: []const T) Allocator.Error!void

Insert slice items at index i. Moves list[i .. list.len] to higher indici…

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

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

Remove the element at index i from the list and return its value. Asserts the…

Remove the element at index i from the list and return its value. Asserts the array has at least one item. Invalidates pointers to last element. This operation is O(N).

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 last element.

fn popOrNull(self: *Self) ?T

Remove and return the last element from the list. If the list is empty, returns…

Remove and return the last element from the list. If the list is empty, returns null. Invalidates pointers to last element.

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

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

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, allocator: Allocator, 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, allocator: Allocator, 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 to elements items[new_len..]

Reduce length to new_len. Invalidates pointers to elements items[new_len..]. Keeps capacity the same.

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. Invalidates pointers to last element. This operation is O(1).

fn toManaged(self: *Self, allocator: Allocator) ArrayListAligned(T, alignment)

Convert this list into an analogous memory-managed one. The returned list has o…

Convert this list into an analogous memory-managed one. The returned list has ownership of the underlying memory.

fn toOwnedSlice(self: *Self, allocator: Allocator) 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, allocator: Allocator, comptime sentinel: T) Allocator.Error!SentinelSlice(sentinel)

The caller owns the returned memory. ArrayList becomes empty.

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, allocator: Allocator) Writer

Initializes a Writer which will append to the list.

Values

Slice
type
Writer
type