GDScript has a custom iterator protocol which enables looping over objects using the standard for loop.

itertools provides several custom iterators so you don't have to reinvent the wheel yourself. It duplicates most of the iterators provided by the Python itertools module.

The library comes in a single source file (itertools.gd) and is using typed code where possible.

Getting started

Installation

Copy the addon to your project's addons folder (or wherever else you like) and then load it into your scripts as follows:

const itertools = preload("res://path/to/itertools.gd")

The only things you actually need to keep around in your code base is the itertools.gd file and the LICENSE file (to comply with the licensing terms). You do not need to keep README.md, which serves as documentation, or the test_itertools.gd, which contains unit tests for itertool's API.

Convenience examples

You can get started with itertools by using it to write code that is slightly more convenient than what the code would look like otherwise:

# This will print the reversed array, ending in 'bananas', 'like' and 'I', without
# allocating a second array
var very_long_list_of_things_i_like = ['I', 'like', 'bananas', 'and', ... ]
for word in itertools.array_rev(very_long_list_of_things_i_like)
    print(word)

# For those of us who miss Python's dict.items() method in loops:
var x = {'Paris': 'France', 'London': 'England', 'Madrid': 'Spain'}
for item in itertools.dict_items(x):
    print("The capital of %s is %s" % [item[1], item[0]])

# processing two arrays in sequence without generating a temporary third array: 
var things_i_like = itertools.iter(['bananas', 'oranges', 'apples', ... ])
var things_you_like = itertools.iter(['chocolate', 'brownies', 'cookies', ...])
var things_we_like = itertools.chain(things_i_like, things_you_like)
for good_thing in things_we_like:
     print(good_thing)

# Filters names based on length - will print Charlie and Hadschi Halef Omar...
var names = ['Adam', 'Bob', 'Charlie', 'Eve', 'Hadschi Halef Omar Ben Hadschi Abul Abbas Ibn Hadschi Dawuhd al Gossarah', ..., 'Matt', 'Zoe']
var long_names = itertools.filter(func (x): return len(x) > 4, itertools.iter(names))
for name in long_names:
    print(name)

Rationale

The above examples can give you an idea about how to use iterators, but they're only toy examples (and not worth using instead of small arrays if you are worried about performance).

itertools is very handy when you have an object which stores a large amount of iterable data, and you would like the give the object's users views of this data without creating copies of it.

The actual power of iterators becomes obvious when you combine them to transform large sets of data. Iterators don't build temporary copies of the source data in memory while handling the transformation, and let you keep the gritty details of the transformation logic out of your loops.

Documentation

The full list of the available functions (itertools public API) is documented in README.md. All the public API functions are also documented via docstrings.

For examples on how to use the provided iterators, either look at the unit tests in test_itertools.gd or read about Python's itertools, which served as the inspiration and template for this addon.

Unit tests

To run the tests in test_itertools.gd, you need to install the GUT addon. It is not provided with the itertools addon.