feat: add ratio reducer

Author: fosskers

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 #### Added
 
+- Reducer: `ratio` for the percentage of items that pass a predicate.
 - Source: `chain` to compose any number of Generators.
 - Source: The `generator` type and its functions have been exposed so that
   others can write their own Generators.

README.org

@@ -69,7 +69,7 @@ Looking for Transducers in other Lisps? Check out the [[https://github.com/fossk
     - [[#string-base-string][string, base-string]]
     - [[#hash-table][hash-table]]
     - [[#count-quantities][count, quantities]]
-    - [[#average-median][average, median]]
+    - [[#average-median-ratio][average, median, ratio]]
     - [[#any-all][any?, all?]]
     - [[#partition][partition]]
     - [[#first-last-find][first, last, find]]
@@ -750,9 +750,9 @@ predicate.
 #+RESULTS:
 : #<COMMON-LISP:HASH-TABLE :TEST EQL :COUNT 5 {10094FE823}>
 
-*** average, median
+*** average, median, ratio
 
-Calculate the average value of all numeric elements in a transduction.
+=average=: Calculate the average value of all numeric elements in a transduction.
 
 #+begin_src lisp :exports both
 (in-package :transducers)
@@ -762,9 +762,9 @@ Calculate the average value of all numeric elements in a transduction.
 #+RESULTS:
 : 7/2
 
-Calculate the median value of all elements in a transduction, provided that they
-are numbers, strings, or characters. The elements are sorted once before the
-median is extracted.
+=median=: Calculate the median value of all elements in a transduction, provided
+that they are numbers, strings, or characters. The elements are sorted once
+before the median is extracted.
 
 #+begin_src lisp :exports both
 (in-package :transducers)
@@ -774,6 +774,17 @@ median is extracted.
 #+RESULTS:
 : 1
 
+=ratio=: The percentage of items that satisfied a predicate. The final value will
+always be between 0 and 1.
+
+#+begin_src lisp :exports both
+(in-package :transducers)
+(transduce #'pass (ratio #'evenp) #(1 2 3 4 5 6))
+#+end_src
+
+#+RESULTS:
+: 1/2
+
 *** any?, all?
 
 Yield =t= if any element in the transduction satisfies PRED. Short-circuits the

transducers/package.lisp

@@ -3,7 +3,7 @@
   (:shadow #:map #:concatenate #:log #:step #:split
            #:string #:base-string #:vector #:bit-vector #:hash-table
            #:cons #:count #:first #:last #:max #:min #:find
-           #:random)
+           #:random #:ratio)
   ;; --- Entry Points --- ;;
   (:export #:transduce)
   ;; --- Transducers -- ;;

transducers/reducers.lisp

@@ -134,6 +134,30 @@ The elements are sorted once before the median is extracted.
 #+nil
 (transduce (filter #'evenp) #'average '(1 3 5))
 
+(defun ratio (pred)
+  "Reducer: The percentage of items that satisfied a predicate. The final value
+will always be between 0 and 1.
+
+# Conditions
+
+- `empty-transduction': when no values made it through the transduction."
+  (lambda (&optional (acc nil a?) (input nil i?))
+    (cond ((and a? i?)
+           (incf (avg-count acc))
+           (when (funcall pred input)
+             (incf (avg-total acc)))
+           acc)
+          ((and a? (not i?))
+           (if (zerop (avg-count acc))
+               (error 'empty-transduction :msg "`ratio' called on an empty transduction.")
+               (/ (avg-total acc) (avg-count acc))))
+          (t (make-avg :count 0 :total 0)))))
+
+#+nil
+(transduce #'pass (ratio #'evenp) #(1 2 3 4 5 6))
+#+nil
+(transduce #'pass (ratio #'evenp) #())
+
 (declaim (ftype (function ((function (t) *)) *) any?))
 (defun any? (pred)
   "Reducer: Yield t if any element in the transduction satisfies PRED.