diff options
Diffstat (limited to 'api/lists.yaml')
| -rw-r--r-- | api/lists.yaml | 660 |
1 files changed, 660 insertions, 0 deletions
diff --git a/api/lists.yaml b/api/lists.yaml new file mode 100644 index 00000000..c746cf57 --- /dev/null +++ b/api/lists.yaml @@ -0,0 +1,660 @@ +List.binary_search: + description: > + Performs a binary search on a sorted list. + return: + type: 'Int' + description: > + 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. + args: + list: + type: '[T]' + description: > + The sorted list to search. + by: + type: 'func(x,y:&T->Int32)' + default: 'T.compare' + description: > + The comparison function used to determine order. If not specified, the + default comparison function for the item type will be used. + example: | + >> [1, 3, 5, 7, 9].binary_search(5) + = 3 + + >> [1, 3, 5, 7, 9].binary_search(-999) + = 1 + + >> [1, 3, 5, 7, 9].binary_search(999) + = 6 + +List.by: + description: > + Creates a new list with elements spaced by the specified step value. + return: + type: '[T]' + description: > + A new list with every `step`-th element from the original list. + args: + list: + type: '[T]' + description: > + The original list. + step: + type: 'Int' + description: > + The step value for selecting elements. + example: | + >> [1, 2, 3, 4, 5, 6].by(2) + = [1, 3, 5] + +List.clear: + description: > + Clears all elements from the list. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list to be cleared. + example: | + >> my_list.clear() + +List.counts: + description: > + Counts the occurrences of each element in the list. + return: + type: '{T=Int}' + description: > + A table mapping each element to its count. + args: + list: + type: '[T]' + description: > + The list to count elements in. + example: | + >> [10, 20, 30, 30, 30].counts() + = {10=1, 20=1, 30=3} + +List.find: + description: > + Finds the index of the first occurrence of an element (if any). + return: + type: 'Int?' + description: > + The index of the first occurrence or `!Int` if not found. + args: + list: + type: '[T]' + description: > + The list to search through. + target: + type: 'T' + description: > + The item to search for. + example: | + >> [10, 20, 30, 40, 50].find(20) + = 2 : Int? + + >> [10, 20, 30, 40, 50].find(9999) + = none : Int? + +List.first: + description: > + Find the index of the first item that matches a predicate function (if any). + return: + type: 'Int' + description: > + Returns the index of the first item where the predicate is true or `!Int` if no + item matches. + args: + list: + type: '[T]' + description: > + The list to search through. + predicate: + type: 'func(item:&T -> Bool)' + description: > + A function that returns `yes` if the item should be returned or + `no` if it should not. + example: | + >> [4, 5, 6].find(func(i:&Int): i.is_prime()) + = 5 : Int? + >> [4, 6, 8].find(func(i:&Int): i.is_prime()) + = none : Int? + +List.from: + description: > + Returns a slice of the list starting from a specified index. + return: + type: '[T]' + description: > + A new list starting from the specified index. + args: + list: + type: '[T]' + description: > + The original list. + first: + type: 'Int' + description: > + The index to start from. + example: | + >> [10, 20, 30, 40, 50].from(3) + = [30, 40, 50] + +List.has: + description: > + Checks if the list has an element. + return: + type: 'Bool' + description: > + `yes` if the list has the element, `no` otherwise. + args: + list: + type: '[T]' + description: > + The list to check. + target: + type: 'T' + description: > + The element to check for. + example: | + >> [10, 20, 30].has(20) + = yes + +List.heap_pop: + description: > + 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. + return: + type: 'T?' + description: > + The removed top element of the heap or `none` if the list is empty. + args: + list: + type: '@[T]' + description: > + The mutable reference to the heap. + by: + type: 'func(x,y:&T->Int32)' + default: 'T.compare' + description: > + The comparison function used to determine order. If not specified, the + default comparison function for the item type will be used. + example: | + >> my_heap := [30, 10, 20] + >> my_heap.heapify() + >> my_heap.heap_pop() + = 10 + +List.heap_push: + description: > + Adds an element to the heap and maintains the heap property. By default, this + is a *minimum* heap. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the heap. + item: + type: 'T' + description: > + The item to be added. + by: + default: 'T.compare' + description: > + The comparison function used to determine order. If not specified, the + default comparison function for the item type will be used. + example: | + >> my_heap.heap_push(10) + +List.heapify: + description: > + Converts a list into a heap. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list to be heapified. + by: + type: 'func(x,y:&T->Int32)' + default: 'T.compare' + description: > + The comparison function used to determine order. If not specified, the + default comparison function for the item type will be used. + example: | + >> my_heap := [30, 10, 20] + >> my_heap.heapify() + +List.insert: + description: > + Inserts an element at a specified position in the list. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list. + item: + type: 'T' + description: > + The item to be inserted. + at: + type: 'Int' + default: '0' + description: > + The index at which to insert the item. + note: > + Since indices are 1-indexed and negative indices mean "starting from the + back", an index of `0` means "after the last item". + example: | + >> list := [10, 20] + >> list.insert(30) + >> list + = [10, 20, 30] + + >> list.insert(999, at=2) + >> list + = [10, 999, 20, 30] + +List.insert_all: + description: > + Inserts a list of items at a specified position in the list. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list. + items: + type: '[T]' + description: > + The items to be inserted. + at: + type: 'Int' + default: '0' + description: > + The index at which to insert the item. + note: > + Since indices are 1-indexed and negative indices mean "starting from the + back", an index of `0` means "after the last item". + example: | + list := [10, 20] + list.insert_all([30, 40]) + >> list + = [10, 20, 30, 40] + + list.insert_all([99, 100], at=2) + >> list + = [10, 99, 100, 20, 30, 40] + +List.pop: + description: > + 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. + return: + type: 'T?' + description: > + `none` if the list is empty or the given index does not exist in the list, + otherwise the item at the given index. + args: + list: + type: '&[T]' + description: > + The list to remove an item from. + index: + type: 'Int' + default: '-1' + description: > + The index from which to remove the item. + note: > + Since negative indices are counted from the back, the default behavior is + to pop the last value. + example: | + >> list := [10, 20, 30, 40] + + >> list.pop() + = 40 + >> list + = &[10, 20, 30] + + >> list.pop(index=2) + = 20 + >> list + = &[10, 30] + +List.random: + description: > + Selects a random element from the list. + return: + type: 'T' + description: > + A random element from the list. + args: + list: + type: '[T]' + description: > + The list from which to select a random element. + random: + type: 'func(min,max:Int64->Int64)?' + default: 'none' + description: > + 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) + example: | + >> [10, 20, 30].random() + = 20 + +List.remove_at: + description: > + Removes elements from the list starting at a specified index. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list. + at: + type: 'Int' + default: '-1' + description: > + The index at which to start removing elements. + count: + type: 'Int' + default: '1' + description: > + The number of elements to remove. + note: > + Since negative indices are counted from the back, the default behavior is + to remove the last item. + example: | + list := [10, 20, 30, 40, 50] + list.remove_at(2) + >> list + = [10, 30, 40, 50] + + list.remove_at(2, count=2) + >> list + = [10, 50] + +List.remove_item: + description: > + Removes all occurrences of a specified item from the list. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list. + item: + type: 'T' + description: > + The item to be removed. + max_count: + type: 'Int' + default: '-1' + description: > + The maximum number of occurrences to remove. + note: > + A negative `max_count` means "remove all occurrences". + example: | + list := [10, 20, 10, 20, 30] + list.remove_item(10) + >> list + = [20, 20, 30] + + list.remove_item(20, max_count=1) + >> list + = [20, 30] + +List.reversed: + description: > + Returns a reversed slice of the list. + return: + type: '[T]' + description: > + A slice of the list with elements in reverse order. + args: + list: + type: '[T]' + description: > + The list to be reversed. + example: | + >> [10, 20, 30].reversed() + = [30, 20, 10] + +List.sample: + description: > + Selects a sample of elements from the list, optionally with weighted + probabilities. + return: + type: '[T]' + description: > + A list of sampled elements from the list. + errors: > + 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). + args: + list: + type: '[T]' + description: > + The list to sample from. + count: + type: 'Int' + description: > + The number of elements to sample. + weights: + type: '[Num]?' + default: '![Num]' + description: > + 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. + random: + type: 'func(->Num)?' + default: 'none' + description: > + 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) + example: | + >> [10, 20, 30].sample(2, weights=[90%, 5%, 5%]) + = [10, 10] + +List.shuffle: + description: > + Shuffles the elements of the list in place. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list to be shuffled. + random: + type: 'func(min,max:Int64->Int64)?' + default: 'none' + description: > + 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) + example: | + >> list.shuffle() + +List.shuffled: + description: > + Creates a new list with elements shuffled. + return: + type: '[T]' + description: > + A new list with shuffled elements. + args: + list: + type: '[T]' + description: > + The list to be shuffled. + random: + type: 'func(min,max:Int64->Int64)?' + default: 'none' + description: > + 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) + example: | + >> [10, 20, 30, 40].shuffled() + = [40, 10, 30, 20] + +List.slice: + description: > + Returns a slice of the list spanning the given indices (inclusive). + return: + type: '[T]' + description: > + 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. + args: + list: + type: '[T]' + description: > + The original list. + from: + type: 'Int' + description: > + The first index to include. + to: + type: 'Int' + description: > + The last index to include. + example: | + >> [10, 20, 30, 40, 50].slice(2, 4) + = [20, 30, 40] + + >> [10, 20, 30, 40, 50].slice(-3, -2) + = [30, 40] + +List.sort: + description: > + Sorts the elements of the list in place in ascending order (small to large). + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list to be sorted. + by: + default: 'T.compare' + description: > + The comparison function used to determine order. If not specified, the + default comparison function for the item type will be used. + example: | + list := [40, 10, -30, 20] + list.sort() + >> list + = [-30, 10, 20, 40] + + list.sort(func(a,b:&Int): a.abs() <> b.abs()) + >> list + = [10, 20, -30, 40] + +List.sorted: + description: > + Creates a new list with elements sorted. + return: + type: '[T]' + description: > + A new list with sorted elements. + args: + list: + type: '[T]' + description: > + The list to be sorted. + by: + default: 'T.compare' + description: > + The comparison function used to determine order. If not specified, the + default comparison function for the item type will be used. + example: | + >> [40, 10, -30, 20].sorted() + = [-30, 10, 20, 40] + + >> [40, 10, -30, 20].sorted(func(a,b:&Int): a.abs() <> b.abs()) + = [10, 20, -30, 40] + +List.to: + description: > + Returns a slice of the list from the start of the original list up to a specified index (inclusive). + return: + type: '[T]' + description: > + A new list containing elements from the start up to the specified index. + args: + list: + type: '[T]' + description: > + The original list. + last: + type: 'Int' + description: > + The index up to which elements should be included. + example: | + >> [10, 20, 30, 40, 50].to(3) + = [10, 20, 30] + + >> [10, 20, 30, 40, 50].to(-2) + = [10, 20, 30, 40] + +List.unique: + description: > + Returns a Set that contains the unique elements of the list. + return: + type: '|T|' + description: > + A set containing only unique elements from the list. + args: + list: + type: '[T]' + description: > + The list to process. + example: | + >> [10, 20, 10, 10, 30].unique() + = {10, 20, 30} + |