From cfcd4aa607a2e60f612292366527f71d1cf4e60a Mon Sep 17 00:00:00 2001
From: Marco Antoniotti
Date: Mon, 12 Nov 2018 22:11:31 +0100
Subject: [PATCH] Fixed a few errors and added several doc strings.
---
common-math.lisp | 326 +++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 314 insertions(+), 12 deletions(-)
diff --git a/common-math.lisp b/common-math.lisp
index f205d07..8736fb5 100644
--- a/common-math.lisp
+++ b/common-math.lisp
@@ -20,7 +20,11 @@
(format stream "Undefined operation ~S called with ~S."
(undefined-operation-operator uoc)
(undefined-operation-arguments uoc))))
- (:default-initargs :arguments () :operator nil))
+ (:default-initargs :arguments () :operator nil)
+ (:documentation "The Undefined Operation Condition.
+
+An ERROR that is generated when a give operation is not (yet) defined.")
+ )
;;; Constants and Variables
@@ -401,6 +405,17 @@ operators.
(defun + (&rest args)
+ "The + Function.
+
+Returns the sum of numbers, performing any necessary type conversions
+in the process. If no numbers are supplied, 0 is returned.
+
+Notes:
+
+This function shadows the CL:+ function, and may signal more
+error types than the TYPE-ERROR and ARITHMETIC-ERROR mentioned in the
+ANSI standard.
+"
(if (null args)
(cl:+) ; Should never happen as a recursive call.
@@ -443,6 +458,26 @@ operators.
(defun - (arg1 &rest args)
+ "The - Function.
+
+Returns the subtraction of numbers, performing any necessary type
+conversions in the process. If no numbers are supplied, 0 is
+returned.The function - performs arithmetic subtraction and negation.
+
+If only one number is supplied, the negation of that number is
+returned.
+
+If more than one argument is given, it subtracts all of the
+subtrahends from the minuend and returns the result.
+
+The function - performs necessary type conversions.
+
+Notes:
+
+This shadows the CL:- function, and may signal more error
+types than the TYPE-ERROR and ARITHMETIC-ERROR mentioned in the ANSI
+standard.
+"
(if (null args)
(-. arg1)
(if (null (cdr args))
@@ -458,6 +493,17 @@ operators.
(defun * (&rest args)
+ "The * Function.
+
+Returns the product of numbers, performing any necessary type
+conversions in the process. If no numbers are supplied, 1 is returned.
+
+Notes:
+
+This function shadows the CL:* function, and may signal more
+error types than the TYPE-ERROR and ARITHMETIC-ERROR mentioned in the
+ANSI standard.
+"
(if (null args)
(cl:*)
(cond ((null (cdr args))
@@ -483,6 +529,31 @@ operators.
(defun / (arg1 &rest args)
+ "The / Function.
+
+The function / performs division or reciprocation.
+
+If no denominators are supplied, the function / returns the reciprocal
+of number.
+
+If at least one denominator is supplied, the function / divides the
+numerator by all of the denominators and returns the resulting
+quotient.
+
+If each argument is either an integer or a ratio, and the result is
+not an integer, then it is a ratio.
+
+The function / performs necessary type conversions.
+
+If any argument is a float then the rules of floating-point contagion
+apply.
+
+Notes:
+
+This function shadows the CL:/ function, and may signal more
+error types than the TYPE-ERROR and ARITHMETIC-ERROR mentioned in the
+ANSI standard.
+"
(if (null args)
(/. arg1)
(if (null (cdr args))
@@ -498,6 +569,18 @@ operators.
(defun = (arg1 &rest args)
+ "The = Function.
+
+The value of = is true if all numbers are the same in value; otherwise
+it is false. Two complexes are considered equal by = if their real and
+imaginary parts are equal according to =.
+
+Notes:
+
+This function shadows the CL:= function, and may signal more
+error types than the TYPE-ERROR and ARITHMETIC-ERROR mentioned in the
+ANSI standard.
+"
(if (null args)
(=. arg1)
(if (null (cdr args))
@@ -513,6 +596,17 @@ operators.
(defun /= (arg1 &rest args)
+ "The /= Function.
+
+The value of /= is true if no two numbers are the same in value;
+otherwise it is false.
+
+Notes:
+
+This function shadows the CL:/= function, and may signal more
+error types than the TYPE-ERROR and ARITHMETIC-ERROR mentioned in the
+ANSI standard.
+"
(if (null args)
(/=. arg1)
(if (null (cdr args))
@@ -528,6 +622,17 @@ operators.
(defun < (arg1 &rest args)
+ "The < Function.
+
+The value of < is true if the numbers are in monotonically increasing
+order; otherwise it is false.
+
+Notes:
+
+This function shadows the CL:< function, and may signal more
+error types than the TYPE-ERROR and ARITHMETIC-ERROR mentioned in the
+ANSI standard.
+"
(if (null args)
(<. arg1)
(if (null (cdr args))
@@ -543,6 +648,17 @@ operators.
(defun <= (arg1 &rest args)
+ "The <= Function.
+
+The value of <= is true if the numbers are in monotonically nondecreasing
+order; otherwise it is false.
+
+Notes:
+
+This function shadows the CL:<= function, and may signal more
+error types than the TYPE-ERROR and ARITHMETIC-ERROR mentioned in the
+ANSI standard.
+"
(if (null args)
(<=. arg1)
(if (null (cdr args))
@@ -558,6 +674,17 @@ operators.
(defun > (arg1 &rest args)
+ "The > Function.
+
+The value of > is true if the numbers are in monotonically decreasing
+order; otherwise it is false.
+
+Notes:
+
+This function shadows the CL:> function, and may signal more
+error types than the TYPE-ERROR and ARITHMETIC-ERROR mentioned in the
+ANSI standard.
+"
(if (null args)
(>. arg1)
(if (null (cdr args))
@@ -573,6 +700,17 @@ operators.
(defun >= (arg1 &rest args)
+ "The >= Function.
+
+The value of >= is true if the numbers are in monotonically nonincreasing
+order; otherwise it is false.
+
+Notes:
+
+This function shadows the CL:>= function, and may signal more
+error types than the TYPE-ERROR and ARITHMETIC-ERROR mentioned in the
+ANSI standard.
+"
(if (null args)
(>=. arg1)
(if (null (cdr args))
@@ -591,12 +729,46 @@ operators.
;;; -------------------------------------
(defgeneric expt (base power &optional r)
+ (:documentation "The EXPT Generic Function.
+
+The EXPT function perform exponentiation.
+
+Notes:
+
+This function shadows the CL:EXPT function, and may signal more
+error types than the ERRORs mentioned in the ANSI standard.
+")
(:method ((base number) (power number) &optional r)
(declare (ignore r))
(cl:expt base power)))
+(defgeneric exp (number &optional r)
+ (:documentation "The EXP Generic Function.
+
+The EXPT function perform exponentiation.
+
+Notes:
+
+This function shadows the CL:EXP function, and may signal more
+error types than the ERRORs mentioned in the ANSI standard.
+")
+ (:method ((n number) &optional r)
+ (declare (ignore r))
+ (cl:exp n)))
+
+
(defgeneric zerop (n)
+ (:documentation "The ZEROP Generic Function.
+
+Returns true if number is zero (integer, float, or complex);
+otherwise, returns false.
+
+Notes:
+
+This generic function shadows the CL:ZEROP function, and may signal more
+error types than the TYPE-ERROR mentioned in the ANSI standard.
+")
(:method ((n number))
(cl:zerop n))
)
@@ -617,6 +789,17 @@ operators.
(defun gcd (&rest args)
+ "The GCD Function.
+
+Returns the greatest common divisor of integers. If only one integer
+is supplied, its absolute value is returned. If no integers are given,
+gcd returns 0, which is an identity for this operation.
+
+Notes:
+
+This function shadows the CL:GCD function, and may signal more
+error types than the TYPE-ERROR mentioned in the ANSI standard.
+"
(cond ((null args) (cl:gcd))
((null (cdr args)) (gcd. (first args)))
((null (cddr args)) (.gcd. (first args) (second args)))
@@ -638,6 +821,15 @@ operators.
(defun lcm (&rest args)
+ "The LCM Function.
+
+The LCM function returns the least common multiple of the integers.
+
+Notes:
+
+This function shadows the CL:LCM function, and may signal more
+error types than the TYPE-ERROR mentioned in the ANSI standard.
+"
(cond ((null args) (cl:lcm))
((null (cdr args)) (lcm. (first args)))
((null (cddr args)) (.lcm. (first args) (second args)))
@@ -645,34 +837,144 @@ operators.
(defgeneric increasing (x)
+ (:documentation "The INCREASING Generic Function.
+
+This function returns non-NIL if the argument has elements that are in
+an increasing order with respect to the < function.
+
+Methods for this generic function should respect this contract.
+")
(:method ((x sequence))
(let ((l (length x)))
(declare (type fixnum l)) ; Should be (integer 0)
- (if (cl:plusp l)
- (loop for i from 0 below (1- l)
- for a1 = (elt x 0) then a2
- for a2 = (elt x (1+ i))
- always (.<. a1 a2))
- t))))
+ (case l
+ (0 t)
+ (1 (<. (elt x 0)))
+ (t
+ (loop for i from 0 below (1- l)
+ for a1 = (elt x 0) then a2
+ for a2 = (elt x (1+ i))
+ always (.<. a1 a2))
+ ))))
+ )
+
+
+(defgeneric non-increasing (x)
+ (:documentation "The NON-INCREASING Generic Function.
+
+This function returns non-NIL if the argument has elements that are in
+an non increasing order with respect to the >= function.
+
+Methods for this generic function should respect this contract.
+")
+ (:method ((x sequence))
+ (let ((l (length x)))
+ (declare (type fixnum l)) ; Should be (integer 0)
+ (case l
+ (0 t)
+ (1 (>=. (elt x 0)))
+ (t
+ (loop for i from 0 below (1- l)
+ for a1 = (elt x 0) then a2
+ for a2 = (elt x (1+ i))
+ always (.>=. a1 a2))
+ ))))
+ )
(defgeneric decreasing (x)
+ (:documentation "The DECREASING Generic Function.
+
+This function returns non-NIL if the argument has elements that are in
+a decreasing order with respect to the > function.
+
+Methods for this generic function should respect this contract.
+")
(:method ((x sequence))
(let ((l (length x)))
(declare (type fixnum l)) ; Should be (integer 0)
- (when (cl:plusp l)
- (loop for i from 0 below (1- l)
- for a1 = (elt x 0) then a2
- for a2 = (elt x (1+ i))
- always (.>. a1 a2))))))
+ (case l
+ (0 t)
+ (1 (>. (elt x 0)))
+ (t
+ (loop for i from 0 below (1- l)
+ for a1 = (elt x 0) then a2
+ for a2 = (elt x (1+ i))
+ always (.>. a1 a2))
+ ))))
+ )
+
+
+(defgeneric non-decreasing (x)
+ (:documentation "The NON-DECREASING Generic Function.
+
+This function returns non-NIL if the argument has elements that are in
+a non decreasing order with respect to the <= function.
+
+Methods for this generic function should respect this contract.
+")
+ (:method ((x sequence))
+ (let ((l (length x)))
+ (declare (type fixnum l)) ; Should be (integer 0)
+ (case l
+ (0 t)
+ (1 (<=. (elt x 0)))
+ (t
+ (loop for i from 0 below (1- l)
+ for a1 = (elt x 0) then a2
+ for a2 = (elt x (1+ i))
+ always (.<=. a1 a2))
+ ))))
+ )
+
+
+(defgeneric sorted (x &key test)
+ (:documentation "The SORTED Generic Function.
+
+This function returns non-NIL if the argument has elements that are
+sorted in order with respect to the TEST.
+")
+ (:method ((x sequence) &key (test #'<))
+ (let ((l (length x)))
+ (declare (type fixnum l)) ; Should be (integer 0)
+ (case l
+ (0 t)
+ (1 (funcall test (elt x 0)))
+ (t
+ (loop for i from 0 below (1- l)
+ for a1 = (elt x 0) then a2
+ for a2 = (elt x (1+ i))
+ always (funcall test a1 a2))
+ ))))
+ )
(defgeneric plusp (x)
+ (:documentation "The PLUSP Generic Function.
+
+Returns true if the argument is greater than zero; otherwise, returns
+false.
+
+Notes:
+
+This function shadows the CL:PLUS function, and may signal more
+error types than the TYPE-ERROR mentioned in the ANSI standard.
+")
(:method ((x real)) (cl:plusp x))
)
(defgeneric minusp (x)
+ (:documentation "The PLUSP Generic Function.
+
+Returns true if the argument is less than zero; otherwise, returns
+false.
+
+Notes:
+
+This function shadows the CL:MINUSP function, and may signal more
+error types than the TYPE-ERROR mentioned in the ANSI standard.
+")
(:method ((x real)) (cl:minusp x))
)
--
2.18.1