@bitbybit-dev/base

import * as Inputs from "../inputs"; /** * Contains various list methods. * <div> * <img src="../assets/images/blockly-images/math/math.svg" alt="Blockly Image"/> * </div> */ export declare class Lists { /** * Gets an item from the list at a specific position using zero-based indexing. * Example: From [10, 20, 30, 40], getting index 2 returns 30 * @param inputs a list and an index * @returns item * @group get * @shortname item by index * @drawable false */ getItem<T>(inputs: Inputs.Lists.ListItemDto<T>): T; /** * Gets the first item from the list. * Example: From [10, 20, 30, 40], returns 10 * @param inputs a list * @returns first item * @group get * @shortname first item * @drawable false */ getFirstItem<T>(inputs: Inputs.Lists.ListCloneDto<T>): T; /** * Gets the last item from the list. * Example: From [10, 20, 30, 40], returns 40 * @param inputs a list * @returns last item * @group get * @shortname last item * @drawable false */ getLastItem<T>(inputs: Inputs.Lists.ListCloneDto<T>): T; /** * Randomly keeps items from the list based on a probability threshold (0 to 1). * Example: From [1, 2, 3, 4, 5] with threshold 0.5, might return [1, 3, 5] (50% chance for each item) * @param inputs a list and a threshold for randomization of items to remove * @returns list with remaining items * @group get * @shortname random get threshold * @drawable false */ randomGetThreshold<T>(inputs: Inputs.Lists.RandomThresholdDto<T>): T[]; /** * Extracts a portion of the list between start and end positions (end is exclusive). * Example: From [10, 20, 30, 40, 50] with start=1 and end=4, returns [20, 30, 40] * @param inputs a list and start and end indexes * @returns sub list * @group get * @shortname sublist * @drawable false */ getSubList<T>(inputs: Inputs.Lists.SubListDto<T>): T[]; /** * Gets every nth item from the list, starting from an optional offset position. * Example: From [0, 1, 2, 3, 4, 5, 6, 7, 8] with nth=3 and offset=0, returns [0, 3, 6] * Example: From [0, 1, 2, 3, 4, 5, 6, 7, 8] with nth=2 and offset=1, returns [1, 3, 5, 7] * @param inputs a list and index * @returns list with filtered items * @group get * @shortname every n-th * @drawable false */ getNthItem<T>(inputs: Inputs.Lists.GetNthItemDto<T>): T[]; /** * Filters items from the list using a repeating true/false pattern. * Example: From [0, 1, 2, 3, 4, 5] with pattern [true, true, false], returns [0, 1, 3, 4] (keeps items where pattern is true) * @param inputs a list and index * @returns list with filtered items * @group get * @shortname by pattern * @drawable false */ getByPattern<T>(inputs: Inputs.Lists.GetByPatternDto<T>): T[]; /** * Merges elements from multiple lists at a specific nesting level, grouping elements by position. * Example: From [[0, 1, 2], [3, 4, 5]] at level 0, returns [[0, 3], [1, 4], [2, 5]] * @param inputs lists, level and flatten data * @returns list with merged lists and flattened lists * @group get * @shortname merge levels * @drawable false */ mergeElementsOfLists<T>(inputs: Inputs.Lists.MergeElementsOfLists<T[]>): T[]; /** * Finds the length of the longest list among multiple lists. * Example: From [[1, 2], [3, 4, 5, 6], [7]], returns 4 (length of [3, 4, 5, 6]) * @param inputs a list of lists * @returns number of max length * @group get * @shortname longest list length * @drawable false */ getLongestListLength<T>(inputs: Inputs.Lists.GetLongestListLength<T[]>): number; /** * Reverses the order of items in the list. * Example: From [1, 2, 3, 4, 5], returns [5, 4, 3, 2, 1] * @param inputs a list and an index * @returns item * @group edit * @shortname reverse * @drawable false */ reverse<T>(inputs: Inputs.Lists.ListCloneDto<T>): T[]; /** * Randomly rearranges all items in the list (using Fisher-Yates algorithm). * Example: From [1, 2, 3, 4, 5], might return [3, 1, 5, 2, 4] (order varies each time) * @param inputs a list * @returns shuffled list * @group edit * @shortname shuffle * @drawable false */ shuffle<T>(inputs: Inputs.Lists.ListCloneDto<T>): T[]; /** * Transposes a 2D list by swapping rows and columns (all sublists must be equal length). * Example: From [[0, 1, 2], [3, 4, 5]], returns [[0, 3], [1, 4], [2, 5]] * @param inputs a list of lists to flip * @returns item * @group edit * @shortname flip lists * @drawable false */ flipLists<T>(inputs: Inputs.Lists.ListCloneDto<T[]>): T[][]; /** * Splits the list into smaller lists of n elements each. * Example: From [0, 1, 2, 3, 4, 5, 6, 7, 8] with n=3, returns [[0, 1, 2], [3, 4, 5], [6, 7, 8]] * Example: From [0, 1, 2, 3, 4] with n=2 and keepRemainder=true, returns [[0, 1], [2, 3], [4]] * @param inputs a list * @returns items grouped in lists of n elements * @group edit * @shortname group elements * @drawable false */ groupNth<T>(inputs: Inputs.Lists.GroupListDto<T>): T[][]; /** * Checks whether the list contains a specific item. * Example: List [10, 20, 30, 40] with item 30 returns true, with item 50 returns false * @param inputs a list and an item * @returns true if item is in list * @group get * @shortname contains item * @drawable false */ includes<T>(inputs: Inputs.Lists.IncludesDto<T>): boolean; /** * Finds the position (index) of the first occurrence of an item in the list. * Example: In [10, 20, 30, 20, 40], finding 20 returns 1 (first occurrence), finding 50 returns -1 (not found) * @param inputs a list and an item * @returns index of the item or -1 if not found * @group get * @shortname find index * @drawable false */ findIndex<T>(inputs: Inputs.Lists.IncludesDto<T>): number; /** * Determines the maximum nesting level (depth) of a list structure. * Example: [1, 2, 3] has depth 1, [[1, 2], [3, 4]] has depth 2, [[[1]]] has depth 3 * @param inputs a list * @returns number of depth * @group get * @shortname max list depth * @drawable false */ getListDepth(inputs: Inputs.Lists.ListCloneDto<[]>): number; /** * Returns the number of items in the list. * Example: [10, 20, 30, 40, 50] returns 5, [] returns 0 * @param inputs a length list * @returns a number * @group get * @shortname list length * @drawable false */ listLength<T>(inputs: Inputs.Lists.ListCloneDto<T>): number; /** * Inserts an item at a specific position in the list. * Example: In [10, 20, 30, 40], adding 99 at index 2 gives [10, 20, 99, 30, 40] * @param inputs a list, item and an index * @returns list with added item * @group add * @shortname add item * @drawable false */ addItemAtIndex<T>(inputs: Inputs.Lists.AddItemAtIndexDto<T>): T[]; /** * Inserts the same item at multiple specified positions in the list. * Example: In [10, 20, 30], adding 99 at indexes [0, 2] gives [99, 10, 20, 99, 30] * @param inputs a list, item and an indexes * @returns list with added item * @group add * @shortname add item at indexes * @drawable false */ addItemAtIndexes<T>(inputs: Inputs.Lists.AddItemAtIndexesDto<T>): T[]; /** * Inserts multiple items at corresponding positions (first item at first index, second item at second index, etc.). * Example: In [10, 20, 30], adding items [88, 99] at indexes [1, 2] gives [10, 88, 20, 99, 30] * @param inputs a list, items and an indexes * @returns list with added items * @group add * @shortname add items * @drawable false */ addItemsAtIndexes<T>(inputs: Inputs.Lists.AddItemsAtIndexesDto<T>): T[]; /** * Removes the item at a specific position in the list. * Example: From [10, 20, 30, 40, 50], removing index 2 gives [10, 20, 40, 50] * @param inputs a list and index * @returns list with removed item * @group remove * @shortname remove item * @drawable false */ removeItemAtIndex<T>(inputs: Inputs.Lists.RemoveItemAtIndexDto<T>): T[]; /** * Removes the first item from the list. * Example: From [10, 20, 30, 40], returns [20, 30, 40] * @param inputs a list * @returns list with first item removed * @group remove * @shortname remove first item * @drawable false */ removeFirstItem<T>(inputs: Inputs.Lists.ListCloneDto<T>): T[]; /** * Removes the last item from the list. * Example: From [10, 20, 30, 40], returns [10, 20, 30] * @param inputs a list * @returns list with last item removed * @group remove * @shortname remove last item * @drawable false */ removeLastItem<T>(inputs: Inputs.Lists.ListCloneDto<T>): T[]; /** * Removes an item counting from the end of the list (index 0 = last item, 1 = second-to-last, etc.). * Example: From [10, 20, 30, 40, 50], removing index 1 from end gives [10, 20, 30, 50] (removes 40) * @param inputs a list and index from end * @returns list with removed item * @group remove * @shortname remove item from end * @drawable false */ removeItemAtIndexFromEnd<T>(inputs: Inputs.Lists.RemoveItemAtIndexDto<T>): T[]; /** * Removes items at multiple specified positions from the list. * Example: From [10, 20, 30, 40, 50], removing indexes [1, 3] gives [10, 30, 50] * @param inputs a list and indexes * @returns list with removed items * @group remove * @shortname remove items * @drawable false */ removeItemsAtIndexes<T>(inputs: Inputs.Lists.RemoveItemsAtIndexesDto<T>): T[]; /** * Clears all items from the list, resulting in an empty list. * Example: From [10, 20, 30, 40], returns [] * @param inputs a list * @returns The length is set to 0 and same array memory object is returned * @group remove * @shortname remove all items * @drawable false */ removeAllItems<T>(inputs: Inputs.Lists.ListDto<T>): T[]; /** * Removes every nth item from the list, starting from an optional offset position. * Example: From [0, 1, 2, 3, 4, 5, 6, 7, 8] with nth=3 and offset=0, returns [1, 2, 4, 5, 7, 8] (removes 0, 3, 6) * @param inputs a list and index * @returns list with removed item * @group remove * @shortname every n-th * @drawable false */ removeNthItem<T>(inputs: Inputs.Lists.RemoveNthItemDto<T>): T[]; /** * Randomly removes items from the list based on a probability threshold (0 to 1). * Example: From [1, 2, 3, 4, 5] with threshold 0.5, might return [2, 4] (50% chance to remove each item) * @param inputs a list and a threshold for randomization of items to remove * @returns list with removed items * @group remove * @shortname random remove threshold * @drawable false */ randomRemoveThreshold<T>(inputs: Inputs.Lists.RandomThresholdDto<T>): T[]; /** * Removes duplicate numbers from the list, keeping only the first occurrence of each value. * Example: From [1, 2, 3, 2, 4, 3, 5], returns [1, 2, 3, 4, 5] * @param inputs a list of numbers * @returns list with unique numbers * @group remove * @shortname remove duplicate numbers * @drawable false */ removeDuplicateNumbers(inputs: Inputs.Lists.RemoveDuplicatesDto<number>): number[]; /** * Removes duplicate numbers that are within a specified tolerance range of each other. * Example: From [1.0, 1.001, 2.0, 2.002, 3.0] with tolerance 0.01, returns [1.0, 2.0, 3.0] * @param inputs a list of numbers and the tolerance * @returns list with unique numbers * @group remove * @shortname remove duplicates tol * @drawable false */ removeDuplicateNumbersTolerance(inputs: Inputs.Lists.RemoveDuplicatesToleranceDto<number>): number[]; /** * Removes duplicate items from the list using strict equality comparison (works with any type). * Example: From ['a', 'b', 'c', 'a', 'd', 'b'], returns ['a', 'b', 'c', 'd'] * @param inputs a list * @returns list with unique items * @group remove * @shortname remove duplicates * @drawable false */ removeDuplicates<T>(inputs: Inputs.Lists.RemoveDuplicatesDto<T>): T[]; /** * Appends an item to the end of the list. * Example: To [10, 20, 30], adding 40 gives [10, 20, 30, 40] * @param inputs a list and an item * @returns list with added item * @group add * @shortname add item to list * @drawable false */ addItem<T>(inputs: Inputs.Lists.AddItemDto<T>): T[]; /** * Adds an item to the beginning of the list. * Example: To [10, 20, 30], prepending 5 gives [5, 10, 20, 30] * @param inputs a list and an item * @returns list with added item * @group add * @shortname prepend item to list * @drawable false */ prependItem<T>(inputs: Inputs.Lists.AddItemDto<T>): T[]; /** * Adds an item either at the beginning or end of the list based on the position parameter. * Example: To [10, 20, 30], adding 5 at 'first' gives [5, 10, 20, 30], at 'last' gives [10, 20, 30, 5] * @param inputs a list, item and an option for first or last position * @returns list with added item * @group add * @shortname item at first or last * @drawable false */ addItemFirstLast<T>(inputs: Inputs.Lists.AddItemFirstLastDto<T>): T[]; /** * Combines multiple lists into a single list by joining them end-to-end. * Example: From [[1, 2], [3, 4], [5, 6]], returns [1, 2, 3, 4, 5, 6] * @param inputs lists to concatenate * @returns concatenated list * @group add * @shortname concatenate lists * @drawable false */ concatenate<T>(inputs: Inputs.Lists.ConcatenateDto<T>): T[]; /** * Creates a new empty list with no items. * Example: Returns [] * @returns an empty array list * @group create * @shortname empty list * @drawable false */ createEmptyList(): []; /** * Creates a new list by repeating an item a specified number of times. * Example: Repeating 5 three times returns [5, 5, 5] * @param inputs an item to multiply * @returns list * @group create * @shortname repeat * @drawable false */ repeat<T>(inputs: Inputs.Lists.MultiplyItemDto<T>): T[]; /** * Repeats a pattern of items cyclically until reaching a target list length. * Example: Pattern [1, 2, 3] with length 7 returns [1, 2, 3, 1, 2, 3, 1] * @param inputs a list to multiply and a length limit * @returns list * @group create * @shortname repeat in pattern * @drawable false */ repeatInPattern<T>(inputs: Inputs.Lists.RepeatInPatternDto<T>): T[]; /** * Sorts numbers in ascending (lowest to highest) or descending (highest to lowest) order. * Example: [5, 2, 8, 1, 9] ascending returns [1, 2, 5, 8, 9], descending returns [9, 8, 5, 2, 1] * @param inputs a list of numbers to sort and an option for ascending or descending order * @returns list * @group sorting * @shortname sort numbers * @drawable false */ sortNumber(inputs: Inputs.Lists.SortDto<number>): number[]; /** * Sorts text strings alphabetically in ascending (A to Z) or descending (Z to A) order. * Example: ['dog', 'apple', 'cat', 'banana'] ascending returns ['apple', 'banana', 'cat', 'dog'] * @param inputs a list of texts to sort and an option for ascending or descending order * @returns list * @group sorting * @shortname sort texts * @drawable false */ sortTexts(inputs: Inputs.Lists.SortDto<string>): string[]; /** * Sorts objects by comparing numeric values of a specified property. * Example: [{age: 30}, {age: 20}, {age: 25}] sorted by 'age' ascending returns [{age: 20}, {age: 25}, {age: 30}] * @param inputs a list to sort, a property to sort by and an option for ascending or descending order * @returns list * @group sorting * @shortname sort json objects * @drawable false */ sortByPropValue(inputs: Inputs.Lists.SortJsonDto<any>): any[]; /** * Combines multiple lists by alternating elements from each list (first from list1, first from list2, second from list1, etc.). * Example: From [[0, 1, 2], [3, 4, 5]], returns [0, 3, 1, 4, 2, 5] * @param inputs Lists to interleave * @returns Flattened interleaved list * @group transform * @shortname interleave lists * @drawable false */ interleave<T>(inputs: Inputs.Lists.InterleaveDto<T>): T[]; }