ModuleIterator - Maple Help

ModuleIterator

iterate over the elements of a module

 Calling Sequence module() local ModuleIterator, ...; ... end module; module() option object; export lowerbound, upperbound, ?[], ...; ...; end module;

Description

 • The ModuleIterator routine allows a module or object to return an interface that can be used to iterate over elements contained within the module (or object).
 • If a module defines a ModuleIterator routine as a local or export, that module may be used as the container in for-in loops, as well as calls to seq, add and mul.
 • A call to ModuleIterator should return two procedures.
 > (hasNext,getNext) := ModuleIterator( obj );

The hasNext function should return true or false depending on if there are more elements remaining.

The getNext function should return the next element to be accessed.

The getNext function has an optional unevaluated name parameter. If passed a name, the function should assign the index of the returned element to this name. If the concept of an index makes no sense for the module or object, the name should be left unassigned.

A module with a getNext function that does assign an index can be used as the container in a two-variable for-in loop.

 • The basic pattern for using these routines is as follows
 > while hasNext() do       e := getNext('i');       # Do something with e; index of e is available in i.   end do;
 • It should always be safe to call getNext if a call to hasNext returns true.  If a call to hasNext returns false, the return value of a call to getNext is unspecified.
 • Calling hasNext multiple times without intervening calls to getNext should always return the same result.
 • If the module being defined is an object, then there is an alternative mechanism for iterating over the module. This works by overriding three methods for the object: lowerbound, upperbound, and ?[]. If an object has these three methods but no ModuleIterator member, then Maple will call the lowerbound and upperbound members to get bounds (which must be integers) for indexing, and the ?[] member to retrieve the elements between these bounds, inclusive. In particular, for such an object m,
 > for i, e in m do       # Do something with e.   end do;
 is equivalent to
 > for i from lowerbound(m) to upperbound(m) do       e := m[i];       # Do something with e.   end do;

Examples

We can create a module that can be used to iterate over all prime numbers.

 > Primes := module()    local ModuleIterator := proc()        local i, e;        i := 1;        e := 1;        (            proc()                true;            end proc,            proc( returnIndex := NULL )                if returnIndex <> NULL then                    returnIndex := i;                    i := i + 1                end if;                e := nextprime( e );            end proc        )    end proc; end module;
 ${\mathrm{Primes}}{≔}{\mathbf{module}}\left({}\right)\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{\mathbf{local}}\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{\mathrm{ModuleIterator}}{;}\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{}\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{\mathbf{end module}}$ (1)

As there are infinitely many primes, we need to introduce our own termination condition. For example, the following loop will print the first 100 primes:

 > $\mathbf{for}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}i,p\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{in}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathrm{Primes}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{do}\phantom{\rule[-0.0ex]{0.0em}{0.0ex}}\phantom{\rule[-0.0ex]{2.0em}{0.0ex}}\mathrm{print}\left(p\right)\phantom{\rule[-0.0ex]{0.0em}{0.0ex}}\mathbf{until}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}100\le i$
 ${2}$
 ${3}$
 ${5}$
 ${7}$
 ${11}$
 ${13}$
 ${17}$
 ${19}$
 ${23}$
 ${29}$
 ${31}$
 ${37}$
 ${41}$
 ${43}$
 ${47}$
 ${53}$
 ${59}$
 ${61}$
 ${67}$
 ${71}$
 ${73}$
 ${79}$
 ${83}$
 ${89}$
 ${97}$
 ${101}$
 ${103}$
 ${107}$
 ${109}$
 ${113}$
 ${127}$
 ${131}$
 ${137}$
 ${139}$
 ${149}$
 ${151}$
 ${157}$
 ${163}$
 ${167}$
 ${173}$
 ${179}$
 ${181}$
 ${191}$
 ${193}$
 ${197}$
 ${199}$
 ${211}$
 ${223}$
 ${227}$
 ${229}$
 ${233}$
 ${239}$
 ${241}$
 ${251}$
 ${257}$
 ${263}$
 ${269}$
 ${271}$
 ${277}$
 ${281}$
 ${283}$
 ${293}$
 ${307}$
 ${311}$
 ${313}$
 ${317}$
 ${331}$
 ${337}$
 ${347}$
 ${349}$
 ${353}$
 ${359}$
 ${367}$
 ${373}$
 ${379}$
 ${383}$
 ${389}$
 ${397}$
 ${401}$
 ${409}$
 ${419}$
 ${421}$
 ${431}$
 ${433}$
 ${439}$
 ${443}$
 ${449}$
 ${457}$
 ${461}$
 ${463}$
 ${467}$
 ${479}$
 ${487}$
 ${491}$
 ${499}$
 ${503}$
 ${509}$
 ${521}$
 ${523}$
 ${541}$ (2)

A container object with a ModuleIterator can be used like a built-in Maple structure.

 > module IterObj()    option object;    local _list;    export setValue::static := proc( obj::IterObj, l::list )        obj:-_list := l    end proc;    export ModuleIterator::static := proc( obj::IterObj )        local i, l;        i := 1;        l := obj:-_list;        (            proc()                i <= numelems( l )            end proc,            proc( returnIndex := NULL )                local e;                e := l[i];                if returnIndex <> NULL then                    returnIndex := i                end if;                i := i+1;                e;            end proc        );    end proc; end module:
 > $\mathrm{io}≔\mathrm{Object}\left(\mathrm{IterObj}\right):$
 > $\mathrm{setValue}\left(\mathrm{io},\left[1,2,3\right]\right):$
 > $\mathrm{hasNext},\mathrm{getNext}≔\mathrm{ModuleIterator}\left(\mathrm{io}\right)$
 ${\mathrm{hasNext}}{,}{\mathrm{getNext}}{≔}{\mathbf{proc}}\left({}\right)\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{i}{<=}{\mathrm{numelems}}{}\left({l}\right)\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{\mathbf{end proc}}{,}{\mathbf{proc}}\left({\mathrm{returnIndex}}{≔}{\mathrm{NULL}}\right)\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{\mathbf{local}}\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{e}{;}\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{e}{≔}{l}{[}{i}{]}{;}\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{\mathbf{if}}\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{\mathrm{returnIndex}}{<>}{\mathrm{NULL}}\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{\mathbf{then}}\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{\mathrm{returnIndex}}{≔}{i}\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{\mathbf{end if}}{;}\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{i}{≔}{i}{+}{1}{;}\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{e}\phantom{\rule[-0.0ex]{0.5em}{0.0ex}}{\mathbf{end proc}}$ (3)
 > $\mathbf{while}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathrm{hasNext}\left(\right)\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{do}\phantom{\rule[-0.0ex]{0.0em}{0.0ex}}\phantom{\rule[-0.0ex]{2.0em}{0.0ex}}e≔\mathrm{getNext}\left(\right)\phantom{\rule[-0.0ex]{0.0em}{0.0ex}}\mathbf{end}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{do}$
 ${1}$
 ${2}$
 ${3}$ (4)
 > $\mathbf{for}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}i\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{in}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathrm{io}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{do}\phantom{\rule[-0.0ex]{0.0em}{0.0ex}}\phantom{\rule[-0.0ex]{2.0em}{0.0ex}}i\phantom{\rule[-0.0ex]{0.0em}{0.0ex}}\mathbf{end}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{do}$
 ${1}$
 ${2}$
 ${3}$ (5)
 > $\mathrm{add}\left(i,i\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{in}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathrm{io}\right)$
 ${6}$ (6)
 > $\mathrm{mul}\left(i,i\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{in}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathrm{io}\right)$
 ${6}$ (7)
 > $\mathrm{seq}\left({i}^{2},i\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{in}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathrm{io}\right)$
 ${1}{,}{4}{,}{9}$ (8)

Alternatively, this object could be implemented as follows.

 > module IterObj2()    option object;    local _list;    export setValue::static := proc( obj::IterObj2, l::list )        obj:-_list := l    end proc;    export lowerbound::static := ( self::IterObj2 ) -> 1;    export upperbound::static := ( self::IterObj2 ) -> numelems( self:-_list );    export ?[]::static := proc( self::IterObj2, idx::list )        if type( idx, ['posint'] ) and idx[1] <= numelems( self:-_list ) then            return self:-_list[idx[1]];        else            error "invalid subscript selector";        end if;    end proc; end module:
 > $\mathrm{io2}≔\mathrm{Object}\left(\mathrm{IterObj2}\right):$
 > $\mathrm{setValue}\left(\mathrm{io2},\left[1,2,3\right]\right):$
 > $\mathbf{for}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}i\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{in}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathrm{io2}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{do}\phantom{\rule[-0.0ex]{0.0em}{0.0ex}}\phantom{\rule[-0.0ex]{2.0em}{0.0ex}}i\phantom{\rule[-0.0ex]{0.0em}{0.0ex}}\mathbf{end}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{do}$
 ${1}$
 ${2}$
 ${3}$ (9)
 > $\mathrm{add}\left(i,i\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{in}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathrm{io2}\right)$
 ${6}$ (10)
 > $\mathrm{mul}\left(i,i\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{in}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathrm{io2}\right)$
 ${6}$ (11)
 > $\mathrm{seq}\left({i}^{2},i\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathbf{in}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathrm{io2}\right)$
 ${1}{,}{4}{,}{9}$ (12)

Compatibility

 • The ModuleIterator command was introduced in Maple 16.