Slices

test_basic_slices.zig

  1. const expect = @import("std").testing.expect;
  3. test "basic slices" {
  4.     var array = [_]i32{ 1, 2, 3, 4 };
  5.     // A slice is a pointer and a length. The difference between an array and
  6.     // a slice is that the array's length is part of the type and known at
  7.     // compile-time, whereas the slice's length is known at runtime.
  8.     // Both can be accessed with the `len` field.
  9.     var known_at_runtime_zero: usize = 0;
  10.     const slice = array[known_at_runtime_zero..array.len];
  11.     try expect(@TypeOf(slice) == []i32);
  12.     try expect(&slice[0] == &array[0]);
  13.     try expect(slice.len == array.len);
  15.     // If you slice with comptime-known start and end positions, the result is
  16.     // a pointer to an array, rather than a slice.
  17.     const array_ptr = array[0..array.len];
  18.     try expect(@TypeOf(array_ptr) == *[array.len]i32);
  20.     // You can perform a slice-by-length by slicing twice. This allows the compiler
  21.     // to perform some optimisations like recognising a comptime-known length when
  22.     // the start position is only known at runtime.
  23.     var runtime_start: usize = 1;
  24.     const length = 2;
  25.     const array_ptr_len = array[runtime_start..][0..length];
  26.     try expect(@TypeOf(array_ptr_len) == *[length]i32);
  28.     // Using the address-of operator on a slice gives a single-item pointer,
  29.     // while using the `ptr` field gives a many-item pointer.
  30.     try expect(@TypeOf(slice.ptr) == [*]i32);
  31.     try expect(@TypeOf(&slice[0]) == *i32);
  32.     try expect(@intFromPtr(slice.ptr) == @intFromPtr(&slice[0]));
  34.     // Slices have array bounds checking. If you try to access something out
  35.     // of bounds, you'll get a safety check failure:
  36.     slice[10] += 1;
  38.     // Note that `slice.ptr` does not invoke safety checking, while `&slice[0]`
  39.     // asserts that the slice has len > 0.
  40. }

Shell

  1. $ zig test test_basic_slices.zig
  2. 1/1 test.basic slices... thread 2451814 panic: index out of bounds: index 10, len 4
  3. /home/ci/actions-runner/_work/zig-bootstrap/zig/docgen_tmp/test_basic_slices.zig:36:10: 0x224695 in test.basic slices (test)
  4.     slice[10] += 1;
  5.          ^
  6. /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/test_runner.zig:176:28: 0x22da69 in mainTerminal (test)
  7.         } else test_fn.func();
  8.                            ^
  9. /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/test_runner.zig:36:28: 0x225bfa in main (test)
  10.         return mainTerminal();
  11.                            ^
  12. /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:564:22: 0x224c92 in posixCallMainAndExit (test)
  13.             root.main();
  14.                      ^
  15. /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:243:5: 0x2247e1 in _start (test)
  16.     asm volatile (switch (native_arch) {
  17.     ^
  18. ???:?:?: 0x0 in ??? (???)
  19. error: the following test command crashed:
  20. /home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/5549974cc24ed8e4b563851bcf6ec010/test

This is one reason we prefer slices to pointers.

test_slices.zig

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  3. const mem = std.mem;
  4. const fmt = std.fmt;
  6. test "using slices for strings" {
  7.     // Zig has no concept of strings. String literals are const pointers
  8.     // to null-terminated arrays of u8, and by convention parameters
  9.     // that are "strings" are expected to be UTF-8 encoded slices of u8.
  10.     // Here we coerce *const [5:0]u8 and *const [6:0]u8 to []const u8
  11.     const hello: []const u8 = "hello";
  12.     const world: []const u8 = "世界";
  14.     var all_together: [100]u8 = undefined;
  15.     // You can use slice syntax with at least one runtime-known index on an
  16.     // array to convert an array into a slice.
  17.     var start : usize = 0;
  18.     const all_together_slice = all_together[start..];
  19.     // String concatenation example.
  20.     const hello_world = try fmt.bufPrint(all_together_slice, "{s} {s}", .{ hello, world });
  22.     // Generally, you can use UTF-8 and not worry about whether something is a
  23.     // string. If you don't need to deal with individual characters, no need
  24.     // to decode.
  25.     try expect(mem.eql(u8, hello_world, "hello 世界"));
  26. }
  28. test "slice pointer" {
  29.     var a: []u8 = undefined;
  30.     try expect(@TypeOf(a) == []u8);
  31.     var array: [10]u8 = undefined;
  32.     const ptr = &array;
  33.     try expect(@TypeOf(ptr) == *[10]u8);
  35.     // A pointer to an array can be sliced just like an array:
  36.     var start: usize = 0;
  37.     var end: usize = 5;
  38.     const slice = ptr[start..end];
  39.     slice[2] = 3;
  40.     try expect(slice[2] == 3);
  41.     // The slice is mutable because we sliced a mutable pointer.
  42.     try expect(@TypeOf(slice) == []u8);
  44.     // Again, slicing with comptime-known indexes will produce another pointer
  45.     // to an array:
  46.     const ptr2 = slice[2..3];
  47.     try expect(ptr2.len == 1);
  48.     try expect(ptr2[0] == 3);
  49.     try expect(@TypeOf(ptr2) == *[1]u8);
  50. }

Shell

  1. $ zig test test_slices.zig
  2. 1/2 test.using slices for strings... OK
  3. 2/2 test.slice pointer... OK
  4. All 2 tests passed.

See also:

Sentinel-Terminated Slices

The syntax [:x]T is a slice which has a runtime-known length and also guarantees a sentinel value at the element indexed by the length. The type does not guarantee that there are no sentinel elements before that. Sentinel-terminated slices allow element access to the len index.

test_null_terminated_slice.zig

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  4. test "null terminated slice" {
  5.     const slice: [:0]const u8 = "hello";
  7.     try expect(slice.len == 5);
  8.     try expect(slice[5] == 0);
  9. }

Shell

  1. $ zig test test_null_terminated_slice.zig
  2. 1/1 test.null terminated slice... OK
  3. All 1 tests passed.

Sentinel-terminated slices can also be created using a variation of the slice syntax data[start..end :x], where data is a many-item pointer, array or slice and x is the sentinel value.

test_null_terminated_slicing.zig

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  4. test "null terminated slicing" {
  5.     var array = [_]u8{ 3, 2, 1, 0, 3, 2, 1, 0 };
  6.     var runtime_length: usize = 3;
  7.     const slice = array[0..runtime_length :0];
  9.     try expect(@TypeOf(slice) == [:0]u8);
  10.     try expect(slice.len == 3);
  11. }

Shell

  1. $ zig test test_null_terminated_slicing.zig
  2. 1/1 test.null terminated slicing... OK
  3. All 1 tests passed.

Sentinel-terminated slicing asserts that the element in the sentinel position of the backing data is actually the sentinel value. If this is not the case, safety-protected Undefined Behavior results.

test_sentinel_mismatch.zig

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  4. test "sentinel mismatch" {
  5.     var array = [_]u8{ 3, 2, 1, 0 };
  7.     // Creating a sentinel-terminated slice from the array with a length of 2
  8.     // will result in the value `1` occupying the sentinel element position.
  9.     // This does not match the indicated sentinel value of `0` and will lead
  10.     // to a runtime panic.
  11.     var runtime_length: usize = 2;
  12.     const slice = array[0..runtime_length :0];
  14.     _ = slice;
  15. }

Shell

  1. $ zig test test_sentinel_mismatch.zig
  2. 1/1 test.sentinel mismatch... thread 2451922 panic: sentinel mismatch: expected 0, found 1
  3. /home/ci/actions-runner/_work/zig-bootstrap/zig/docgen_tmp/test_sentinel_mismatch.zig:12:24: 0x224246 in test.sentinel mismatch (test)
  4.     const slice = array[0..runtime_length :0];
  5.                        ^
  6. /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/test_runner.zig:176:28: 0x22da49 in mainTerminal (test)
  7.         } else test_fn.func();
  8.                            ^
  9. /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/test_runner.zig:36:28: 0x225a0a in main (test)
  10.         return mainTerminal();
  11.                            ^
  12. /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:564:22: 0x224842 in posixCallMainAndExit (test)
  13.             root.main();
  14.                      ^
  15. /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:243:5: 0x224391 in _start (test)
  16.     asm volatile (switch (native_arch) {
  17.     ^
  18. ???:?:?: 0x0 in ??? (???)
  19. error: the following test command crashed:
  20. /home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/3510ea03a08182d3c72b6b3a42d629a3/test

See also: