1 | '\" |
---|
2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. |
---|
5 | '\" |
---|
6 | '\" See the file "license.terms" for information on usage and redistribution |
---|
7 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
8 | '\" |
---|
9 | '\" RCS: @(#) $Id: lreplace.n,v 1.19 2008/03/26 09:59:22 dkf Exp $ |
---|
10 | '\" |
---|
11 | .so man.macros |
---|
12 | .TH lreplace n 7.4 Tcl "Tcl Built-In Commands" |
---|
13 | .BS |
---|
14 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
15 | .SH NAME |
---|
16 | lreplace \- Replace elements in a list with new elements |
---|
17 | .SH SYNOPSIS |
---|
18 | \fBlreplace \fIlist first last \fR?\fIelement element ...\fR? |
---|
19 | .BE |
---|
20 | .SH DESCRIPTION |
---|
21 | .PP |
---|
22 | \fBlreplace\fR returns a new list formed by replacing one or more elements of |
---|
23 | \fIlist\fR with the \fIelement\fR arguments. |
---|
24 | .VS 8.5 |
---|
25 | \fIfirst\fR and \fIlast\fR are index values specifying the first and |
---|
26 | last elements of the range to replace. |
---|
27 | The index values \fIfirst\fR and \fIlast\fR are interpreted |
---|
28 | the same as index values for the command \fBstring index\fR, |
---|
29 | supporting simple index arithmetic and indices relative to the |
---|
30 | end of the list. |
---|
31 | 0 refers to the first element of the |
---|
32 | list, and \fBend\fR refers to the last element of the list. |
---|
33 | If \fIlist\fR is empty, then \fIfirst\fR and \fIlast\fR are ignored. |
---|
34 | .VE |
---|
35 | .PP |
---|
36 | If \fIfirst\fR is less than zero, it is considered to refer to before the |
---|
37 | first element of the list. For non-empty lists, the element indicated |
---|
38 | by \fIfirst\fR must exist or \fIfirst\fR must indicate before the |
---|
39 | start of the list. |
---|
40 | .PP |
---|
41 | If \fIlast\fR is less than \fIfirst\fR, then any specified elements |
---|
42 | will be inserted into the list at the point specified by \fIfirst\fR |
---|
43 | with no elements being deleted. |
---|
44 | .PP |
---|
45 | The \fIelement\fR arguments specify zero or more new arguments to |
---|
46 | be added to the list in place of those that were deleted. |
---|
47 | Each \fIelement\fR argument will become a separate element of |
---|
48 | the list. If no \fIelement\fR arguments are specified, then the elements |
---|
49 | between \fIfirst\fR and \fIlast\fR are simply deleted. If \fIlist\fR |
---|
50 | is empty, any \fIelement\fR arguments are added to the end of the list. |
---|
51 | .SH EXAMPLES |
---|
52 | Replacing an element of a list with another: |
---|
53 | .CS |
---|
54 | % \fBlreplace\fR {a b c d e} 1 1 foo |
---|
55 | a foo c d e |
---|
56 | .CE |
---|
57 | .PP |
---|
58 | Replacing two elements of a list with three: |
---|
59 | .CS |
---|
60 | % \fBlreplace\fR {a b c d e} 1 2 three more elements |
---|
61 | a three more elements d e |
---|
62 | .CE |
---|
63 | .PP |
---|
64 | Deleting the last element from a list in a variable: |
---|
65 | .CS |
---|
66 | % set var {a b c d e} |
---|
67 | a b c d e |
---|
68 | % set var [\fBlreplace\fR $var end end] |
---|
69 | a b c d |
---|
70 | .CE |
---|
71 | .PP |
---|
72 | A procedure to delete a given element from a list: |
---|
73 | .CS |
---|
74 | proc lremove {listVariable value} { |
---|
75 | upvar 1 $listVariable var |
---|
76 | set idx [lsearch -exact $var $value] |
---|
77 | set var [\fBlreplace\fR $var $idx $idx] |
---|
78 | } |
---|
79 | .CE |
---|
80 | .SH "SEE ALSO" |
---|
81 | list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), |
---|
82 | lset(n), lrange(n), lsort(n), |
---|
83 | .VS 8.5 |
---|
84 | string(n) |
---|
85 | .VE |
---|
86 | .SH KEYWORDS |
---|
87 | element, list, replace |
---|