lib: sort becomes non-destructive; nsort introduced.

I'm fixing a historic mistake copied from ANSI Lisp,
which trips up language newcomers and sometimes even
experienced users.

The function innocently named sort will now return newly
allocated structure. The function previously called sort will
be available as nsort (non-consing/allocating sort).

The shuffle function also becomes pure, and is accompanied by
nshuffle.

* eval (me_op): Continue to use destructive sort in this
legacy code that is only triggered in very old compat mode.
(eval_init): Registered nsort and nshuffle.

* lib.c (nsort, nshuffle): New functions introduced, closely
based on sort and shuffle.
(sort, shuffle): Rewritten to avoid destructive behavior: work
by copying the input and calling destructive counterparts.
(sort_group): Continue to use destructive sort, which is safe;
the structure is locally allocated. The sort_group function
has pure semantics.
(grade): Likewise.

* lib.h (nsort, nshuffle): Declared.

* share/txr/stdlib/getopts.tl (opthelp): Replace an instance
of the (sort (copy-list ...)) pattern with just (sort ...).

* tags.tl (toplevel): Continue to use destructive sort to sort
tags before writing the tag file; the lifetime of the tags
list ends when the file is written.

* tests/010/seq.txr: Switch some sort calls to nsort to keep
test case working.

* txr.1: Documented.

1 files changed, 3 insertions, 3 deletions

diff --git a/tests/010/seq.txr b/tests/010/seq.txr
index 080b01ad..9b3edf28 100644
--- a/tests/010/seq.txr
+++ b/tests/010/seq.txr
@@ -14,7 +14,7 @@
    (format t "~s ~s\n" (del [*s* 1]) *s*)
    (format t "~s ~s\n" (del [*s* -1]) *s*)
    (catch (pr (del [*s* 3]) *s*) (t (x) (caught x)))
-   (pr [sort *v* >])
-   (pr [sort *v2* > cdr])
-   (pr [sort (range 1 100) >])
+   (pr [nsort *v* >])
+   (pr [nsort *v2* > cdr])
+   (pr [nsort (range 1 100) >])
    (pr2 (del [*v2* 1..3]) *v2*))