iter

The module exposes functionality that enables any object to be an iterable object and provides functions do work with such iterable objects.

For an object to be iterable it has to provide an Iterator when passed into the iter() function. It does so by exposing an __iter__() method which is called by iter(). The return value of that method must be an Iterator which is then used for iterating over the elements of the iterable object. See iter.iter() and iter.Iterator for more information.

A number of function are provided for iterating over iterable object and performing operations on it's items. iter() - for iterating over iterable objects, map() - for maping items from an iterable object to a list, filter() - for creating a list containing only certain items from an iterable object list() - for creating a list containing all items from an iterable object.

The above functions only create an iterator for an iteratable object and call one of it's methods depending on what protocoll is used. See iter.Iterator for more information.

There is also a range() function for creating an iterator for a range of numbers.

module methods

  • iter(iterable) - Returns the Iterator for an object. iter() will look for an __iter___() method the iterable object might expose. If it does then the object returned from calling that method is returned otherwise it will check if the object is an Array or if it has a length property and will return an ArrayItereator. If that fails it will return an ObjectIterator or raise an error.

  • iter(iterable, thisObj=null, itemCallBack=null) - The iter() function can also be used to iterate over objects by suppliing an iterable, a callback and an optional this - object. It will create an Iterator and call it's __iterate__() method passing in the thisObj and the itemCallBack. In case the itemCallBack returns any value but undefined the iter() method will stop iterating and will return that value.
  • filter(iterable, thisObj=null, itemCallBack=null) - This method creates an Iterator and call it's __iterate__() method passing in the thisObj and the itemCallBack. It will return a list containing all items from the iterable object for which the itemCallBack returned True.
  • map(iterable, thisObj=null, itemCallBack=null) - This method creates an Iterator and call it's __map__() method passing in the thisObj and the itemCallBack. It will return a list containing all values returned by itemCallBack for each item in teh iterable object..
  • list(iterable) - This method creates an Iterator and return the value returned by calling the Iterator's __list__() method. This should return an Array containing all items from the iterable object.
  • range(start=0, end, step=1) - Returns a Range object. This is a shorthand for writing new Range(...).
  • zip(iterable1, iterable2, ...) - Returns an iterator which iterates over teh given iterable objects simulatiously. For each iteration step the items returned by each iterator for the iterable objects are passed into the callback as parameters.

module classes

Iterator() - This is the base class of all iterators. It provides default implementation for iteration, maping, filtering and conversion functionality. Any method may be overwritten in any subclass to increase performance as long as the functionality is implemented.

  • next() - returns the next item or undefined if there are no more items.
  • __iter__() - returns itself, so an Iterator can always be used as an iterable object.
  • __iterate__(thisObj, itemCallBack) - iterates over all items and calls the itemCallBack for each item with thisObj as the this-object. Iteration stops when there are no more items or if the itemCallBack returns any value but undefined. The return value will be the value returned by the itemCallBack or undefined.
  • __filter__(thisObj, itemCallBack) - iterates over all items and calls the itemCallBack for each item with thisObj as the this-object. Each item the itemCallBack returns true for will be appended to a list which is returned to the caller.
  • __map__(thisObj, itemCallBack) - iterates over all items and calls the itemCallBack for each item with thisObj as the this-object. Each value returned by the itemCallBack is added to a list which is returned to the caller.
  • __list__() - iterates over all items and adds them to a list which is returned to the caller.

Range(start=0, end, step=1) - A range class which inherits from Iterator. It can be used to iterate over a range of numbers.

  • start - The first number to start with.
  • end - The last number the Iterator will produce.
  • step - The ammount to add to the current number/item to generate the next.

ArrayItereator(arrayObject) - An Iterator which is specialized in iterating over arrays or any other object that has a length property and an index based access to items(e.g. some HTML objects, or arguments - object).

ObjectIterator(obj) - An Itereator which iterates over the members of an object. Each item it produces is a pair of {key:..., value:...} .

interfaces

IterationCallback(item, iterator) - This is the interfaces of the method which is called by the Iterator's iteration methods (__iterate__(), __filter__() and __map__()).

  • item - The item returned by the iterator for the current iteration step.
  • iterator - The iterator object itself. In case the iteration methods are not called with a thisObj parameter the this - object for the callback scope is the iterator itself.