authorgravatar for mlugg@mlugg.co.ukMatthew Lugg <mlugg@mlugg.co.uk> 2023-06-23 19:37:50+01:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2023-06-24 16:56:39-07:00
loga84a8953257ccfb70567a75017c98830eca250e3
tree6af3dcc5132a64767001287f13715bdb33ea6e83
parentf26dda21171e26f44aeec8c59a75bbb3331eeb2e

langref: update to new cast builtin syntax

1 files changed, 65 insertions(+), 59 deletions(-)

doc/langref.html.in+65-59
......@@ -2410,7 +2410,7 @@ var some_integers: [100]i32 = undefined;
24102410
24112411test "modify an array" {
24122412 for (&some_integers, 0..) |*item, i| {
2413 item.* = @intCast(i32, i);
2413 item.* = @intCast(i);
24142414 }
24152415 try expect(some_integers[10] == 10);
24162416 try expect(some_integers[99] == 99);
......@@ -2452,8 +2452,8 @@ var fancy_array = init: {
24522452 var initial_value: [10]Point = undefined;
24532453 for (&initial_value, 0..) |*pt, i| {
24542454 pt.* = Point{
2455 .x = @intCast(i32, i),
2456 .y = @intCast(i32, i) * 2,
2455 .x = @intCast(i),
2456 .y = @intCast(i * 2),
24572457 };
24582458 }
24592459 break :init initial_value;
......@@ -2769,7 +2769,7 @@ test "comptime pointers" {
27692769const expect = @import("std").testing.expect;
27702770
27712771test "@intFromPtr and @ptrFromInt" {
2772 const ptr = @ptrFromInt(*i32, 0xdeadbee0);
2772 const ptr: *i32 = @ptrFromInt(0xdeadbee0);
27732773 const addr = @intFromPtr(ptr);
27742774 try expect(@TypeOf(addr) == usize);
27752775 try expect(addr == 0xdeadbee0);
......@@ -2784,7 +2784,7 @@ test "comptime @ptrFromInt" {
27842784 comptime {
27852785 // Zig is able to do this at compile-time, as long as
27862786 // ptr is never dereferenced.
2787 const ptr = @ptrFromInt(*i32, 0xdeadbee0);
2787 const ptr: *i32 = @ptrFromInt(0xdeadbee0);
27882788 const addr = @intFromPtr(ptr);
27892789 try expect(@TypeOf(addr) == usize);
27902790 try expect(addr == 0xdeadbee0);
......@@ -2801,7 +2801,7 @@ test "comptime @ptrFromInt" {
28012801const expect = @import("std").testing.expect;
28022802
28032803test "volatile" {
2804 const mmio_ptr = @ptrFromInt(*volatile u8, 0x12345678);
2804 const mmio_ptr: *volatile u8 = @ptrFromInt(0x12345678);
28052805 try expect(@TypeOf(mmio_ptr) == *volatile u8);
28062806}
28072807 {#code_end#}
......@@ -2822,7 +2822,7 @@ const expect = std.testing.expect;
28222822
28232823test "pointer casting" {
28242824 const bytes align(@alignOf(u32)) = [_]u8{ 0x12, 0x12, 0x12, 0x12 };
2825 const u32_ptr = @ptrCast(*const u32, &bytes);
2825 const u32_ptr: *const u32 = @ptrCast(&bytes);
28262826 try expect(u32_ptr.* == 0x12121212);
28272827
28282828 // Even this example is contrived - there are better ways to do the above than
......@@ -2831,7 +2831,7 @@ test "pointer casting" {
28312831 try expect(u32_value == 0x12121212);
28322832
28332833 // And even another way, the most straightforward way to do it:
2834 try expect(@bitCast(u32, bytes) == 0x12121212);
2834 try expect(@as(u32, @bitCast(bytes)) == 0x12121212);
28352835}
28362836
28372837test "pointer child type" {
......@@ -2921,7 +2921,7 @@ test "pointer alignment safety" {
29212921}
29222922fn foo(bytes: []u8) u32 {
29232923 const slice4 = bytes[1..5];
2924 const int_slice = std.mem.bytesAsSlice(u32, @alignCast(4, slice4));
2924 const int_slice = std.mem.bytesAsSlice(u32, @as([]align(4) u8, @alignCast(slice4)));
29252925 return int_slice[0];
29262926}
29272927 {#code_end#}
......@@ -2942,7 +2942,7 @@ const expect = std.testing.expect;
29422942
29432943test "allowzero" {
29442944 var zero: usize = 0;
2945 var ptr = @ptrFromInt(*allowzero i32, zero);
2945 var ptr: *allowzero i32 = @ptrFromInt(zero);
29462946 try expect(@intFromPtr(ptr) == 0);
29472947}
29482948 {#code_end#}
......@@ -3354,12 +3354,12 @@ fn doTheTest() !void {
33543354 try expect(@sizeOf(Full) == 2);
33553355 try expect(@sizeOf(Divided) == 2);
33563356 var full = Full{ .number = 0x1234 };
3357 var divided = @bitCast(Divided, full);
3357 var divided: Divided = @bitCast(full);
33583358 try expect(divided.half1 == 0x34);
33593359 try expect(divided.quarter3 == 0x2);
33603360 try expect(divided.quarter4 == 0x1);
33613361
3362 var ordered = @bitCast([2]u8, full);
3362 var ordered: [2]u8 = @bitCast(full);
33633363 switch (native_endian) {
33643364 .Big => {
33653365 try expect(ordered[0] == 0x12);
......@@ -4428,7 +4428,7 @@ fn getNum(u: U) u32 {
44284428 // `u.a` or `u.b` and `tag` is `u`'s comptime-known tag value.
44294429 inline else => |num, tag| {
44304430 if (tag == .b) {
4431 return @intFromFloat(u32, num);
4431 return @intFromFloat(num);
44324432 }
44334433 return num;
44344434 }
......@@ -4714,7 +4714,7 @@ test "for basics" {
47144714 var sum2: i32 = 0;
47154715 for (items, 0..) |_, i| {
47164716 try expect(@TypeOf(i) == usize);
4717 sum2 += @intCast(i32, i);
4717 sum2 += @as(i32, @intCast(i));
47184718 }
47194719 try expect(sum2 == 10);
47204720
......@@ -6363,7 +6363,7 @@ const mem = std.mem;
63636363test "cast *[1][*]const u8 to [*]const ?[*]const u8" {
63646364 const window_name = [1][*]const u8{"window name"};
63656365 const x: [*]const ?[*]const u8 = &window_name;
6366 try expect(mem.eql(u8, std.mem.sliceTo(@ptrCast([*:0]const u8, x[0].?), 0), "window name"));
6366 try expect(mem.eql(u8, std.mem.sliceTo(@as([*:0]const u8, @ptrCast(x[0].?)), 0), "window name"));
63676367}
63686368 {#code_end#}
63696369 {#header_close#}
......@@ -6760,8 +6760,8 @@ fn peerTypeEmptyArrayAndSliceAndError(a: bool, slice: []u8) anyerror![]u8 {
67606760}
67616761
67626762test "peer type resolution: *const T and ?*T" {
6763 const a = @ptrFromInt(*const usize, 0x123456780);
6764 const b = @ptrFromInt(?*usize, 0x123456780);
6763 const a: *const usize = @ptrFromInt(0x123456780);
6764 const b: ?*usize = @ptrFromInt(0x123456780);
67656765 try expect(a == b);
67666766 try expect(b == a);
67676767}
......@@ -7762,12 +7762,13 @@ test "global assembly" {
77627762 at compile time.
77637763 </p>
77647764 {#header_open|@addrSpaceCast#}
7765 <pre>{#syntax#}@addrSpaceCast(comptime addrspace: std.builtin.AddressSpace, ptr: anytype) anytype{#endsyntax#}</pre>
7765 <pre>{#syntax#}@addrSpaceCast(ptr: anytype) anytype{#endsyntax#}</pre>
77667766 <p>
7767 Converts a pointer from one address space to another. Depending on the current target and
7768 address spaces, this cast may be a no-op, a complex operation, or illegal. If the cast is
7769 legal, then the resulting pointer points to the same memory location as the pointer operand.
7770 It is always valid to cast a pointer between the same address spaces.
7767 Converts a pointer from one address space to another. The new address space is inferred
7768 based on the result type. Depending on the current target and address spaces, this cast
7769 may be a no-op, a complex operation, or illegal. If the cast is legal, then the resulting
7770 pointer points to the same memory location as the pointer operand. It is always valid to
7771 cast a pointer between the same address spaces.
77717772 </p>
77727773 {#header_close#}
77737774 {#header_open|@addWithOverflow#}
......@@ -7777,10 +7778,10 @@ test "global assembly" {
77777778 </p>
77787779 {#header_close#}
77797780 {#header_open|@alignCast#}
7780 <pre>{#syntax#}@alignCast(comptime alignment: u29, ptr: anytype) anytype{#endsyntax#}</pre>
7781 <pre>{#syntax#}@alignCast(ptr: anytype) anytype{#endsyntax#}</pre>
77817782 <p>
77827783 {#syntax#}ptr{#endsyntax#} can be {#syntax#}*T{#endsyntax#}, {#syntax#}?*T{#endsyntax#}, or {#syntax#}[]T{#endsyntax#}.
7783 It returns the same type as {#syntax#}ptr{#endsyntax#} except with the alignment adjusted to the new value.
7784 Changes the alignment of a pointer. The alignment to use is inferred based on the result type.
77847785 </p>
77857786 <p>A {#link|pointer alignment safety check|Incorrect Pointer Alignment#} is added
77867787 to the generated code to make sure the pointer is aligned as promised.</p>
......@@ -7865,9 +7866,10 @@ comptime {
78657866 {#header_close#}
78667867
78677868 {#header_open|@bitCast#}
7868 <pre>{#syntax#}@bitCast(comptime DestType: type, value: anytype) DestType{#endsyntax#}</pre>
7869 <pre>{#syntax#}@bitCast(value: anytype) anytype{#endsyntax#}</pre>
78697870 <p>
7870 Converts a value of one type to another type.
7871 Converts a value of one type to another type. The return type is the
7872 inferred result type.
78717873 </p>
78727874 <p>
78737875 Asserts that {#syntax#}@sizeOf(@TypeOf(value)) == @sizeOf(DestType){#endsyntax#}.
......@@ -8420,10 +8422,11 @@ test "main" {
84208422 {#header_close#}
84218423
84228424 {#header_open|@errSetCast#}
8423 <pre>{#syntax#}@errSetCast(comptime T: DestType, value: anytype) DestType{#endsyntax#}</pre>
8425 <pre>{#syntax#}@errSetCast(value: anytype) anytype{#endsyntax#}</pre>
84248426 <p>
8425 Converts an error value from one error set to another error set. Attempting to convert an error
8426 which is not in the destination error set results in safety-protected {#link|Undefined Behavior#}.
8427 Converts an error value from one error set to another error set. The return type is the
8428 inferred result type. Attempting to convert an error which is not in the destination error
8429 set results in safety-protected {#link|Undefined Behavior#}.
84278430 </p>
84288431 {#header_close#}
84298432
......@@ -8535,17 +8538,17 @@ test "decl access by string" {
85358538 {#header_close#}
85368539
85378540 {#header_open|@floatCast#}
8538 <pre>{#syntax#}@floatCast(comptime DestType: type, value: anytype) DestType{#endsyntax#}</pre>
8541 <pre>{#syntax#}@floatCast(value: anytype) anytype{#endsyntax#}</pre>
85398542 <p>
85408543 Convert from one float type to another. This cast is safe, but may cause the
8541 numeric value to lose precision.
8544 numeric value to lose precision. The return type is the inferred result type.
85428545 </p>
85438546 {#header_close#}
85448547
85458548 {#header_open|@intFromFloat#}
8546 <pre>{#syntax#}@intFromFloat(comptime DestType: type, float: anytype) DestType{#endsyntax#}</pre>
8549 <pre>{#syntax#}@intFromFloat(float: anytype) anytype{#endsyntax#}</pre>
85478550 <p>
8548 Converts the integer part of a floating point number to the destination type.
8551 Converts the integer part of a floating point number to the inferred result type.
85498552 </p>
85508553 <p>
85518554 If the integer part of the floating point number cannot fit in the destination type,
......@@ -8660,16 +8663,17 @@ test "@hasDecl" {
86608663 {#header_close#}
86618664
86628665 {#header_open|@intCast#}
8663 <pre>{#syntax#}@intCast(comptime DestType: type, int: anytype) DestType{#endsyntax#}</pre>
8666 <pre>{#syntax#}@intCast(int: anytype) anytype{#endsyntax#}</pre>
86648667 <p>
86658668 Converts an integer to another integer while keeping the same numerical value.
8669 The return type is the inferred result type.
86668670 Attempting to convert a number which is out of range of the destination type results in
86678671 safety-protected {#link|Undefined Behavior#}.
86688672 </p>
86698673 {#code_begin|test_err|test_intCast_builtin|cast truncated bits#}
86708674test "integer cast panic" {
86718675 var a: u16 = 0xabcd;
8672 var b: u8 = @intCast(u8, a);
8676 var b: u8 = @intCast(a);
86738677 _ = b;
86748678}
86758679 {#code_end#}
......@@ -8683,9 +8687,9 @@ test "integer cast panic" {
86838687 {#header_close#}
86848688
86858689 {#header_open|@enumFromInt#}
8686 <pre>{#syntax#}@enumFromInt(comptime DestType: type, integer: anytype) DestType{#endsyntax#}</pre>
8690 <pre>{#syntax#}@enumFromInt(integer: anytype) anytype{#endsyntax#}</pre>
86878691 <p>
8688 Converts an integer into an {#link|enum#} value.
8692 Converts an integer into an {#link|enum#} value. The return type is the inferred result type.
86898693 </p>
86908694 <p>
86918695 Attempting to convert an integer which represents no value in the chosen enum type invokes
......@@ -8711,16 +8715,18 @@ test "integer cast panic" {
87118715 {#header_close#}
87128716
87138717 {#header_open|@floatFromInt#}
8714 <pre>{#syntax#}@floatFromInt(comptime DestType: type, int: anytype) DestType{#endsyntax#}</pre>
8718 <pre>{#syntax#}@floatFromInt(int: anytype) anytype{#endsyntax#}</pre>
87158719 <p>
8716 Converts an integer to the closest floating point representation. To convert the other way, use {#link|@intFromFloat#}. This cast is always safe.
8720 Converts an integer to the closest floating point representation. The return type is the inferred result type.
8721 To convert the other way, use {#link|@intFromFloat#}. This cast is always safe.
87178722 </p>
87188723 {#header_close#}
87198724
87208725 {#header_open|@ptrFromInt#}
8721 <pre>{#syntax#}@ptrFromInt(comptime DestType: type, address: usize) DestType{#endsyntax#}</pre>
8726 <pre>{#syntax#}@ptrFromInt(address: usize) anytype{#endsyntax#}</pre>
87228727 <p>
8723 Converts an integer to a {#link|pointer|Pointers#}. To convert the other way, use {#link|@intFromPtr#}. Casting an address of 0 to a destination type
8728 Converts an integer to a {#link|pointer|Pointers#}. The return type is the inferred result type.
8729 To convert the other way, use {#link|@intFromPtr#}. Casting an address of 0 to a destination type
87248730 which in not {#link|optional|Optional Pointers#} and does not have the {#syntax#}allowzero{#endsyntax#} attribute will result in a
87258731 {#link|Pointer Cast Invalid Null#} panic when runtime safety checks are enabled.
87268732 </p>
......@@ -8924,9 +8930,9 @@ pub const PrefetchOptions = struct {
89248930 {#header_close#}
89258931
89268932 {#header_open|@ptrCast#}
8927 <pre>{#syntax#}@ptrCast(comptime DestType: type, value: anytype) DestType{#endsyntax#}</pre>
8933 <pre>{#syntax#}@ptrCast(value: anytype) anytype{#endsyntax#}</pre>
89288934 <p>
8929 Converts a pointer of one type to a pointer of another type.
8935 Converts a pointer of one type to a pointer of another type. The return type is the inferred result type.
89308936 </p>
89318937 <p>
89328938 {#link|Optional Pointers#} are allowed. Casting an optional pointer which is {#link|null#}
......@@ -9522,10 +9528,10 @@ fn List(comptime T: type) type {
95229528 {#header_close#}
95239529
95249530 {#header_open|@truncate#}
9525 <pre>{#syntax#}@truncate(comptime T: type, integer: anytype) T{#endsyntax#}</pre>
9531 <pre>{#syntax#}@truncate(integer: anytype) anytype{#endsyntax#}</pre>
95269532 <p>
95279533 This function truncates bits from an integer type, resulting in a smaller
9528 or same-sized integer type.
9534 or same-sized integer type. The return type is the inferred result type.
95299535 </p>
95309536 <p>
95319537 This function always truncates the significant bits of the integer, regardless
......@@ -9540,7 +9546,7 @@ const expect = std.testing.expect;
95409546
95419547test "integer truncation" {
95429548 var a: u16 = 0xabcd;
9543 var b: u8 = @truncate(u8, a);
9549 var b: u8 = @truncate(a);
95449550 try expect(b == 0xcd);
95459551}
95469552 {#code_end#}
......@@ -9838,7 +9844,7 @@ fn foo(x: []const u8) u8 {
98389844 {#code_begin|test_err|test_comptime_invalid_cast|type 'u32' cannot represent integer value '-1'#}
98399845comptime {
98409846 var value: i32 = -1;
9841 const unsigned = @intCast(u32, value);
9847 const unsigned: u32 = @intCast(value);
98429848 _ = unsigned;
98439849}
98449850 {#code_end#}
......@@ -9848,7 +9854,7 @@ const std = @import("std");
98489854
98499855pub fn main() void {
98509856 var value: i32 = -1;
9851 var unsigned = @intCast(u32, value);
9857 var unsigned: u32 = @intCast(value);
98529858 std.debug.print("value: {}\n", .{unsigned});
98539859}
98549860 {#code_end#}
......@@ -9861,7 +9867,7 @@ pub fn main() void {
98619867 {#code_begin|test_err|test_comptime_invalid_cast_truncate|type 'u8' cannot represent integer value '300'#}
98629868comptime {
98639869 const spartan_count: u16 = 300;
9864 const byte = @intCast(u8, spartan_count);
9870 const byte: u8 = @intCast(spartan_count);
98659871 _ = byte;
98669872}
98679873 {#code_end#}
......@@ -9871,7 +9877,7 @@ const std = @import("std");
98719877
98729878pub fn main() void {
98739879 var spartan_count: u16 = 300;
9874 const byte = @intCast(u8, spartan_count);
9880 const byte: u8 = @intCast(spartan_count);
98759881 std.debug.print("value: {}\n", .{byte});
98769882}
98779883 {#code_end#}
......@@ -10208,7 +10214,7 @@ const Foo = enum {
1020810214};
1020910215comptime {
1021010216 const a: u2 = 3;
10211 const b = @enumFromInt(Foo, a);
10217 const b: Foo = @enumFromInt(a);
1021210218 _ = b;
1021310219}
1021410220 {#code_end#}
......@@ -10224,7 +10230,7 @@ const Foo = enum {
1022410230
1022510231pub fn main() void {
1022610232 var a: u2 = 3;
10227 var b = @enumFromInt(Foo, a);
10233 var b: Foo = @enumFromInt(a);
1022810234 std.debug.print("value: {s}\n", .{@tagName(b)});
1022910235}
1023010236 {#code_end#}
......@@ -10242,7 +10248,7 @@ const Set2 = error{
1024210248 C,
1024310249};
1024410250comptime {
10245 _ = @errSetCast(Set2, Set1.B);
10251 _ = @as(Set2, @errSetCast(Set1.B));
1024610252}
1024710253 {#code_end#}
1024810254 <p>At runtime:</p>
......@@ -10261,7 +10267,7 @@ pub fn main() void {
1026110267 foo(Set1.B);
1026210268}
1026310269fn foo(set1: Set1) void {
10264 const x = @errSetCast(Set2, set1);
10270 const x = @as(Set2, @errSetCast(set1));
1026510271 std.debug.print("value: {}\n", .{x});
1026610272}
1026710273 {#code_end#}
......@@ -10271,8 +10277,8 @@ fn foo(set1: Set1) void {
1027110277 <p>At compile-time:</p>
1027210278 {#code_begin|test_err|test_comptime_incorrect_pointer_alignment|pointer address 0x1 is not aligned to 4 bytes#}
1027310279comptime {
10274 const ptr = @ptrFromInt(*align(1) i32, 0x1);
10275 const aligned = @alignCast(4, ptr);
10280 const ptr: *align(1) i32 = @ptrFromInt(0x1);
10281 const aligned: *align(4) i32 = @alignCast(ptr);
1027610282 _ = aligned;
1027710283}
1027810284 {#code_end#}
......@@ -10286,7 +10292,7 @@ pub fn main() !void {
1028610292}
1028710293fn foo(bytes: []u8) u32 {
1028810294 const slice4 = bytes[1..5];
10289 const int_slice = mem.bytesAsSlice(u32, @alignCast(4, slice4));
10295 const int_slice = mem.bytesAsSlice(u32, @as([]align(4) u8, @alignCast(slice4)));
1029010296 return int_slice[0];
1029110297}
1029210298 {#code_end#}
......@@ -10387,7 +10393,7 @@ fn bar(f: *Foo) void {
1038710393 {#code_begin|test_err|test_comptime_invalid_null_pointer_cast|null pointer casted to type#}
1038810394comptime {
1038910395 const opt_ptr: ?*i32 = null;
10390 const ptr = @ptrCast(*i32, opt_ptr);
10396 const ptr: *i32 = @ptrCast(opt_ptr);
1039110397 _ = ptr;
1039210398}
1039310399 {#code_end#}
......@@ -10395,7 +10401,7 @@ comptime {
1039510401 {#code_begin|exe_err|runtime_invalid_null_pointer_cast#}
1039610402pub fn main() void {
1039710403 var opt_ptr: ?*i32 = null;
10398 var ptr = @ptrCast(*i32, opt_ptr);
10404 var ptr: *i32 = @ptrCast(opt_ptr);
1039910405 _ = ptr;
1040010406}
1040110407 {#code_end#}