NAME python::itertools

SYNOPSIS

A direct port of Python's itertools to perl6.

DESCRIPTION

It provides all the functionality that python's itertools does, including lazy evaluation. In the future, I'd like to maximize the performance of these functions. Function signatures may be a little different.

I needed a itertools.combinations_with_replacement and couldn't find an easy builtin or library to do it. So why not write the library myself? It turns out raku has most of these functions built in already. Unfortunatley, I did not realize that until after writing it. Oops.

FUNCTIONS

accumulate(@iterable, $func=&[+]) Gathers accumulated sums, or accumulated results of other binary functions (specified via the optional $func argument). If $func is supplied, it should be a function of two arguments.

accumulate((1,2,3,4,5)) --> (1, 3, 6, 10, 15)
accumulate((1,2,3,4,5), &[*]) --> (1, 2, 6, 24, 120)

batched(@iterable, $n) groups items of @iterable into lists of size $n. If there's not enough to create a list of size $n, then takes the remaining items.

batched(('a','b','c','d','e','f','g'), 2) -> (('a', 'b'), ('c', 'd'), ('e', 'f'), ('g'))

combinations(@iterable, $r) Gathers all combinations of length $r from @iterable, not allowing repeated elements

combinations(('a','b','c','d'), 2) -> (('a','b'), ('a','c'), ('a','d'), ('b','c'), ('b','d'), ('c','d'));

combinations_with_replacement(@iterable, $r) Gathers all combinations of length $r from @iterable, allowing elements to repeat.

combinations_with_replacement(('a','b','c'), 2) -> (('a','a'), ('a','b'), ('a','c'), ('b','a'), ('b','b'), ('b','c'), ('c','a'), ('c','b'), ('c','c'));

chain(*@iterables) Merges all of *@iterables into a single list.

chain(("A","B","C"), ("D","E","F")) --> ("A", "B", "C", "D", "E", "F")

count($start is copy, $step=1) Gathers values from $start, increasing by $step each time. Infinte list.

count(10)[^5] --> (10, 11, 12, 13, 14)
count(10, 2)[^5], (10,12,14,16,18);

compress(@elements, @selectors) Returns all members of @elements where the corresponding ?@selector is True.

compress(['a','b','c','d'], [True,False,True,False]) -> ['a','c']

cycle(@iterable ) Creates an infinite repeating List from @iterable

cycle(['a','b','c','d'])[^6] -> ['a','b','c','d','a','b']

dropwhile(@elements, $predicate=Bool) Shifts @elements until $predicate evaluates to False and gathers remaining elements

dropwhile([1,4,6,4,1], {$_ < 5;}) --> [6,4,1];

filterfalse($predicate, @iterable) Filters elements from @iterable where $predicate is False

filterfalse({ $_ % 2 == 1}, 0..5) -> [0,2,4];

groupby(@iterable, $key={ $_} ) Groups elements into Lists by a function defined in $key. Default is the identity function.

groupby(['a','b','a','a','a','b','b','c','a']) -> (('a','a','a','a','a'),('b','b','b'),('c'));
groupby(0..5, { $_ % 2 }) -> ((0, 2, 4),(1, 3, 5));

islice(@iterable, $stop)

islice(@iterable, $start, $stop, :$step=1) Slices @iterable from $start to $stop, skipping $step-1 elements. If only $stop is defined, starts from 0. If $stop is Nil, uses the entire @iterable;

islice(('a','b','c','d','e','f','g') , 2) -> ('a', 'b');
islice(('a','b','c','d','e','f','g') , 2, 4) -> ('c', 'd');
islice(('a','b','c','d','e','f','g') , 2, Nil) -> ('c', 'd', 'e', 'f', 'g');
islice(('a','b','c','d','e','f','g') , 0, Nil, step => 2) -> ('a', 'c', 'e', 'g');

pairwise(@iterable) Creates sucessive overlapping pairs of elements from @iterable. If @iterable has less than 2 elements, returns empty list

pairwise(('a','b','c','d','e','f','g')) -> (('a', 'b'), ('b', 'c'), ('c', 'd'), ('d', 'e'), ('e', 'f'), ('f', 'g'));
pairwise(['a']) -> ();

permutations(@iterable, $r) Creates sucessive $r-length permutations from iterable. If $r is Nil, uses the length of @iterable as $r

permutations(('A', 'B', 'C', 'D'), 2) -> (('A', 'B') , ('A', 'C'), ('A','D'), ('B', 'A'), ('B', 'C'), ('B', 'D'), ('C', 'A'), ('C', 'B'), ('C', 'D'), ('D', 'A'), ('D', 'B'), ('D', 'C'));

product(**@iterables, :$repeat=1) Duplicates each item in @iterables $repeat times and then creates the cartesian product of all items.

product([0,1], :repeat(3)) -> ((0,0,0), (0,0,1), (0,1,0), (0,1,1), (1,0,0), (1,0,1), (1,1,0), (1,1,1));
product([0,1], [0,1]) -> ((0,0), (0,1), (1,0), (1,1));
product([0,1], [0,1], :repeat(2)) -> ((0, 0, 0, 0), (0, 0, 0, 1), (0, 0, 1, 0), (0, 0, 1, 1), (0, 1, 0, 0), (0, 1, 0, 1), (0, 1, 1, 0), (0, 1, 1, 1), (1, 0, 0, 0), (1, 0, 0, 1), (1, 0, 1, 0), (1, 0, 1, 1), (1, 1, 0, 0), (1, 1, 0, 1), (1, 1, 1, 0), (1, 1, 1, 1));

repeat($obj, Int $times=0) Gathers $obj $times times or Infintely if $times is 0.

repeat("3")[^5] -> [3,3,3,3,3];  
repeat("3",3) -> [3,3,3];  

starmap($function, @iterable) Gathers items where each item in @iterable is computed with $function. Used instead of map when argument parameters are already grouped in tuples from a single iterable (the data has been “pre-zipped"

starmap(&sum, ((1,2,3), (4,5,6))) -> (6, 15)

tee(@iterable, $n) Gathers $n independent @iterable;

tee(1..5 ,3) -> (1..5, 1..5, 1..5);

takewhile(@elements, $predicate=Bool) Gathers items from @elements until $predicate evaluates to False.

takewhile([1,4,6,4,1], {$_ < 5;}) -> [1,4];

zip_longest(@elements, :$fillvalue=Nil) zips elements from each of @iterables. If the iterables are of uneven length, fillvalue replaces the missing values. Iteration continues until the longest iterable is exhausted.

zip_longest((1,2,3,4),(1,2), (-1,-2,-3), :fillvalue("0")) -> ((1,1,-1), (2,2,-2), (3,"0",-3), (4, "0","0"));