From 933a3f8fa70f5c7746ac5c438140192c5c93a0e7 Mon Sep 17 00:00:00 2001
From: Colin Okay <cbeok@protonmail.com>
Date: Wed, 8 Jul 2020 13:33:25 -0500
Subject: docstring for merge!

---
 gtwiwtg.lisp | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

(limited to 'gtwiwtg.lisp')

diff --git a/gtwiwtg.lisp b/gtwiwtg.lisp
index c273680..88e820c 100644
--- a/gtwiwtg.lisp
+++ b/gtwiwtg.lisp
@@ -427,6 +427,26 @@ CONCAT! MODIFIES AND RETURNS ITS FIRST ARGUMENT."
 
 
 (defun merge! (comparator gen1 gen2 &rest gens)
+  "Emulates the behavior of MERGE (in the ANSI standard), but for generators.
+
+The emulation is not perfect, but it holds in the following sense: If
+all the inputs are sorted according to COMPARATOR then the output will
+also be sorted according to COMPARATOR.
+
+The generator created through a merge has a length that is maximal
+among the lengths of the arguments to MERGE!. Hence, if any of the
+arguments is an infinite generator, then the merged generator is also
+infinite.
+
+An example:
+
+> (collect (merge! #'< 
+                  (times 4) 
+                  (range :from 4 :to 10 :by 2)
+                  (range :from -10 :to 28 :by 6)))
+
+ (-10 -4 0 1 2 2 3 4 6 8 8 14 20 26)
+"
   (let ((all-gens (list* gen1 gen2 gens)))
 
     (assert (all-good all-gens))
-- 
cgit v1.2.3