| delete() | insert() | join() | listgraft() |
| listidx() | listlen() | replace() | setadd() |
| setremove() | sublist() | union() |
delete()
LIST delete(LIST list, INTEGER pos)
This function deletes the element in the argument list, pointed to by the position argument pos, and returns the result. If position is less than 1 or is greater than the length of list, then the function throws a ~range error.
delete([2, 3, 4], 2)
=> [2, 4]
insert()
LIST insert(LIST list, INTEGER pos, ANY value)
This function inserts value into list before the element specified by the integer pos. If pos is equal to listlen(list) + 1 then value will be appended to the end of the list. Otherwise, if pos is outside the range of the list, the error ~range is thrown.
insert([2, 3, 4], 3, 'foo)
=> [2, 3, 'foo, 4]
insert(["foo", 'bar, ~none], 4, 'baz)
=> ["foo", 'bar, ~none, 'baz]
The function listgraft() performs a similar role to this function.
join()
STRING join(LIST list[, STRING seperator])
This function joins a list together as a string. The second argument is used to specify what seperates each element in the list. If the second argument is unspecified, this will default to a single space. If any element in the list is not a string, it will have a literal representation used instead, in the same manner as when using non-arithmetic operators.
join(["Joe", "Sally", "Bob", "Sue"])
=> "Joe Sally Bob Sue"
join(["This", "That", 'there, 10], ", ")
=> "This, That, there, 10"
listgraft()
LIST listgraft(LIST list1, INTEGER pos, LIST list2)
This function is similar to the splice operator and insert(), except it grafts a list into another list rather than inserting an element at a point in the list. It will take the list specified by list2 and place each element in that list into the list specified by list1, starting at the position specified by pos. If pos is equal to listlen(list) + 1, then list2 will be appended to the end of list1.
listgraft([1, 2, 3, 4, 5], 3, ["foo", "bar", "baz"])
=> [1, 2, "foo", "bar", "baz", 3, 4, 5]
listidx()
INTEGER listidx(LIST list, ANY what[, INTEGER origin])
This function returns the position in the list, starting from origin, where what exists or 0 (zero) if it does not exist. If origin is not specified it will default to 1. The origin represents where to start searching in the list. If it is a positive number it starts that many elements into the list. If it is a negative number it starts that many elements from the end of the list, and searches backwards from the end of the list to the start.
listidx([4, "this", [], 'bar], [])
=> 3
listidx([4, "this", [], "this", 'bar], "this", -1)
=> 4
listidx([4, "this", [], "this", 'bar], "this", -3)
=> 2
listlen()
INTEGER listlen(LIST list)
This function returns the length of list.
listlen(['foo, 'bar, 'baz])
=> 3
replace()
LIST replace(LIST list, INTEGER pos, ANY value)
This function replaces the element in the argument list pointed to by the argument pos with the argument value, and returns the result. If posis outside the range of the list, the error ~range is thrown.
replace([2, 3, 4], 2, 'foo)
=> [2, 'foo, 4]
setadd()
LIST setadd(LIST list, ANY value)
This function appends the argument value to the argument list, if it is not already in the list, and returns the result. If value is already in the list, it does not add it.
setadd([2, 3, 4], 'foo)
=> [2, 3, 4, 'foo]
setadd([2, 3, 4], 3)
=> [2, 3, 4]
setremove()
LIST setremove(LIST list, ANY value)
This function removes the first instance of the argument value from the argument list, if it exists, and returns the result.
setremove([2, 3, 4, 'foo], 'foo)
=> [2, 3, 4]
setremove([2, 3, 4], 5)
=> [2, 3, 4]
setremove([2, 3, 2, 4], 2)
=> [3, 2, 4]
sublist()
LIST sublist(LIST list, INTEGER start[, INTEGER length])
This function returns a subrange of the list specified by list. The subrange starts at position start, and continues length elements. If length is unspecified, it will continue to the end of the list. If start is equal to listlen(list) + 1 and length is 0, an empty list will be returned. Otherwise, if start is outside of the range of the list, or length will extend past the end of the list, the error ~range is thrown.
sublist([2, 3, 4, 5, 6, 7], 2, 3)
=> [3, 4, 5]
sublist([2, 3, 4, 5, 6, 7], 3)
=> [4, 5, 6, 7]
sublist([2, 3, 4, 5, 6, 7], 7)
=> []
union()
LIST union(LIST list1, LIST list2)
This function adds each element of list2 to list1 which does not already exist in list1. Elements which exist more than once in list2 will only be added to list1 once, but duplicate elements in list1 will remain.
union([2, 3, 4], [4, 5, 4, 6])
=> [2, 3, 4, 5, 6]
union([2, 2, 4, 5], [4, 5, 6, 6, 7])
=> [2, 2, 4, 5, 6, 7])
