fn ArrayList(comptime T: type) type
A contiguous, growable list of items in memory. This is a wrapper around an array of T values. Initialize with init
.
This struct internally stores a std.mem.Allocator
for memory management. To manually specify an allocator with each method call see ArrayListUnmanaged
.
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 haveundefined
values. The r…Resize the array, adding
n
new elements, which haveundefined
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 ifself.capacity
is not large enough.fn addManyAsArrayAssumeCapacity(self: *Self, comptime n: usize) *[n]T
Resize the array, adding
n
new elements, which haveundefined
values. The r…Resize the array, adding
n
new elements, which haveundefined
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 haveundefined
values. The r…Resize the array, adding
n
new elements, which haveundefined
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 ifself.capacity
is not large enough.fn addManyAsSliceAssumeCapacity(self: *Self, n: usize) []T
Resize the array, adding
n
new elements, which haveundefined
values. The r…Resize the array, adding
n
new elements, which haveundefined
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-knownvalue
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-knownvalue
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 clone(self: Self) Allocator.Error!Self
Creates a copy of this ArrayList, using the same allocator.
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. LikeensureTotalCapacity
, but the resulting capacity is guaranteed to be equal tonew_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 withdeinit
or usetoOwnedSlice
.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 withdeinit
or usetoOwnedSlice
.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 equalnum
exactly. Deinitialize withdeinit
or usetoOwnedSlice
.fn insert(self: *Self, n: usize, item: T) Allocator.Error!void
Insert
item
at indexn
. Moveslist[n .. list.len]
to higher indices to mak…Insert
item
at indexn
. Moveslist[n .. list.len]
to higher indices to make room. Ifn
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 indexn
. Moveslist[n .. list.len]
to higher indices to mak…Insert
item
at indexn
. Moveslist[n .. list.len]
to higher indices to make room. Ifn
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 indexi
by movinglist[i .. list.len]
to make room. …Insert slice
items
at indexi
by movinglist[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
andcapacity
fields of thi…Initializes an ArrayListUnmanaged with the
items
andcapacity
fields of this ArrayList. Empties this ArrayList.fn orderedRemove(self: *Self, i: usize) T
Remove the element at index
i
, shift elements after indexi
forward, and re…Remove the element at index
i
, shift elements after indexi
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. UseswapRemove
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]
withnew_items
. Grows list …Replace range of elements
list[start..][0..len]
withnew_items
. Grows list iflen < new_items.len
. Shrinks list iflen > 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 elementsitems[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
.