TIP#176 IMPLEMENTATION [Patch 1165695]

        * generic/tclUtil.c:    Extended TclGetIntForIndex to recognize
        index formats including end+integer and integer+/-integer.

        * generic/tclCmdMZ.c:   Extended the -start switch of [regexp]
        and [regsub] to accept all index formats known by TclGetIntForIndex.

        * doc/lindex.n:         Updated docs to note new index formats.
        * doc/linsert.n:
        * doc/lrange.n:
        * doc/lreplace.n:
        * doc/lsearch.n:
        * doc/lset.n:
        * doc/lsort.n:
        * doc/regexp.n:
        * doc/regsub.n:
        * doc/string.n:

        * tests/cmdIL.test:     Updated tests.
        * tests/compile.test:
        * tests/lindex.test:
        * tests/linsert.test:
        * tests/lrange.test:
        * tests/lreplace.test:
        * tests/lsearch.test:
        * tests/lset.test:
        * tests/regexp.test:
        * tests/regexpComp.test:
        * tests/string.test:
        * tests/stringComp.test:
        * tests/util.test:

10 files changed, 124 insertions, 52 deletions

diff --git a/doc/lindex.n b/doc/lindex.n
index eba3cc3..d3b85b2 100644
--- a/doc/lindex.n
+++ b/doc/lindex.n
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lindex.n,v 1.9 2005/04/06 20:55:23 dkf Exp $
+'\" RCS: @(#) $Id: lindex.n,v 1.10 2005/04/29 20:49:43 dgp Exp $
 '\" 
 .so man.macros
 .TH lindex n 8.4 Tcl "Tcl Built-In Commands"
@@ -46,9 +46,11 @@ substitution and command substitution do not occur.
 If \fIindex\fR is negative or greater than or equal to the number
 of elements in \fIvalue\fR, then an empty
 string is returned.
-If \fIindex\fR has the value \fBend\fR, it refers to the last element
-in the list, and \fBend\-\fIinteger\fR refers to the last element in
-the list minus the specified integer offset.
+.VS 8.5
+The interpretation of each simple \fIindex\fR value is the same as 
+for the command \fBstring index\fR, supporting simple index
+arithmetic and indices relative to the end of the list.
+.VE 8.5
 .PP
 If additional \fIindex\fR arguments are supplied, then each argument is
 used in turn to select an element from the previous indexing operation,
@@ -79,7 +81,10 @@ lindex [lindex [lindex $a 1] 2] 3
 .CE
 .SH "SEE ALSO"
 list(n), lappend(n), linsert(n), llength(n), lsearch(n), 
-lset(n), lsort(n), lrange(n), lreplace(n)
+lset(n), lsort(n), lrange(n), lreplace(n),
+.VS 8.5
+string(n)
+.VE
 
 .SH KEYWORDS
 element, index, list
diff --git a/doc/linsert.n b/doc/linsert.n
index 1f4508c..d563650 100644
--- a/doc/linsert.n
+++ b/doc/linsert.n
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: linsert.n,v 1.11 2005/04/06 20:55:23 dkf Exp $
+'\" RCS: @(#) $Id: linsert.n,v 1.12 2005/04/29 20:49:43 dgp Exp $
 '\" 
 .so man.macros
 .TH linsert n 8.2 Tcl "Tcl Built-In Commands"
@@ -24,11 +24,12 @@ This command produces a new list from \fIlist\fR by inserting all of the
 \fIelement\fR arguments just before the \fIindex\fR'th element of
 \fIlist\fR.  Each \fIelement\fR argument will become a separate element of
 the new list.  If \fIindex\fR is less than or equal to zero, then the new
-elements are inserted at the beginning of the list.  If \fIindex\fR has the
-value \fBend\fR, or if it is greater than or equal to the number of
-elements in the list, then the new elements are appended to the list.
-\fBend\-\fIinteger\fR refers to the last element in the list minus the
-specified integer offset.
+elements are inserted at the beginning of the list.  
+.VS 8.5
+The interpretation of the \fIindex\fR value is the same as
+for the command \fBstring index\fR, supporting simple index
+arithmetic and indices relative to the end of the list.
+.VE
 .SH EXAMPLE
 Putting some values into a list, first indexing from the start and
 then indexing from the end, and then chaining them together:
@@ -42,7 +43,10 @@ set newerList [\fBlinsert\fR [\fBlinsert\fR $oldList end-1 quick] 1 lazy]
 
 .SH "SEE ALSO"
 list(n), lappend(n), lindex(n), llength(n), lsearch(n), 
-lset(n), lsort(n), lrange(n), lreplace(n)
+lset(n), lsort(n), lrange(n), lreplace(n),
+.VS 8.5
+string(n)
+.VE
 
 .SH KEYWORDS
 element, insert, list
diff --git a/doc/lrange.n b/doc/lrange.n
index b502dba..974947a 100644
--- a/doc/lrange.n
+++ b/doc/lrange.n
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lrange.n,v 1.10 2005/04/06 20:55:23 dkf Exp $
+'\" RCS: @(#) $Id: lrange.n,v 1.11 2005/04/29 20:49:43 dgp Exp $
 '\" 
 .so man.macros
 .TH lrange n 7.4 Tcl "Tcl Built-In Commands"
@@ -23,9 +23,12 @@ lrange \- Return one or more adjacent elements from a list
 \fIList\fR must be a valid Tcl list.  This command will
 return a new list consisting of elements
 \fIfirst\fR through \fIlast\fR, inclusive.
-\fIFirst\fR or \fIlast\fR
-may be \fBend\fR (or any abbreviation of it) to refer to the last
-element of the list.
+.VS 8.5
+The index values \fIfirst\fR and \fIlast\fR are interpreted
+the same as index values for the command \fBstring index\fR,
+supporting simple index arithmetic and indices relative to the
+end of the list.
+.VE
 If \fIfirst\fR is less than zero, it is treated as if it were zero.
 If \fIlast\fR is greater than or equal to the number of elements
 in the list, then it is treated as if it were \fBend\fR.
@@ -67,7 +70,10 @@ elements to
 
 .SH "SEE ALSO"
 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
-lset(n), lreplace(n), lsort(n)
+lset(n), lreplace(n), lsort(n),
+.VS 8.5
+string(n)
+.VE
 
 .SH KEYWORDS
 element, list, range, sublist
diff --git a/doc/lreplace.n b/doc/lreplace.n
index ac6e434..f9f12e2 100644
--- a/doc/lreplace.n
+++ b/doc/lreplace.n
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lreplace.n,v 1.11 2005/04/06 20:55:23 dkf Exp $
+'\" RCS: @(#) $Id: lreplace.n,v 1.12 2005/04/29 20:49:43 dgp Exp $
 '\" 
 .so man.macros
 .TH lreplace n 7.4 Tcl "Tcl Built-In Commands"
@@ -22,11 +22,17 @@ lreplace \- Replace elements in a list with new elements
 .PP
 \fBlreplace\fR returns a new list formed by replacing one or more elements of
 \fIlist\fR with the \fIelement\fR arguments.
-\fIfirst\fR and \fIlast\fR specify the first and last index of the
-range of elements to replace.  0 refers to the first element of the
-list, and \fBend\fR (or any abbreviation of it) may be used to refer
-to the last element of the list.  If \fIlist\fR is empty, then
-\fIfirst\fR and \fIlast\fR are ignored.
+.VS 8.5
+\fIfirst\fR and \fIlast\fR are index values specifying the first and
+last elements of the range to replace.  
+The index values \fIfirst\fR and \fIlast\fR are interpreted
+the same as index values for the command \fBstring index\fR,
+supporting simple index arithmetic and indices relative to the
+end of the list.
+0 refers to the first element of the
+list, and \fBend\fR refers to the last element of the list.
+If \fIlist\fR is empty, then \fIfirst\fR and \fIlast\fR are ignored.
+.VE
 
 If \fIfirst\fR is less than zero, it is considered to refer to the
 first element of the list.  For non-empty lists, the element indicated
@@ -66,7 +72,11 @@ a b c d
 
 .SH "SEE ALSO"
 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
-lset(n), lrange(n), lsort(n)
+lset(n), lrange(n), lsort(n),
+.VS 8.5
+string(n)
+.VE
+
 
 .SH KEYWORDS
 element, list, replace
diff --git a/doc/lsearch.n b/doc/lsearch.n
index d456181..ffac227 100644
--- a/doc/lsearch.n
+++ b/doc/lsearch.n
@@ -7,7 +7,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lsearch.n,v 1.22 2005/01/05 16:38:54 dkf Exp $
+'\" RCS: @(#) $Id: lsearch.n,v 1.23 2005/04/29 20:49:43 dgp Exp $
 '\" 
 .so man.macros
 .TH lsearch n 8.5 Tcl "Tcl Built-In Commands"
@@ -70,10 +70,12 @@ This negates the sense of the match, returning the index of the first
 non-matching value in the list.
 .TP
 \fB\-start\fR\0\fIindex\fR
-The list is searched starting at position \fIindex\fR.  If \fIindex\fR
-has the value \fBend\fR, it refers to the last element in the list,
-and \fBend\-\fIinteger\fR refers to the last element in the list minus
-the specified integer offset.
+The list is searched starting at position \fIindex\fR.  
+.VS 8.5
+The interpretation of the \fIindex\fR value is the same as
+for the command \fBstring index\fR, supporting simple index
+arithmetic and indices relative to the end of the list.
+.VE 8.5
 .SS "CONTENTS DESCRIPTION OPTIONS"
 These options describe how to interpret the items in the list being
 searched.  They are only meaningful when used with the \fB\-exact\fR
@@ -166,7 +168,11 @@ It is also possible to search inside elements:
 
 .SH "SEE ALSO"
 foreach(n), list(n), lappend(n), lindex(n), linsert(n), llength(n), 
-lset(n), lsort(n), lrange(n), lreplace(n)
+lset(n), lsort(n), lrange(n), lreplace(n),
+.VS 8.5
+string(n)
+.VE
+
 
 .SH KEYWORDS
 list, match, pattern, regular expression, search, string
diff --git a/doc/lset.n b/doc/lset.n
index 18a784a..5f6e2d5 100755
--- a/doc/lset.n
+++ b/doc/lset.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lset.n,v 1.7 2003/12/01 21:27:14 msofer Exp $
+'\" RCS: @(#) $Id: lset.n,v 1.8 2005/04/29 20:49:43 dgp Exp $
 '\" 
 .so man.macros
 .TH lset n 8.4 Tcl "Tcl Built-In Commands"
@@ -52,9 +52,11 @@ command.
 If \fIindex\fR is negative or greater than or equal to the number
 of elements in \fI$varName\fR, then an error occurs.
 .PP
-If \fIindex\fR has the value \fBend\fR, it refers to the last element
-in the list, and \fBend\-\fIinteger\fR refers to the last element in
-the list minus the specified integer offset.
+.VS 8.5
+The interpretation of each simple \fIindex\fR value is the same as
+for the command \fBstring index\fR, supporting simple index
+arithmetic and indices relative to the end of the list.
+.VE 8.5
 .PP
 If additional \fIindex\fR arguments are supplied, then each argument is
 used in turn to address an element within a sublist designated
@@ -107,7 +109,11 @@ lset x {1 1 0} j => {{a b} {c d}} {{e f} {j h}}
 .CE
 .SH "SEE ALSO"
 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
-lsort(n), lrange(n), lreplace(n)
+lsort(n), lrange(n), lreplace(n),
+.VS 8.5
+string(n)
+.VE
+
 
 .SH KEYWORDS
 element, index, list, replace, set
diff --git a/doc/lsort.n b/doc/lsort.n
index ae7d177..f1b29d4 100644
--- a/doc/lsort.n
+++ b/doc/lsort.n
@@ -7,7 +7,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lsort.n,v 1.18 2004/10/27 12:53:22 dkf Exp $
+'\" RCS: @(#) $Id: lsort.n,v 1.19 2005/04/29 20:49:43 dgp Exp $
 '\" 
 .so man.macros
 .TH lsort n 8.3 Tcl "Tcl Built-In Commands"
@@ -78,10 +78,7 @@ sublists, \fBlsort\fR will extract the \fIindexList\fR'th element from
 each sublist
 .VS 8.5
 (as if the overall element and the \fIindexList\fR were passed to
-\fBlindex\fR) and sort based on the given element.  The keyword
-\fBend\fP is allowed for each element of the \fIindexList\fR to sort
-on the last sublist element, and \fBend-\fIindex\fR sorts on a sublist
-element offset from the end.
+\fBlindex\fR) and sort based on the given element.  
 .VE 8.5
 For example,
 .RS
diff --git a/doc/regexp.n b/doc/regexp.n
index 7fece66..9567824 100644
--- a/doc/regexp.n
+++ b/doc/regexp.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: regexp.n,v 1.17 2005/04/06 20:55:23 dkf Exp $
+'\" RCS: @(#) $Id: regexp.n,v 1.18 2005/04/29 20:49:43 dgp Exp $
 '\" 
 .so man.macros
 .TH regexp n 8.3 Tcl "Tcl Built-In Commands"
@@ -107,7 +107,12 @@ regular expression.  Examples are:
 .TP 15
 \fB\-start\fR \fIindex\fR
 Specifies a character index offset into the string to start
-matching the regular expression at.  When using this switch, `^'
+matching the regular expression at.  
+.VS 8.5
+The \fIindex\fR value is interpreted in the same manner
+as the \fIindex\fR argument to \fBstring index\fR.
+.VE 8.5
+When using this switch, `^'
 will not match the beginning of the line, and \\A will still
 match the start of the string at \fIindex\fR.  If \fB\-indices\fR
 is specified, the indices will be indexed starting from the
@@ -153,7 +158,11 @@ characters) in a string:
 .CE
 
 .SH "SEE ALSO"
-re_syntax(n), regsub(n)
+re_syntax(n), regsub(n),
+.VS 8.5
+string(n)
+.VE
+
 
 .SH KEYWORDS
 match, regular expression, string
diff --git a/doc/regsub.n b/doc/regsub.n
index 43b940f..259f2a5 100644
--- a/doc/regsub.n
+++ b/doc/regsub.n
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: regsub.n,v 1.13 2005/04/06 20:55:24 dkf Exp $
+'\" RCS: @(#) $Id: regsub.n,v 1.14 2005/04/29 20:49:43 dgp Exp $
 '\" 
 .so man.macros
 .TH regsub n 8.3 Tcl "Tcl Built-In Commands"
@@ -92,7 +92,12 @@ by \fIsubSpec\fR use the original unconverted form of \fIstring\fR.
 .TP 10
 \fB\-start\fR \fIindex\fR
 Specifies a character index offset into the string to start
-matching the regular expression at.  When using this switch, `^'
+matching the regular expression at.  
+.VS 8.5
+The \fIindex\fR value is interpreted in the same manner
+as the \fIindex\fR argument to \fBstring index\fR.
+.VE 8.5
+When using this switch, `^'
 will not match the beginning of the line, and \\A will still
 match the start of the string at \fIindex\fR.
 \fIindex\fR will be constrained to the bounds of the input string.
@@ -134,7 +139,11 @@ set quoted [subst [\fBregsub\fR -all $RE $string $substitution]]
 .CE
 
 .SH "SEE ALSO"
-regexp(n), re_syntax(n), subst(n)
+regexp(n), re_syntax(n), subst(n),
+.VS 8.5
+string(n)
+.VE
+
 
 .SH KEYWORDS
 match, pattern, regular expression, substitute
diff --git a/doc/string.n b/doc/string.n
index 7d46ccb..3fe9678 100644
--- a/doc/string.n
+++ b/doc/string.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: string.n,v 1.26 2005/03/07 21:38:10 dkf Exp $
+'\" RCS: @(#) $Id: string.n,v 1.27 2005/04/29 20:49:43 dgp Exp $
 '\" 
 .so man.macros
 .TH string n 8.1 Tcl "Tcl Built-In Commands"
@@ -72,18 +72,38 @@ will return \fB\-1\fR.
 Returns the \fIcharIndex\fR'th character of the \fIstring\fR argument.
 A \fIcharIndex\fR of 0 corresponds to the first character of the
 string.  \fIcharIndex\fR may be specified as follows:
+.VS 8.5
 .RS
 .IP \fIinteger\fR 10
-The char specified at this integral index.
+For any index value that passes \fBstring is integer -strict\fR,
+the char specified at this integral index
+(e.g. \fB2\fR would refer to the "c" in "abcd").
 .IP \fBend\fR 10
-The last char of the string.
-.IP \fBend\-\fIinteger\fR 10
-The last char of the string minus the specified integer offset
+The last char of the string
+(e.g. \fBend\fR would refer to the "d" in "abcd").
+.IP \fBend\-\fIN\fR 10
+The last char of the string minus the specified integer offset \fIN\fR
 (e.g. \fBend\-1\fR would refer to the "c" in "abcd").
+.IP \fBend\+\fIN\fR 10
+The last char of the string plus the specified integer offset \fIN\fR
+(e.g. \fBend\+\-1\fR would refer to the "c" in "abcd").
+.IP \fIM\fR\+\fIN\fR 10
+The char specified at the integral index that is the sum of 
+integer values \fIM\fR and \fIN\fR
+(e.g. \fB1\+1\fR would refer to the "c" in "abcd").
+.IP \fIM\fR\-\fIN\fR 10
+The char specified at the integral index that is the difference of 
+integer values \fIM\fR and \fIN\fR
+(e.g. \fB2\-1\fR would refer to the "b" in "abcd").
+.PP
+In the specifications above, the integer value \fIM\fR contains no
+trailing whitespace and the integer value \fIN\fR contains no
+leading whitespace.
 .PP
 If \fIcharIndex\fR is less than 0 or greater than or equal to the
-length of the string then an empty string is returned.
+length of the string then this command returns an empty string.
 .RE
+.VE
 .TP
 \fBstring is \fIclass\fR ?\fB\-strict\fR? ?\fB\-failindex \fIvarname\fR? \fIstring\fR
 Returns 1 if \fIstring\fR is a valid member of the specified character