From 2111f61524e5fbdf843950de60740f3a15b5274f Mon Sep 17 00:00:00 2001
From: colin <colin@cicadas.surf>
Date: Tue, 18 Jun 2024 08:47:42 -0700
Subject: Fix: docstring in def:fast; update readme

---
 README.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index bfe785c..418f3da 100644
--- a/README.md
+++ b/README.md
@@ -64,3 +64,39 @@ The above would expand out into
       (:DOCUMENTATION "A point in real 3d space"))
       
 See `def:class`'s docstring for details.
+
+## `def:fast` 
+
+Common Lisp compilers like SBCL can produce extremely fast code
+... if, that is, you help them out a little.  
+
+Declaring types and `optimize` declare expressions can be a little
+verbose and irritating to add to every function that you want to be
+fast.  
+
+`def:fast` lightens some of the typing load by embedding types inside
+the lambda list, and by declaring the return type of functions.  E.g.:
+
+
+    (defun list-of-fixnum-p (xs)
+      (and (listp xs) (every #'sb-int:fixnump xs)))
+    
+    (deftype list-of-fixnum ()
+      '(satisfies list-of-fixnum-p))
+    
+    (def:fast sum-fixnum ((x fixnum) (y fixnum) &rest (xs list-of-fixnum)) -> fixnum
+      "Sums fixnums"
+      (+ x y (reduce #'+ xs)))
+    
+
+The above expands into
+
+    (DEFUN SUM-FIXNUM (X Y &REST XS)
+      "Sums fixnums"
+      (DECLARE (TYPE LIST-OF-FIXNUM XS)
+               (TYPE FIXNUM Y X)
+               (VALUES FIXNUM)
+               (OPTIMIZE (SPEED 3) (SAFETY 0)))
+      (+ x y (REDUCE #'+ XS)))
+    
+    
-- 
cgit v1.2.3