diff options
Diffstat (limited to 'doc/lreplace.n')
-rw-r--r-- | doc/lreplace.n | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/doc/lreplace.n b/doc/lreplace.n new file mode 100644 index 0000000..d19f0cd --- /dev/null +++ b/doc/lreplace.n @@ -0,0 +1,86 @@ +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" 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. +'\" +.TH lreplace n 7.4 Tcl "Tcl Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +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 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. +.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 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 before 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 +the list. If no \fIelement\fR arguments are specified, then the elements +between \fIfirst\fR and \fIlast\fR are simply deleted. If \fIlist\fR +is empty, any \fIelement\fR arguments are added to the end of the list. +.SH EXAMPLES +.PP +Replacing an element of a list with another: +.PP +.CS +% \fBlreplace\fR {a b c d e} 1 1 foo +a foo c d e +.CE +.PP +Replacing two elements of a list with three: +.PP +.CS +% \fBlreplace\fR {a b c d e} 1 2 three more elements +a three more elements d e +.CE +.PP +Deleting the last element from a list in a variable: +.PP +.CS +% set var {a b c d e} +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: +.PP +.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), +string(n) +.SH KEYWORDS +element, list, replace |