Commit 2b29424efd05fb059ba35f16eb804613676c869d | zig

author	praschke <stel@comfy.monster> 2021-11-28 11:28:47+00:00
committer	Andrew Kelley <andrew@ziglang.org> 2022-02-02 22:00:00-07:00
log	2b29424efd05fb059ba35f16eb804613676c869d
tree	1c9e1f3119ed6a92862891629b6995549c3c20ea
parent	8f89056dc27a77e0e35739db5b4310e68a49d9d3

docs: reorganize `@truncate` and `@intCast` for clarity

1 files changed, 14 insertions(+), 11 deletions(-)

doc
- langref.html.in

doc/langref.html.in+14-11

 @@ -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
+      Use {#link|@intCast#} to convert numbers guaranteed to fit the destination type.
-      of endianness on the target platform.
       </p>
       {#header_close#}