.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "elvish-math" "7" "Feb 25, 2023" "Elvish 0.18.0" "Miscellaneous Information Manual"
.hy
.PP
.SH Introduction
.PP
The \f[V]math:\f[R] module provides mathematical functions and
constants.
.PP
Function usages are given in the same format as in the reference doc for
the builtin module.
In particular, all the commands in this module conform to the convention
of numeric commands.
.SH Variables
.PP
.SS $math:e {#math:e}
.IP
.nf
\f[C]
$math:e
\f[R]
.fi
.PP
Approximate value of
\f[V]e\f[R] (https://en.wikipedia.org/wiki/E_(mathematical_constant)):
2.718281\&....
This variable is read-only.
.PP
.SS $math:pi {#math:pi}
.IP
.nf
\f[C]
$math:pi
\f[R]
.fi
.PP
Approximate value of \f[V]\[*p]\f[R] (https://en.wikipedia.org/wiki/Pi):
3.141592\&....
This variable is read-only.
.SH Functions
.PP
.SS math:abs {#math:abs}
.IP
.nf
\f[C]
math:abs $number
\f[R]
.fi
.PP
Computes the absolute value \f[V]$number\f[R].
This function is exactness-preserving.
Examples:
.IP
.nf
\f[C]
\[ti]> math:abs 2
\[u25B6] (num 2)
\[ti]> math:abs -2
\[u25B6] (num 2)
\[ti]> math:abs 10000000000000000000
\[u25B6] (num 10000000000000000000)
\[ti]> math:abs -10000000000000000000
\[u25B6] (num 10000000000000000000)
\[ti]> math:abs 1/2
\[u25B6] (num 1/2)
\[ti]> math:abs -1/2
\[u25B6] (num 1/2)
\[ti]> math:abs 1.23
\[u25B6] (num 1.23)
\[ti]> math:abs -1.23
\[u25B6] (num 1.23)
\f[R]
.fi
.PP
.SS math:acos {#math:acos}
.IP
.nf
\f[C]
math:acos $number
\f[R]
.fi
.PP
Outputs the arccosine of \f[V]$number\f[R], in radians (not degrees).
Examples:
.IP
.nf
\f[C]
\[ti]> math:acos 1
\[u25B6] (float64 1)
\[ti]> math:acos 1.00001
\[u25B6] (float64 NaN)
\f[R]
.fi
.PP
.SS math:acosh {#math:acosh}
.IP
.nf
\f[C]
math:acosh $number
\f[R]
.fi
.PP
Outputs the inverse hyperbolic cosine of \f[V]$number\f[R].
Examples:
.IP
.nf
\f[C]
\[ti]> math:acosh 1
\[u25B6] (float64 0)
\[ti]> math:acosh 0
\[u25B6] (float64 NaN)
\f[R]
.fi
.PP
.SS math:asin {#math:asin}
.IP
.nf
\f[C]
math:asin $number
\f[R]
.fi
.PP
Outputs the arcsine of \f[V]$number\f[R], in radians (not degrees).
Examples:
.IP
.nf
\f[C]
\[ti]> math:asin 0
\[u25B6] (float64 0)
\[ti]> math:asin 1
\[u25B6] (float64 1.5707963267948966)
\[ti]> math:asin 1.00001
\[u25B6] (float64 NaN)
\f[R]
.fi
.PP
.SS math:asinh {#math:asinh}
.IP
.nf
\f[C]
math:asinh $number
\f[R]
.fi
.PP
Outputs the inverse hyperbolic sine of \f[V]$number\f[R].
Examples:
.IP
.nf
\f[C]
\[ti]> math:asinh 0
\[u25B6] (float64 0)
\[ti]> math:asinh inf
\[u25B6] (float64 +Inf)
\f[R]
.fi
.PP
.SS math:atan {#math:atan}
.IP
.nf
\f[C]
math:atan $number
\f[R]
.fi
.PP
Outputs the arctangent of \f[V]$number\f[R], in radians (not degrees).
Examples:
.IP
.nf
\f[C]
\[ti]> math:atan 0
\[u25B6] (float64 0)
\[ti]> math:atan $math:inf
\[u25B6] (float64 1.5707963267948966)
\f[R]
.fi
.PP
.SS math:atanh {#math:atanh}
.IP
.nf
\f[C]
math:atanh $number
\f[R]
.fi
.PP
Outputs the inverse hyperbolic tangent of \f[V]$number\f[R].
Examples:
.IP
.nf
\f[C]
\[ti]> math:atanh 0
\[u25B6] (float64 0)
\[ti]> math:atanh 1
\[u25B6] (float64 +Inf)
\f[R]
.fi
.PP
.SS math:ceil {#math:ceil}
.IP
.nf
\f[C]
math:ceil $number
\f[R]
.fi
.PP
Computes the least integer greater than or equal to \f[V]$number\f[R].
This function is exactness-preserving.
.PP
The results for the special floating-point values -0.0, +0.0, -Inf, +Inf
and NaN are themselves.
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> math:floor 1
\[u25B6] (num 1)
\[ti]> math:floor 3/2
\[u25B6] (num 1)
\[ti]> math:floor -3/2
\[u25B6] (num -2)
\[ti]> math:floor 1.1
\[u25B6] (num 1.0)
\[ti]> math:floor -1.1
\[u25B6] (num -2.0)
\f[R]
.fi
.PP
.SS math:cos {#math:cos}
.IP
.nf
\f[C]
math:cos $number
\f[R]
.fi
.PP
Computes the cosine of \f[V]$number\f[R] in units of radians (not
degrees).
Examples:
.IP
.nf
\f[C]
\[ti]> math:cos 0
\[u25B6] (float64 1)
\[ti]> math:cos 3.14159265
\[u25B6] (float64 -1)
\f[R]
.fi
.PP
.SS math:cosh {#math:cosh}
.IP
.nf
\f[C]
math:cosh $number
\f[R]
.fi
.PP
Computes the hyperbolic cosine of \f[V]$number\f[R].
Example:
.IP
.nf
\f[C]
\[ti]> math:cosh 0
\[u25B6] (float64 1)
\f[R]
.fi
.PP
.SS math:floor {#math:floor}
.IP
.nf
\f[C]
math:floor $number
\f[R]
.fi
.PP
Computes the greatest integer less than or equal to \f[V]$number\f[R].
This function is exactness-preserving.
.PP
The results for the special floating-point values -0.0, +0.0, -Inf, +Inf
and NaN are themselves.
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> math:floor 1
\[u25B6] (num 1)
\[ti]> math:floor 3/2
\[u25B6] (num 1)
\[ti]> math:floor -3/2
\[u25B6] (num -2)
\[ti]> math:floor 1.1
\[u25B6] (num 1.0)
\[ti]> math:floor -1.1
\[u25B6] (num -2.0)
\f[R]
.fi
.PP
.SS math:is-inf {#math:is-inf}
.IP
.nf
\f[C]
math:is-inf &sign=0 $number
\f[R]
.fi
.PP
Tests whether the number is infinity.
If sign > 0, tests whether \f[V]$number\f[R] is positive infinity.
If sign < 0, tests whether \f[V]$number\f[R] is negative infinity.
If sign == 0, tests whether \f[V]$number\f[R] is either infinity.
.IP
.nf
\f[C]
\[ti]> math:is-inf 123
\[u25B6] $false
\[ti]> math:is-inf inf
\[u25B6] $true
\[ti]> math:is-inf -inf
\[u25B6] $true
\[ti]> math:is-inf &sign=1 inf
\[u25B6] $true
\[ti]> math:is-inf &sign=-1 inf
\[u25B6] $false
\[ti]> math:is-inf &sign=-1 -inf
\[u25B6] $true
\f[R]
.fi
.PP
.SS math:is-nan {#math:is-nan}
.IP
.nf
\f[C]
math:is-nan $number
\f[R]
.fi
.PP
Tests whether the number is a NaN (not-a-number).
.IP
.nf
\f[C]
\[ti]> math:is-nan 123
\[u25B6] $false
\[ti]> math:is-nan (float64 inf)
\[u25B6] $false
\[ti]> math:is-nan (float64 nan)
\[u25B6] $true
\f[R]
.fi
.PP
.SS math:log {#math:log}
.IP
.nf
\f[C]
math:log $number
\f[R]
.fi
.PP
Computes the natural (base \f[I]e\f[R]) logarithm of \f[V]$number\f[R].
Examples:
.IP
.nf
\f[C]
\[ti]> math:log 1.0
\[u25B6] (float64 1)
\[ti]> math:log -2.3
\[u25B6] (float64 NaN)
\f[R]
.fi
.PP
.SS math:log10 {#math:log10}
.IP
.nf
\f[C]
math:log10 $number
\f[R]
.fi
.PP
Computes the base 10 logarithm of \f[V]$number\f[R].
Examples:
.IP
.nf
\f[C]
\[ti]> math:log10 100.0
\[u25B6] (float64 2)
\[ti]> math:log10 -1.7
\[u25B6] (float64 NaN)
\f[R]
.fi
.PP
.SS math:log2 {#math:log2}
.IP
.nf
\f[C]
math:log2 $number
\f[R]
.fi
.PP
Computes the base 2 logarithm of \f[V]$number\f[R].
Examples:
.IP
.nf
\f[C]
\[ti]> math:log2 8
\[u25B6] (float64 3)
\[ti]> math:log2 -5.3
\[u25B6] (float64 NaN)
\f[R]
.fi
.PP
.SS math:max {#math:max}
.IP
.nf
\f[C]
math:max $number...
\f[R]
.fi
.PP
Outputs the maximum number in the arguments.
If there are no arguments, an exception is thrown.
If any number is NaN then NaN is output.
This function is exactness-preserving.
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> math:max 3 5 2
\[u25B6] (num 5)
\[ti]> math:max (range 100)
\[u25B6] (num 99)
\[ti]> math:max 1/2 1/3 2/3
\[u25B6] (num 2/3)
\f[R]
.fi
.PP
.SS math:min {#math:min}
.IP
.nf
\f[C]
math:min $number...
\f[R]
.fi
.PP
Outputs the minimum number in the arguments.
If there are no arguments an exception is thrown.
If any number is NaN then NaN is output.
This function is exactness-preserving.
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> math:min
Exception: arity mismatch: arguments must be 1 or more values, but is 0 values
[tty 17], line 1: math:min
\[ti]> math:min 3 5 2
\[u25B6] (num 2)
\[ti]> math:min 1/2 1/3 2/3
\[u25B6] (num 1/3)
\f[R]
.fi
.PP
.SS math:pow {#math:pow}
.IP
.nf
\f[C]
math:pow $base $exponent
\f[R]
.fi
.PP
Outputs the result of raising \f[V]$base\f[R] to the power of
\f[V]$exponent\f[R].
.PP
This function produces an exact result when \f[V]$base\f[R] is exact and
\f[V]$exponent\f[R] is an exact integer.
Otherwise it produces an inexact result.
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> math:pow 3 2
\[u25B6] (num 9)
\[ti]> math:pow -2 2
\[u25B6] (num 4)
\[ti]> math:pow 1/2 3
\[u25B6] (num 1/8)
\[ti]> math:pow 1/2 -3
\[u25B6] (num 8)
\[ti]> math:pow 9 1/2
\[u25B6] (num 3.0)
\[ti]> math:pow 12 1.1
\[u25B6] (num 15.38506624784179)
\f[R]
.fi
.PP
.SS math:round {#math:round}
.IP
.nf
\f[C]
math:round $number
\f[R]
.fi
.PP
Outputs the nearest integer, rounding half away from zero.
This function is exactness-preserving.
.PP
The results for the special floating-point values -0.0, +0.0, -Inf, +Inf
and NaN are themselves.
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> math:round 2
\[u25B6] (num 2)
\[ti]> math:round 1/3
\[u25B6] (num 0)
\[ti]> math:round 1/2
\[u25B6] (num 1)
\[ti]> math:round 2/3
\[u25B6] (num 1)
\[ti]> math:round -1/3
\[u25B6] (num 0)
\[ti]> math:round -1/2
\[u25B6] (num -1)
\[ti]> math:round -2/3
\[u25B6] (num -1)
\[ti]> math:round 2.5
\[u25B6] (num 3.0)
\f[R]
.fi
.PP
.SS math:round-to-even {#math:round-to-even}
.IP
.nf
\f[C]
math:round-to-even $number
\f[R]
.fi
.PP
Outputs the nearest integer, rounding ties to even.
This function is exactness-preserving.
.PP
The results for the special floating-point values -0.0, +0.0, -Inf, +Inf
and NaN are themselves.
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> math:round-to-even 2
\[u25B6] (num 2)
\[ti]> math:round-to-even 1/2
\[u25B6] (num 0)
\[ti]> math:round-to-even 3/2
\[u25B6] (num 2)
\[ti]> math:round-to-even 5/2
\[u25B6] (num 2)
\[ti]> math:round-to-even -5/2
\[u25B6] (num -2)
\[ti]> math:round-to-even 2.5
\[u25B6] (num 2.0)
\[ti]> math:round-to-even 1.5
\[u25B6] (num 2.0)
\f[R]
.fi
.PP
.SS math:sin {#math:sin}
.IP
.nf
\f[C]
math:sin $number
\f[R]
.fi
.PP
Computes the sine of \f[V]$number\f[R] in units of radians (not
degrees).
Examples:
.IP
.nf
\f[C]
\[ti]> math:sin 0
\[u25B6] (float64 0)
\[ti]> math:sin 3.14159265
\[u25B6] (float64 3.5897930298416118e-09)
\f[R]
.fi
.PP
.SS math:sinh {#math:sinh}
.IP
.nf
\f[C]
math:sinh $number
\f[R]
.fi
.PP
Computes the hyperbolic sine of \f[V]$number\f[R].
Example:
.IP
.nf
\f[C]
\[ti]> math:sinh 0
\[u25B6] (float64 0)
\f[R]
.fi
.PP
.SS math:sqrt {#math:sqrt}
.IP
.nf
\f[C]
math:sqrt $number
\f[R]
.fi
.PP
Computes the square-root of \f[V]$number\f[R].
Examples:
.IP
.nf
\f[C]
\[ti]> math:sqrt 0
\[u25B6] (float64 0)
\[ti]> math:sqrt 4
\[u25B6] (float64 2)
\[ti]> math:sqrt -4
\[u25B6] (float64 NaN)
\f[R]
.fi
.PP
.SS math:tan {#math:tan}
.IP
.nf
\f[C]
math:tan $number
\f[R]
.fi
.PP
Computes the tangent of \f[V]$number\f[R] in units of radians (not
degrees).
Examples:
.IP
.nf
\f[C]
\[ti]> math:tan 0
\[u25B6] (float64 0)
\[ti]> math:tan 3.14159265
\[u25B6] (float64 -0.0000000035897930298416118)
\f[R]
.fi
.PP
.SS math:tanh {#math:tanh}
.IP
.nf
\f[C]
math:tanh $number
\f[R]
.fi
.PP
Computes the hyperbolic tangent of \f[V]$number\f[R].
Example:
.IP
.nf
\f[C]
\[ti]> math:tanh 0
\[u25B6] (float64 0)
\f[R]
.fi
.PP
.SS math:trunc {#math:trunc}
.IP
.nf
\f[C]
math:trunc $number
\f[R]
.fi
.PP
Outputs the integer portion of \f[V]$number\f[R].
This function is exactness-preserving.
.PP
The results for the special floating-point values -0.0, +0.0, -Inf, +Inf
and NaN are themselves.
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> math:trunc 1
\[u25B6] (num 1)
\[ti]> math:trunc 3/2
\[u25B6] (num 1)
\[ti]> math:trunc 5/3
\[u25B6] (num 1)
\[ti]> math:trunc -3/2
\[u25B6] (num -1)
\[ti]> math:trunc -5/3
\[u25B6] (num -1)
\[ti]> math:trunc 1.7
\[u25B6] (num 1.0)
\[ti]> math:trunc -1.7
\[u25B6] (num -1.0)
\f[R]
.fi