mirror/zig
1
0
Fork 0
mirror of https://github.com/ziglang/zig.git synced 2026-01-12 02:15:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: reorganize @truncate and @intCast for clarity

Browse Source
This commit is contained in:
praschke 2021-11-28 11:28:47 +00:00 committed by Andrew Kelley
parent 8f89056dc2
commit 2b29424efd
1 changed files with 14 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
doc/langref.html.in
View File

@ -8537,6 +8537,16 @@ test "@hasDecl" {
Attempting to convert a number which is out of range of the destination type results in
safety-protected {#link|Undefined Behavior#}.
</p>
{#code_begin|test_err|cast truncated bits#}
test "integer cast panic" {
var a: u16 = 0xabcd;
var b: u8 = @intCast(u8, a);
_ = b;
}
{#code_end#}
<p>
To truncate the significant bits of a number out of range of the destination type, use {#link|@truncate#}.
</p>
<p>
If {#syntax#}T{#endsyntax#} is {#syntax#}comptime_int{#endsyntax#},
then this is semantically equivalent to {#link|Type Coercion#}.
@ -9380,17 +9390,11 @@ fn List(comptime T: type) type {
or same-sized integer type.
</p>
<p>
The following produces safety-checked {#link|Undefined Behavior#}:
This function always truncates the significant bits of the integer, regardless
of endianness on the target platform.
</p>
{#code_begin|test_err|cast truncated bits#}
test "integer cast panic" {
var a: u16 = 0xabcd;
var b: u8 = @intCast(u8, a);
_ = b;
}
{#code_end#}
<p>
However this is well defined and working code:
Calling {#syntax#}@truncate{#endsyntax#} on a number out of range of the destination type is well defined and working code:
</p>
{#code_begin|test|truncate#}
const std = @import("std");
@ -9403,8 +9407,7 @@ test "integer truncation" {
}
{#code_end#}
<p>
This function always truncates the significant bits of the integer, regardless
of endianness on the target platform.
Use {#link|@intCast#} to convert numbers guaranteed to fit the destination type.
</p>
{#header_close#}