Skip to main content
ArrayList is a contiguous, growable list of items in memory. It provides dynamic resizing and efficient append operations.

​
Type Definition

pub fn ArrayList(comptime T: type) type
Creates an ArrayList that stores values of type T.

​
Structure

const ArrayList = struct {
    items: []T,      // Current slice of items
    capacity: usize, // Total allocated capacity
    allocator: Allocator,
};
​
items
[]T
Direct access to the underlying slice of items. Pointers to elements may be invalidated by operations that grow the list.
​
capacity
usize
The number of items that can be held without allocating additional memory.
​
allocator
Allocator
The allocator used for all memory operations.

​
Creation and Destruction

​
init

pub fn init(allocator: Allocator) ArrayList(T)
Creates an empty ArrayList. Must be deinitialized with deinit or toOwnedSlice.

​
initCapacity

pub fn initCapacity(allocator: Allocator, num: usize) !ArrayList(T)
Creates an ArrayList with pre-allocated capacity for num elements.

​
deinit

pub fn deinit(self: ArrayList(T)) void
Releases all allocated memory.

​
fromOwnedSlice

pub fn fromOwnedSlice(allocator: Allocator, slice: []T) ArrayList(T)
Takes ownership of an existing slice allocated with the given allocator.

​
Adding Elements

​
append

pub fn append(self: *ArrayList(T), item: T) !void
Adds an item to the end of the list. May trigger reallocation.

​
appendSlice

pub fn appendSlice(self: *ArrayList(T), items: []const T) !void
Adds multiple items to the end of the list.

​
appendNTimes

pub fn appendNTimes(self: *ArrayList(T), value: T, n: usize) !void
Appends value exactly n times.

​
insert

pub fn insert(self: *ArrayList(T), index: usize, item: T) !void
Inserts an item at the specified index, shifting existing elements.

​
insertSlice

pub fn insertSlice(self: *ArrayList(T), index: usize, items: []const T) !void
Inserts multiple items at the specified index.

​
Removing Elements

​
pop

pub fn pop(self: *ArrayList(T)) T
Removes and returns the last item. Asserts the list is not empty.

​
popOrNull

pub fn popOrNull(self: *ArrayList(T)) ?T
Removes and returns the last item, or null if empty.

​
orderedRemove

pub fn orderedRemove(self: *ArrayList(T), index: usize) T
Removes and returns the item at index, preserving order by shifting elements.

​
swapRemove

pub fn swapRemove(self: *ArrayList(T), index: usize) T
Removes and returns the item at index by swapping with the last element. O(1) but doesn’t preserve order.

​
clearRetainingCapacity

pub fn clearRetainingCapacity(self: *ArrayList(T)) void
Removes all items but keeps allocated memory.

​
clearAndFree

pub fn clearAndFree(self: *ArrayList(T)) void
Removes all items and frees allocated memory.

​
Capacity Management

​
ensureTotalCapacity

pub fn ensureTotalCapacity(self: *ArrayList(T), new_capacity: usize) !void
Ensures the list can hold at least new_capacity items.

​
ensureUnusedCapacity

pub fn ensureUnusedCapacity(self: *ArrayList(T), additional_count: usize) !void
Ensures there is space for additional_count more items.

​
shrinkAndFree

pub fn shrinkAndFree(self: *ArrayList(T), new_len: usize) void
Reduces length to new_len and frees excess capacity.

​
shrinkRetainingCapacity

pub fn shrinkRetainingCapacity(self: *ArrayList(T), new_len: usize) void
Reduces length to new_len but keeps allocated memory.

​
Ownership Transfer

​
toOwnedSlice

pub fn toOwnedSlice(self: *ArrayList(T)) []T
Transfers ownership of the internal buffer to the caller. The ArrayList is emptied and its capacity cleared.

​
toOwnedSliceSentinel

pub fn toOwnedSliceSentinel(self: *ArrayList(T), comptime sentinel: T) ![:sentinel]T
Returns a sentinel-terminated slice. The ArrayList is emptied.

​
Usage Example

const std = @import("std");
const ArrayList = std.ArrayList;

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var list = ArrayList(i32).init(allocator);
    defer list.deinit();

    // Add elements
    try list.append(1);
    try list.append(2);
    try list.append(3);

    // Access elements
    std.debug.print("First: {}\n", .{list.items[0]});

    // Remove last element
    const last = list.pop();
    std.debug.print("Popped: {}\n", .{last});

    // Iterate
    for (list.items) |item| {
        std.debug.print("Item: {}\n", .{item});
    }
}

​
Performance Characteristics

  • Append: Amortized O(1)
  • Insert/Remove at index: O(n)
  • Random access: O(1)
  • Pop: O(1)
  • Swap remove: O(1)

Build docs developers (and LLMs) love

Get started for freeTalk to us