zig

commit 2b29424efd05fb059ba35f16eb804613676c869d (tree)
parent 8f89056dc27a77e0e35739db5b4310e68a49d9d3
Author: praschke <stel@comfy.monster>
Date:   Sun, 28 Nov 2021 11:28:47 +0000

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

Diffstat:
M
doc/langref.html.in
 | 
25
++++++++++++++-----------

1 file changed, 14 insertions(+), 11 deletions(-)
diff --git a/doc/langref.html.in b/doc/langref.html.in
@@ -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#}