(622 lines)

% API

Builtins

List

List.binary_search

List.binary_search : func(list: [T], by: func(x,y:&T->Int32) = T.compare -> Int)

Performs a binary search on a sorted list.

Argument	Type	Description	Default
list	`[T]`	The sorted list to search.	-
by	`func(x,y:&T->Int32)`	The comparison function used to determine order. If not specified, the default comparison function for the item type will be used.	`T.compare`

Return: Assuming the input list is sorted according to the given comparison function, return the index where the given item would be inserted to maintain the sorted order. That is, if the item is found, return its index, otherwise return the place where it would be found if it were inserted and the list were sorted.

Example:

assert [1, 3, 5, 7, 9].binary_search(5) == 3
assert [1, 3, 5, 7, 9].binary_search(-999) == 1
assert [1, 3, 5, 7, 9].binary_search(999) == 6

List.by

List.by : func(list: [T], step: Int -> [T])

Creates a new list with elements spaced by the specified step value.

Argument	Type	Description	Default
list	`[T]`	The original list.	-
step	`Int`	The step value for selecting elements.	-

Return: A new list with every step-th element from the original list.

Example:

assert [1, 2, 3, 4, 5, 6].by(2) == [1, 3, 5]

List.clear

List.clear : func(list: @[T] -> Void)

Clears all elements from the list.

Argument	Type	Description	Default
list	`@[T]`	The mutable reference to the list to be cleared.	-

Return: Nothing.

Example:

list := &[10, 20]
list.clear()
assert list[] == []

List.counts

List.counts : func(list: [T] -> {T=Int})

Counts the occurrences of each element in the list.

Argument	Type	Description	Default
list	`[T]`	The list to count elements in.	-

Return: A table mapping each element to its count.

Example:

assert [10, 20, 30, 30, 30].counts() == {10:1, 20:1, 30:3}

List.find

List.find : func(list: [T], target: T -> Int?)

Finds the index of the first occurrence of an element (if any).

Argument	Type	Description	Default
list	`[T]`	The list to search through.	-
target	`T`	The item to search for.	-

Return: The index of the first occurrence or none if not found.

Example:

assert [10, 20, 30, 40, 50].find(20) == 2
assert [10, 20, 30, 40, 50].find(9999) == none

List.from

List.from : func(list: [T], first: Int -> [T])

Returns a slice of the list starting from a specified index.

Argument	Type	Description	Default
list	`[T]`	The original list.	-
first	`Int`	The index to start from.	-

Return: A new list starting from the specified index.

Example:

assert [10, 20, 30, 40, 50].from(3) == [30, 40, 50]

List.has

List.has : func(list: [T], target: T -> Bool)

Checks if the list has an element.

Argument	Type	Description	Default
list	`[T]`	The list to check.	-
target	`T`	The element to check for.	-

Return: yes if the list has the element, no otherwise.

Example:

assert [10, 20, 30].has(20) == yes

List.heap_pop

List.heap_pop : func(list: @[T], by: func(x,y:&T->Int32) = T.compare -> T?)

Removes and returns the top element of a heap or none if the list is empty. By default, this is the minimum value in the heap.

Argument	Type	Description	Default
list	`@[T]`	The mutable reference to the heap.	-
by	`func(x,y:&T->Int32)`	The comparison function used to determine order. If not specified, the default comparison function for the item type will be used.	`T.compare`

Return: The removed top element of the heap or none if the list is empty.

Example:

my_heap := &[30, 10, 20]
my_heap.heapify()
assert my_heap.heap_pop() == 10

List.heap_push

List.heap_push : func(list: @[T], item: T, by = T.compare -> Void)

Adds an element to the heap and maintains the heap property. By default, this is a minimum heap.

Argument	Type	Description	Default
list	`@[T]`	The mutable reference to the heap.	-
item	`T`	The item to be added.	-
by	``	The comparison function used to determine order. If not specified, the default comparison function for the item type will be used.	`T.compare`

Return: Nothing.

Example:

my_heap : &[Int]
my_heap.heap_push(10)
assert my_heap.heap_pop() == 10

List.heapify

List.heapify : func(list: @[T], by: func(x,y:&T->Int32) = T.compare -> Void)

Converts a list into a heap.

Argument	Type	Description	Default
list	`@[T]`	The mutable reference to the list to be heapified.	-
by	`func(x,y:&T->Int32)`	The comparison function used to determine order. If not specified, the default comparison function for the item type will be used.	`T.compare`

Return: Nothing.

Example:

my_heap := &[30, 10, 20]
my_heap.heapify()

List.insert

List.insert : func(list: @[T], item: T, at: Int = 0 -> Void)

Inserts an element at a specified position in the list.

Since indices are 1-indexed and negative indices mean "starting from the back", an index of 0 means "after the last item".

Argument	Type	Description	Default
list	`@[T]`	The mutable reference to the list.	-
item	`T`	The item to be inserted.	-
at	`Int`	The index at which to insert the item.	`0`

Return: Nothing.

Example:

list := &[10, 20]
list.insert(30)
assert list == [10, 20, 30]

list.insert(999, at=2)
assert list == [10, 999, 20, 30]

List.insert_all

List.insert_all : func(list: @[T], items: [T], at: Int = 0 -> Void)

Inserts a list of items at a specified position in the list.

Since indices are 1-indexed and negative indices mean "starting from the back", an index of 0 means "after the last item".

Argument	Type	Description	Default
list	`@[T]`	The mutable reference to the list.	-
items	`[T]`	The items to be inserted.	-
at	`Int`	The index at which to insert the item.	`0`

Return: Nothing.

Example:

list := &[10, 20]
list.insert_all([30, 40])
assert list == [10, 20, 30, 40]

list.insert_all([99, 100], at=2)
assert list == [10, 99, 100, 20, 30, 40]

List.pop

List.pop : func(list: &[T], index: Int = -1 -> T?)

Removes and returns an item from the list. If the given index is present in the list, the item at that index will be removed and the list will become one element shorter.

Since negative indices are counted from the back, the default behavior is to pop the last value.

Argument	Type	Description	Default
list	`&[T]`	The list to remove an item from.	-
index	`Int`	The index from which to remove the item.	`-1`

Return: none if the list is empty or the given index does not exist in the list, otherwise the item at the given index.

Example:

list := &[10, 20, 30, 40]

assert list.pop() == 40
assert list[] == [10, 20, 30]

assert list.pop(index=2) == 20
assert list[] == [10, 30]

List.random

List.random : func(list: [T], random: func(min,max:Int64->Int64)? = none -> T?)

Selects a random element from the list.

Argument	Type	Description	Default
list	`[T]`	The list from which to select a random element.	-
random	`func(min,max:Int64->Int64)?`	If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation)	`none`

Return: A random element from the list or none if the list is empty.

Example:

nums := [10, 20, 30]
pick := nums.random()!
assert nums.has(pick)
empty : [Int]
assert empty.random() == none

List.remove_at

List.remove_at : func(list: @[T], at: Int = -1, count: Int = 1 -> Void)

Removes elements from the list starting at a specified index.

Since negative indices are counted from the back, the default behavior is to remove the last item.

Argument	Type	Description	Default
list	`@[T]`	The mutable reference to the list.	-
at	`Int`	The index at which to start removing elements.	`-1`
count	`Int`	The number of elements to remove.	`1`

Return: Nothing.

Example:

list := &[10, 20, 30, 40, 50]
list.remove_at(2)
assert list == [10, 30, 40, 50]

list.remove_at(2, count=2)
assert list == [10, 50]

List.remove_item

List.remove_item : func(list: @[T], item: T, max_count: Int = -1 -> Void)

Removes all occurrences of a specified item from the list.

A negative max_count means "remove all occurrences".

Argument	Type	Description	Default
list	`@[T]`	The mutable reference to the list.	-
item	`T`	The item to be removed.	-
max_count	`Int`	The maximum number of occurrences to remove.	`-1`

Return: Nothing.

Example:

list := &[10, 20, 10, 20, 30]
list.remove_item(10)
assert list == [20, 20, 30]

list.remove_item(20, max_count=1)
assert list == [20, 30]

List.reversed

List.reversed : func(list: [T] -> [T])

Returns a reversed slice of the list.

Argument	Type	Description	Default
list	`[T]`	The list to be reversed.	-

Return: A slice of the list with elements in reverse order.

Example:

assert [10, 20, 30].reversed() == [30, 20, 10]

List.sample

List.sample : func(list: [T], count: Int, weights: [Num]? = none, random: func(->Num)? = none -> [T])

Selects a sample of elements from the list, optionally with weighted probabilities.

Errors will be raised if any of the following conditions occurs: - The given list has no elements and count >= 1 - count < 0 (negative count) - The number of weights provided doesn't match the length of the list. - Any weight in the weights list is negative, infinite, or NaN - The sum of the given weights is zero (zero probability for every element).

Argument	Type	Description	Default
list	`[T]`	The list to sample from.	-
count	`Int`	The number of elements to sample.	-
weights	`[Num]?`	The probability weights for each element in the list. These values do not need to add up to any particular number, they are relative weights. If no weights are given, elements will be sampled with uniform probability.	`none`
random	`func(->Num)?`	If provided, this function will be used to get random values for sampling the list. The provided function should return random numbers between `0.0` (inclusive) and `1.0` (exclusive). (Used for deterministic pseudorandom number generation)	`none`

Return: A list of sampled elements from the list.

Example:

_ := [10, 20, 30].sample(2, weights=[90%, 5%, 5%]) # E.g. [10, 10]

List.shuffle

List.shuffle : func(list: @[T], random: func(min,max:Int64->Int64)? = none -> Void)

Shuffles the elements of the list in place.

Argument	Type	Description	Default
list	`@[T]`	The mutable reference to the list to be shuffled.	-
random	`func(min,max:Int64->Int64)?`	If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation)	`none`

Return: Nothing.

Example:

nums := &[10, 20, 30, 40]
nums.shuffle()
# E.g. [20, 40, 10, 30]

List.shuffled

List.shuffled : func(list: [T], random: func(min,max:Int64->Int64)? = none -> [T])

Creates a new list with elements shuffled.

Argument	Type	Description	Default
list	`[T]`	The list to be shuffled.	-
random	`func(min,max:Int64->Int64)?`	If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation)	`none`

Return: A new list with shuffled elements.

Example:

nums := [10, 20, 30, 40]
_ := nums.shuffled()
# E.g. [20, 40, 10, 30]

List.slice

List.slice : func(list: [T], from: Int, to: Int -> [T])

Returns a slice of the list spanning the given indices (inclusive).

Argument	Type	Description	Default
list	`[T]`	The original list.	-
from	`Int`	The first index to include.	-
to	`Int`	The last index to include.	-

Return: A new list spanning the given indices. Note: negative indices are counted from the back of the list, so -1 refers to the last element, -2 the second-to-last, and so on.

Example:

assert [10, 20, 30, 40, 50].slice(2, 4) == [20, 30, 40]
assert [10, 20, 30, 40, 50].slice(-3, -2) == [30, 40]

List.sort

List.sort : func(list: @[T], by = T.compare -> Void)

Sorts the elements of the list in place in ascending order (small to large).

Argument	Type	Description	Default
list	`@[T]`	The mutable reference to the list to be sorted.	-
by	``	The comparison function used to determine order. If not specified, the default comparison function for the item type will be used.	`T.compare`

Return: Nothing.

Example:

list := &[40, 10, -30, 20]
list.sort()
assert list == [-30, 10, 20, 40]

list.sort(func(a,b:&Int) a.abs() <> b.abs())
assert list == [10, 20, -30, 40]

List.sorted

List.sorted : func(list: [T], by = T.compare -> [T])

Creates a new list with elements sorted.

Argument	Type	Description	Default
list	`[T]`	The list to be sorted.	-
by	``	The comparison function used to determine order. If not specified, the default comparison function for the item type will be used.	`T.compare`

Return: A new list with sorted elements.

Example:

assert [40, 10, -30, 20].sorted() == [-30, 10, 20, 40]
assert [40, 10, -30, 20].sorted(
   func(a,b:&Int) a.abs() <> b.abs()
) == [10, 20, -30, 40]

List.to

List.to : func(list: [T], last: Int -> [T])

Returns a slice of the list from the start of the original list up to a specified index (inclusive).

Argument	Type	Description	Default
list	`[T]`	The original list.	-
last	`Int`	The index up to which elements should be included.	-

Return: A new list containing elements from the start up to the specified index.

Example:

assert [10, 20, 30, 40, 50].to(3) == [10, 20, 30]
assert [10, 20, 30, 40, 50].to(-2) == [10, 20, 30, 40]

List.unique

List.unique : func(list: [T] -> {T})

Returns a set of the unique elements of the list.

Argument	Type	Description	Default
list	`[T]`	The list to process.	-

Return: A set of the unique elements from the list.

Example:

assert [10, 20, 10, 10, 30].unique() == {10, 20, 30}

List.where

List.where : func(list: [T], predicate: func(item:&T -> Bool) -> Int)

Find the index of the first item that matches a predicate function (if any).

Argument	Type	Description	Default
list	`[T]`	The list to search through.	-
predicate	`func(item:&T -> Bool)`	A function that returns `yes` if the item's index should be returned or `no` if it should not.	-

Return: Returns the index of the first item where the predicate is true or none if no item matches.

Example:

assert ["BC", "ABC", "CD"].where(func(t:&Text) t.starts_with("A")) == 2
assert ["BC", "ABC", "CD"].where(func(t:&Text) t.starts_with("X")) == none

   1 % API
   2 
   3 # Builtins
   4 
   5 # List
   6 ## List.binary_search
   7 
   8 ```tomo
   9 List.binary_search : func(list: [T], by: func(x,y:&T->Int32) = T.compare -> Int)
  10 ```
  11 
  12 Performs a binary search on a sorted list.
  13 
  14 Argument | Type | Description | Default
  15 ---------|------|-------------|---------
  16 list | `[T]` | The sorted list to search.  | -
  17 by | `func(x,y:&T->Int32)` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used.  | `T.compare`
  18 
  19 **Return:** Assuming the input list is sorted according to the given comparison function, return the index where the given item would be inserted to maintain the sorted order. That is, if the item is found, return its index, otherwise return the place where it would be found if it were inserted and the list were sorted.
  20 
  21 
  22 **Example:**
  23 ```tomo
  24 assert [1, 3, 5, 7, 9].binary_search(5) == 3
  25 assert [1, 3, 5, 7, 9].binary_search(-999) == 1
  26 assert [1, 3, 5, 7, 9].binary_search(999) == 6
  27 
  28 ```
  29 ## List.by
  30 
  31 ```tomo
  32 List.by : func(list: [T], step: Int -> [T])
  33 ```
  34 
  35 Creates a new list with elements spaced by the specified step value.
  36 
  37 Argument | Type | Description | Default
  38 ---------|------|-------------|---------
  39 list | `[T]` | The original list.  | -
  40 step | `Int` | The step value for selecting elements.  | -
  41 
  42 **Return:** A new list with every `step`-th element from the original list.
  43 
  44 
  45 **Example:**
  46 ```tomo
  47 assert [1, 2, 3, 4, 5, 6].by(2) == [1, 3, 5]
  48 
  49 ```
  50 ## List.clear
  51 
  52 ```tomo
  53 List.clear : func(list: @[T] -> Void)
  54 ```
  55 
  56 Clears all elements from the list.
  57 
  58 Argument | Type | Description | Default
  59 ---------|------|-------------|---------
  60 list | `@[T]` | The mutable reference to the list to be cleared.  | -
  61 
  62 **Return:** Nothing.
  63 
  64 
  65 **Example:**
  66 ```tomo
  67 list := &[10, 20]
  68 list.clear()
  69 assert list[] == []
  70 
  71 ```
  72 ## List.counts
  73 
  74 ```tomo
  75 List.counts : func(list: [T] -> {T=Int})
  76 ```
  77 
  78 Counts the occurrences of each element in the list.
  79 
  80 Argument | Type | Description | Default
  81 ---------|------|-------------|---------
  82 list | `[T]` | The list to count elements in.  | -
  83 
  84 **Return:** A table mapping each element to its count.
  85 
  86 
  87 **Example:**
  88 ```tomo
  89 assert [10, 20, 30, 30, 30].counts() == {10:1, 20:1, 30:3}
  90 
  91 ```
  92 ## List.find
  93 
  94 ```tomo
  95 List.find : func(list: [T], target: T -> Int?)
  96 ```
  97 
  98 Finds the index of the first occurrence of an element (if any).
  99 
 100 Argument | Type | Description | Default
 101 ---------|------|-------------|---------
 102 list | `[T]` | The list to search through.  | -
 103 target | `T` | The item to search for.  | -
 104 
 105 **Return:** The index of the first occurrence or `none` if not found.
 106 
 107 
 108 **Example:**
 109 ```tomo
 110 assert [10, 20, 30, 40, 50].find(20) == 2
 111 assert [10, 20, 30, 40, 50].find(9999) == none
 112 
 113 ```
 114 ## List.from
 115 
 116 ```tomo
 117 List.from : func(list: [T], first: Int -> [T])
 118 ```
 119 
 120 Returns a slice of the list starting from a specified index.
 121 
 122 Argument | Type | Description | Default
 123 ---------|------|-------------|---------
 124 list | `[T]` | The original list.  | -
 125 first | `Int` | The index to start from.  | -
 126 
 127 **Return:** A new list starting from the specified index.
 128 
 129 
 130 **Example:**
 131 ```tomo
 132 assert [10, 20, 30, 40, 50].from(3) == [30, 40, 50]
 133 
 134 ```
 135 ## List.has
 136 
 137 ```tomo
 138 List.has : func(list: [T], target: T -> Bool)
 139 ```
 140 
 141 Checks if the list has an element.
 142 
 143 Argument | Type | Description | Default
 144 ---------|------|-------------|---------
 145 list | `[T]` | The list to check.  | -
 146 target | `T` | The element to check for.  | -
 147 
 148 **Return:** `yes` if the list has the element, `no` otherwise.
 149 
 150 
 151 **Example:**
 152 ```tomo
 153 assert [10, 20, 30].has(20) == yes
 154 
 155 ```
 156 ## List.heap_pop
 157 
 158 ```tomo
 159 List.heap_pop : func(list: @[T], by: func(x,y:&T->Int32) = T.compare -> T?)
 160 ```
 161 
 162 Removes and returns the top element of a heap or `none` if the list is empty. By default, this is the *minimum* value in the heap.
 163 
 164 Argument | Type | Description | Default
 165 ---------|------|-------------|---------
 166 list | `@[T]` | The mutable reference to the heap.  | -
 167 by | `func(x,y:&T->Int32)` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used.  | `T.compare`
 168 
 169 **Return:** The removed top element of the heap or `none` if the list is empty.
 170 
 171 
 172 **Example:**
 173 ```tomo
 174 my_heap := &[30, 10, 20]
 175 my_heap.heapify()
 176 assert my_heap.heap_pop() == 10
 177 
 178 ```
 179 ## List.heap_push
 180 
 181 ```tomo
 182 List.heap_push : func(list: @[T], item: T, by = T.compare -> Void)
 183 ```
 184 
 185 Adds an element to the heap and maintains the heap property. By default, this is a *minimum* heap.
 186 
 187 Argument | Type | Description | Default
 188 ---------|------|-------------|---------
 189 list | `@[T]` | The mutable reference to the heap.  | -
 190 item | `T` | The item to be added.  | -
 191 by | `` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used.  | `T.compare`
 192 
 193 **Return:** Nothing.
 194 
 195 
 196 **Example:**
 197 ```tomo
 198 my_heap : &[Int]
 199 my_heap.heap_push(10)
 200 assert my_heap.heap_pop() == 10
 201 
 202 ```
 203 ## List.heapify
 204 
 205 ```tomo
 206 List.heapify : func(list: @[T], by: func(x,y:&T->Int32) = T.compare -> Void)
 207 ```
 208 
 209 Converts a list into a heap.
 210 
 211 Argument | Type | Description | Default
 212 ---------|------|-------------|---------
 213 list | `@[T]` | The mutable reference to the list to be heapified.  | -
 214 by | `func(x,y:&T->Int32)` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used.  | `T.compare`
 215 
 216 **Return:** Nothing.
 217 
 218 
 219 **Example:**
 220 ```tomo
 221 my_heap := &[30, 10, 20]
 222 my_heap.heapify()
 223 
 224 ```
 225 ## List.insert
 226 
 227 ```tomo
 228 List.insert : func(list: @[T], item: T, at: Int = 0 -> Void)
 229 ```
 230 
 231 Inserts an element at a specified position in the list.
 232 
 233 Since indices are 1-indexed and negative indices mean "starting from the back", an index of `0` means "after the last item".
 234 
 235 Argument | Type | Description | Default
 236 ---------|------|-------------|---------
 237 list | `@[T]` | The mutable reference to the list.  | -
 238 item | `T` | The item to be inserted.  | -
 239 at | `Int` | The index at which to insert the item.  | `0`
 240 
 241 **Return:** Nothing.
 242 
 243 
 244 **Example:**
 245 ```tomo
 246 list := &[10, 20]
 247 list.insert(30)
 248 assert list == [10, 20, 30]
 249 
 250 list.insert(999, at=2)
 251 assert list == [10, 999, 20, 30]
 252 
 253 ```
 254 ## List.insert_all
 255 
 256 ```tomo
 257 List.insert_all : func(list: @[T], items: [T], at: Int = 0 -> Void)
 258 ```
 259 
 260 Inserts a list of items at a specified position in the list.
 261 
 262 Since indices are 1-indexed and negative indices mean "starting from the back", an index of `0` means "after the last item".
 263 
 264 Argument | Type | Description | Default
 265 ---------|------|-------------|---------
 266 list | `@[T]` | The mutable reference to the list.  | -
 267 items | `[T]` | The items to be inserted.  | -
 268 at | `Int` | The index at which to insert the item.  | `0`
 269 
 270 **Return:** Nothing.
 271 
 272 
 273 **Example:**
 274 ```tomo
 275 list := &[10, 20]
 276 list.insert_all([30, 40])
 277 assert list == [10, 20, 30, 40]
 278 
 279 list.insert_all([99, 100], at=2)
 280 assert list == [10, 99, 100, 20, 30, 40]
 281 
 282 ```
 283 ## List.pop
 284 
 285 ```tomo
 286 List.pop : func(list: &[T], index: Int = -1 -> T?)
 287 ```
 288 
 289 Removes and returns an item from the list. If the given index is present in the list, the item at that index will be removed and the list will become one element shorter.
 290 
 291 Since negative indices are counted from the back, the default behavior is to pop the last value.
 292 
 293 Argument | Type | Description | Default
 294 ---------|------|-------------|---------
 295 list | `&[T]` | The list to remove an item from.  | -
 296 index | `Int` | The index from which to remove the item.  | `-1`
 297 
 298 **Return:** `none` if the list is empty or the given index does not exist in the list, otherwise the item at the given index.
 299 
 300 
 301 **Example:**
 302 ```tomo
 303 list := &[10, 20, 30, 40]
 304 
 305 assert list.pop() == 40
 306 assert list[] == [10, 20, 30]
 307 
 308 assert list.pop(index=2) == 20
 309 assert list[] == [10, 30]
 310 
 311 ```
 312 ## List.random
 313 
 314 ```tomo
 315 List.random : func(list: [T], random: func(min,max:Int64->Int64)? = none -> T?)
 316 ```
 317 
 318 Selects a random element from the list.
 319 
 320 Argument | Type | Description | Default
 321 ---------|------|-------------|---------
 322 list | `[T]` | The list from which to select a random element.  | -
 323 random | `func(min,max:Int64->Int64)?` | If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation)  | `none`
 324 
 325 **Return:** A random element from the list or `none` if the list is empty.
 326 
 327 
 328 **Example:**
 329 ```tomo
 330 nums := [10, 20, 30]
 331 pick := nums.random()!
 332 assert nums.has(pick)
 333 empty : [Int]
 334 assert empty.random() == none
 335 
 336 ```
 337 ## List.remove_at
 338 
 339 ```tomo
 340 List.remove_at : func(list: @[T], at: Int = -1, count: Int = 1 -> Void)
 341 ```
 342 
 343 Removes elements from the list starting at a specified index.
 344 
 345 Since negative indices are counted from the back, the default behavior is to remove the last item.
 346 
 347 Argument | Type | Description | Default
 348 ---------|------|-------------|---------
 349 list | `@[T]` | The mutable reference to the list.  | -
 350 at | `Int` | The index at which to start removing elements.  | `-1`
 351 count | `Int` | The number of elements to remove.  | `1`
 352 
 353 **Return:** Nothing.
 354 
 355 
 356 **Example:**
 357 ```tomo
 358 list := &[10, 20, 30, 40, 50]
 359 list.remove_at(2)
 360 assert list == [10, 30, 40, 50]
 361 
 362 list.remove_at(2, count=2)
 363 assert list == [10, 50]
 364 
 365 ```
 366 ## List.remove_item
 367 
 368 ```tomo
 369 List.remove_item : func(list: @[T], item: T, max_count: Int = -1 -> Void)
 370 ```
 371 
 372 Removes all occurrences of a specified item from the list.
 373 
 374 A negative `max_count` means "remove all occurrences".
 375 
 376 Argument | Type | Description | Default
 377 ---------|------|-------------|---------
 378 list | `@[T]` | The mutable reference to the list.  | -
 379 item | `T` | The item to be removed.  | -
 380 max_count | `Int` | The maximum number of occurrences to remove.  | `-1`
 381 
 382 **Return:** Nothing.
 383 
 384 
 385 **Example:**
 386 ```tomo
 387 list := &[10, 20, 10, 20, 30]
 388 list.remove_item(10)
 389 assert list == [20, 20, 30]
 390 
 391 list.remove_item(20, max_count=1)
 392 assert list == [20, 30]
 393 
 394 ```
 395 ## List.reversed
 396 
 397 ```tomo
 398 List.reversed : func(list: [T] -> [T])
 399 ```
 400 
 401 Returns a reversed slice of the list.
 402 
 403 Argument | Type | Description | Default
 404 ---------|------|-------------|---------
 405 list | `[T]` | The list to be reversed.  | -
 406 
 407 **Return:** A slice of the list with elements in reverse order.
 408 
 409 
 410 **Example:**
 411 ```tomo
 412 assert [10, 20, 30].reversed() == [30, 20, 10]
 413 
 414 ```
 415 ## List.sample
 416 
 417 ```tomo
 418 List.sample : func(list: [T], count: Int, weights: [Num]? = none, random: func(->Num)? = none -> [T])
 419 ```
 420 
 421 Selects a sample of elements from the list, optionally with weighted probabilities.
 422 
 423 Errors will be raised if any of the following conditions occurs: - The given list has no elements and `count >= 1` - `count < 0` (negative count) - The number of weights provided doesn't match the length of the list.  - Any weight in the weights list is negative, infinite, or `NaN` - The sum of the given weights is zero (zero probability for every element).
 424 
 425 Argument | Type | Description | Default
 426 ---------|------|-------------|---------
 427 list | `[T]` | The list to sample from.  | -
 428 count | `Int` | The number of elements to sample.  | -
 429 weights | `[Num]?` | The probability weights for each element in the list. These values do not need to add up to any particular number, they are relative weights. If no weights are given, elements will be sampled with uniform probability.  | `none`
 430 random | `func(->Num)?` | If provided, this function will be used to get random values for sampling the list. The provided function should return random numbers between `0.0` (inclusive) and `1.0` (exclusive). (Used for deterministic pseudorandom number generation)  | `none`
 431 
 432 **Return:** A list of sampled elements from the list.
 433 
 434 
 435 **Example:**
 436 ```tomo
 437 _ := [10, 20, 30].sample(2, weights=[90%, 5%, 5%]) # E.g. [10, 10]
 438 
 439 ```
 440 ## List.shuffle
 441 
 442 ```tomo
 443 List.shuffle : func(list: @[T], random: func(min,max:Int64->Int64)? = none -> Void)
 444 ```
 445 
 446 Shuffles the elements of the list in place.
 447 
 448 Argument | Type | Description | Default
 449 ---------|------|-------------|---------
 450 list | `@[T]` | The mutable reference to the list to be shuffled.  | -
 451 random | `func(min,max:Int64->Int64)?` | If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation)  | `none`
 452 
 453 **Return:** Nothing.
 454 
 455 
 456 **Example:**
 457 ```tomo
 458 nums := &[10, 20, 30, 40]
 459 nums.shuffle()
 460 # E.g. [20, 40, 10, 30]
 461 
 462 ```
 463 ## List.shuffled
 464 
 465 ```tomo
 466 List.shuffled : func(list: [T], random: func(min,max:Int64->Int64)? = none -> [T])
 467 ```
 468 
 469 Creates a new list with elements shuffled.
 470 
 471 Argument | Type | Description | Default
 472 ---------|------|-------------|---------
 473 list | `[T]` | The list to be shuffled.  | -
 474 random | `func(min,max:Int64->Int64)?` | If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation)  | `none`
 475 
 476 **Return:** A new list with shuffled elements.
 477 
 478 
 479 **Example:**
 480 ```tomo
 481 nums := [10, 20, 30, 40]
 482 _ := nums.shuffled()
 483 # E.g. [20, 40, 10, 30]
 484 
 485 ```
 486 ## List.slice
 487 
 488 ```tomo
 489 List.slice : func(list: [T], from: Int, to: Int -> [T])
 490 ```
 491 
 492 Returns a slice of the list spanning the given indices (inclusive).
 493 
 494 Argument | Type | Description | Default
 495 ---------|------|-------------|---------
 496 list | `[T]` | The original list.  | -
 497 from | `Int` | The first index to include.  | -
 498 to | `Int` | The last index to include.  | -
 499 
 500 **Return:** A new list spanning the given indices. Note: negative indices are counted from the back of the list, so `-1` refers to the last element, `-2` the second-to-last, and so on.
 501 
 502 
 503 **Example:**
 504 ```tomo
 505 assert [10, 20, 30, 40, 50].slice(2, 4) == [20, 30, 40]
 506 assert [10, 20, 30, 40, 50].slice(-3, -2) == [30, 40]
 507 
 508 ```
 509 ## List.sort
 510 
 511 ```tomo
 512 List.sort : func(list: @[T], by = T.compare -> Void)
 513 ```
 514 
 515 Sorts the elements of the list in place in ascending order (small to large).
 516 
 517 Argument | Type | Description | Default
 518 ---------|------|-------------|---------
 519 list | `@[T]` | The mutable reference to the list to be sorted.  | -
 520 by | `` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used.  | `T.compare`
 521 
 522 **Return:** Nothing.
 523 
 524 
 525 **Example:**
 526 ```tomo
 527 list := &[40, 10, -30, 20]
 528 list.sort()
 529 assert list == [-30, 10, 20, 40]
 530 
 531 list.sort(func(a,b:&Int) a.abs() <> b.abs())
 532 assert list == [10, 20, -30, 40]
 533 
 534 ```
 535 ## List.sorted
 536 
 537 ```tomo
 538 List.sorted : func(list: [T], by = T.compare -> [T])
 539 ```
 540 
 541 Creates a new list with elements sorted.
 542 
 543 Argument | Type | Description | Default
 544 ---------|------|-------------|---------
 545 list | `[T]` | The list to be sorted.  | -
 546 by | `` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used.  | `T.compare`
 547 
 548 **Return:** A new list with sorted elements.
 549 
 550 
 551 **Example:**
 552 ```tomo
 553 assert [40, 10, -30, 20].sorted() == [-30, 10, 20, 40]
 554 assert [40, 10, -30, 20].sorted(
 555    func(a,b:&Int) a.abs() <> b.abs()
 556 ) == [10, 20, -30, 40]
 557 
 558 ```
 559 ## List.to
 560 
 561 ```tomo
 562 List.to : func(list: [T], last: Int -> [T])
 563 ```
 564 
 565 Returns a slice of the list from the start of the original list up to a specified index (inclusive).
 566 
 567 Argument | Type | Description | Default
 568 ---------|------|-------------|---------
 569 list | `[T]` | The original list.  | -
 570 last | `Int` | The index up to which elements should be included.  | -
 571 
 572 **Return:** A new list containing elements from the start up to the specified index.
 573 
 574 
 575 **Example:**
 576 ```tomo
 577 assert [10, 20, 30, 40, 50].to(3) == [10, 20, 30]
 578 assert [10, 20, 30, 40, 50].to(-2) == [10, 20, 30, 40]
 579 
 580 ```
 581 ## List.unique
 582 
 583 ```tomo
 584 List.unique : func(list: [T] -> {T})
 585 ```
 586 
 587 Returns a set of the unique elements of the list.
 588 
 589 Argument | Type | Description | Default
 590 ---------|------|-------------|---------
 591 list | `[T]` | The list to process.  | -
 592 
 593 **Return:** A set of the unique elements from the list.
 594 
 595 
 596 **Example:**
 597 ```tomo
 598 assert [10, 20, 10, 10, 30].unique() == {10, 20, 30}
 599 
 600 ```
 601 ## List.where
 602 
 603 ```tomo
 604 List.where : func(list: [T], predicate: func(item:&T -> Bool) -> Int)
 605 ```
 606 
 607 Find the index of the first item that matches a predicate function (if any).
 608 
 609 Argument | Type | Description | Default
 610 ---------|------|-------------|---------
 611 list | `[T]` | The list to search through.  | -
 612 predicate | `func(item:&T -> Bool)` | A function that returns `yes` if the item's index should be returned or `no` if it should not.  | -
 613 
 614 **Return:** Returns the index of the first item where the predicate is true or `none` if no item matches.
 615 
 616 
 617 **Example:**
 618 ```tomo
 619 assert ["BC", "ABC", "CD"].where(func(t:&Text) t.starts_with("A")) == 2
 620 assert ["BC", "ABC", "CD"].where(func(t:&Text) t.starts_with("X")) == none
 621 
 622 ```