lsearch, lsort: support for -stride and -index

Add -stride support to both lsearch and lsort
Add -index support to lsearch
Improve -index for lsort to support multiple indices

Also harmonise some error messages with Tcl 8.7

Signed-off-by: Steve Bennett <steveb@workware.net.au>

1 files changed, 67 insertions, 19 deletions

diff --git a/jim_tcl.txt b/jim_tcl.txt
index 14cee1e..1889ac9 100644
--- a/jim_tcl.txt
+++ b/jim_tcl.txt
@@ -61,6 +61,9 @@ Changes since 0.80
 4. `loop` can now omit the start value
 5. Add the `xtrace` command for execution trace support
 6. Add `history keep`
+7. Add support for `lsearch -index` and `lsearch -stride`, the latter per TIP 351
+8. `lsort -index` now supports multiple indices
+9. Add support for `lsort -stride`
 
 Changes between 0.79 and 0.80
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3371,35 +3374,80 @@ the list are to be matched against pattern and must have one of the values below
 +*-nocase*+::
     Causes comparisons to be handled in a case-insensitive manner.
 
++*-index* 'indexList'+::
+    This option is designed for use when searching within nested lists. The
+    'indexList' gives a path of indices (much as might be used with
+    the lindex or lset commands) within each element to allow the location
+    of the term being matched against.
+
++*-stride* 'strideLength'+::
+    If this option is specified, the list is treated as consisting of
+    groups of 'strideLength' elements and the groups are searched by
+    either their first element or, if the +-index+ option is used,
+    by the element within each group given by the first index passed to
+    +-index+ (which is then ignored by +-index+). The resulting
+    index always points to the first element in a group.
+ ::
+    The list length must be an integer multiple of 'strideLength', which
+    in turn must be at least 1. A 'strideLength' of 1 is the default and
+    indicates no grouping.
+
 lsort
 ~~~~~
-+*lsort* ?*-index* 'listindex'? ?*-nocase|-integer|-real|-command* 'cmdname'? ?*-unique*? ?*-decreasing*|*-increasing*? 'list'+
++*lsort* '?options? list'+
 
 Sort the elements of +'list'+, returning a new list in sorted order.
 By default, ASCII (or UTF-8) sorting is used, with the result in increasing order.
 
-If +-nocase+ is specified, comparisons are case-insensitive.
-
-If +-integer+ is specified, numeric sorting is used.
-
-If +-real+ is specified, floating point number sorting is used.
+Note that only one sort type may be selected with +-integer+, +-real+, +-nocase+ or +-command+
+with last option being used.
 
-If +-command 'cmdname'+ is specified, +'cmdname'+ is treated as a command
-name. For each comparison, +'cmdname $value1 $value2+' is called which
-should compare the values and return an integer less than, equal
-to, or greater than zero if the +'$value1'+ is to be considered less
-than, equal to, or greater than +'$value2'+, respectively.
++*-integer*+::
+    Sort using numeric (integer) comparison.
 
-If +-decreasing+ is specified, the resulting list is in the opposite
-order to what it would be otherwise. +-increasing+ is the default.
++*-real*+::
+    Sort using floating point comparison.
 
-If +-unique+ is specified, then only the last set of duplicate elements found in the list will be retained.
-Note that duplicates are determined relative to the comparison used in the sort. Thus if +-index 0+ is used,
-+{1 a}+ and +{1 b}+ would be considered duplicates and only the second element, +{1 b}+, would be retained.
++*-nocase*+::
+    Sort using using string comparison without regard for case.
 
-If +-index 'listindex'+ is specified, each element of the list is treated as a list and
-the given index is extracted from the list for comparison. The list index may
-be any valid list index, such as +1+, +end+ or +end-2+.
++*-command* 'cmdname'+::
+    +'cmdname'+ is treated as a command name. For each comparison,
+    +'cmdname $value1 $value2+' is called which
+    should compare the values and return an integer less than, equal
+    to, or greater than zero if the +'$value1'+ is to be considered less
+    than, equal to, or greater than +'$value2'+, respectively.
+
++*-increasing*+::
+    The resulting list is in ascending order, from smallest/lowest to largest/highest.
+    This is the default and does not need to be specified.
+
++*-decreasing*+::
+    The resulting list is in the opposite order to what it would be otherwise.
+
++*-unique*+::
+    Only the last set of duplicate elements found in the list will
+    be retained.  Note that duplicates are determined relative to the
+    comparison used in the sort. Thus if +-index 0+ is used, +{1 a}+ and
+    +{1 b}+ would be considered duplicates and only the second element,
+    +{1 b}+, would be retained.
+
++*-index* 'indexList'+::
+    This option is designed for use when sorting nested lists. The
+    'indexList' gives a path of indices (much as might be used with
+    the lindex or lset commands) within each element to specify the
+    value to be used for comparison.
+
++*-stride* 'strideLength'+::
+    If this option is specified, the list is treated as consisting of
+    groups of 'strideLength' elements and the groups are sorted by
+    either their first element or, if the +-index+ option is used,
+    by the element within each group given by the first index passed to
+    +-index+ (which is then ignored by +-index+). The resulting list
+    is once again a flat list.
+ ::
+    The list length must be an integer multiple of 'strideLength', which
+    in turn must be at least 2.
 
 defer
 ~~~~~