div(3scm)

💅 div(3scm) — number-theoretic integer division, bestie edition

okay so this is page div(3scm) from the Scheme Programmer's Manual and honestly it's giving math-girlie main character energy. Let's get into it ✨

🌸 NAME 🌸

div, mod, div-and-mod — number-theoretic integer division. periodt. that's the whole vibe.

📚 LIBRARY 📚

import these bestie, pick your fighter:

(import (rnrs))                     ;R6RS
(import (rnrs base))                ;R6RS
(import (rnrs arithmetic fixnums))  ;R6RS
(import (rnrs arithmetic flonums))  ;R6RS

✨ SYNOPSIS ✨

look at all these lil functions, they're literally a whole friend group:

(div x1 x2)
(mod x1 x2)
(div-and-mod x1 x2)
(div0 x1 x2)
(mod0 x1 x2)
(div0-and-mod0 x1 x2)
(fldiv fl1 fl2)
(flmod fl1 fl2)
(fldiv-and-mod fl1 fl2)
(fldiv0 fl1 fl2)
(flmod0 fl1 fl2)
(fldiv0-and-mod0 fl1 fl2)
(fxdiv fx1 fx2)
(fxmod fx1 fx2)
(fxdiv-and-mod fx1 fx2)
(fxdiv0 fx1 fx2)
(fxmod0 fx1 fx2)
(fxdiv0-and-mod0 fx1 fx2)

💖 DESCRIPTION 💖

these procedures implement number-theoretic integer division and return the results of the corresponding mathematical operations specified below. no cap, that's the whole assignment.

(div x1 x2)                  => x1 div x2
(mod x1 x2)                  => x1 mod x2
(div-and-mod x1 x2)
    => x1 div x2, x1 mod x2
       ; two return values
(div0 x1 x2)                 => x1 div₀ x2
(mod0 x1 x2)                 => x1 mod₀ x2
(div0-and-mod0 x1 x2 )
    => x1 div₀ x2, x1 mod₀ x2
       ; two return values

🧮 Mathematical definition 🧮

these procedures are defined in terms of the mathematical operations div, mod, div₀ and mod₀:

div, mod, div0, and mod0 each accept two real numbers x_1 and x_2 as operands, where x_2 must be nonzero. div returns an integer, and mod returns a real. Their results are specified by

x_1 div x_2 = n_d
x_1 mod x_2 = x_m

where

x_1 = n_d x_2 + x_m
  0 ≤ xm < abs(x2)

div0 and mod0 are like div and mod, except the result of mod0 lies within a half-open interval centered on zero. The results are specified by

x_1 div₀ x_2 = n_d
x_1 mod₀ x_2 = x_m

where:

        x_1 = n_d x_2 + x_m
  −abs(x_2/2) ≤ x_m < abs(x_2/2)

(a note to those who are eager to implement these procedures: the mathematical definition says essentially nothing about how to calculate the results). 💀 yeah. iconic of it honestly.

🌈 Generic variants 🌈

if x1 and x2 are exact, x2 must be nonzero.

in the cases where the mathematical requirements specified above cannot be satisfied by any number object, either an exception is raised with condition type &implementation-restriction(7scm), or unspecified number objects are returned — one for div, mod, div0 and mod0, two for div-and-mod and div0-and-mod0. yeah they just kinda hand you a mystery object. slay i guess 🙈

🧚 Fixnum variants 🧚

Fx2 must be nonzero. All arguments and return values are fixnums.

in the cases where the mathematical requirements above cannot be satisfied by any fixnum, either an exception is raised with condition type &implementation-restriction. This happens with (fxdiv (least-fixnum) -1). like it literally cannot. the math said no. 😭

🦋 Flonum variants 🦋

All arguments and return values are flonums.

in the cases where the mathematical requirements above cannot be satisfied by any flonum, either an exception is raised with condition type &implementation-restriction, or unspecified flonums are returned.

🎀 RETURN VALUES 🎀

The procedures div-and-mod and div0-and-mod0 (and their variants) return two values which are number objects. two-for-one deal, we love to see it.

The div and mod (and their variants) return a single value; a number object. just the one. lowkey humble of them.

🔥 EXAMPLES 🔥

these are the examples for the mathematical operators, and honestly the negative numbers ate:

    123 div 10 = 12
    123 mod 10 = 3
   123 div −10 = −12
   123 mod −10 = 3
   −123 div 10 = −13
   −123 mod 10 = 7
  −123 div −10 = 13
  −123 mod −10 = 7
   123 div₀ 10 = 12
   123 mod₀ 10 = 3
  123 div₀ −10 = −12
  123 mod₀ −10 = 3
  −123 div₀ 10 = −12
  −123 mod₀ 10 = −3
 −123 div₀ −10 = 12
 −123 mod₀ −10 = −3

🌸 COMPATIBILITY 🌸

These procedures are unique to R6RS. if you're looking for the same energy under different names, compatible procedures can be found in SRFI-141. iykyk 💅

💀 ERRORS 💀

this procedure can raise exceptions with the following condition types, bestie, be aware:

• &assertion (R6RS) — the wrong number of arguments was passed, or an argument was outside its domain.
• &implementation-restriction (R6RS) — there is no number object of the correct type that can represent the result under the mathematical restrictions described above.

👀 SEE ALSO 👀

quotient(3scm) — go say hi, it's family 🫶

⭐ STANDARDS ⭐

R6RS

🎀 HISTORY 🎀

These procedures first appeared in R6RS. RnRS revisions before that had /(3scm), quotient(3scm) and remainder(3scm). so like, the ancestors. respect them.

👑 AUTHORS 👑

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://github.com/schemedoc/manpages/.

---

okay that's the whole page, hope that cleared things up bestie 💖

this cutie dropped in the Scheme Programmer's Manual (that's the manual name, keeping it official), dated 2023-07-21, and yes it's still div(3scm) at the bottom because that's just where the page lives. go forth and divide. ✨