Zig 0.17.0-dev (Split by item)

This is an example of documentation generated by ZigDoc, an alternative to Zig's built-in Auto Doc feature. See also examples in other modes/formats. The project being documented here (as the example) is the Zig library itself.

remap

Request to modify the size of an allocation, allowing relocation.

A non-null return value indicates the resize was successful. The allocation may have same address, or may have been relocated. In either case, the allocation now has size of new_len. A null return value indicates that the resize would be equivalent to allocating new memory, copying the bytes from the old memory, and then freeing the old memory. In such case, it is more efficient for the caller to perform those operations.

allocation may be an empty slice, in which case null is returned, unless new_len is also 0, in which case allocation is returned.

new_len may be zero, in which case the allocation is freed.

If the allocation's elements' type is zero bytes sized, allocation.len is set to new_len.

Allocator.remap

pub fn remap(self: Allocator, allocation: anytype, new_len: usize) ?@TypeOf(allocation)

File

lib/std/mem/Allocator.zig:357

Code

pub fn remap(self: Allocator, allocation: anytype, new_len: usize) ?@TypeOf(allocation) {
    const slice_info = @typeInfo(@TypeOf(allocation)).pointer;
    comptime assert(slice_info.size == .slice);
    const T = slice_info.child;

    if (new_len == 0) {
        self.free(allocation);
        return allocation[0..0];
    }
    if (allocation.len == 0) {
        return null;
    }
    if (@sizeOf(T) == 0) {
        var new_memory = allocation;
        new_memory.len = new_len;
        return new_memory;
    }
    const old_memory: []u8 = @ptrCast(@constCast(mem.absorbSentinel(allocation)));
    // I would like to use saturating multiplication here, but LLVM cannot lower it
    // on WebAssembly: https://github.com/ziglang/zig/issues/9660
    //const new_len_bytes = new_len *| @sizeOf(T);
    const new_len_bytes = math.mul(usize, @sizeOf(T), new_len) catch return null;
    const new_ptr = self.rawRemap(
        old_memory,
        .fromByteUnits(slice_info.attrs.@"align" orelse @alignOf(T)),
        new_len_bytes,
        @returnAddress(),
    ) orelse return null;
    return @ptrCast(@alignCast(new_ptr[0..new_len_bytes]));
}