wren/manual_src/pages/api/number.html

{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}

{% set page_title = "Num" %}
{% set breadcrumb = [{"url": "api/index.html", "title": "API Reference"}, {"title": "Num"}] %}
{% set prev_page = {"url": "api/string.html", "title": "String"} %}
{% set next_page = {"url": "api/http.html", "title": "http"} %}

{% block article %}
                <h1>Num</h1>

                <p>The <code>Num</code> class is the core numeric type in Wren. All numbers are double-precision floating point. The class provides arithmetic, trigonometric, bitwise, rounding, query, conversion, and formatting methods.</p>

                <h2>Static Constants</h2>

                <div class="method-signature">
                    <span class="method-name">Num.pi</span> → <span class="type">Num</span>
                </div>
                <p>The ratio of a circle's circumference to its diameter (3.14159...).</p>

                <div class="method-signature">
                    <span class="method-name">Num.tau</span> → <span class="type">Num</span>
                </div>
                <p>Two times pi (6.28318...).</p>

                <div class="method-signature">
                    <span class="method-name">Num.e</span> → <span class="type">Num</span>
                </div>
                <p>Euler's number (2.71828...).</p>

                <div class="method-signature">
                    <span class="method-name">Num.infinity</span> → <span class="type">Num</span>
                </div>
                <p>Positive infinity.</p>

                <div class="method-signature">
                    <span class="method-name">Num.nan</span> → <span class="type">Num</span>
                </div>
                <p>Not-a-number value.</p>

                <div class="method-signature">
                    <span class="method-name">Num.largest</span> → <span class="type">Num</span>
                </div>
                <p>The largest representable double value.</p>

                <div class="method-signature">
                    <span class="method-name">Num.smallest</span> → <span class="type">Num</span>
                </div>
                <p>The smallest positive representable double value.</p>

                <div class="method-signature">
                    <span class="method-name">Num.maxSafeInteger</span> → <span class="type">Num</span>
                </div>
                <p>The largest integer representable without loss of precision (9007199254740991).</p>

                <div class="method-signature">
                    <span class="method-name">Num.minSafeInteger</span> → <span class="type">Num</span>
                </div>
                <p>The smallest integer representable without loss of precision (-9007199254740991).</p>

                <h3>Static Methods</h3>

                <div class="method-signature">
                    <span class="method-name">Num.fromString</span>(<span class="param">string</span>) → <span class="type">Num|null</span>
                </div>
                <p>Parses a string as a number. Returns <code>null</code> if the string is not a valid number.</p>
                <pre><code>Num.fromString("42")    // 42
Num.fromString("3.14")  // 3.14
Num.fromString("nope")  // null</code></pre>

                <h2>Query Methods</h2>

                <div class="method-signature">
                    <span class="method-name">isInteger</span> → <span class="type">Bool</span>
                </div>
                <p>Whether the number is an integer (has no fractional part).</p>

                <div class="method-signature">
                    <span class="method-name">isNan</span> → <span class="type">Bool</span>
                </div>
                <p>Whether the number is NaN.</p>

                <div class="method-signature">
                    <span class="method-name">isInfinity</span> → <span class="type">Bool</span>
                </div>
                <p>Whether the number is positive or negative infinity.</p>

                <div class="method-signature">
                    <span class="method-name">isFinite</span> → <span class="type">Bool</span>
                </div>
                <p>Whether the number is finite (not infinity and not NaN).</p>
                <pre><code>42.isFinite      // true
(1/0).isFinite   // false
(0/0).isFinite   // false</code></pre>

                <div class="method-signature">
                    <span class="method-name">isZero</span> → <span class="type">Bool</span>
                </div>
                <p>Whether the number equals zero.</p>

                <div class="method-signature">
                    <span class="method-name">isPositive</span> → <span class="type">Bool</span>
                </div>
                <p>Whether the number is strictly greater than zero.</p>

                <div class="method-signature">
                    <span class="method-name">isNegative</span> → <span class="type">Bool</span>
                </div>
                <p>Whether the number is strictly less than zero.</p>

                <div class="method-signature">
                    <span class="method-name">isEven</span> → <span class="type">Bool</span>
                </div>
                <p>Whether the number is an even integer.</p>

                <div class="method-signature">
                    <span class="method-name">isOdd</span> → <span class="type">Bool</span>
                </div>
                <p>Whether the number is an odd integer.</p>

                <div class="method-signature">
                    <span class="method-name">isBetween</span>(<span class="param">min</span>, <span class="param">max</span>) → <span class="type">Bool</span>
                </div>
                <p>Whether the number is within the inclusive range [min, max].</p>
                <pre><code>5.isBetween(1, 10)   // true
0.isBetween(1, 10)   // false
10.isBetween(1, 10)  // true</code></pre>

                <div class="method-signature">
                    <span class="method-name">sign</span> → <span class="type">Num</span>
                </div>
                <p>Returns 1 for positive, -1 for negative, or 0 for zero.</p>

                <h2>Arithmetic</h2>

                <div class="method-signature">
                    <span class="method-name">abs</span> → <span class="type">Num</span>
                </div>
                <p>Absolute value.</p>

                <div class="method-signature">
                    <span class="method-name">min</span>(<span class="param">other</span>) → <span class="type">Num</span>
                </div>
                <p>Returns the smaller of this number and <code>other</code>.</p>

                <div class="method-signature">
                    <span class="method-name">max</span>(<span class="param">other</span>) → <span class="type">Num</span>
                </div>
                <p>Returns the larger of this number and <code>other</code>.</p>

                <div class="method-signature">
                    <span class="method-name">clamp</span>(<span class="param">min</span>, <span class="param">max</span>) → <span class="type">Num</span>
                </div>
                <p>Constrains this number to the range [min, max].</p>
                <pre><code>15.clamp(0, 10)  // 10
5.clamp(0, 10)   // 5
(-3).clamp(0, 10) // 0</code></pre>

                <div class="method-signature">
                    <span class="method-name">pow</span>(<span class="param">exponent</span>) → <span class="type">Num</span>
                </div>
                <p>Raises this number to the given power.</p>

                <h2>Rounding</h2>

                <div class="method-signature">
                    <span class="method-name">ceil</span> → <span class="type">Num</span>
                </div>
                <p>Rounds up to the nearest integer.</p>

                <div class="method-signature">
                    <span class="method-name">floor</span> → <span class="type">Num</span>
                </div>
                <p>Rounds down to the nearest integer.</p>

                <div class="method-signature">
                    <span class="method-name">round</span> → <span class="type">Num</span>
                </div>
                <p>Rounds to the nearest integer.</p>

                <div class="method-signature">
                    <span class="method-name">truncate</span> → <span class="type">Num</span>
                </div>
                <p>Removes the fractional part, rounding toward zero.</p>

                <div class="method-signature">
                    <span class="method-name">fraction</span> → <span class="type">Num</span>
                </div>
                <p>Returns the fractional part of the number.</p>

                <h2>Roots &amp; Exponents</h2>

                <div class="method-signature">
                    <span class="method-name">sqrt</span> → <span class="type">Num</span>
                </div>
                <p>Square root.</p>

                <div class="method-signature">
                    <span class="method-name">cbrt</span> → <span class="type">Num</span>
                </div>
                <p>Cube root.</p>

                <div class="method-signature">
                    <span class="method-name">exp</span> → <span class="type">Num</span>
                </div>
                <p>Returns e raised to this power.</p>

                <h2>Logarithms</h2>

                <div class="method-signature">
                    <span class="method-name">log</span> → <span class="type">Num</span>
                </div>
                <p>Natural logarithm (base e).</p>

                <div class="method-signature">
                    <span class="method-name">log2</span> → <span class="type">Num</span>
                </div>
                <p>Base-2 logarithm.</p>

                <div class="method-signature">
                    <span class="method-name">log10</span> → <span class="type">Num</span>
                </div>
                <p>Base-10 logarithm.</p>
                <pre><code>100.log10   // 2
1000.log10  // 3
1.log10     // 0</code></pre>

                <h2>Trigonometry</h2>

                <div class="method-signature">
                    <span class="method-name">sin</span> → <span class="type">Num</span>
                </div>
                <p>Sine (argument in radians).</p>

                <div class="method-signature">
                    <span class="method-name">cos</span> → <span class="type">Num</span>
                </div>
                <p>Cosine (argument in radians).</p>

                <div class="method-signature">
                    <span class="method-name">tan</span> → <span class="type">Num</span>
                </div>
                <p>Tangent (argument in radians).</p>

                <div class="method-signature">
                    <span class="method-name">asin</span> → <span class="type">Num</span>
                </div>
                <p>Arc sine, returns radians.</p>

                <div class="method-signature">
                    <span class="method-name">acos</span> → <span class="type">Num</span>
                </div>
                <p>Arc cosine, returns radians.</p>

                <div class="method-signature">
                    <span class="method-name">atan</span> → <span class="type">Num</span>
                </div>
                <p>Arc tangent, returns radians.</p>

                <div class="method-signature">
                    <span class="method-name">atan</span>(<span class="param">x</span>) → <span class="type">Num</span>
                </div>
                <p>Two-argument arc tangent (atan2). Returns the angle between the positive x-axis and the point (x, this).</p>

                <h3>Hyperbolic Functions</h3>

                <div class="method-signature">
                    <span class="method-name">sinh</span> → <span class="type">Num</span>
                </div>
                <p>Hyperbolic sine.</p>

                <div class="method-signature">
                    <span class="method-name">cosh</span> → <span class="type">Num</span>
                </div>
                <p>Hyperbolic cosine.</p>

                <div class="method-signature">
                    <span class="method-name">tanh</span> → <span class="type">Num</span>
                </div>
                <p>Hyperbolic tangent.</p>
                <pre><code>0.sinh  // 0
0.cosh  // 1
0.tanh  // 0</code></pre>

                <h2>Angle Conversion</h2>

                <div class="method-signature">
                    <span class="method-name">toDegrees</span> → <span class="type">Num</span>
                </div>
                <p>Converts radians to degrees.</p>

                <div class="method-signature">
                    <span class="method-name">toRadians</span> → <span class="type">Num</span>
                </div>
                <p>Converts degrees to radians.</p>
                <pre><code>Num.pi.toDegrees  // 180
180.toRadians     // 3.14159...</code></pre>

                <h2>Conversion</h2>

                <div class="method-signature">
                    <span class="method-name">toString</span> → <span class="type">String</span>
                </div>
                <p>Converts the number to its string representation.</p>

                <div class="method-signature">
                    <span class="method-name">toChar</span> → <span class="type">String</span>
                </div>
                <p>Returns the Unicode character for this code point.</p>
                <pre><code>65.toChar  // "A"
97.toChar  // "a"</code></pre>

                <div class="method-signature">
                    <span class="method-name">toBase</span>(<span class="param">radix</span>) → <span class="type">String</span>
                </div>
                <p>Converts the integer part to a string in the given base (2-36).</p>
                <pre><code>255.toBase(16)  // "ff"
255.toBase(2)   // "11111111"
255.toBase(8)   // "377"</code></pre>

                <div class="method-signature">
                    <span class="method-name">toHex</span> → <span class="type">String</span>
                </div>
                <p>Shorthand for <code>toBase(16)</code>.</p>

                <div class="method-signature">
                    <span class="method-name">toBinary</span> → <span class="type">String</span>
                </div>
                <p>Shorthand for <code>toBase(2)</code>.</p>

                <div class="method-signature">
                    <span class="method-name">toOctal</span> → <span class="type">String</span>
                </div>
                <p>Shorthand for <code>toBase(8)</code>.</p>

                <h2>Formatting</h2>

                <div class="method-signature">
                    <span class="method-name">format</span>(<span class="param">decimals</span>) → <span class="type">String</span>
                </div>
                <p>Formats the number with a fixed number of decimal places (0-20).</p>
                <pre><code>3.14159.format(2)  // "3.14"
42.format(3)       // "42.000"
(-1.5).format(1)   // "-1.5"</code></pre>

                <h2>Integer Operations</h2>

                <div class="method-signature">
                    <span class="method-name">gcd</span>(<span class="param">other</span>) → <span class="type">Num</span>
                </div>
                <p>Greatest common divisor using the Euclidean algorithm. Operates on absolute values.</p>
                <pre><code>12.gcd(8)   // 4
54.gcd(24)  // 6
7.gcd(13)   // 1</code></pre>

                <div class="method-signature">
                    <span class="method-name">lcm</span>(<span class="param">other</span>) → <span class="type">Num</span>
                </div>
                <p>Least common multiple.</p>
                <pre><code>4.lcm(6)  // 12
3.lcm(5)  // 15</code></pre>

                <div class="method-signature">
                    <span class="method-name">digits</span> → <span class="type">List</span>
                </div>
                <p>Returns a list of the individual digits of the integer's absolute value. Aborts if the number is not an integer.</p>
                <pre><code>123.digits     // [1, 2, 3]
0.digits       // [0]
(-456).digits  // [4, 5, 6]</code></pre>

                <h2>Bitwise Operations</h2>

                <p>Bitwise operators work on 32-bit unsigned integers.</p>

                <table>
                    <tr>
                        <th>Operator</th>
                        <th>Description</th>
                    </tr>
                    <tr><td><code>&amp;(other)</code></td><td>Bitwise AND</td></tr>
                    <tr><td><code>|(other)</code></td><td>Bitwise OR</td></tr>
                    <tr><td><code>^(other)</code></td><td>Bitwise XOR</td></tr>
                    <tr><td><code>&lt;&lt;(other)</code></td><td>Left shift</td></tr>
                    <tr><td><code>&gt;&gt;(other)</code></td><td>Right shift</td></tr>
                    <tr><td><code>~</code></td><td>Bitwise NOT</td></tr>
                </table>

                <h2>Ranges</h2>

                <div class="method-signature">
                    <span class="method-name">..</span>(<span class="param">to</span>) → <span class="type">Range</span>
                </div>
                <p>Creates an inclusive range from this number to <code>to</code>.</p>

                <div class="method-signature">
                    <span class="method-name">...</span>(<span class="param">to</span>) → <span class="type">Range</span>
                </div>
                <p>Creates an exclusive range from this number to <code>to</code> (excludes the end).</p>
                <pre><code>for (i in 1..5) System.print(i)   // 1 2 3 4 5
for (i in 1...5) System.print(i)  // 1 2 3 4</code></pre>
{% endblock %}