Itertools

This package is a Nim rewrite of a very popular Python module of the same name.

It also includes some of the iterators from iterutils.

Installation

nimble install itertools

Required Nim version is at least 0.18.0.

Supported iterators

infinite iterators:
- count
- cycle
- repeat
terminating iterators:
- accumulate
- chain
- compress
- dropWhile
- filterFalse
- groupBy
- groupConsecutive
- islice
- takeWhile
combinatoric iterators:
- product
- distinctPermutations
- permutations
- combinations
iterutils iterators:
- chunked
- windowed
- pairwise
- unique

Usage

For more comprehensive examples, see the documentation.

Infinite iterators

WARNING: Version 0.3.0 introduced breaking changes regarding how these three iterators are implemented and used. See the examples below for the new behaviour.

import itertools

for i in count(5):
  if i > 9: break
  echo i
# 5; 6; 7; 8; 9

for i in count(100, 30):
  if i > 200: break
  echo i
# 100; 130; 160; 190

var n = 0
for i in @["I", "repeat", "myself"].cycle:
  inc n
  if n > 8: break
  echo i
# I; repeat; myself; I; repeat; myself; I; repeat

for i in "Beetlejuice".repeat(3):
  echo i
# Beetlejuice; Beetlejuice; Beetlejuice

var k = 0
for i in "forever".repeat:
  inc k
  if k > 6: break
  echo i
# forever; forever; forever; forever; forever; forever

Terminating iterators

import itertools
import future # to use `=>` for anonymous proc


let # you can use: sequences, arrays, strings
  numbers = @[1, 3, 7, 8, 4, 2, 6, 5, 9]
  constants = [2.7183, 3.1416, 1.4142, 1.7321]
  word = "abracadabra"


for i in accumulate(constants, (x, y) => x + y):
  echo i
# 2.7183; 5.8599; 7.2741; 9.0062

for i in compress(numbers, [true, true, false, true, false, true]):
  echo i
# 1; 3; 8; 2

for i in dropWhile(numbers, x => (x != 8)):
  echo i
# 8; 4; 2; 6; 5; 9

for i in filterFalse(word, x => (x == 'a')):
  echo i
# b; r; c; d; b; r

for key, group in numbers.groupBy(x => x mod 2 == 0):
  echo "key: ", key, " group: ", group
# key: true, group: @[8, 4, 2, 6]; key: false, group: @[1, 3, 7, 5, 9]

for key, group in word.groupBy():
  echo group
# @['a', 'a', 'a', 'a', 'a']; @['b', 'b']; @['c']; @['d']; @['r', 'r']

for key, group in groupConsecutive("aaabaabb"):
  echo group
# @['a', 'a', 'a']; @['b']; @['a', 'a']; @['b', 'b']

for i in islice(numbers, 5):
  echo i
# 2; 6; 5; 9

for i in islice(word, 1, step=2):
  echo i
# b; a; a; a; r

for i in islice(numbers, stop=5, step=2):
  echo i
# 1; 7; 4

for i in takeWhile(constants, x => (x >= 2.0)):
  echo i
# 2.7183; 3.1416

for i in chain(@[1, 3, 5], @[2, 4, 6], @[7, 8, 9]):
  echo i
# 1; 3; 5; 2; 4; 6; 7; 8; 9

Combinatoric iterators

import itertools
import strutils # to join seq[char] into a string


let # you can use: sequences, arrays, strings
  numbers = @[1, 3, 7, 8, 4]
  constants = [2.7183, 3.1416]
  word = "abba"


for i in product([0, 1], repeat = 3):
  echo i
# @[0, 0, 0]; @[0, 0, 1]; @[0, 1, 0]; @[0, 1, 1]; @[1, 0, 0]; @[1, 0, 1]; @[1, 1, 0]; @[1, 1, 1]

for i in product(numbers, constants):
  echo i
# (a: 1, b: 2.7183); (a: 1, b: 3.1416); (a: 3, b: 2.7183); (a: 3, b: 3.1416); (a: 7, b: 2.7183); (a: 7, b: 3.1416); (a: 8, b: 2.7183); (a: 8, b: 3.1416); (a: 4, b: 2.7183); (a: 4, b: 3.1416)

for i in distinctPermutations(word):
  echo i.join
# aabb; abab; abba; baab; baba; bbaa

for i in permutations(word):
  echo i.join
# abba; abab; abba; abab; aabb; aabb; baba; baab; bbaa; bbaa; baab; baba; baba; baab; bbaa; bbaa; baab; baba; aabb; aabb; abab; abba; abab; abba

for i in combinations(5, 3):
  echo i
# @[0, 1, 2]; @[0, 1, 3]; @[0, 1, 4]; @[0, 2, 3]; @[0, 2, 4]; @[0, 3, 4]; @[1, 2, 3]; @[1, 2, 4]; @[1, 3, 4]; @[2, 3, 4]

for i in combinations(numbers, 2):
  echo i
# @[1, 3]; @[1, 7]; @[1, 8]; @[1, 4]; @[3, 7]; @[3, 8]; @[3, 4]; @[7, 8]; @[7, 4]; @[8, 4]

Iterutils iterators

import itertools


let # you can use: sequences, arrays, strings
  numbers = @[1, 3, 7, 8, 4, 2, 6, 5, 9]
  constants = [2.7183, 3.1416, 1.4142, 1.7321]
  word = "abracadabra"


for i in chunked(numbers, 3):
  echo i
# @[1, 3, 7]; @[8, 4, 2]; @[6, 5, 9]

for i in windowed(numbers, 4):
  echo i
# @[1, 3, 7, 8]; @[3, 7, 8, 4]; @[7, 8, 4, 2]; @[8, 4, 2, 6]; @[4, 2, 6, 5]; @[2, 6, 5, 9]

for i in pairwise(constants):
  echo i
# @[2.7183, 3.1416]; @[3.1416, 1.4142]; @[1.4142, 1.7321]

for i in unique(word):
  echo i
# a; b; r; c; d

Contributing

There is probably a lot of room for improvement. Feel free to fork the repo and submit your PRs.

Before submitting, run nim doc -o:./docs/index.html ./src/itertools.nim to make sure that all the asserts in runnableExamples are passing.

License

MIT license

narimiran/itertools