summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKaz Kylheku <kaz@kylheku.com>2011-12-22 22:34:12 -0800
committerKaz Kylheku <kaz@kylheku.com>2011-12-22 22:34:12 -0800
commitc11346723fc9142c9199591f21ce1b4e1447b741 (patch)
tree8885c749a6bea6c1730e4adabeb92a99f3cd5162
parent176679af947ff4b72c974ed94f68c2b33879f8c5 (diff)
downloadtxr-c11346723fc9142c9199591f21ce1b4e1447b741.tar.gz
txr-c11346723fc9142c9199591f21ce1b4e1447b741.tar.bz2
txr-c11346723fc9142c9199591f21ce1b4e1447b741.zip
* txr.1: Documented copy-list, reverse, nreverse, ldiff and flatten.
-rw-r--r--ChangeLog4
-rw-r--r--txr.1103
2 files changed, 107 insertions, 0 deletions
diff --git a/ChangeLog b/ChangeLog
index 246beda7..990fa3e0 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
2011-12-22 Kaz Kylheku <kaz@kylheku.com>
+ * txr.1: Documented copy-list, reverse, nreverse, ldiff and flatten.
+
+2011-12-22 Kaz Kylheku <kaz@kylheku.com>
+
* txr.1: Documented reduce-left and reduce-right.
2011-12-22 Kaz Kylheku <kaz@kylheku.com>
diff --git a/txr.1 b/txr.1
index 75fb84f9..63de5fc0 100644
--- a/txr.1
+++ b/txr.1
@@ -5522,12 +5522,115 @@ Examples:
.SS Function copy-list
+.TP
+Syntax:
+
+(copy-list <list>)
+
+.TP
+Description:
+
+The copy-list function which returns a list similar <list>, but with
+a newly allocated cons cell structure.
+
+If <list> is an atom, it is simply returned.
+
+Otherwise, <list> is a cons cell, and copy-list returns
+(cons (car <list>) (copy-list (cdr <list>))) except that recursion
+is not used.
+
+.TP
+Dialect Note:
+
+Common Lisp does not allow the argument to be an atom, except
+for the empty list nil.
+
.SS Functions reverse, nreverse
+.TP
+Syntax:
+
+(reverse <list>)
+(nreverse <list>)
+
+.TP
+Description:
+
+The functions reverse and nreverse produce an object which contains
+the same items as proper list <list>, but in reverse order.
+If <list> is nil, then both functions return nil.
+
+The reverse function is non-destructive: it creates a new list.
+
+The nreverse function creates the structure of the reversed list out of the
+cons cells of the input list, thereby destructively altering it (if it contains
+more than one element). How nreverse uses the material from the original list
+is unspecified. It may rearrange the cons cells into a reverse order, or it may
+keep the structure intact, but transfer the "car" values among cons cells into
+reverse order. Other approaches are possible.
+
.SS Function ldiff
+.TP
+Syntax:
+
+(ldiff <list> <sublist>)
+
+.TP
+Description:
+
+The values <list> and <sublist> are proper lists.
+
+The ldiff function determines whether <sublist> is a structural suffix of
+<list> (meaning that it actually is a suffix, and is not merely equal to one).
+
+This is true if <list> and <sublist> are the same object, or else,
+recursively, if <sublist> is a suffix of (cdr <list>).
+
+The object nil is the sublist of every list, including itself.
+
+The ldiff function returns a new list consisting of the elements of
+the prefix of <list> which come before the <sublist> suffix. The elements
+are in the same order as in <list>. If <sublist> is not a suffix of <list>,
+then a copy of <list> is returned.
+
+.TP
+Examples:
+
+;;; unspecified: the compiler could make '(2 3) a suffix of '(1 2 3),
+;;; or they could be separate objects.
+(ldiff '(1 2 3) '(2 3)) -> either (1) or (1 2 3)
+
+;; b is the (1 2) suffix of a, so the ldiff is (1)
+(let ((a '(1 2 3)) (b (cdr a)))
+ (ldiff a b))
+-> (1)
+
.SS Function flatten
+.TP
+Syntax:
+
+(flatten <list>)
+
+.TP
+Description:
+
+The flatten function produces a list whose elements are all of the non-nil
+atoms contained in the structure of <list>.
+
+.TP
+Examples:
+
+(flatten '(1 2 () (3 4))) -> (1 2 3 4)
+
+;; precisely equivalent to previous example! nil is the same thing as ()
+(flatten '(1 2 nil (3 4))) -> (1 2 3 4)
+
+(flatten nil) -> nil
+
+(flatten '(((()) ()))) -> nil
+
.SS Functions memq and memqual
.SS Function tree-find