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, 2 insertions, 0 deletions

diff --git a/lib.h b/lib.h
index e8cc31d6..c3330344 100644
--- a/lib.h
+++ b/lib.h
@@ -1104,7 +1104,9 @@ val window_mappend(val range, val boundary, val fun, val seq);
 val window_mapdo(val range, val boundary, val fun, val seq);
 val interpose(val sep, val seq);
 val merge(val list1, val list2, val lessfun, val keyfun);
+val nsort(val seq, val lessfun, val keyfun);
 val sort(val seq, val lessfun, val keyfun);
+val nshuffle(val seq);
 val shuffle(val seq);
 val multi_sort(val lists, val funcs, val key_funcs);
 val sort_group(val seq, val keyfun, val lessfun);