Add function to round to nearest integer

beutlich · Apr 11, 2020 · 9e303b5 · 9e303b5
1 parent f5f97ab
commit 9e303b5
Show file tree

Hide file tree

Showing 2 changed files with 51 additions and 0 deletions.
diff --git a/Modelica/Math/nearestInteger.mo b/Modelica/Math/nearestInteger.mo
@@ -0,0 +1,50 @@
+within Modelica.Math;
+function nearestInteger "Convert real number to nearest integer value"
+  extends Modelica.Icons.Function;
+
+  input Real r "Real number to convert to integer";
+  output Integer i "Integer value, which is closest to the given real number";
+
+algorithm
+  i :=if (r > 0) then integer(floor(r + 0.5)) else integer(ceil(r - 0.5));
+
+  annotation (Documentation(info="<html>
+
+<h4>Syntax</h4>
+<blockquote><pre>
+Math.<strong>nearestInteger</strong>(r);
+</pre></blockquote>
+
+<h4>Description</h4>
+<p>
+    The input value \"r\" of type Real is converted to the closest Integer value \"i\", 
+    using the <i>round half away from zero</i> rule with the equation:
+</p>
+<blockquote><pre>
+i = <strong>integer</strong>( <strong>floor</strong>( r + 0.5 ) )  for  r &gt; 0;
+i = <strong>integer</strong>(  <strong>ceil</strong>( r - 0.5 ) )  for  r &lt; 0;
+</pre></blockquote>
+
+<h4>Example</h4>
+<blockquote><pre>
+import Modelica.Math;
+Math.nearestInteger(0.4);                     // = 0
+Math.nearestInteger(0.5);                     // = 1
+Math.nearestInteger(-0.4);                    // = 0
+Math.nearestInteger(-0.5);                    // = -1
+Math.nearestInteger(0.3999999999999999+0.1);  // = 0
+Math.nearestInteger(1.39999999999999999+0.1); // = 1 (errorneous border case, see note below)
+</pre></blockquote>
+
+<h4>Note</h4>
+
+<p>
+    This function does the same conversion as the block
+    <a href=\"modelica://Modelica.Blocks.Math.RealToInteger\">RealToInteger</a>.
+</p>
+<p>
+    The underlying equation is simple, but not always correct. Due to floating point arithmetic some border cases
+    are not converted correct, like shown in the example above.
+</p>
+</html>"));
+end nearestInteger;
diff --git a/Modelica/Math/package.order b/Modelica/Math/package.order
@@ -10,6 +10,7 @@ FastFourierTransform
 Icons
 isEqual
 isPowerOf2
+nearestInteger
 sin
 cos
 tan