Skip to main content

module List

rascal-Not specified

Library functions for lists.

Usage​

import List;

Dependencies​

import Exception;
import Map;

Description​

The following library functions are available for lists:

function concat​

Concatenate a list of lists.

list[&T] concat(list[list[&T]] xxs)

Examples​

rascal>import List;
ok
rascal>concat([]);
list[void]: []
rascal>concat([[]]);
list[void]: []
rascal>concat([[1]]);
list[int]: [1]
rascal>concat([[1],[],[2,3]]);
list[int]: [1,2,3]
rascal>concat([[1,2],[3],[4,5],[]]);
list[int]: [1,2,3,4,5]

function delete​

Delete an element from a list.

list[&T] delete(list[&T] lst, int n)

Delete the n-th element from a list. A new list without the n-th element is returned as result. The IndexOutOfBounds exception is thrown when n is not a valid index.

Examples​

rascal>import List;
ok
rascal>delete([1, 2, 3], 1);
list[int]: [1,3]
rascal>delete(["zebra", "elephant", "snake", "owl"], 2);
list[str]: ["zebra","elephant","owl"]

function distribution​

Get the distribution of the elements of the list. That is how often does each element occur in the list?

map[&T element, int occurs] distribution(list[&T] lst)

Examples​

rascal>import List;
ok
rascal>distribution([4,4,4,3,1,2,1,1,3,4]);
map[int element, int occurs]: (1:3,3:2,2:1,4:4)

function drop​

Drop elements from the head of a list.

list[&T] drop(int n, list[&T] lst)

Drop n elements (or size(lst) elements if size(lst) < n) from the head of lst. See Take to get elements from the head of a list].

Examples​

rascal>import List;
ok
rascal>drop(2, [5, 1, 7, 3]);
list[int]: [7,3]
rascal>drop(10, [5, 1, 7, 3]);
list[int]: []
rascal>drop(2, ["zebra", "elephant", "snake", "owl"]);
list[str]: ["snake","owl"]

function dup​

Remove multiple occurrences of elements in a list. The first occurrence remains.

list[&T] dup(list[&T] lst)

Examples​

rascal>import List;
ok
rascal>dup([3, 1, 5, 3, 1, 7, 1, 2]);
list[int]: [3,1,5,7,2]

function elementAt​

A function that implements lst[index]

&T elementAt(list[&T] lst, int index)

The expression lst[index] has the same semantics as calling elementAt(index).

Benefits​

Pitfalls​

  • lst[index] is significantly faster than elementAt(index)

function getOneFrom​

Pick a random element from a list.

&T getOneFrom(list[&T] lst)

Get an arbitrary element from a list. See TakeOneFrom for a function that also removes the selected element.

Examples​

rascal>import List;
ok
rascal>getOneFrom(["zebra", "elephant", "snake", "owl"]);
str: "zebra"
───
zebra
───
rascal>getOneFrom(["zebra", "elephant", "snake", "owl"]);
str: "owl"
───
owl
───
rascal>getOneFrom(["zebra", "elephant", "snake", "owl"]);
str: "zebra"
───
zebra
───

function getFirstFrom​

Pick first element from a list.

&T getFirstFrom([&T f, *&T _])

&T getFirstFrom(list[&T] _ :[])

Get the first element from a list. As opposed to GetOneFrom this function always returns the same (first) list element.

function head​

Get the first element(s) from a list.

&T head([&T h, *&T _])

&T head(list[&T] _:[])

list[&T] head(list[&T] lst, int n) throws IndexOutOfBounds
  • Returns the first element of a list or throws EmptyList when the list is empty. This is identical to Top.
  • Returns the first n elements of a list or throws IndexOutOfBounds when the list is too short. This is similar to Take.

Examples​

rascal>import List;
ok

Get the first element:

rascal>head([1, 2, 3]);
int: 1
rascal>head(["zebra", "elephant", "snake", "owl"]);
str: "zebra"
───
zebra
───

An exception is thrown when taking the head of an empty list:

rascal>head([]);
|file:///home/runner/work/rascal/rascal/src/org/rascalmpl/library/List.rsc|(4461,9,<167,31>,<167,40>): EmptyList()
    at head(|file:///home/runner/work/rascal/rascal/src/org/rascalmpl/library/List.rsc|(4430,45,<167,0>,<167,45>))
    at $(|prompt:///|(0,9,<1,0>,<1,9>))

Get the first n elements:

rascal>head([1, 2, 3, 4], 2);
list[int]: [1,2]
rascal>head(["zebra", "elephant", "snake", "owl"], 2);
list[str]: ["zebra","elephant"]

An exception is thrown when the second argument exceeds the length of the list:

rascal>head([1, 2, 3, 5], 5);
|file:///home/runner/work/rascal/rascal/src/org/rascalmpl/library/List.rsc|(4515,106,<170,0>,<171,64>): IndexOutOfBounds(4)
    at head(|file:///home/runner/work/rascal/rascal/src/org/rascalmpl/library/List.rsc|(4515,106,<170,0>,<171,64>))
    at head(|prompt:///|(19,1,<1,19>,<1,20>))

function headTail​

Split a list in a head and a tail.

tuple[&T, list[&T]] headTail([&T h, *&T t])

tuple[&T, list[&T]] headTail(list[&T] _:[])

This function is identical to Pop.

Examples​

rascal>import List;
ok
rascal>headTail([3, 1, 4, 5]);
tuple[int,list[int]]: <3,[1,4,5]>
rascal>pop([3, 1, 4, 5]);
tuple[int,list[int]]: <3,[1,4,5]>
rascal>headTail(["zebra", "elephant", "snake", "owl"]);
tuple[str,list[str]]: <"zebra",["elephant","snake","owl"]>

function index​

A list of legal index values of a list.

list[int] index(list[&T] lst)

Returns a list of all legal index values for a given list lst.

Examples​

rascal>import List;
ok
rascal>index([1, 3, 5]);
list[int]: [0,1,2]
rascal>index(["zebra", "elephant", "snake", "owl"]);
list[int]: [0,1,2,3]

Benefits​

This function is useful in for loops over lists.

function indexOf​

Index of first occurrence of an element in a list.

int indexOf(list[&T] lst, &T elt)

Return index of first occurrence of elt in lst, or -1 if elt is not found. Also see LastIndexOf.

Examples​

rascal>import List;
ok
rascal>indexOf([3, 1, 4, 5], 4);
int: 2
rascal>indexOf([3, 1, 4, 5], 7);
int: -1
rascal>indexOf(["zebra", "elephant", "snake", "owl"], "snake");
int: 2
rascal>indexOf(["zebra", "elephant", "snake", "owl"], "eagle");
int: -1

function insertAt​

Insert an element at a specific position in a list.

list[&T] insertAt(list[&T] lst, int n, &T elm) throws IndexOutOfBounds

Returns a new list with the value of elm inserted at index position n of the old list.

Examples​

rascal>import List;
ok
rascal>insertAt([1,2,3], 1, 5);
list[int]: [1,5,2,3]
rascal>insertAt(["zebra", "elephant", "snake", "owl"], 2, "eagle");
list[str]: ["zebra","elephant","eagle","snake","owl"]

An exception is thrown when the index position is outside the list:

rascal>insertAt([1,2,3], 10, 5);
|file:///home/runner/work/rascal/rascal/src/org/rascalmpl/library/List.rsc|(5872,549,<231,0>,<247,76>): IndexOutOfBounds(10)
    at insertAt(|file:///home/runner/work/rascal/rascal/src/org/rascalmpl/library/List.rsc|(5872,549,<231,0>,<247,76>))
    at insertAt(|prompt:///|(22,1,<1,22>,<1,23>))

function intercalate​

Join a list of values into a string separated by a separator.

str intercalate(str sep, list[value] l)

Examples​

rascal>import List;
ok
rascal>intercalate("/", [3]);
str: "3"
───
3
───
rascal>intercalate("/", [3, 1, 4, 5]);
str: "3/1/4/5"
───
3/1/4/5
───
rascal>intercalate(", ", [3, 1, 4, 5]);
str: "3, 1, 4, 5"
───
3, 1, 4, 5
───
rascal>intercalate(", ", ["zebra", "elephant", "snake", "owl"]);
str: "zebra, elephant, snake, owl"
───
zebra, elephant, snake, owl
───

function intersperse​

Intersperses a list of values with a separator.

list[&T] intersperse(&T sep, list[&T] xs)

Examples​

rascal>import List;
ok
rascal>intersperse(", ", ["a","b","c"]);
list[str]: ["a",", ","b",", ","c"]
rascal>intersperse(0, [1, 2, 3]);
list[int]: [1,0,2,0,3]
rascal>intersperse(1, []);
list[int]: []
rascal>intersperse([], [1]);
list[value]: [1]

function isEmpty​

Test whether a list is empty.

bool isEmpty(list[&T] lst)

Returns true when a list is empty and false otherwise.

Examples​

rascal>import List;
ok
rascal>isEmpty([]);
bool: true
rascal>isEmpty([1, 2, 3]);
bool: false

function last​

Return the last element of a list, if any.

&T last(list[&T] lst) throws EmptyList

Also see Tail that returns a list of one or more of the last elements of a list.

Examples​

rascal>import List;
ok
rascal>last([1]);
int: 1
rascal>last([3, 1, 4, 5]);
int: 5
rascal>last(["zebra", "elephant", "snake", "owl"]);
str: "owl"
───
owl
───
rascal>tail([3, 1, 4, 5]);
list[int]: [1,4,5]

function lastIndexOf​

Return index of last occurrence of elt in lst, or -1 if elt is not found.

int lastIndexOf(list[&T] lst, &T elt)

Also see IndexOf.

Examples​

rascal>import List;
ok
rascal>lastIndexOf([3, 1, 4, 5, 4], 4);
int: 4
rascal>lastIndexOf([3, 1, 4, 5, 4], 7);
int: -1
rascal>lastIndexOf(["zebra", "owl", "elephant", "snake", "owl"], "owl");
int: 4

function mapper​

Apply a function to all list elements and return list of results.

list[&U] mapper(list[&T] lst, &U (&T) fn)

Apply a function fn to each element of lst and return the list of results.

Examples​

rascal>import List;
ok
rascal>int incr(int x) { return x + 1; }
int (int): function(|prompt:///|(0,33,<1,0>,<1,33>))
rascal>mapper([1, 2, 3, 4], incr);
list[int]: [2,3,4,5]

function max​

Determine the largest element in a list.

&T max([&T h, *&T t])

&T max(list[&T] _:[])

Examples​

rascal>import List;
ok
rascal>max([1, 3, 5, 2, 4]);
int: 5
rascal>max(["zebra", "elephant", "snake", "owl"]);
str: "zebra"
───
zebra
───

function merge​

Merge the elements of two sorted lists into one list.

list[&T] merge(list[&T] left, list[&T] right)

list[&T] merge(list[&T] left, list[&T] right, bool (&T a, &T b) lessOrEqual)

Merge the elements of two sorted lists into one list using the built-in ordering between values. Optional, a comparison function lessOrEqual may be given for a user-defined ordering between values.

Examples​

rascal>import List;
ok
rascal>merge([1, 3, 5], [2, 7, 9, 15]);
list[int]: [1,2,3,5,7,9,15]
rascal>merge(["ape", "elephant", "owl", "snail", "zebra"], ["apple", "berry", "orange", "pineapple"]);
list[str]: ["ape","apple","berry","elephant","orange","owl","pineapple","snail","zebra"]

Merge two lists of strings and use their length as ordering:

rascal>import String;
ok
rascal>merge(["ape", "owl", "snail", "zebra", "elephant"], ["apple", "berry", "orange", "pineapple"], bool(str x, str y){ return size(x) <= size(y); });
list[str]: ["ape","owl","snail","zebra","apple","berry","orange","elephant","pineapple"]

function min​

Determine the smallest element in a list.

&T min([&T h, *&T t])

&T min(list[&T] _: [])

Examples​

rascal>import List;
ok
rascal>min([1, 3, 5, 2, 4]);
int: 1
rascal>min(["zebra", "elephant", "snake", "owl"]);
str: "elephant"
───
elephant
───

function mix​

Mix the elements of two lists.

list[&T] mix(list[&T] l, list[&T] r)

Let n be the minimum of the length of the two lists l and r. mix returns a list in which the first n elements are taken alternately from the left and the right list, followed by the remaining elements of the longest list.

Examples​

rascal>import List;
ok
rascal>mix([3, 1, 7, 5, 9], [15, 25, 35]);
list[int]: [3,15,1,25,7,35,5,9]
rascal>mix([3, 1, 7], [15, 25, 35, 45, 55]);
list[int]: [3,15,1,25,7,35,45,55]
rascal>mix([3, 1, 7], ["elephant", "snake"]);
list[value]: [3,"elephant",1,"snake",7]

function permutations​

Compute all permutations of a list.

set[list[&T]] permutations(list[&T] lst)

Examples​

rascal>import List;
ok
rascal>permutations([1,2,3]);
set[list[int]]: {
  [3,2,1],
  [1,2,3],
  [2,1,3],
  [1,3,2],
  [2,3,1],
  [3,1,2]
}

function permutationsBag​

set[list[&T]] permutationsBag(map[&T element, int occurs] b)

function pop​

Pop top element from list, return a tuple.

tuple[&T, list[&T]] pop(list[&T] lst)

This function is identical to Head Tail. Also see Push and Top.

Examples​

rascal>import List;
ok
rascal>pop([3, 1, 4, 5]);
tuple[int,list[int]]: <3,[1,4,5]>
rascal>headTail([3, 1, 4, 5]);
tuple[int,list[int]]: <3,[1,4,5]>
rascal>pop(["zebra", "elephant", "snake", "owl"]);
tuple[str,list[str]]: <"zebra",["elephant","snake","owl"]>

function prefix​

Return all but the last element of a list.

list[&T] prefix(list[&T] lst)

Examples​

rascal>import List;
ok
rascal>prefix([3, 1, 4, 5]);
list[int]: [3,1,4]
rascal>prefix([]);
list[void]: []
rascal>prefix(["zebra", "elephant", "snake", "owl"]);
list[str]: ["zebra","elephant","snake"]

function push​

Push an element in front of a list.

list[&T] push(&T elem, list[&T] lst)

Also see Pop and Top.

Examples​

rascal>import List;
ok
rascal>push(7, [3, 1, 4, 5]);
list[int]: [7,3,1,4,5]
rascal>push("eagle", ["zebra", "elephant", "snake", "owl"]);
list[str]: ["eagle","zebra","elephant","snake","owl"]

function reducer​

Apply a function to successive elements of list and combine the results.

&T reducer(list[&T] lst, &T (&T, &T) fn, &T unit)

Apply the function fn to successive elements of list lst starting with unit. The function application reducer(lst, add, 0) has the same semantics as the expression (0 | add(it, e) | e <- lst).

Examples​

rascal>import List;
ok
rascal>int add(int x, int y) { return x + y; }
int (int, int): function(|prompt:///|(0,39,<1,0>,<1,39>))
rascal>reducer([10, 20, 30, 40], add, 0); 
int: 100

Benefits​

  • reducer can be passed as a function argument

Pitfalls​

  • a reducer expression can be a lot faster
  • reducer expressions are more versatile (allowing multiple generators and filters)

function remove​

list[&T] remove(list[&T] lst, int indexToDelete)

function removeFromBag​

map[&T element, int occurs] removeFromBag(map[&T element, int occurs] b, &T el)

map[&T element, int occurs] removeFromBag(map[&T element, int occurs] b, &T el, int nr)

function reverse​

Reverse a list.

list[&T] reverse(list[&T] lst)

Returns a list with the elements of lst in reverse order.

Examples​

rascal>import List;
ok
rascal>reverse([1,4,2,3]);
list[int]: [3,2,4,1]
rascal>reverse(["zebra", "elephant", "snake", "owl"]);
list[str]: ["owl","snake","elephant","zebra"]

function size​

Determine the number of elements in a list.

int size(list[&T] lst)

Examples​

rascal>import List;
ok
rascal>size([20, 10, 30]);
int: 3
rascal>size(["zebra", "elephant", "snake", "owl"]);
int: 4

function slice​

Compute a sublist of a list.

list[&T] slice(list[&T] lst, int begin, int len)

Returns a sublist of lst from index start of length len.

danger

In most cases it is better to use the built-in slice notation, see the example below.

Examples​

rascal>import List;
ok
rascal>slice([10, 20, 30, 40, 50, 60], 2, 3);
list[int]: [30,40,50]
rascal>slice(["zebra", "elephant", "snake", "owl"], 1, 2);
list[str]: ["elephant","snake"]

Here are the equivalent expressions using the slice notation:

rascal>[10, 20, 30, 40, 50, 60][2 .. 5];
list[int]: [30,40,50]
rascal>["zebra", "elephant", "snake", "owl"][1 .. 3];
list[str]: ["elephant","snake"]

WARNING: In the slice notation the upper bound is exclusive.

function sort​

Sort the elements of a list.

list[&T] sort(list[&T] lst)

list[&T] sort(list[&T] l, bool (&T a, &T b) less)

Sort the elements of a list:

  • Use the built-in ordering on values to compare list elements.
  • Give an additional lessThan function that will be used to compare elements.

Examples​

rascal>import List;
ok
rascal>import String;
ok
rascal>sort([10, 4, -2, 11, 100, 5]);
list[int]: [-2,4,5,10,11,100]
rascal>fruits = ["mango", "strawberry", "pear", "pineapple", "banana", "grape", "kiwi"];
list[str]: ["mango","strawberry","pear","pineapple","banana","grape","kiwi"]
rascal>sort(fruits);
list[str]: ["banana","grape","kiwi","mango","pear","pineapple","strawberry"]
rascal>sort(fruits, bool(str a, str b){ return size(a) > size(b); });
list[str]: ["strawberry","pineapple","banana","mango","grape","pear","kiwi"]

function isSorted​

Check whether a list is sorted or not.

bool isSorted(list[&T] l, bool (&T a, &T b) less = bool (&T a, &T b) { return a < b; })

Checks whether or not a list is sorted by searching for any out-of-order elements. The empty list is defined to be "sorted" and what sorted means is defined the higher-order parameter "less" which should implement a partial-order relation between the two parameters.

function shuffle​

Shuffle a list.

list[&T] shuffle(list[&T] l)

Returns a random (unbiased) shuffled list.

Examples​

rascal>import List;
ok
rascal>shuffle([1,4,2,3]);
list[int]: [3,1,4,2]
rascal>shuffle(["zebra", "elephant", "snake", "owl"]);
list[str]: ["zebra","snake","elephant","owl"]

function shuffle​

Shuffle a list with a seed.

list[&T] shuffle(list[&T] l, int seed)

Returns a random (unbiased) shuffled list, every call with the same seed shuffles in the same order.

Examples​

rascal>import List;
ok
rascal>shuffle([1,2,3,4]);
list[int]: [1,3,4,2]
rascal>shuffle([1,2,3,4]);
list[int]: [1,3,2,4]
rascal>shuffle([1,2,3,4], 1);
list[int]: [4,1,3,2]
rascal>shuffle([1,2,3,4], 1);
list[int]: [4,1,3,2]

function split​

Split a list into two halves.

tuple[list[&T],list[&T]] split(list[&T] l)

Examples​

rascal>import List;
ok
rascal>split([3, 1, 4, 5, 7]);
tuple[list[int],list[int]]: <[3,1],[4,5,7]>
rascal>split(["zebra", "elephant", "snake", "owl"]);
tuple[list[str],list[str]]: <["zebra","elephant"],["snake","owl"]>

function group​

Groups sublists for consecutive elements which are similar

list[list[&T]] group(list[&T] input, bool (&T a, &T b) similar)

This function does not change the order of the elements. Only elements which are similar end-up in a sub-list with more than one element. The elements which are not similar to their siblings, end up in singleton lists.

Examples​

rascal>import List;
ok
rascal>bool bothEvenOrBothOdd(int a, int b) = (a % 2 == 0 && b % 2 == 0) || (a % 2 == 1 && b % 2 == 1);
bool (int, int): function(|prompt:///|(0,96,<1,0>,<1,96>))
rascal>group([1,7,3,6,2,9], bothEvenOrBothOdd);
list[list[int]]: [
  [1,7,3],
  [6,2],
  [9]
]

function sum​

Sum the elements of a list.

(&T <:num) sum([(&T <: num) hd, *(&T <: num) tl])

(&T <:num) sum(list[&T] _: [])

Examples​

rascal>import List;
ok
rascal>sum([3, 1, 4, 5]);
int: 13
rascal>sum([3, 1.5, 4, 5]);
num: 13.5

function tail​

Get the tail element(s) from a list.

list[&T] tail([&T _, *&T t])

list[&T] tail(list[&T] _:[])

list[&T] tail(list[&T] lst, int len) throws IndexOutOfBounds
  • Return a list consisting of all but the first element of lst.
  • Return a list consisting of the last n elements of lst.

Examples​

All but first element:

rascal>import List;
ok
rascal>tail([10,20,30]);
list[int]: [20,30]

Try an error case:

rascal>tail([]);
|file:///home/runner/work/rascal/rascal/src/org/rascalmpl/library/List.rsc|(18289,9,<716,37>,<716,46>): EmptyList()
    at tail(|file:///home/runner/work/rascal/rascal/src/org/rascalmpl/library/List.rsc|(18252,51,<716,0>,<716,51>))
    at $(|prompt:///|(0,9,<1,0>,<1,9>))

Last n elements:

rascal>tail([10, 20, 30, 40, 50, 60], 3);
list[int]: [40,50,60]

Try an error case:

rascal>tail([10, 20, 30, 40, 50, 60], 10);
|file:///home/runner/work/rascal/rascal/src/org/rascalmpl/library/List.rsc|(18306,108,<718,0>,<719,66>): IndexOutOfBounds(4)
    at tail(|file:///home/runner/work/rascal/rascal/src/org/rascalmpl/library/List.rsc|(18306,108,<718,0>,<719,66>))
    at tail(|prompt:///|(31,2,<1,31>,<1,33>))

function take​

Get number of elements from the head of a list.

list[&T] take(int n, list[&T] lst)

Get n elements (or size(lst) elements if size(lst) < n) from the head of the list. See Drop to remove elements from the head of a list.

Examples​

rascal>import List;
ok
rascal>take(2, [3, 1, 4, 5]);
list[int]: [3,1]
rascal>take(6, [3, 1, 4, 5]);
list[int]: [3,1,4,5]
rascal>take(2, ["zebra", "elephant", "snake", "owl"]);
list[str]: ["zebra","elephant"]

function takeOneFrom​

Remove an arbitrary element from a list, returns the element and the modified list.

tuple[&T, list[&T]] takeOneFrom(list[&T] lst)

Select an arbitrary element from lst, and return a tuple consisting of:

  • the selected element, and
  • a new list consisting of all elements of lst except the selected element.

See GetOneFrom to only selected an element from a list.

Examples​

rascal>import List;
ok
rascal>takeOneFrom([10,20,30,40,50]);
tuple[int,list[int]]: <40,[10,20,30,50]>
rascal>takeOneFrom([10,20,30,40,50]);
tuple[int,list[int]]: <40,[10,20,30,50]>
rascal>takeOneFrom([10,20,30,40,50]);
tuple[int,list[int]]: <50,[10,20,30,40]>
rascal>takeOneFrom(["zebra", "elephant", "snake", "owl"]);
tuple[str,list[str]]: <"owl",["zebra","elephant","snake"]>
rascal>takeOneFrom(["zebra", "elephant", "snake", "owl"]);
tuple[str,list[str]]: <"elephant",["zebra","snake","owl"]>
rascal>takeOneFrom(["zebra", "elephant", "snake", "owl"]);
tuple[str,list[str]]: <"zebra",["elephant","snake","owl"]>

function takeWhile​

Take elements from the front of the list as long as a predicate is true.

list[&T] takeWhile(list[&T] lst, bool (&T a) take)

Examples​

rascal>import List;
ok
rascal>bool isEven(int a) = a mod 2 == 0;
bool (int): function(|prompt:///|(0,34,<1,0>,<1,34>))
rascal>takeWhile([2,4,6,8,1,2,3,4,5],isEven);
list[int]: [2,4,6,8]

function toMap​

Convert a list of pairs to a map; first elements are associated with a set of second elements.

map[&A,list[&B]] toMap(list[tuple[&A, &B]] lst) throws MultipleKey

Convert a list of tuples to a map in which the first element of each tuple is associated with the set of second elements from all tuples with the same first element. Keys should be unique.

Examples​

rascal>import List;
ok
rascal>toMap([<1,10>, <1, 11>, <2, 20>, <3, 30>, <3, 31>]);
map[int, list[int]]: (
  1:[10,11],
  3:[30,31],
  2:[20]
)

Pitfalls​

toMap collects all values in tuples with the same first value in a set. Contrast this with toMapUnique that associates each first tuple value with the second tuple value, but imposes the constraint that those keys are unique.

function toMapUnique​

Convert a list of tuples to a map; result must be a map.

map[&A,&B] toMapUnique(list[tuple[&A, &B]] lst) throws MultipleKey

Convert a list of tuples to a map; result must be a map.

Examples​

rascal>import List;
ok
rascal>toMapUnique([<1,10>, <2, 20>, <3, 30>]);
map[int, int]: (1:10,3:30,2:20)

Let's explore an error case:

rascal>toMapUnique([<1,10>, <1, 11>, <2, 20>, <3, 30>]);
|file:///home/runner/work/rascal/rascal/src/org/rascalmpl/library/List.rsc|(20736,630,<801,0>,<820,72>): MultipleKey(1,10,11)
    at toMapUnique(|file:///home/runner/work/rascal/rascal/src/org/rascalmpl/library/List.rsc|(20736,630,<801,0>,<820,72>))
    at toMapUnique(|prompt:///|(43,2,<1,43>,<1,45>))

Pitfalls​

The keys in a map are unique by definition. toMapUnique throws a MultipleKey exception when the list contains more than one tuple with the same first value.

function top​

Take the top element of a list.

&T top([&T t, *&T _])

This function is identical to Head. Also see Pop and Push.

Examples​

rascal>import List;
ok
rascal>top([3, 1, 4, 5]);
int: 3
rascal>top(["zebra", "elephant", "snake", "owl"]);
str: "zebra"
───
zebra
───

function toRel​

Convert a list to a relation.

rel[&T,&T] toRel(list[&T] lst)

Convert a list to relation, where each tuple encodes which elements are followed by each other. This function will return an empty relation for empty lists and for singleton lists.

Examples​

rascal>import List;
ok
rascal>toRel([3, 1, 4, 5]);
rel[int,int]: {
  <1,4>,
  <3,1>,
  <4,5>
}
rascal>toRel(["zebra", "elephant", "snake", "owl"]);
rel[str,str]: {
  <"snake","owl">,
  <"zebra","elephant">,
  <"elephant","snake">
}

function toSet​

Convert a list to a set.

set[&T] toSet(list[&T] lst)

Convert lst to a set.

Examples​

rascal>import List;
ok
rascal>toSet([10, 20, 30, 40]);
set[int]: {10,40,20,30}
rascal>toSet(["zebra", "elephant", "snake", "owl"]);
set[str]: {"snake","owl","zebra","elephant"}

Note that the same can be done using splicing

rascal>l = [10,20,30,40];
list[int]: [10,20,30,40]
rascal>s = {*l};
set[int]: {10,40,20,30}

function toString​

Convert a list to a string.

str toString(list[&T] lst)

Convert lst to a string.

Examples​

rascal>import List;
ok
rascal>toString([10, 20, 30]);
str: "[10,20,30]"
───
[10,20,30]
───
rascal>toString(["zebra", "elephant", "snake", "owl"]);
str: "[\"zebra\",\"elephant\",\"snake\",\"owl\"]"
───
["zebra","elephant","snake","owl"]
───

function itoString​

Convert a list to an indented string.

str itoString(list[&T] lst)

Convert lst to a indented string.

Examples​

rascal>import List;
ok
rascal>itoString([10, 20, 30]);
str: "[10,20,30]"
───
[10,20,30]
───
rascal>itoString(["zebra", "elephant", "snake", "owl"]);
str: "[\"zebra\",\"elephant\",\"snake\",\"owl\"]"
───
["zebra","elephant","snake","owl"]
───

function unzip2​

Make a pair (triple) of lists from a list of pairs (triples).

tuple[list[&T],list[&U]] unzip2(lrel[&T,&U] lst)

Also see Unzip3;

Examples​

rascal>import List;
ok
rascal>unzip2([<3,"thirty">, <1,"ten">, <4,"forty">]);
tuple[list[int],list[str]]: <[3,1,4],["thirty","ten","forty"]>
rascal>unzip3([<3,"thirty",300>, <1,"ten",100>, <4,"forty",400>]);
tuple[list[int],list[str],list[int]]: <[3,1,4],["thirty","ten","forty"],[300,100,400]>

function unzip3​

tuple[list[&T],list[&U],list[&V]] unzip3(lrel[&T,&U,&V] lst)

function upTill​

Returns the list 0,1..n-1.

list[int] upTill(int n)

Returns the list 0, 1, .., n-1, this is slightly faster than [0..n], since the returned values are shared.

Examples​

rascal>import List;
ok
rascal>upTill(10);
list[int]: [0,1,2,3,4,5,6,7,8,9]

function zip2​

Make a list of pairs from two lists of the same length.

lrel[&T first, &U second] zip2(list[&T] a, list[&U] b)

Also see Unzip2.

Examples​

rascal>import List;
ok
rascal>zip2([3, 1, 4], ["thirty", "ten", "forty"]);
lrel[int first,str second]: [
  <3,"thirty">,
  <1,"ten">,
  <4,"forty">
]
rascal>zip3([3, 1, 4], ["thirty", "ten", "forty"], [300, 100, 400]);
lrel[int first,str second,int third]: [
  <3,"thirty",300>,
  <1,"ten",100>,
  <4,"forty",400>
]

function zip2​

Make a list of pairs from two lists of possibly unequal length.

lrel[&T first, &U second] zip2(list[&T] a, &T defA, list[&U] b, &U defB)

function zipi​

Make a list of pairs: <i, e>, where i is the index of the e element of a list.

lrel[int index, &T elem] zipi(list[&T] a)

function zipi​

Make a list of pairs: <i, e>, where i is the index of the e element a set.

lrel[int index, &T elem] zipi(set[&T] a)

Useful for a countable iteration over a set. Does not make an intermediate copy of the set, but iterates over the elements.

function zip3​

Make a list of pairs from three lists of the same length.

lrel[&T first, &U second, &V third] zip3(list[&T] a, list[&U] b, list[&V] c)

function zip3​

Make a list of pairs from three lists of possibly unequal length.

lrel[&T first, &U second, &T third] zip3(list[&T] a, &T defA, list[&U] b, &U defB, list[&V] c, &V defC)