Commit 6d1b1374f722f2b6f6f91e181e831238e3c8ce00 | zig

author	praschke <stel@comfy.monster> 2021-11-28 11:28:47+00:00
committer	Veikka Tuominen <git@vexu.eu> 2022-01-27 19:51:17+02:00
log	6d1b1374f722f2b6f6f91e181e831238e3c8ce00
tree	89608bd60607ae14893f268bf0cf766391ef19df
parent	1adb6440db30e5906f685ca5c188ce87bbe0d475

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#}