round(3scm)

💅 round(3scm) — bestie edition

okay so this is a page straight out of the Scheme Programmer's Manual and it's literally about rounding numbers. four whole procedures. plus their flonum glow-ups. let's get into it 🫶

---

✨ NAME ✨

ceiling, floor, round, truncate — round a number. that's it. that's the whole vibe.

---

📚 LIBRARY 📚

like, import it from whichever flavour of Scheme you're living in, no cap:

(import (rnrs))                     ;R6RS
(import (rnrs base))                ;R6RS
(import (scheme r5rs))              ;R7RS
(import (scheme base))              ;R7RS
(import (rnrs arithmetic flonums))  ;R6RS

---

🌸 SYNOPSIS 🌸

(ceiling x)
(floor x)
(round x)
(truncate x)
(flceiling fl)
(flfloor fl)
(flround fl)
(fltruncate fl)

eight little icons, all lined up 💖

---

🔥 DESCRIPTION 🔥

so these procedures return inexact integer objects when you feed them inexact arguments that aren't infinities or NaNs, and exact integer objects when you give them exact rational arguments. that's the whole deal.

• ceiling — returns the smallest integer object not smaller than x. like, it looks up ✨
• floor — returns the largest integer object not larger than x. looks down 💅
• round — returns the closest integer object to x, and when x is literally halfway between two integers it rounds to even. iconic behaviour, we'll get to why.
• truncate — returns the integer object closest to x whose absolute value is not larger than the absolute value of x. it just chops, bestie.

if the argument to one of these procedures is inexact, then the result is also inexact. matching energy, fr fr.

and okay this part is kind of the plot twist 😭 — although infinities and NaNs are not integer objects, these procedures return an infinity when you hand them an infinity, and a NaN when you hand them a NaN. they simply refuse to be weird about it.

the flonum variants work exactly as described above, except the argument and the return value are always a flonum. always. no exceptions. 🦋

---

🎀 RETURN VALUES 🎀

returns a single number object that is an integer, an infinity, or a NaN. one object. that's the one. 👑

---

⭐ EXAMPLES ⭐

the classic negative-numbers moment:

(floor -4.3)         =>  -5.0
(ceiling -4.3)       =>  -4.0
(truncate -4.3)      =>  -4.0
(round -4.3)         =>  -4.0

and the positive ones, slay:

(floor 3.5)          =>  3.0
(ceiling 3.5)        =>  4.0
(truncate 3.5)       =>  3.0
(round 3.5)          =>  4.0

now watch this — exact rationals getting the exact treatment:

(round 7/2)          =>  4
(round 7)            =>  7

and the "weird but valid" squad:

(floor +inf.0)       =>  +inf.0
(ceiling -inf.0)     =>  -inf.0
(round +nan.0)       =>  +nan.0

plus the flonum versions doing the exact same bits:

(flfloor +inf.0)     =>  +inf.0
(flceiling -inf.0)   =>  -inf.0
(fltruncate +nan.0)  =>  +nan.0

---

🧚 RATIONALE 🧚

okay so why does round(3scm) go to even on a tie? because it's matching the default rounding mode specified by the IEEE 754 floating-point standard. consistency. that's the reason. iykyk 💜

---

💀 ERRORS 💀

this procedure can raise exceptions with the following condition types:

• &assertion (R6RS) — the wrong number of arguments was passed, or an argument was outside its domain.
• R7RS — the assertions described above are errors. implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically. yeah. catastrophically. 😭

---

💖 SEE ALSO 💖

rationalize(3scm), div-and-mod(3scm), exact(3scm) — go read those next, they're the friend group.

---

🌈 STANDARDS 🌈

R4RS, IEEE Scheme, R5RS, R6RS, R7RS. five whole standards. she's certified. 👑

---

🌸 HISTORY 🌸

these procedures first appeared in R2RS, which based them on similar functions in Common Lisp. and like, tea ☕ — note that the Common Lisp versions have a second return value. we don't. we're built different.

---

🫶 AUTHORS 🫶

this page is part of the scheme-manpages project. it includes materials from the RnRS documents. more info lives at https://github.com/schemedoc/manpages/.

---

that's the whole page bestie, no notes ✨🦋💅 dated 2022-03-27, from the round(3scm) era, and yeah — the round-up is complete 🍓