BlueScript: List Procedures
Contents
Description
Procedures for creating and manipulating lists.
Documentation
Many of the procedures in this package allow for
the specification of an index into a string.
An index can have any of the following formats:
- n - where n is an integer representing an
offset into the list. The first element in the list is index
0, the second element is 1, etc.
end - indicating the last element in the list.end-n - indicating the
last-but-n'th element of the list. For example,
end-0 is equivalent to end while
end-1 is the second-last element of the list.
All elements outside of a list's valid elements are
assumed to be empty strings. For example, "lindex $l -1" will
always return an empty string. However, if a request is made
for a range of elements that extends outside of the list then
the result is trimmed to be just those elements that are part
of the actual list. For example, "lrange $l -3 5" has the
same result as "lrange $l 0 5". If "$l" has only 3 elements,
then "lrange $l 0 5" has the same result as "lrange $l 0 2".
Procedures
lconcat
Usage
lconcat [list ...]
Examples
1. Concatenating two lists
lconcat {a b c} {d e f}
Result: a b c
d e f
lempty
Usage
lempty list
Examples
1. Testing an empty list
lempty {}
Result: 1
2. Testing a non-empty list
lempty {a b c}
Result: 0
lindex
Usage
lindex list i
Returns
The element located at index i in list.
Examples
1. Retrieve the third element in the list {a b c}.
lindex
{a b c} 2
Result: c
list
Usage
list [elem ...]
Generally, creating a list via the list command
is safer and faster than explicitly creating a string
(e.g. through quote substitution) and then allowing the engine
to parse the generated string.
Examples
1. Creating an empty list
list
Result: none
2. Creating a list of three elements
list a b c
Result: a b c
llength
Usage
llength list
Returns
The number of elements in the list.
Examples
1. Getting the length of a list
llength {a b c d}
Result: 4
lpop
Usage
lpop var
Examples
1. Popping an element
set x {a b c}
lpop x
Result: c
2. List after popping
set x
Result: a b
lpush
Usage
lpush var elem
Examples
1. Pushing an element
set x {a b c}
lpush x d
set x
Result: a b c d
lrange
Usage
lrange list start finish
Returns
A list containing the elements of list between indices
start and finish inclusive.
Examples
1. Return the first three elements of the list {a b c d e
f}
lrange {a b c d e f} 0 2
Result: a b c
2. Return the last 2 elements of the list {a b c d e f}
lrange {a b c d e f} end-1 end
Result: e f
lreplace
Usage
lreplace list start finish [elem ...]
Returns
A modified copy of list.
Creates a copy of list
with the range of elements between start and
finish inclusive replaced with the new elements
(elem ...) specified on the command line. If no
new elements are specified, then the returned copy of
list will merely have the elements between start
and finish inclusive, deleted.
Examples
1. Replace the third element of {a b c d} with {e f}
lreplace {a b c d} 2 2 e f
Result: a b e f d
2. Remove the first two elements of {a b c d e f}
lreplace
{a b c d e f} 0 1
Result: c d e f
lshift
Usage
lshift var
Examples
1. Shifting an element
set x {a b c}
lshift x
Result: a
2. List after shifting
set x
Result: b c
lunshift
Usage
lunshift var elem
Examples
1. Unshifting an element
set x {a b c}
lunshift x d
set x
Result: d a b c