* eval.c (dwim_loc): Support indexing using a list of positions,

such as obtained by the where function.

* lib.c (replace_list, replace_str, replace_vec): Allow the
from argument to be a list of index positions, possibly empty.

* txr.1: Condensed syntactic descriptions under dwim operator.
Range Indexing section no longer says that the value nil
can be used as either endpoint of a range. This will not
work any longer since a "from" value of nil looks like an
empty list of indexes. Documented new behavior under
replace, and shortened documentation for replace-list,
replace-str and replace-vec.

1 files changed, 83 insertions, 70 deletions

diff --git a/txr.1 b/txr.1
index 499eb25a..53557fa6 100644
--- a/txr.1
+++ b/txr.1
@@ -6059,48 +6059,51 @@ is resolved in the function namespace, and then
 the resulting function, if found, is called with the
 given arguments.
 
-.IP "[<list> <index>]"
-Retrieve the specified element from the specified list. Index zero
-refers to the first element. Indexed list access does not throw exceptions.
-Negative indices yield nil, and indices beyond the end of a list
-yield nil. (However assignment to a nonexistent list element throws.)
-
-.IP "[<list> <from-index>..<to-below-index>]"
-Retrieve the specified range of elements, exactly as if
-using (sub-list <list> <from-index> <to-below-index>).
-The range of elements is specified in the car and cdr fields of a cons cell,
-for which the .. (dotdot) syntactic sugar is useful.
-See the section on Indexing below.
+.IP "[<sequence> <index>]"
+Retrieve an element from <sequence>, given by the integer <index>, given by the
+integer <index>.
+
+The following equivalences hold:
+
+  [seq index] <--> (ref seq index)
 
-.IP "[<vector> <index>]"
-Retrieve the specified element of a vector. This is equivalent to
-(vecref <vector> <index>).
+  (set [seq index] new) <--> (refset seq index new)
 
-.IP "[<vector> <from-index>..<to-below-index>]"
-Retrieve the specified range of elements, exactly as if
-using (sub-vec <list> <from-index> <to-below-index>).
+This form accepts update operators like inc and flip.
+
+.IP "[<sequence> <from-index>..<to-below-index>]"
+Retrieve the specified range of elements.
 The range of elements is specified in the car and cdr fields of a cons cell,
 for which the .. (dotdot) syntactic sugar is useful.
 See the section on Range Indexing below.
 
-.IP "[<string> <index>]"
-Retrieve the specified element of a string. This is equivalent to
-(chr-str <string> <index>).
+The following equivalences hold:
 
-.IP "[<string> <from-index>..<to-below-index>]"
-Retrieve the specified range of characters from the string, exactly as if
-using (sub-str <string> <from-index> <to-below-index>).
-The range of elements is specified in the car and cdr fields of a cons cell,
-for which the .. (dotdot) syntactic sugar is useful.
-See the section on Indexing below.
+  [seq from..to] <--> (sub seq from to)
+
+  (set [seq from..to] new) <--> (refset seq new from to)
+
+This form does not accept update operators like inc and flip.
 
 .IP [<sequence> <index-list>]
-This is equivalent to (select <sequence> <index-list>). Elements specified
+Elements specified
 by <index-list> are extracted from <sequence> and returned as a sequence
-of the same kind as <sequence>. See the description of the sequence function
-for the exact semantics.
+of the same kind as <sequence>. Equivalent to (select <sequence>
+<where-index>), except when the target of an assignment operation.
+
+The following equivalences hold:
+
+  [seq list] <--> (select seq list)
+
+  (set [seq list] new) <--> (refset seq new list)
+
+This form does not accept update operators like inc and flip.
 
-.IP "[<hash-table> <key> <default-value>]"
+Note that unlike the select function, this does not support [<hash>
+<index-list>], because since hash keys may be lists, that syntax is
+indistinguishable from a simple hash lookup where <index-list> is the key.
+
+.IP "[<hash> <key> <default-value>]"
 Retrieve a value from the hash table corresponding to <key>,
 or <default-value> if there is no such entry.
 
@@ -6133,15 +6136,11 @@ It is possible to assign to t .. t. For instance:
   (defvar list '(1 2 3))
   (set [list t .. t] '(4)) ;; list is now (1 2 3 4)
 
-Either end of the range can also be specified as nil. If the start is specified
-as nil, it means zero. If the end is specified as nil, it means one element
-past the end. Thus nil .. nil spans all of the elements.
-
 The value zero has a "floating" behavior when used as the end of a range.
 If the start of the range is a negative value, and the end of the
 range is zero, the zero is interpreted as being the position past the
 end of the sequence, rather than the first element. For instance the range
--1..0 means the same thing as -1..t or -1..nil. Zero at the start of a range
+-1..0 means the same thing as -1..t. Zero at the start of a range
 always means the first element, so that 0..-1 refers to all the elements except
 for the last one.
 
@@ -7342,8 +7341,9 @@ Syntax:
 .TP
 Description:
 
-The sub-list function extracts a sublist from <list>. It is exactly like the
-more generic function sub, except that it operates only on lists.
+This function is like the sub function, except that it operates
+strictly on lists.
+
 For a description of the arguments and semantics, refer to the sub function.
 
 .SS Function replace-list
@@ -7356,12 +7356,8 @@ Syntax:
 .TP
 Description:
 
-The replace-list function replaces a subrange of <list> with items from
-the item-sequence argument, which may be any kind of sequence (list, vector
-or string).
-
-It is like the replace function, except that the first argument must be
-a list.
+The replace-list function is like the replace function, except that the first
+argument must be a list.
 
 For a description of the arguments and semantics, refer to the replace function.
 
@@ -9273,9 +9269,9 @@ Syntax:
 .TP
 Description:
 
-The sub-str function extracts a substring from <string>. It is exactly like the
-more generic function sub, except that it operates only on strings.  For a
-description of the arguments and semantics, refer to the sub function.
+The sub-str function is like the more generic function sub, except that it
+operates only on strings.  For a description of the arguments and semantics,
+refer to the sub function.
 
 .SS Function replace-str
 
@@ -9287,12 +9283,8 @@ Syntax:
 .TP
 Description:
 
-The replace-str function replaces a substring of <string> with items from
-<item-sequence>, which may be any kind of sequence (list, vector
-or string) provided that it, if it is nonempty, it contains only characters.
-
-It is like the replace function, except that the first argument must be
-a list.
+The replace-str function is like the replace function, except that the first
+argument must be a string.
 
 For a description of the arguments and semantics, refer to the replace function.
 
@@ -10192,8 +10184,9 @@ Syntax:
 .TP
 Description:
 
-The sub-vec function extracts a subvector from <list>. It is exactly like the
-more generic function sub, except that it operates only on vectors.
+The sub-vec function is like the more generic function sub, except that it
+operates only on vectors.
+
 For a description of the arguments and semantics, refer to the sub function.
 
 .SS Function replace-vec
@@ -10206,12 +10199,8 @@ Syntax:
 .TP
 Description:
 
-The replace-vec function replaces a subrange of <vec> with items from
-the item-sequence argument, which may be any kind of sequence (list, vector
-or string).
-
-It is like the replace function, except that the first argument must be
-a vector.
+The replace-vec is like the replace function, except that the first argument
+must be a vector.
 
 For a description of the arguments and semantics, refer to the replace function.
 
@@ -10311,14 +10300,14 @@ Description:
 The sub function extracts a slice from input sequence <sequence>. The slice is
 a sequence of the same type as <sequence>.
 
-If the <to> parameter is omitted, the behavior is as if it were specified
-as 0. Likewise, if the <from> parameter is omitted, the behavior is
-as if t were specified. Thus (sub a) means (sub a 0 t).
+If the <from> parameter is omitted, it defaults to 0.  If the <to> parameter is
+omitted, it defaults to t.  Thus (sub a) means (sub a 0 t).
 
 The following equivalence holds between the sub function and
 the DWIM-bracket syntax:
 
-  (sub seq from to) <--> [seq from..to] 
+  ;; from is not a list
+  (sub seq from to) <--> [seq from..to]
 
 The the description of the dwim operator - in particular, the
 section on Range Indexing - explains the semantics of the range
@@ -10333,20 +10322,27 @@ substructure with the input sequence.
 Syntax:
 
    (replace <sequence> <replacement-sequence> [<from> [<to>]])
+   (replace <sequence> <replacement-sequence> <index-list>)
 
 .TP
 Description:
 
-The replace function replaces a subsequence of the <sequence> with
-<replacement-sequence>. The replaced subsequence may be empty, in which case an
-insertion is performed. If <replacement-sequence> is empty (for example, the
-empty list nil), then a deletion is performed.
+The replace function has two invocation styles, distinguished by the
+type of the third argument. If the third argument is a list,
+then it is deemed to be the <index-list> parameter of the second form.
+Otherwise, if the third argument is missing, or is not a list, then
+it is deemed to be the <from> argument of the first form.
+
+The first form of the replace function replaces a contiguous subsequence of the
+<sequence> with <replacement-sequence>. The replaced subsequence may be empty,
+in which case an insertion is performed. If <replacement-sequence> is empty
+(for example, the empty list nil), then a deletion is performed.
 
 If the <from> and <to> parameters are omitted, their values default
 to 0 and t respectively.
 
 The following equivalence holds between assignment to a place denoted by
-DWIM bracket syntax and the replace function:
+DWIM bracket syntax and first form of the replace function:
 
   (set seq (replace seq new from to)) <--> (set [seq from..to] new)
 
@@ -10358,6 +10354,23 @@ This operation is destructive: it may work "in place" by modifying
 the original sequence. The caller should retain the return value
 and stop relying on the original input sequence.
 
+The second form of the replace function replaces a subsequence of
+elements from <sequence> given by <index-list>, with their counterparts
+from <replacement-sequence>. This form of the replace function does not insert
+or delete; it simply overwrites elements. If <replacement-sequence> and
+<index-list> are of different lengths, then the shorter of the two determines
+the maximum number of elements which are overwritten.
+Furthermore, similar restrictions apply on <index-list> as under the
+select function. Namely, the replacement stops when an index value
+in <index-list> is encountered which is out of range for <sequence>.
+Furthermore, if <sequence> is a list, then <index-list> must
+be monotonically increasing.
+
+The following equivalence holds between assignment to a place denoted by
+DWIM bracket syntax and second form of the replace function:
+
+  (set seq (replace seq new index-list)) <--> (set [seq index-list] new)
+
 .SS Function search
 
 .TP