summaryrefslogtreecommitdiffstats
path: root/doc/linsert.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/linsert.n')
-rw-r--r--doc/linsert.n29
1 files changed, 17 insertions, 12 deletions
diff --git a/doc/linsert.n b/doc/linsert.n
index d73a05a..51b64cf 100644
--- a/doc/linsert.n
+++ b/doc/linsert.n
@@ -13,24 +13,30 @@
.SH NAME
linsert \- Insert elements into a list
.SH SYNOPSIS
-\fBlinsert \fIlist index element \fR?\fIelement element ...\fR?
+\fBlinsert \fIlist index \fR?\fIelement element ...\fR?
.BE
-
.SH DESCRIPTION
.PP
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.
-.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
+elements are inserted at the beginning of the list, and if \fIindex\fR is
+greater or equal to the length of \fIlist\fR, it is as if it was \fBend\fR.
+As with \fBstring index\fR, the \fIindex\fR value supports both simple index
+arithmetic and end-relative indexing.
+.PP
+Subject to the restrictions that indices must refer to locations inside the
+list and that the \fIelement\fRs will always be inserted in order, insertions
+are done so that when \fIindex\fR is start-relative, the first \fIelement\fR
+will be at that index in the resulting list, and when \fIindex\fR is
+end-relative, the last \fIelement\fR will be at that index in the resulting
+list.
.SH EXAMPLE
+.PP
Putting some values into a list, first indexing from the start and
then indexing from the end, and then chaining them together:
+.PP
.CS
set oldList {the fox jumps over the dog}
set midList [\fBlinsert\fR $oldList 1 quick]
@@ -38,13 +44,12 @@ set newList [\fBlinsert\fR $midList end-1 lazy]
# The old lists still exist though...
set newerList [\fBlinsert\fR [\fBlinsert\fR $oldList end-1 quick] 1 lazy]
.CE
-
.SH "SEE ALSO"
list(n), lappend(n), lindex(n), llength(n), lsearch(n),
lset(n), lsort(n), lrange(n), lreplace(n),
-.VS 8.5
string(n)
-.VE
-
.SH KEYWORDS
element, insert, list
+'\" Local Variables:
+'\" mode: nroff
+'\" End: