List Methods

List methods are pure. Methods with mutating Python names return a new list instead of changing the receiver.

Signatures

| Method | Returns | Notes | | ----------------------------- | -------------------------- | -------------------------------------------------- | | xs.append(object) | list | Adds object at the end. | | xs.extend(iterable) | list | Extends with a list, tuple, or string. | | xs.insert(index, object) | list | Inserts before normalized index. | | xs.remove(value) | list \| err | ValueError/NLK4002 when value is absent. | | xs.pop() | tuple[item, list] \| err | IndexError/NLK4004 when the list is empty. | | xs.pop(index) | tuple[item, list] \| err | IndexError/NLK4004 when index is out of range. | | xs.clear() | list | Returns an empty list. | | xs.reverse() | list | Returns reversed items. | | xs.copy() | list | Returns a shallow copy. | | xs.deepcopy() | list | Returns a deep copy. | | xs.set(index, value) | list \| err | IndexError/NLK4004 unless index exists. | | xs.index(value) | num \| err | ValueError/NLK4002 when absent. | | xs.index(value, start) | num \| err | First index at or after start, or error. | | xs.index(value, start, end) | num \| err | First index in the normalized range, or error. | | xs.count(value) | num | Count of structurally equal items. | | xs.get(index) | item | err | Item, or IndexError/NLK4004 on a miss. |

Errors

Indexes must be integers. Raw indexing is fatal on an out-of-range index. get() is the safe value-level alternative and returns IndexError/NLK4004 on a miss. remove() and index() return registered value errors when the item is not present. extend() accepts only a list, tuple, or string.

Negative indexes count from the end. insert(index, object) clamps low and high indexes into the insertion range. Existing-index operations such as pop(index) and set(index, value) require the normalized index to exist.

pop() on an empty list returns IndexError/NLK4004. remove, index, and count use structural equality. These recoverable failures must be handled with catch, try, or an error-capable annotation before the value is used.

copy() is shallow. deepcopy() recursively copies nested Nilakan containers.

Errors cannot participate in remove, index, or count, including when structural traversal reaches an error stored inside a container.

Examples

xs = [1, 2]
ys = xs.append(3)
print(xs)
print(ys)

item, rest = ys.pop(0) catch (0, ys)
print(item)
print(rest)

print(ys.set(1, 20))

base = [[1], [2]]
shallow = base.copy()
deep = base.deepcopy()
base[0][0] = 9
print(shallow)
print(deep)