zig

commit eb7f318ea897d51082b70c84591242735c8a2c53 (tree)
parent b7a1ef3e19039690b182a295dff7cffe5fcc521f
Author: T <torque@users.noreply.github.com>
Date:   Wed, 14 Aug 2024 10:29:45 -0700

langref: clarify functionality of the round builtin (#19503)

A test has also been added to demonstrate the expected behavior.

* std.math: update round doc comment to match the builtin
Diffstat:
M
doc/langref.html.in
 | 
6
++++--
A
doc/langref/test_round_builtin.zig
 | 
10
++++++++++
M
lib/std/math.zig
 | 
3
++-

3 files changed, 16 insertions(+), 3 deletions(-)
diff --git a/doc/langref.html.in b/doc/langref.html.in
@@ -5618,9 +5618,11 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
       {#header_open|@round#}
       <pre>{#syntax#}@round(value: anytype) @TypeOf(value){#endsyntax#}</pre>
       <p>
-      Rounds the given floating point number to an integer, away from zero. Uses a dedicated hardware instruction
-      when available.
+      Rounds the given floating point number to the nearest integer. If two integers are equally close, rounds away from zero.
+      Uses a dedicated hardware instruction when available.
       </p>
+      {#code|test_round_builtin.zig#}
+
       <p>
       Supports {#link|Floats#} and {#link|Vectors#} of floats.
       </p>
diff --git a/doc/langref/test_round_builtin.zig b/doc/langref/test_round_builtin.zig
@@ -0,0 +1,10 @@
+const expect = @import("std").testing.expect;
+
+test "@round" {
+    try expect(@round(1.4) == 1);
+    try expect(@round(1.5) == 2);
+    try expect(@round(-1.4) == -1);
+    try expect(@round(-2.5) == -3);
+}
+
+// test
diff --git a/lib/std/math.zig b/lib/std/math.zig
@@ -1140,7 +1140,8 @@ test ByteAlignedInt {
     try testing.expect(ByteAlignedInt(u129) == u136);
 }
 
-/// Rounds the given floating point number to an integer, away from zero.
+/// Rounds the given floating point number to the nearest integer.
+/// If two integers are equally close, rounds away from zero.
 /// Uses a dedicated hardware instruction when available.
 /// This is the same as calling the builtin @round
 pub inline fn round(value: anytype) @TypeOf(value) {