11. Collections and text
11.1 list[T]#
list is a growable ordered collection with identity: two bindings of one list are the same list, is says so, and .copy() makes an independent shallow copy. Indexing is checked.
| Operation | Meaning |
|---|---|
length, is_empty | properties, O(1) |
values[i], values[i] = x | get and set; i out of range traps; negative indexes count from the end |
values[a..<b], values[a..], values[..<b] | a new list of the elements; bounds checked |
append(value), insert(index, value), extend(other), remove_at(index) -> T, pop() -> T, remove(value) -> bool, clear() | shape changes |
first, last | T? |
contains(value), index_of(value) -> int?, count(value) -> int | search, elements equatable |
sort(key = f, reverse = false), sorted(...), reverse(), reversed() | in place and as a copy |
min(key = f) -> T?, max(key = f) -> T? | the first least or greatest; none when empty |
sum() | of a list[int], checked, or a list[float] |
map(function), flat_map(function), filter(predicate), any(predicate), all(predicate), find(predicate) -> T?, reduce(function, initial) | with a function value |
zip(other) -> list[(T, U)], chunks(size) -> list[list[T]], distinct(), indexed() -> list[(int, T)] | new lists |
join(separator) | on list[str] |
a + b | a new list of both |
copy() | a shallow copy |
remove(value) takes out the first element equal to value and says whether there was one. sort and sorted are stable, as Python's are: elements, or their keys, that compare equal keep their order, also with reverse. A key is a function of an element whose result is of an ordered type (§4.4); it is called once per element, in order. Without a key the elements are ordered. While a list sorts, its elements are out of it, as in Python: a key or a comparison sees it empty, and one that changes it traps. min and max compare elements, or their keys, and answer the first least or greatest. sum() adds left to right; an int overflow traps, and a list[float] is added with Neumaier's compensation, as Python's sum does; an empty list sums to zero. any and all stop at the first element that decides, and find answers the first element predicate holds for. reduce(function, initial) folds left, function(function(initial, first), second), its total of the initial value's type, func(A, T) -> A. flat_map joins the lists its function makes. A function given the elements gets a copy of each, and one that changes the list's length traps, as a for over it does (§8.3). zip pairs the elements at each index for the shorter list's length; chunks(size) cuts the list into lists of size, the last shorter, and traps on a size below one; distinct() keeps the first of equal elements, which are hashable, in order; indexed() pairs each element with its index, and in a for walks the list without making the pairs (§8.3).
11.2 map[K, V] and set[T]#
Maps and sets have identity, keep insertion order, and require equatable and hashable keys. m[key] is V?; m.get(key, default) -> V is the value or default; m[key] = v inserts or replaces; m.update(other) inserts or replaces every entry of other, in its order; m.remove(key) -> V?; key in m; m.keys(), m.values(), m.items() iterate. s.insert(x), s.remove(x) -> bool, x in s, s.union(t), s.intersection(t), s.difference(t), s.symmetric_difference(t), each a new set in the order of s and then t, and the tests s.is_subset(t), s.is_superset(t), s.is_disjoint(t). Both have length, is_empty, clear(), copy().
11.3 str#
str is immutable UTF-8 with value semantics and content equality.
| Operation | Meaning |
|---|---|
length | scalars, O(n); byte_count is O(1); is_empty |
a + b, f"..." | concatenation and formatting |
text[a..<b] | a substring by scalar index; bounds checked |
for c in text, characters() -> list[str] | one-scalar strings |
contains(text), starts_with(prefix), ends_with(suffix), index_of(text) -> int?, last_index_of(text) -> int?, count(text) -> int | search |
split() -> list[str], split(separator), lines() | pieces |
trim(), trim_start(), trim_end(), remove_prefix(prefix), remove_suffix(suffix) | the text without some of it |
upper(), lower(), capitalize(), title(), replace(old, new), repeat(count), reversed() | the common transforms |
pad_left(width, fill = " "), pad_right(width, fill = " "), center(width, fill = " ") | padded to a width in scalars |
is_digit(), is_alpha(), is_alnum(), is_space() | ASCII classes |
bytes() | the UTF-8 as bytes |
White space is ASCII's: space, tab, line feed, carriage return, vertical tab and form feed. split() cuts at runs of white space and keeps no empty piece, as Python's does; split(separator) cuts at every occurrence of a non-empty separator, keeping empty pieces, so "a,,b".split(",") is ["a", "", "b"]; an empty separator traps. lines() cuts at "\n", drops a "\r" before it, and a trailing newline ends the last line rather than opening an empty one. trim() removes white space at both ends, trim_start() and trim_end() at one. count(text) counts occurrences that do not overlap, left to right, and traps on an empty text; last_index_of finds the last occurrence, an empty text at the end. remove_prefix and remove_suffix remove one occurrence at that end, or nothing. upper() and lower() map the ASCII letters; capitalize() maps the first scalar up and the rest down, and title() the first letter of every word up and the rest down, a word being a run of letters in which any scalar past ASCII counts as one and stays as it is. replace(old, new) replaces every non-overlapping occurrence left to right and traps on an empty old; repeat(count) traps on a negative count; reversed() reverses the scalars. pad_left puts the fill before the text, pad_right after it, and center on both sides, the odd one where Python's str.center puts it; a width the text already has changes nothing, and a fill that is not one scalar traps. The is_ tests are true when the text has a scalar and every one is an ASCII digit, letter, either, or white space. Normalisation, grapheme segmentation, collation and locale are library operations.
11.4 bytes#
Immutable, with length, data[i] as an int 0 to 255, slicing, +, equality, and text(), which decodes UTF-8 and is str!, failing with the message invalid UTF-8. Bytes are what a Base package hands a Luce program when the data is not text; a Luce program does not compute on bytes, it passes them.