Casting

A type cast converts a value of one type to another. Zig has Implicit Casts for conversions that are known to be completely safe and unambiguous, and Explicit Casts for conversions that one would not want to happen on accident. There is also a third kind of type conversion called Peer Type Resolution for the case when a result type must be decided given multiple operand types.

Implicit Casts

An implicit cast occurs when one type is expected, but different type is provided:

test.zig

  1. test "implicit cast - variable declaration" {
  2.     var a: u8 = 1;
  3.     var b: u16 = a;
  4. }
  6. test "implicit cast - function call" {
  7.     var a: u8 = 1;
  8.     foo(a);
  9. }
  11. fn foo(b: u16) void {}
  13. test "implicit cast - invoke a type as a function" {
  14.     var a: u8 = 1;
  15.     var b = u16(a);
  16. }
  1. $ zig test test.zig
  2. 1/3 test "implicit cast - variable declaration"...OK
  3. 2/3 test "implicit cast - function call"...OK
  4. 3/3 test "implicit cast - invoke a type as a function"...OK
  5. All tests passed.

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

Implicit Cast: Stricter Qualification

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
  • error sets to supersets is allowed

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

test.zig

  1. test "implicit cast - 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 "implicit cast - const qualification"...OK
  3. All tests passed.

In addition, pointers implicitly cast to const optional pointers:

test.zig

  1. const std = @import("std");
  2. const assert = std.debug.assert;
  3. const mem = std.mem;
  5. test "cast *[1][*]const u8 to [*]const ?[*]const u8" {
  6.     const window_name = [1][*]const u8{c"window name"};
  7.     const x: [*]const ?[*]const u8 = &window_name;
  8.     assert(mem.eql(u8, std.mem.toSliceConst(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 tests passed.

Implicit Cast: Integer and Float Widening

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

test.zig

  1. const std = @import("std");
  2. const assert = std.debug.assert;
  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.     assert(f == a);
  13. }
  15. test "implicit unsigned integer to signed integer" {
  16.     var a: u8 = 250;
  17.     var b: i16 = a;
  18.     assert(b == 250);
  19. }
  21. test "float widening" {
  22.     var a: f16 = 12.34;
  23.     var b: f32 = a;
  24.     var c: f64 = b;
  25.     var d: f128 = c;
  26.     assert(d == a);
  27. }
  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 tests passed.

Implicit Cast: Arrays and Pointers

test.zig

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

See also:

Implicit Cast: Optionals

The payload type of Optionals, as well as null, implicitly cast to the optional type.

test.zig

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

It works nested inside the Error Union Type, too:

test.zig

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

Implicit Cast: Error Unions

The payload type of an Error Union Type as well as the Error Set Type implicitly cast to the error union type:

test.zig

  1. const std = @import("std");
  2. const assert = std.debug.assert;
  4. test "implicit casting to error unions" {
  5.     const x: anyerror!i32 = 1234;
  6.     const y: anyerror!i32 = error.Failure;
  8.     assert((try x) == 1234);
  9.     std.testing.expectError(error.Failure, y);
  10. }
  1. $ zig test test.zig
  2. 1/1 test "implicit casting to error unions"...OK
  3. All tests passed.

Implicit Cast: Compile-Time Known Numbers

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

test.zig

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

Implicit Cast: unions and enums

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

test.zig

  1. const std = @import("std");
  2. const assert = std.debug.assert;
  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 "implicit casting between unions and enums" {
  17.     var u = U{ .Two = 12.34 };
  18.     var e: E = u;
  19.     assert(e == E.Two);
  21.     const three = E.Three;
  22.     var another_u: U = three;
  23.     assert(another_u == E.Three);
  24. }
  1. $ zig test test.zig
  2. 1/1 test "implicit casting between unions and enums"...OK
  3. All tests passed.

See also:

Implicit Cast: Zero Bit Types

Zero Bit Types may be implicitly casted 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 "implicit casting 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 "implicit casting of zero bit types"...OK
  3. All tests passed.

Implicit Cast: undefined

undefined can be cast to any type.

Explicit Casts

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.

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

Peer Type Resolution

Peer Type Resolution occurs in these places:

This kind of type resolution chooses a type that all peer types can implicitly cast into. Here are some examples:

test.zig

  1. const std = @import("std");
  2. const assert = std.debug.assert;
  3. const mem = std.mem;
  5. test "peer resolve int widening" {
  6.     var a: i8 = 12;
  7.     var b: i16 = 34;
  8.     var c = a + b;
  9.     assert(c == 46);
  10.     assert(@typeOf(c) == i16);
  11. }
  13. test "peer resolve arrays of different size to const slice" {
  14.     assert(mem.eql(u8, boolToStr(true), "true"));
  15.     assert(mem.eql(u8, boolToStr(false), "false"));
  16.     comptime assert(mem.eql(u8, boolToStr(true), "true"));
  17.     comptime assert(mem.eql(u8, boolToStr(false), "false"));
  18. }
  19. fn boolToStr(b: bool) []const u8 {
  20.     return if (b) "true" else "false";
  21. }
  23. test "peer resolve array and const slice" {
  24.     testPeerResolveArrayConstSlice(true);
  25.     comptime testPeerResolveArrayConstSlice(true);
  26. }
  27. fn testPeerResolveArrayConstSlice(b: bool) void {
  28.     const value1 = if (b) "aoeu" else ([]const u8)("zz");
  29.     const value2 = if (b) ([]const u8)("zz") else "aoeu";
  30.     assert(mem.eql(u8, value1, "aoeu"));
  31.     assert(mem.eql(u8, value2, "zz"));
  32. }
  34. test "peer type resolution: ?T and T" {
  35.     assert(peerTypeTAndOptionalT(true, false).? == 0);
  36.     assert(peerTypeTAndOptionalT(false, false).? == 3);
  37.     comptime {
  38.         assert(peerTypeTAndOptionalT(true, false).? == 0);
  39.         assert(peerTypeTAndOptionalT(false, false).? == 3);
  40.     }
  41. }
  42. fn peerTypeTAndOptionalT(c: bool, b: bool) ?usize {
  43.     if (c) {
  44.         return if (b) null else usize(0);
  45.     }
  47.     return usize(3);
  48. }
  50. test "peer type resolution: [0]u8 and []const u8" {
  51.     assert(peerTypeEmptyArrayAndSlice(true, "hi").len == 0);
  52.     assert(peerTypeEmptyArrayAndSlice(false, "hi").len == 1);
  53.     comptime {
  54.         assert(peerTypeEmptyArrayAndSlice(true, "hi").len == 0);
  55.         assert(peerTypeEmptyArrayAndSlice(false, "hi").len == 1);
  56.     }
  57. }
  58. fn peerTypeEmptyArrayAndSlice(a: bool, slice: []const u8) []const u8 {
  59.     if (a) {
  60.         return [_]u8{};
  61.     }
  63.     return slice[0..1];
  64. }
  65. test "peer type resolution: [0]u8, []const u8, and anyerror![]u8" {
  66.     {
  67.         var data = "hi";
  68.         const slice = data[0..];
  69.         assert((try peerTypeEmptyArrayAndSliceAndError(true, slice)).len == 0);
  70.         assert((try peerTypeEmptyArrayAndSliceAndError(false, slice)).len == 1);
  71.     }
  72.     comptime {
  73.         var data = "hi";
  74.         const slice = data[0..];
  75.         assert((try peerTypeEmptyArrayAndSliceAndError(true, slice)).len == 0);
  76.         assert((try peerTypeEmptyArrayAndSliceAndError(false, slice)).len == 1);
  77.     }
  78. }
  79. fn peerTypeEmptyArrayAndSliceAndError(a: bool, slice: []u8) anyerror![]u8 {
  80.     if (a) {
  81.         return [_]u8{};
  82.     }
  84.     return slice[0..1];
  85. }
  87. test "peer type resolution: *const T and ?*T" {
  88.     const a = @intToPtr(*const usize, 0x123456789);
  89.     const b = @intToPtr(?*usize, 0x123456789);
  90.     assert(a == b);
  91.     assert(b == a);
  92. }
  1. $ zig test test.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
  8. 7/7 test "peer type resolution: *const T and ?*T"...OK
  9. All tests passed.