Slices

test.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.     // Using the address-of operator on a slice gives a single-item pointer,
  21.     // while using the `ptr` field gives a many-item pointer.
  22.     try expect(@TypeOf(slice.ptr) == [*]i32);
  23.     try expect(@TypeOf(&slice[0]) == *i32);
  24.     try expect(@ptrToInt(slice.ptr) == @ptrToInt(&slice[0]));
  26.     // Slices have array bounds checking. If you try to access something out
  27.     // of bounds, you'll get a safety check failure:
  28.     slice[10] += 1;
  30.     // Note that `slice.ptr` does not invoke safety checking, while `&slice[0]`
  31.     // asserts that the slice has len >= 1.
  32. }

Shell

  1. $ zig test test.zig
  2. 1/1 test.basic slices... thread 3567298 panic: index out of bounds: index 10, len 4
  3. docgen_tmp/test.zig:28:10: 0x2119c6 in test.basic slices (test)
  4.     slice[10] += 1;
  5.          ^
  6. /home/ci/release-0.10.1/out/zig-x86_64-linux-musl-baseline/lib/zig/test_runner.zig:63:28: 0x2131b3 in main (test)
  7.         } else test_fn.func();
  8.                            ^
  9. /home/ci/release-0.10.1/out/zig-x86_64-linux-musl-baseline/lib/zig/std/start.zig:604:22: 0x21233c in posixCallMainAndExit (test)
  10.             root.main();
  11.                      ^
  12. /home/ci/release-0.10.1/out/zig-x86_64-linux-musl-baseline/lib/zig/std/start.zig:376:5: 0x211e41 in _start (test)
  13.     @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
  14.     ^
  15. error: the following test command crashed:
  16. /home/ci/release-0.10.1/out/zig-local-cache/o/886dbde2c2a21074c6c6d3ff9b83336b/test

This is one reason we prefer slices to pointers.

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 on an array to convert an array into a slice.
  16.     const all_together_slice = all_together[0..];
  17.     // String concatenation example.
  18.     const hello_world = try fmt.bufPrint(all_together_slice, "{s} {s}", .{ hello, world });
  20.     // Generally, you can use UTF-8 and not worry about whether something is a
  21.     // string. If you don't need to deal with individual characters, no need
  22.     // to decode.
  23.     try expect(mem.eql(u8, hello_world, "hello 世界"));
  24. }
  26. test "slice pointer" {
  27.     var a: []u8 = undefined;
  28.     try expect(@TypeOf(a) == []u8);
  29.     var array: [10]u8 = undefined;
  30.     const ptr = &array;
  31.     try expect(@TypeOf(ptr) == *[10]u8);
  33.     // A pointer to an array can be sliced just like an array:
  34.     var start: usize = 0;
  35.     var end: usize = 5;
  36.     const slice = ptr[start..end];
  37.     slice[2] = 3;
  38.     try expect(slice[2] == 3);
  39.     // The slice is mutable because we sliced a mutable pointer.
  40.     try expect(@TypeOf(slice) == []u8);
  42.     // Again, slicing with constant indexes will produce another pointer to an array:
  43.     const ptr2 = slice[2..3];
  44.     try expect(ptr2.len == 1);
  45.     try expect(ptr2[0] == 3);
  46.     try expect(@TypeOf(ptr2) == *[1]u8);
  47. }

Shell

  1. $ zig 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.

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

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 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.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.zig
  2. 1/1 test.sentinel mismatch... thread 3567804 panic: sentinel mismatch: expected 0, found 1
  3. docgen_tmp/test.zig:12:24: 0x211604 in test.sentinel mismatch (test)
  4.     const slice = array[0..runtime_length :0];
  5.                        ^
  6. /home/ci/release-0.10.1/out/zig-x86_64-linux-musl-baseline/lib/zig/test_runner.zig:63:28: 0x212fc3 in main (test)
  7.         } else test_fn.func();
  8.                            ^
  9. /home/ci/release-0.10.1/out/zig-x86_64-linux-musl-baseline/lib/zig/std/start.zig:604:22: 0x211f6c in posixCallMainAndExit (test)
  10.             root.main();
  11.                      ^
  12. /home/ci/release-0.10.1/out/zig-x86_64-linux-musl-baseline/lib/zig/std/start.zig:376:5: 0x211a71 in _start (test)
  13.     @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
  14.     ^
  15. error: the following test command crashed:
  16. /home/ci/release-0.10.1/out/zig-local-cache/o/886dbde2c2a21074c6c6d3ff9b83336b/test

See also: