Type coercion occurs when one type is expected, but different type is provided:

    test.zig

    2. 1/3 test "type coercion - variable declaration"... OK
    3. 2/3 test "type coercion - function call"... OK
    4. 3/3 test "type coercion - @as builtin"... OK
    5. All 3 tests passed.

    Type coercions are only allowed when it is completely unambiguous how to get from one type to another, and the transformation is guaranteed to be safe. There is one exception, which is C Pointers.

    Values which have the same representation at runtime can be cast to increase the strictness of the qualifiers, no matter how nested the qualifiers are:

    • const - non-const to const is allowed
    • volatile - non-volatile to volatile is allowed
    • align - bigger to smaller alignment is allowed
    • to supersets is allowed

    These casts are no-ops at runtime since the value representation does not change.

    test.zig

    1. test "type coercion - const qualification" {
    2.     var a: i32 = 1;
    3.     var b: *i32 = &a;
    4.     foo(b);
    5. }
    7. fn foo(a: *const i32) void {}
    1. $ zig test test.zig
    2. 1/1 test "type coercion - const qualification"... OK
    3. All 1 tests passed.

    In addition, pointers coerce to const optional pointers:

    test.zig

    1. const std = @import("std");
    2. const expect = std.testing.expect;
    3. const mem = std.mem;
    5. test "cast *[1][*]const u8 to [*]const ?[*]const u8" {
    6.     const window_name = [1][*]const u8{"window name"};
    7.     const x: [*]const ?[*]const u8 = &window_name;
    8.     expect(mem.eql(u8, std.mem.spanZ(@ptrCast([*:0]const u8, x[0].?)), "window name"));
    9. }
    1. $ zig test test.zig
    2. 1/1 test "cast *[1][*]const u8 to [*]const ?[*]const u8"... OK
    3. All 1 tests passed.

    Type Coercion: Integer and Float Widening

    coerce to integer types which can represent every value of the old type, and likewise Floats coerce to float types which can represent every value of the old type.

    test.zig

    1. const std = @import("std");
    2. const expect = std.testing.expect;
    3. const mem = std.mem;
    5. test "integer widening" {
    6.     var a: u8 = 250;
    7.     var b: u16 = a;
    8.     var c: u32 = b;
    9.     var d: u64 = c;
    10.     var e: u64 = d;
    11.     var f: u128 = e;
    12.     expect(f == a);
    13. }
    15. test "implicit unsigned integer to signed integer" {
    16.     var a: u8 = 250;
    17.     var b: i16 = a;
    18.     expect(b == 250);
    19. }
    21. test "float widening" {
    22.     // Note: there is an open issue preventing this from working on aarch64:
    23.     // https://github.com/ziglang/zig/issues/3282
    24.     if (std.Target.current.cpu.arch == .aarch64) return error.SkipZigTest;
    26.     var a: f16 = 12.34;
    27.     var b: f32 = a;
    28.     var c: f64 = b;
    29.     var d: f128 = c;
    30.     expect(d == a);
    31. }
    1. $ zig test test.zig
    2. 1/3 test "integer widening"... OK
    3. 2/3 test "implicit unsigned integer to signed integer"... OK
    4. 3/3 test "float widening"... OK
    5. All 3 tests passed.

    • Cast 54.0 to comptime_int resulting in @as(comptime_int, 10), which is casted to @as(f32, 10)
    • Cast 5 to comptime_float resulting in @as(comptime_float, 10.8), which is casted to @as(f32, 10.8)

    test.zig

    1. $ zig test test.zig
    2. ./docgen_tmp/test.zig:3:18: error: float value 54.000000 cannot be coerced to type 'comptime_int'
    3.     var f: f32 = 54.0 / 5;
    4.                  ^
    5. ./docgen_tmp/test.zig:3:23: note: referenced here
    6.     var f: f32 = 54.0 / 5;
    7.                       ^

    coerce_arrays_and_ptrs.zig

    2. const expect = std.testing.expect;
    3. // This cast exists primarily so that string literals can be
    4. // passed to functions that accept const slices. However
    5. // it is probably going to be removed from the language when
    6. // https://github.com/ziglang/zig/issues/265 is implemented.
    7. test "[N]T to []const T" {
    8.     var x1: []const u8 = "hello";
    9.     var x2: []const u8 = &[5]u8{ 'h', 'e', 'l', 'l', 111 };
    10.     expect(std.mem.eql(u8, x1, x2));
    12.     var y: []const f32 = &[2]f32{ 1.2, 3.4 };
    13.     expect(y[0] == 1.2);
    14. }
    16. // Likewise, it works when the destination type is an error union.
    17. test "[N]T to E![]const T" {
    18.     var x1: anyerror![]const u8 = "hello";
    19.     var x2: anyerror![]const u8 = &[5]u8{ 'h', 'e', 'l', 'l', 111 };
    20.     expect(std.mem.eql(u8, try x1, try x2));
    22.     var y: anyerror![]const f32 = &[2]f32{ 1.2, 3.4 };
    23.     expect((try y)[0] == 1.2);
    24. }
    26. // Likewise, it works when the destination type is an optional.
    27. test "[N]T to ?[]const T" {
    28.     var x1: ?[]const u8 = "hello";
    29.     var x2: ?[]const u8 = &[5]u8{ 'h', 'e', 'l', 'l', 111 };
    30.     expect(std.mem.eql(u8, x1.?, x2.?));
    32.     var y: ?[]const f32 = &[2]f32{ 1.2, 3.4 };
    33.     expect(y.?[0] == 1.2);
    34. }
    36. // In this cast, the array length becomes the slice length.
    37. test "*[N]T to []T" {
    38.     var buf: [5]u8 = "hello".*;
    39.     const x: []u8 = &buf;
    40.     expect(std.mem.eql(u8, x, "hello"));
    42.     const buf2 = [2]f32{ 1.2, 3.4 };
    43.     const x2: []const f32 = &buf2;
    44.     expect(std.mem.eql(f32, x2, &[2]f32{ 1.2, 3.4 }));
    45. }
    47. // Single-item pointers to arrays can be coerced to
    48. // unknown length pointers.
    49. test "*[N]T to [*]T" {
    50.     var buf: [5]u8 = "hello".*;
    51.     const x: [*]u8 = &buf;
    52.     expect(x[4] == 'o');
    53.     // x[5] would be an uncaught out of bounds pointer dereference!
    54. }
    56. // Likewise, it works when the destination type is an optional.
    57. test "*[N]T to ?[*]T" {
    58.     var buf: [5]u8 = "hello".*;
    59.     const x: ?[*]u8 = &buf;
    60.     expect(x.?[4] == 'o');
    61. }
    63. // Single-item pointers can be cast to len-1 single-item arrays.
    64. test "*T to *[1]T" {
    65.     var x: i32 = 1234;
    66.     const y: *[1]i32 = &x;
    67.     const z: [*]i32 = y;
    68.     expect(z[0] == 1234);
    69. }
    1. $ zig test coerce_arrays_and_ptrs.zig
    2. 1/7 test "[N]T to []const T"... OK
    3. 2/7 test "[N]T to E![]const T"... OK
    4. 3/7 test "[N]T to ?[]const T"... OK
    5. 4/7 test "*[N]T to []T"... OK
    6. 5/7 test "*[N]T to [*]T"... OK
    7. 6/7 test "*[N]T to ?[*]T"... OK
    8. 7/7 test "*T to *[1]T"... OK
    9. All 7 tests passed.

    See also:

    The payload type of Optionals, as well as , coerce to the optional type.

    test.zig

    1. const std = @import("std");
    2. const expect = std.testing.expect;
    4. test "coerce to optionals" {
    5.     const x: ?i32 = 1234;
    6.     const y: ?i32 = null;
    8.     expect(x.? == 1234);
    9.     expect(y == null);
    10. }
    1. $ zig test test.zig
    2. 1/1 test "coerce to optionals"... OK
    3. All 1 tests passed.

    It works nested inside the Error Union Type, too:

    test.zig

    1. const std = @import("std");
    3. test "coerce to optionals wrapped in error union" {
    4.     const x: anyerror!?i32 = 1234;
    5.     const y: anyerror!?i32 = null;
    7.     expect((try x).? == 1234);
    8.     expect((try y) == null);
    9. }
    1. $ zig test test.zig
    2. 1/1 test "coerce to optionals wrapped in error union"... OK
    3. All 1 tests passed.

    The payload type of an Error Union Type as well as the coerce to the error union type:

    test.zig

    1. $ zig test test.zig
    2. 1/1 test "coercion to error unions"... OK
    3. All 1 tests passed.

    When a number is comptime-known to be representable in the destination type, it may be coerced:

    1. const std = @import("std");
    2. const expect = std.testing.expect;
    4. test "coercing large integer type to smaller one when value is comptime known to fit" {
    5.     const x: u64 = 255;
    6.     const y: u8 = x;
    7.     expect(y == 255);
    8. }
    1. $ zig test test.zig
    2. 1/1 test "coercing large integer type to smaller one when value is comptime known to fit"... OK
    3. All 1 tests passed.

    Tagged unions can be coerced to enums, and enums can be coerced to tagged unions when they are comptime-known to be a field of the union that has only one possible value, such as :

    test.zig

    1. const std = @import("std");
    2. const expect = std.testing.expect;
    4. const E = enum {
    5.     one,
    6.     two,
    7.     three,
    8. };
    10. const U = union(E) {
    11.     one: i32,
    12.     two: f32,
    13.     three,
    14. };
    16. test "coercion between unions and enums" {
    17.     var u = U{ .two = 12.34 };
    18.     var e: E = u;
    19.     expect(e == E.two);
    21.     const three = E.three;
    22.     var another_u: U = three;
    23.     expect(another_u == E.three);
    24. }
    1. $ zig test test.zig
    2. 1/1 test "coercion between unions and enums"... OK
    3. All 1 tests passed.

    See also:

    Type Coercion: Zero Bit Types

    may be coerced to single-item Pointers, regardless of const.

    TODO document the reasoning for this

    TODO document whether vice versa should work and why

    test.zig

    1. test "coercion of zero bit types" {
    2.     var x: void = {};
    3.     var y: *void = x;
    4.     //var z: void = y; // TODO
    5. }
    1. $ zig test test.zig
    2. 1/1 test "coercion of zero bit types"... OK
    3. All 1 tests passed.

    can be cast to any type.

    Explicit casts are performed via Builtin Functions. Some explicit casts are safe; some are not. Some explicit casts perform language-level assertions; some do not. Some explicit casts are no-ops at runtime; some are not.

    • - change type but maintain bit representation
    • @alignCast - make a pointer have more alignment
    • - convert true to 1 and false to 0
    • @enumToInt - obtain the integer tag value of an enum or tagged union
    • - convert to a smaller error set
    • @errorToInt - obtain the integer value of an error code
    • - convert a larger float to a smaller float
    • @floatToInt - obtain the integer part of a float value
    • - convert between integer types
    • @intToEnum - obtain an enum value based on its integer tag value
    • - obtain an error code based on its integer value
    • @intToFloat - convert an integer to a float value
    • - convert an address to a pointer
    • @ptrCast - convert between pointer types
    • - obtain the address of a pointer
    • @truncate - convert between integer types, chopping off bits

    Peer Type Resolution occurs in these places:

    • expressions
    • if expressions
    • expressions
    • for expressions
    • Multiple break statements in a block
    • Some

    peer_type_resolution.zig

    1. $ zig test peer_type_resolution.zig
    2. 1/7 test "peer resolve int widening"... OK
    3. 2/7 test "peer resolve arrays of different size to const slice"... OK
    4. 3/7 test "peer resolve array and const slice"... OK
    5. 4/7 test "peer type resolution: ?T and T"... OK
    6. 5/7 test "peer type resolution: *[0]u8 and []const u8"... OK
    7. 6/7 test "peer type resolution: *[0]u8, []const u8, and anyerror![]u8"... OK