More docs

docs/api/srfi/1.md

@@ -199,60 +199,269 @@ The `start` and `step` parameters default to 0 and 1, respectively. This procedu
 
 # proper-list?
 
+    (proper-list? x)
+
+Returns true iff `x` is a proper list -- a finite, nil-terminated list.
+
+More carefully: The empty list is a proper list. A pair whose cdr is a proper list is also a proper list:
+
+    <proper-list> ::= ()                            (Empty proper list)
+                  |   (cons <x> <proper-list>)      (Proper-list pair)
+
+Note that this definition rules out circular lists. This function is required to detect this case and return false.
+
+Nil-terminated lists are called "proper" lists by R7RS and Common Lisp. The opposite of proper is improper.
+
 # circular-list?
 
+    (circular-list? x)
+
+True if `x` is a circular list. A circular list is a value such that for every `n >= 0`, the `n`th `cdr(x)` is a pair.
+
+Terminology: The opposite of circular is finite.
+
+    (not (circular-list? x)) = (or (proper-list? x) (dotted-list? x))
+
 # dotted-list?
 
+    (dotted-list? x)
+
+True if `x` is a finite, non-nil-terminated list. That is, there exists an `n >= 0` such that the `n`th `cdr(x)` is neither a pair nor (). This includes non-pair, non-() values (e.g. symbols, numbers), which are considered to be dotted lists of length 0.
+
+    (not (dotted-list? x)) = (or (proper-list? x) (circular-list? x))
+
 # not-pair?
 
+    (not-pair? x)
+
+Equivalent to:
+
+    (lambda (x) (not (pair? x)))
+
+Provided as a procedure as it can be useful as the termination condition for list-processing procedures that wish to handle all finite lists, both proper and dotted.
+
 # null-list?
 
+    (null-list? list)
+
+`list` is a proper or circular list. This procedure returns true if the argument is the empty list (), and false otherwise. It is an error to pass this procedure a value which is not a proper or circular list. This procedure is recommended as the termination condition for list-processing procedures that are not defined on dotted lists.
+
 # list=
 
-# length+
+    (list= elt= list1 ...)
+
+Determines list equality, given an element-equality procedure. Proper list A equals proper list B if they are of the same length, and their corresponding elements are equal, as determined by `elt=`. If the element-comparison procedure's first argument is from listi, then its second argument is from listi+1, i.e. it is always called as `(elt= a b)` for a an element of list A, and b an element of list B.
+
+In the n-ary case, every list `i` is compared to list `i+1` (as opposed, for example, to comparing list element `1` to every list element `i`, for `i>1`). If there are no list arguments at all, list= simply returns true.
+
+It is an error to apply list= to anything except proper lists. While implementations may choose to extend it to circular lists, note that it cannot reasonably be extended to dotted lists, as it provides no way to specify an equality procedure for comparing the list terminators.
+
+Note that the dynamic order in which the elt= procedure is applied to pairs of elements is not specified. For example, if list= is applied to three lists, A, B, and C, it may first completely compare A to B, then compare B to C, or it may compare the first elements of A and B, then the first elements of B and C, then the second elements of A and B, and so forth.
+
+The equality procedure must be consistent with eq?. That is, it must be the case that
+
+    (eq? x y) => (elt= x y).
+
+Note that this implies that two lists which are eq? are always list=, as well; implementations may exploit this fact to "short-cut" the element-by-element comparisons.
+
+    (list= eq?) => #t       ; Trivial cases
+    (list= eq? '(a)) => #t
 
 # first
 
+    (first x)
+
+Synonyms for `car`, `cadr`, `caddr`, `...`
+
+    (first '(a b c d e f g h i j)) => a
+
 # second
 
+    (second x)
+
+Synonyms for `car`, `cadr`, `caddr`, `...`
+
+    (second '(a b c d e f g h i j)) => b
+
 # third
 
+    (third x)
+
+Synonyms for `car`, `cadr`, `caddr`, `...`
+
+    (third '(a b c d e f g h i j)) => c
+
 # fourth
 
+    (fourth x)
+
+Synonyms for `car`, `cadr`, `caddr`, `...`
+
+    (fourth '(a b c d e f g h i j)) => d
+
 # fifth
 
+    (fifth x)
+
+Synonyms for `car`, `cadr`, `caddr`, `...`
+
+    (fifth '(a b c d e f g h i j)) => e
+
 # sixth
 
+    (sixth x)
+
+Synonyms for `car`, `cadr`, `caddr`, `...`
+
+    (sixth '(a b c d e f g h i j)) => f
+
 # seventh
 
+    (seventh x)
+
+Synonyms for `car`, `cadr`, `caddr`, `...`
+
+    (seventh '(a b c d e f g h i j)) => g
+
 # eighth
 
+    (eighth x)
+
+Synonyms for `car`, `cadr`, `caddr`, `...`
+
+    (eighth '(a b c d e f g h i j)) => h
+
 # ninth
 
+    (ninth x)
+
+Synonyms for `car`, `cadr`, `caddr`, `...`
+
+    (ninth '(a b c d e f g h i j)) => i
+
 # tenth
 
+    (tenth x)
+
+Synonyms for `car`, `cadr`, `caddr`, `...`
+
+    (tenth '(a b c d e f g h i j)) => j
+
 # car+cdr
 
+    (car+cdr pair)
+
+The fundamental pair deconstructor:
+
+    (lambda (p) (values (car p) (cdr p)))
+
 # take
 
+    (take x i)
+
+`take` returns the first `i` elements of list `x`.
+
+    (take '(a b c d e)  2) => (a b)
+
+`x` may be any value -- a proper, circular, or dotted list:
+
+    (take '(1 2 3 . d) 2) => (1 2)
+    (take '(1 2 3 . d) 3) => (1 2 3)
+
+For a legal i, take and drop partition the list in a manner which can be inverted with append:
+
+    (append (take x i) (drop x i)) = x
+
+If the argument is a list of non-zero length, `take` is guaranteed to return a freshly-allocated list, even in the case where the entire list is taken, e.g. `(take lis (length lis))`.
+
 # drop
 
+    (drop x i)
+
+`drop` returns all but the first `i` elements of list `x`.
+
+    (drop '(a b c d e)  2) => (c d e)
+
+`x` may be any value -- a proper, circular, or dotted list:
+
+    (drop '(1 2 3 . d) 2) => (3 . d)
+    (drop '(1 2 3 . d) 3) => d
+
+For a legal i, take and drop partition the list in a manner which can be inverted with append:
+
+    (append (take x i) (drop x i)) = x
+
+`drop` is exactly equivalent to performing `i` `cdr` operations on `x`; the returned value shares a common tail with `x`.
+
 # take-right
 
+    (take-right flist i)
+
+`take-right` returns the last `i` elements of `flist`.
+
+    (take-right '(a b c d e) 2) => (d e)
+
 # drop-right
 
+    (drop-right flist i)
+
+`drop-right` returns all but the last `i` elements of `flist`.
+
+    (drop-right '(a b c d e) 2) => (a b c)
+
 # take!
 
+    (take! x i)
+
+`take!` is a "linear-update" variant of `take`: the procedure is allowed, but not required, to alter the argument list to produce the result.
+
+If x is circular, take! may return a shorter-than-expected list:
+
+    (take! (circular-list 1 3 5) 8) => (1 3)
+    (take! (circular-list 1 3 5) 8) => (1 3 5 1 3 5 1 3)
+
 # drop-right!
 
+    (drop-right! flist i)
+
+`drop-right!` is a "linear-update" variant of `drop-right`: the procedure is allowed, but not required, to alter the argument list to produce the result.
+
 # split-at
 
+    (split-at x i)
+
+`split-at` splits the list `x` at index `i`, returning a list of the first `i` elements, and the remaining tail. It is equivalent to
+
+    (values (take x i) (drop x i))
+
 # split-at!
 
+    (split-at! x i)
+
+`split-at!` is the linear-update variant. It is allowed, but not required, to alter the argument list to produce the result.
+
+    (split-at '(a b c d e f g h) 3) =>
+        (a b c)
+            (d e f g h)
+
 # last
 
+    (last pair)
+
+`last` returns the last element of the non-empty, finite list `pair`. 
+
+    (last '(a b c)) => c
+
 # last-pair
 
+    (last-pair pair)
+
+`last-pair` returns the last pair in the non-empty, finite list `pair`.
+
+    (last-pair '(a b c)) => (c)
+
+# length+
+
 # zip
 
 # unzip1