; Copyright (c) Rich Hickey. All rights reserved.

(ns

^{:author "David Miller",

:doc "Clojure wrapper functions for System.Math static methods.

https://docs.microsoft.com/en-us/dotnet/api/system.math?view=net-6.0"}

clojure.math)

(set! *warn-on-reflection* true)

;;; I followed the overall style of clojure.java.math, but the java.lang.math and System.Math do not have the same methods defined.

;;; Given that this is about giving performant access, I stuck with matching what is in System.Math.

;;; Generally, System.Math has a lot more overloads; nevertheless, java.lang.math does have some overloads.

;;; clojure.java.math deals with overloads as follows:

;;; (i) if a method is overloaded for double vs float args only, then a double version is typed.

;;; (ii) if a method is overloaded for long vs int args only, then a long version is typed.

;;; (iii) the serveral methods that have multiple overloads, such as min, max, and max, are not included here. they are handled in Numbers.

;;;

;;; Note that (i) and (ii) are quite reasonble given generally that int and float values get widened to long/double.

;;;

;;; The System.Math package generally has a lot more overloads.

;;; We follow all three rules listed above.

;;; There are still some cases that are not dealt with by those rules.

;;;

;;; The following have overloads for double and decimal:

;;; Ceiling

;;; Floor

;;; Round

;;; Truncate

;;; I have provided implementations for double arguments only.

;;;

;;; The following have many overloads:

;;; Clamp (13 overloads)

;;; Sign (8 overloads)

;;;

;;; I have decided to pick just a few, using the suffixes Long and Double, i.e.

;;; clamp-long, clamp-double, sign-long, sign-double.

;;;

;;; I have left out DivRem and BigMul because of the out parameters. Inlining problematic for those.

(def

^{:doc "Constant for e, the base for natural logarithms.

:added "1.11"

:const true

:tag 'double}

E

Math/E)

(def

^{:doc "Constant for pi, the ratio of the circumference of a circle to its diameter.

:added "1.11"

:const true

:tag 'double}

PI

Math/PI)

(compile-when (>= (:major dotnet-version) 5)

(def

^{:doc "Constant for tau, the number of radians in one turn.

:added "1.11"

:const true

:tag 'double}

Tau

Math/Tau)

) ;; compile-when

(defn sin

{:doc "Returns the sine of the specified angle.

:inline-arities #{1}

:inline (fn [a] `(Math/Sin (double ~a)))

:added "1.11"}

^double [^double a]

(Math/Sin a))

(defn cos

{:doc "Returns the cosine of the specified angle.

:inline-arities #{1}

:inline (fn [a] `(Math/Cos (double ~a)))

:added "1.11"}

^double [^double a]

(Math/Cos a))

(defn tan

{:doc "Returns the tangent of the specified angle.

:inline-arities #{1}

:inline (fn [a] `(Math/Tan (double ~a)))

:added "1.11"}

^double [^double a]

(Math/Tan a))

(defn asin

{:doc "Returns the arc sine of an angle, in the range -pi/2 to pi/2.

:inline-arities #{1}

:inline (fn [a] `(Math/Asin (double ~a)))

:added "1.11"}

^double [^double a]

(Math/Asin a))

(defn acos

{:doc "Returns the arc cosine of a, in the range 0.0 to pi.

:inline-arities #{1}

:inline (fn [a] `(Math/Acos (double ~a)))

:added "1.11"}

^double [^double a]

(Math/Acos a))

(defn atan

{:doc "Returns the arc tangent of a, in the range of -pi/2 to pi/2.

:inline-arities #{1}

:inline (fn [a] `(Math/Atan (double ~a)))

:added "1.11"}

^double [^double a]

(Math/Atan a))

(defn atan2

{:doc "Returns the angle theta from the conversion of rectangular coordinates (x, y) to polar coordinates (r, theta).

:inline-arities #{2}

:inline (fn [y x] `(Math/Atan2 (double ~y) (double ~x)))

:added "1.11"}

^double [^double y ^double x]

(Math/Atan2 y x))

;;; hyperbolic functions

(defn sinh

{:doc "Returns the hyperbolic sine of x, (e^x - e^-x)/2.

:inline-arities #{1}

:inline (fn [x] `(Math/Sinh (double ~x)))

:added "1.11"}

^double [^double x]

(Math/Sinh x))

(defn cosh

{:doc "Returns the hyperbolic cosine of x, (e^x + e^-x)/2.

:inline-arities #{1}

:inline (fn [x] `(Math/Cosh (double ~x)))

:added "1.11"}

^double [^double x]

(Math/Cosh x))

(defn tanh

{:doc "Returns the hyperbolic tangent of x, sinh(x)/cosh(x).

:inline-arities #{1}

:inline (fn [x] `(Math/Tanh (double ~x)))

:added "1.11"}

^double [^double x]

(Math/Tanh x))

(compile-when (contains? #{:dotnet :core} dotnet-platform)

(defn asinh

{:doc "Returns the angle whose hyperbolic sine is the specified number.

:inline-arities #{1}

:inline (fn [x] `(Math/Asinh (double ~x)))

:added "1.11"}

^double [^double x]

(Math/Asinh x))

(defn acosh

{:doc "Returns the angle whose hyperbolic cosine is the specified number.

:inline-arities #{1}

:inline (fn [x] `(Math/Acosh (double ~x)))

:added "1.11"}

^double [^double x]

(Math/Acosh x))

(defn atanh

{:doc "Returns the angle whose hyperbolic tangent is the specified number.

:inline-arities #{1}

:inline (fn [x] `(Math/Atanh (double ~x)))

:added "1.11"}

^double [^double x]

(Math/Atanh x))

) ;; compile-when

(defn exp

{:doc "Returns Euler's number e raised to the power of a.

:inline-arities #{1}

:inline (fn [a] `(Math/Exp (double ~a)))

:added "1.11"}

^double [^double a]

(Math/Exp a))

(defn log

{:doc "Returns the natural logarithm (base e) of a, or in the specified base.

:inline-arities #{1 2}

:inline (fn [a & args] `(Math/Log (double ~a) ~@args))

:added "1.11"}

(^double [^double a] (Math/Log a))

(^double [^double a b] (Math/Log a b)))

(defn log10

{:doc "Returns the logarithm (base 10) of a.

:inline-arities #{1}

:inline (fn [a] `(Math/Log10 (double ~a)))

:added "1.11"}

^double [^double a]

(Math/Log10 a))

(compile-when (contains? #{:dotnet :core} dotnet-platform)

(defn log2

{:doc "Returns the logarithm (base 2) of a.

:inline-arities #{1}

:inline (fn [a] `(Math/Log2 (double ~a)))

:added "1.11"}

^double [^double a]

(Math/Log2 a))

(defn ilogb

{:doc "Returns the base 2 integer logarithm of a specified number.

:inline-arities #{1}

:inline (fn [a] `(Math/ILogB (double ~a)))

:added "1.11"}

[^double a]

(Math/ILogB a))

) ;; compile-when

(defn sqrt

{:doc "Returns the positive square root of a.

:inline-arities #{1}

:inline (fn [a] `(Math/Sqrt (double ~a)))

:added "1.11"}

^double [^double a]

(Math/Sqrt a))

(compile-when (contains? #{:dotnet :core} dotnet-platform)

(defn cbrt

{:doc "Returns the cube root of a.

:inline-arities #{1}

:inline (fn [a] `(Math/Cbrt (double ~a)))

:added "1.11"}

^double [^double a]

(Math/Cbrt a))

) ;; compile-when

(defn pow

{:doc "Returns the value of a raised to the power of b.

:inline-arities #{2}

:inline (fn [a b] `(Math/Pow (double ~a) (double ~b)))

:added "1.11"}

^double [^double a ^double b]

(Math/Pow a b))

;;; Division, remainder, rounding, etc.

(defn IEEE-remainder

{:doc "A number equal to x - (y Q), where Q is the quotient of x / y rounded to the nearest integer.

:inline-arities #{2}

:inline (fn [dividend divisor] `(Math/IEEERemainder (double ~dividend) (double ~divisor)))

:added "1.11"}

^double [^double dividend ^double divisor]

(Math/IEEERemainder dividend divisor))

(defn ceiling

{:doc "Returns the smallest integral value greater than or equal to the specified number.

:inline-arities #{1}

:inline (fn [a] `(Math/Ceiling (double ~a)))

:added "1.11"}

^double [^double a]

(Math/Ceiling a))

(defn floor

{:doc "Returns the largest integral value less than or equal to the specified number.

:inline-arities #{1}

:inline (fn [a] `(Math/Floor (double ~a)))

:added "1.11"}

^double [^double a]

(Math/Floor a))

(defn round

{:doc "Rounds a value to the nearest integer or to the specified number of fractional digits.

:inline-arities #{1 2 3}

:inline (fn [a & args] `(Math/Round (double ~a) ~@args))

:added "1.11"}

(^double [^double a] (Math/Round a))

(^double [^double a b] (Math/Round a (int b)))

(^double [^double a b c] (Math/Round a (int b) ^System.MidpointRounding c)))

(defn truncate

{:doc "Integer division that rounds to negative infinity (as opposed to zero).

:inline-arities #{1}

:inline (fn [x] `(Math/Truncate (double ~x)))

:added "1.11"}

^double [^double x]

(Math/Truncate x))

(compile-when (contains? #{:dotnet :core} dotnet-platform)

(defn scaleb

{:doc "Returns d * 2^scaleFactor, scaling by a factor of 2.

:inline-arities #{2}

:inline (fn [d scaleFactor] `(Math/ScaleB (double ~d) (int ~scaleFactor)))

:added "1.11"}

^double [^double d scaleFactor]

(Math/ScaleB d scaleFactor))

) ;; compile-when

;;; abs, max,min and related

;;; abs, min, max implemented math-polymorphically in clojure.lang.Numbers

(defn sign-long

{:doc "Returns an integer that indicates the sign of a number.

:inline-arities #{1}

:inline (fn [d] `(Math/Sign (long ~d)))

:added "1.11"}

[^long d]

(Math/Sign d))

(defn sign-double

{:doc "Returns an integer that indicates the sign of a number.

:inline-arities #{1}

:inline (fn [d] `(Math/Sign (double ~d)))

:added "1.11"}

[^double d]

(Math/Sign d))

(compile-when (contains? #{:dotnet :core} dotnet-platform)

(defn max-magnitude

{:doc "Returns the larger magnitude of two double-precision floating-point numbers.

:inline-arities #{2}

:inline (fn [a b] `(Math/MaxMagnitude (double ~a) (double ~b)))

:added "1.11"}

^double [^double a ^double b]

(Math/MaxMagnitude a b))

(defn min-magnitude

{:doc "Returns the smaller magnitude of two double-precision floating-point numbers.

:inline-arities #{2}

:inline (fn [a b] `(Math/MinMagnitude (double ~a) (double ~b)))

:added "1.11"}

^double [^double a ^double b]

(Math/MinMagnitude a b))

(defn clamp-long

{:doc "Returns value clamped to the inclusive range of min and max.

:inline-arities #{3}

:inline (fn [a b c] `(Math/Clamp (long ~a) (long ~b) (long ~c)))

:added "1.11"}

^long [^long val ^long min ^long max]

(Math/Clamp val min max))

(defn clamp-double

{:doc "Returns value clamped to the inclusive range of min and max.

:inline-arities #{3}

:inline (fn [a b c] `(Math/Clamp (double ~a) (double ~b) (double ~c)))

:added "1.11"}

^double [^double val ^double min ^double max]

(Math/Clamp val min max))

(defn copy-sign

{:doc "Returns a double with the magnitude of the first argument and the sign of

:inline-arities #{2}

:inline (fn [magnitude sign] `(Math/CopySign (double ~magnitude) (double ~sign)))

:added "1.11"}

^double [^double magnitude ^double sign]

(Math/CopySign magnitude sign))

(defn bit-decrement

{:doc "Returns the next smallest value that compares less than d.

:inline-arities #{1}

:inline (fn [d] `(Math/BitDecrement (double ~d)))

:added "1.11"}

^double [^double d]

(Math/BitDecrement d))

(defn bit-increment

{:doc "Returns the next largest value that compares greater than d.

:inline-arities #{1}

:inline (fn [d] `(Math/BitIncrement (double ~d)))

:added "1.11"}

^double [^double d]

(Math/BitIncrement d))

(defn fused-multiply-add

{:doc "Returns (x * y) + z, rounded as one ternary operation.

:inline-arities #{3}

:inline (fn [x y z] `(Math/FusedMultiplyAdd (double ~x) (double ~y) (double ~z)))

:added "1.11"}

^double [^double x ^double y ^double z]

(Math/FusedMultiplyAdd x y z))

) ;; compile-when

(compile-when (>= (:major dotnet-version) 6)

(defn reciprocal-estimate

{:doc "Returns an estimate of the reciprocal of a specified number.

:inline-arities #{1}

:inline (fn [a] `(Math/ReciprocalEstimate (double ~a)))

:added "1.11"}

^double [^double a]

(Math/ReciprocalEstimate a))

(defn reciprocal-sqrt-estimate

{:doc "Returns an estimate of the reciprocal square root of a specified number.

:inline-arities #{1}

:inline (fn [a] `(Math/ReciprocalSqrtEstimate (double ~a)))

:added "1.11"}

^double [^double a]

(Math/ReciprocalSqrtEstimate a))

) ;; compile-when