diff options
Diffstat (limited to 'doc/lreplace.n')
-rw-r--r-- | doc/lreplace.n | 55 |
1 files changed, 34 insertions, 21 deletions
diff --git a/doc/lreplace.n b/doc/lreplace.n index 600a986..2cd79d8 100644 --- a/doc/lreplace.n +++ b/doc/lreplace.n @@ -1,7 +1,7 @@ '\" '\" Copyright (c) 1993 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved. +'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -15,26 +15,31 @@ 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. -\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. - -If \fIfirst\fR is less than zero, it is considered to refer to the +.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 +.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 @@ -61,12 +66,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" -.VS 8.4 -list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), -lset(n), lrange(n), lsort(n) +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 |