Clarified documentation of what happens with negative indices. [Bug 1905809]

Added example, tidied up formatting.

2 files changed, 71 insertions, 62 deletions

diff --git a/ChangeLog b/ChangeLog
index 9986761..9ac9644 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,34 +1,39 @@
+2008-03-16  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/lreplace.n: Clarified documentation of what happens with
+	negative indices. [Bug 1905809] Added example, tidied up formatting.
+
 2008-03-14  Don Porter	<dgp@users.sourceforge.net>
 
 	* generic/tclBasic.c (OldMathFuncProc):	Same workaround protection
-	from bad TclStackAlloc() alignment.  Thanks George Peter Staplin.
+	from bad TclStackAlloc() alignment. Thanks George Peter Staplin.
 
 	* generic/tclCmdIL.c (Tcl_LsortObjCmd):	Use ckalloc() to allocate
 	SortElement arrays instead of TclStackAlloc() which isn't getting
-	alignment right.  Workaround for [Bug 1914503].
+	alignment right. Workaround for [Bug 1914503].
 
 2008-03-14  Reinhard Max  <max@suse.de>
 
-	* generic/tclTest.c:  Ignore the return value of write() when
-	* unix/tclUnixPipe.c: we are about to exit anyways.
+	* generic/tclTest.c:  Ignore the return value of write() when we are
+	* unix/tclUnixPipe.c: about to exit anyways.
 
 2008-03-13  Daniel Steffen  <das@users.sourceforge.net>
 
-	* unix/configure.in:	use backslash-quoting instead of double-quoting
-	* unix/tcl.m4:		for lib paths in tclConfig.sh [Bug 1913622].
+	* unix/configure.in:	Use backslash-quoting instead of double-quoting
+	* unix/tcl.m4:		for lib paths in tclConfig.sh. [Bug 1913622]
 	* unix/configure:	autoconf-2.59
 
 2008-03-13  Don Porter	<dgp@users.sourceforge.net>
 
 	* changes:		Updated for 8.5.2 release.
 
-	* generic/tclStrToD.c:	Resolve identifier conflict over "pow10"
-	with libm in Cygwin and DJGPP.  Thanks to Gordon Schumacher and
-	Philip Moore.  [Patch 1800636]
+	* generic/tclStrToD.c:	Resolve identifier conflict over "pow10" with
+	libm in Cygwin and DJGPP. Thanks to Gordon Schumacher and Philip
+	Moore. [Patch 1800636]
 
 2008-03-12  Daniel Steffen  <das@users.sourceforge.net>
 
-	* macosx/Tcl.xcodeproj/project.pbxproj:	add support for Xcode 3.1
+	* macosx/Tcl.xcodeproj/project.pbxproj:	Add support for Xcode 3.1
 	* macosx/Tcl.xcodeproj/default.pbxuser:	CODE_SIGN_IDENTITY and
 	* macosx/Tcl-Common.xcconfig:		'xcodebuild install'.
 
@@ -43,41 +48,41 @@
 	* library/http/http.tcl (http::geturl):	control of selected socket
 	* library/http/pkgIndex.tcl:		interface. [Bug 559898]
 	* doc/http.n, tests/http.test:		Added -keepalive and
-	-protocol 1.1 with chunked transfer encoding support. [Bug
-	1063703, 1470377, 219225] (default keepalive is 0)
+	-protocol 1.1 with chunked transfer encoding support. [Bug 1063703,
+	1470377, 219225] (default keepalive is 0)
 	Added ability to override Host in -headers. [Bug 928154]
 	Added -strict option to control URL validation on per-call basis.
 	[Bug 1560506]
 
 2008-03-11  Jeff Hobbs  <jeffh@ActiveState.com>
 
-	* library/http/http.tcl (http::geturl): add -method option to support
+	* library/http/http.tcl (http::geturl): Add -method option to support
 	* tests/http.test (http-3.1):		http PUT and DELETE requests.
 	* doc/http.n:				[Bug 1599901, 862554]
 
-	* library/http/http.tcl: whitespace changes, code cleanup.  Allow
-	http to be re-sourced without overwriting http state.
+	* library/http/http.tcl: whitespace changes, code cleanup. Allow http
+	to be re-sourced without overwriting http state.
 
 2008-03-11  Daniel Steffen  <das@users.sourceforge.net>
 
-	* generic/tclEncoding.c (LoadEscapeEncoding): avoid leaking escape
+	* generic/tclEncoding.c (LoadEscapeEncoding): Avoid leaking escape
 	sub-encodings, fixes encoding-11.1 failing after iso2022-jp loaded.
 	[Bug 1893053]
 
-	* macosx/tclMacOSXNotify.c: avoid using CoreFoundation after fork() on
+	* macosx/tclMacOSXNotify.c: Avoid using CoreFoundation after fork() on
 	Darwin 9 even when TclpCreateProcess() uses vfork().
 
-	* macosx/Tcl.xcodeproj/project.pbxproj:	add support for Xcode 3.1 and
+	* macosx/Tcl.xcodeproj/project.pbxproj:	Add support for Xcode 3.1 and
 	* macosx/Tcl.xcodeproj/default.pbxuser:	targets for building with
 	* macosx/Tcl-Common.xcconfig:		gcc-4.2 and llvm-gcc-4.2.
 
-	* unix/tclUnixPort.h:			workaround vfork() problems
+	* unix/tclUnixPort.h:			Workaround vfork() problems
 						in llvm-gcc-4.2.1 -O4 build.
 
-	* unix/tclUnixPort.h:			move MODULE_SCOPE compat define
+	* unix/tclUnixPort.h:			Move MODULE_SCOPE compat define
 						to top [Bug 1911102].
 
-	* macosx/GNUmakefile:			fix quoting to allow paths to
+	* macosx/GNUmakefile:			Fix quoting to allow paths to
 	* macosx/Tcl-Common.xcconfig:		${builddir} and ${INSTALL_ROOT}
 	* unix/Makefile.in:			to contain spaces.
 	* unix/configure.in:
@@ -87,23 +92,23 @@
 
 	* unix/configure:			autoconf-2.59
 
-	* unix/Makefile.in (install-strip):	strip non-global symbols from
+	* unix/Makefile.in (install-strip):	Strip non-global symbols from
 						dynamic library.
 
-	* unix/tclUnixNotfy.c:			fix warning.
+	* unix/tclUnixNotfy.c:			Fix warning.
 
-	* tests/exec.test (exec-9.7):		reduce timing sensitivity
+	* tests/exec.test (exec-9.7):		Reduce timing sensitivity
 	* tests/socket.test (socket-2.11):	(esp. on multi-proc machines).
 
-	* tests/fCmd.test (fCmd-9.4):		skip on Darwin 9 (xfail).
+	* tests/fCmd.test (fCmd-9.4):		Skip on Darwin 9 (xfail).
 
 2008-03-11  Miguel Sofer  <msofer@users.sf.net>
 
 	* generic/tclVar.c (TclDeleteNamespaceVars):
-	* tests/var.test (var-8.2): unset traces on vars should be called
-	with a FQ named during namespace deletion. This was causing
-	infinite loops when unset traces recreated the var, as reported by
-	Julian Noble on [Bug 1911919]. 
+	* tests/var.test (var-8.2): unset traces on vars should be called with
+	a FQ named during namespace deletion. This was causing infinite loops
+	when unset traces recreated the var, as reported by Julian Noble. [Bug
+	1911919]
 
 2008-03-10  Don Porter	<dgp@users.sourceforge.net>
 
@@ -114,32 +119,31 @@
 
 	* generic/tclEvent.c (TclDefaultBgErrorHandlerObjCmd):  Added error
 	* tests/event.test (event-5.*):	checking to protect against callers
-	passing invalid return options dictionaries.  [Bug 1901113]
+	passing invalid return options dictionaries. [Bug 1901113]
 
 	* generic/tclBasic.c (ExprAbsFunc):	Revised so that the abs()
 	* tests/expr.test:	function and the [::tcl::mathfunc::abs]
-	command do not return the value of -0, or equivalent values with
-	more alarming string reps like -1e-350.  [Bug 1893815].
+	command do not return the value of -0, or equivalent values with more
+	alarming string reps like -1e-350. [Bug 1893815]
 
 2008-03-07  Andreas Kupries  <andreask@activestate.com>
 
-	* generic/tclResult.c (ReleaseKeys): Workaround for [Bug
-	  1904907]. Reset the return option keys to NULL to allow full
-	  re-initialization by GetKeys(). This introduces a memory leak
-	  for the key objects, but gets us around a crash in the
-	  finalization of reflected channels when handling returns, either
-	  at compile- or runtime. In both cases we access the keys after
-	  they have been released by their thread exit handler. A proper
-	  fix is entangled with the untangling of the finalization
-	  ordering and attendant issues. For now we choose the lesser
-	  evil.
+	* generic/tclResult.c (ReleaseKeys): Workaround for [Bug 1904907].
+	Reset the return option keys to NULL to allow full re-initialization
+	by GetKeys(). This introduces a memory leak for the key objects, but
+	gets us around a crash in the finalization of reflected channels when
+	handling returns, either at compile- or runtime. In both cases we
+	access the keys after they have been released by their thread exit
+	handler. A proper fix is entangled with the untangling of the
+	finalization ordering and attendant issues. For now we choose the
+	lesser evil.
 
 2008-03-07  Don Porter	<dgp@users.sourceforge.net>
 
 	* generic/tclExecute.c (Tcl_ExprObj):	Revised expression bytecode
-	compiling so that bytecodes invalid due to changing context or due
-	to the difference between expressions and scripts are not reused.
-	[Bug 1899164].
+	compiling so that bytecodes invalid due to changing context or due to
+	the difference between expressions and scripts are not reused. [Bug
+	1899164]
 
 	* generic/tclCmdAH.c:	Revised direct evaluation implementation of
 	[expr] so that [expr $e] caches compiled bytecodes for the expression
diff --git a/doc/lreplace.n b/doc/lreplace.n
index 23e49f2..8510a84 100644
--- a/doc/lreplace.n
+++ b/doc/lreplace.n
@@ -5,9 +5,9 @@
 '\"
 '\" 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.16 2007/12/13 15:22:32 dgp Exp $
-'\" 
+'\"
+'\" RCS: @(#) $Id: lreplace.n,v 1.17 2008/03/16 12:38:18 dkf Exp $
+'\"
 .so man.macros
 .TH lreplace n 7.4 Tcl "Tcl Built-In Commands"
 .BS
@@ -17,14 +17,13 @@ lreplace \- Replace elements in a list with new elements
 .SH SYNOPSIS
 \fBlreplace \fIlist first last \fR?\fIelement element ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBlreplace\fR returns a new list formed by replacing one or more elements of
 \fIlist\fR with the \fIelement\fR arguments.
 .VS 8.5
 \fIfirst\fR and \fIlast\fR are index values specifying the first and
-last elements of the range to replace.  
+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
@@ -33,16 +32,16 @@ end of the list.
 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
+.PP
+If \fIfirst\fR is less than zero, it is considered to refer to before the
 first element of the list.  For non-empty lists, the element indicated
-by \fIfirst\fR must exist.
-
-If \fIlast\fR is less than zero but greater than \fIfirst\fR, then any
-specified elements will be prepended to the list.  If \fIlast\fR is
-less than \fIfirst\fR then no elements are deleted; the new elements
-are simply inserted before \fIfirst\fR.
-
+by \fIfirst\fR must exist or \fIfirst\fR must indicate before the
+start of the list.
+.PP
+If \fIlast\fR is less than \fIfirst\fR, then any specified elements
+will be inserted into the list at the point specified by \fIfirst\fR
+with no elements being deleted.
+.PP
 The \fIelement\fR arguments specify zero or more new arguments to
 be added to the list in place of those that were deleted.
 Each \fIelement\fR argument will become a separate element of
@@ -69,14 +68,20 @@ a b c d e
 % set var [\fBlreplace\fR $var end end]
 a b c d
 .CE
-
+.PP
+A procedure to delete a given element from a list:
+.CS
+proc lremove {listVariable value} {
+    upvar 1 $listVariable var
+    set idx [lsearch -exact $var $value]
+    set var [\fBlreplace\fR $var $idx $idx]
+}
+.CE
 .SH "SEE ALSO"
 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
 lset(n), lrange(n), lsort(n),
 .VS 8.5
 string(n)
 .VE
-
-
 .SH KEYWORDS
 element, list, replace