math::exact(3tcl)

💖 math::exact — Exact Real Arithmetic 💖

ok so bestie, you've stumbled into math::exact, part of the Tcl Math Library (that's the 3tcl manual, iykyk). Buckle up because this one is genuinely iconic: it does math that is actually exact, not just "exact-ish with more digits". Let's get into it. 🦋

---

✨ SYNOPSIS ✨

package require Tcl 8.6 9

package require grammar::aycock 1.0

package require math::exact 1.0.2

::math::exact::exactexpr expr

number ref

number unref

number asPrint precision

number asFloat precision

---

🌸 DESCRIPTION 🌸

okay so the exactexpr command in the math::exact package lets you do exact computations over the computable real numbers. And no, this is not your regular arbitrary-precision situation — bestie, this is a whole different vibe. These are exact. The numbers are represented by algorithms that keep producing successive approximations. 💅

At the end of a calculation you (the caller, the main character) can ask for a specific precision for the final result, and all the intermediate results get computed to whatever precision is actually necessary to satisfy that request. No more, no less. It's giving efficiency. ✨

---

🎀 PROCEDURES 🎀

This next one is the primary entry point into the math::exact package. The way that it's the front door of the whole thing.

• ::math::exact::exactexpr expr — takes a mathematical expression in Tcl syntax and hands you back an object representing the program that will calculate successive approximations of that expression's value. We're gonna call that result an exact real number. 🫶
• number ref — bumps up the reference count of a given exact real number. (Yes queen, we're doing manual refcounting, stay with me.)
• number unref — drops the reference count of a given exact real number, and destroys the number if the reference count hits zero. 💀
• number asPrint precision — formats the given number for printing at the specified precision. (How precision gets interpreted? Scroll down, we got you.) Numbers that are known to be rational get formatted as fractions. 🍓
• number asFloat precision — formats the given number for printing at the specified precision. (Same deal with precision, see below.) Every single number gets formatted in floating-point E format.

---

💜 PARAMETERS 💜

• expr — the expression to evaluate. The syntax for expressions is the same as it is in Tcl, but the set of operations is smaller. Head to Expressions below for the details.
• number — the object returned by an earlier invocation of math::exact::exactexpr.
• precision — the requested 'precision' of the result. So basically, precision is (approximately) the absolute value of the binary exponent plus the number of bits of the binary significand. For instance, to return results to IEEE-754 double precision, you need 56 bits plus the exponent. Let's break it down because this is lowkey the whole game:
  • Numbers between 1/2 and 2 → precision of 57
  • Numbers between 1/4 and 1/2, or between 2 and 4 → 58
  • Numbers between 1/8 and 1/4, or between 4 and 8 → 59
  • and so on, forever, slay. ⭐

---

🌈 EXPRESSIONS 🌈

The math::exact::exactexpr command accepts expressions in a subset of Tcl's syntax. Here's what you're allowed to use in an expression:

• Decimal integers. 🔢
• Variable references with the dollar sign ($). The value of the variable must be the result of another call to math::exact::exactexpr. The reference count of that value gets increased by one for each position at which it appears in the expression. (Yes, every position. Count them. 👀)
• The exponentiation operator (**).
• Unary plus (+) and minus (-) operators.
• Multiplication (*) and division (/) operators.
• Parentheses used for grouping.
• Functions. See Functions below for what's available.

---

🧚 FUNCTIONS 🧚

These are the functions you can use inside exact real expressions. All of them, no skips:

• acos(x) — the inverse cosine of x. Result comes out in radians. The absolute value of x must be less than 1.
• acosh(x) — the inverse hyperbolic cosine of x. x must be greater than 1.
• asin(x) — the inverse sine of x. Result comes out in radians. The absolute value of x must be less than 1.
• asinh(x) — the inverse hyperbolic sine of x.
• atan(x) — the inverse tangent of x. Result comes out in radians.
• atanh(x) — the inverse hyperbolic tangent of x. The absolute value of x must be less than 1.
• cos(x) — the cosine of x. x is expressed in radians.
• cosh(x) — the hyperbolic cosine of x.
• e() — the base of the natural logarithms = 2.71828...
• exp(x) — the exponential function of x.
• log(x) — the natural logarithm of x. x must be positive.
• pi() — the value of pi = 3.15159...
• sin(x) — the sine of x. x is expressed in radians.
• sinh(x) — the hyperbolic sine of x.
• sqrt(x) — the square root of x. x must be positive.
• tan(x) — the tangent of x. x is expressed in radians.
• tanh(x) — the hyperbolic tangent of x.

---

👑 SUMMARY 👑

The math::exact::exactexpr command gives you a system that performs exact arithmetic over computable real numbers, representing those numbers as algorithms for successive approximation. Here's an example that implements the high-school quadratic formula. It's giving nostalgia but make it rigorous. 💅

namespace import math::exact::exactexpr
proc exactquad {a b c} {
    set d [[exactexpr {sqrt($b*$b - 4*$a*$c)}] ref]
    set r0 [[exactexpr {(-$b - $d) / (2 * $a)}] ref]
    set r1 [[exactexpr {(-$b + $d) / (2 * $a)}] ref]
    $d unref
    return [list $r0 $r1]
}

set a [[exactexpr 1] ref]
set b [[exactexpr 200] ref]
set c [[exactexpr {(-3/2) * 10**-12}] ref]
lassign [exactquad $a $b $c] r0 r1
$a unref; $b unref; $c unref
puts [list [$r0 asFloat 70] [$r1 asFloat 110]]
$r0 unref; $r1 unref

And the program prints the result:

-2.000000000000000075e2 7.499999999999999719e-15

Now here's the tea: if IEEE-754 floating point had been used, a catastrophic roundoff error would have handed you a smaller root that is a factor of two too high:

-200.0 1.4210854715202004e-14

The invocations of exactexpr should be fairly self-explanatory. The other commands of note are ref and unref. And fr fr, it is necessary for the caller to keep track of references to exact expressions — call ref every single time an exact expression gets stored in a variable, and unref every time that variable goes out of scope or gets overwritten. Don't be sloppy, the refcounts will know. 😭

The asFloat method emits decimal digits for as long as the requested precision supports them. It terminates when the requested precision yields an uncertainty of more than one unit in the least significant digit. 🎯

---

⭐ CATEGORY ⭐

Mathematics

---

📜 COPYRIGHT 📜

Copyright (c) 2015 Kevin B. Kenny <kennykb@acm.org> Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/>

---

ok bestie that's the whole page, you ate it, periodt. 🫶✨ this was math::exact, version 1.0.2, from the tcllib collection, and this manual page is dated 1.0.2 too — go forth and compute exactly, no cap 💅🎀🦋