pif_Iterator

pif_Iterator implements a 'protocol class' for Iterator objects. By 'protocol class', I mean that the /pif_Iterator class defines seven methods (three of which are optional) to be used by subclasses to allow programmers to incrementally iterate through some set of data, whether it is from a data structure or streaming from another source or randomly generate as the sequence is iterated through.

The "pif_Iterator class.dm" file defines the /pif_Iterator protocol class and details the protocol itself. Refer to this file for the protocol in full detail, but an abbreivation of it is here.

A particular Iterator class should be designed to only accept and 'understand' data from a given source. That is, there should be no "swiss-army knife" Iterator designed to work with any and every possible source of data. Make a given Iterator class do one thing and do it well.

The protocol consists of seven methods, along with the constructor. Their behavior is as follows.

1. The Iterator class constructor should accept an argument indicating the data source to read from.
2. The Iterator Initialize() method should be called to begin iterating through data from the source provided to the constructor.
3. The Next() method moves to the 'next' piece of data from the data source, and returns either the new position or 0, if the end of the data has been reached. It may optionally take an argument indicating a position to move to.
4. The Look() method gives the data from the source data at the current position.
5. The Done() method returns true when the end of the data has been reached, and false otherwise.
6. The Step() method moves the current position forward or backwards by a certain amount, as indicated by its argument. This method is optional.
7. The Peek() method looks at the data in a position forward or backwards by a certain amount, as indicated by its argument. This method is optional.
8. The Position() method indicates the current position in the data. If the data has no meaningful position, it may also be used as a counter, to indicate how much data has been moved through.

Four additional classes are included as a demonstration of the protocol, as well as for general use. These are,

• ForwardListIterator and BackwardListIterator are iterators on the native DM /list object.
  • The ForwardListIterator class iterates over a list from the first element to the last
  • The BackwardListIterator class iterates over a list from the last element to the first.
• The RangeIterator class iterates over a used-specified range with an optional step size.
• The MethodIterator class iterates a supplied method or function over a specified domain.

Release Notes
Version 1.02.20191216.

• Reorganized files.
• Added MIT license to project, under "+License.dm".
• Updated documentation to reflect MIT license.

Version 1.01.20151028.

• Added /pif_Iterator/RangeIterator class.
  
  • Added RangeIterator class documentation.
• Added /pif_Iterator/MethodIterator class.
  • Added MethodIterator class documentation.
• Clarified protocol note for when methods are called before Initialize().

Version 1.0.20151023.

• Initial release.

The MIT License

Copyright (c) 2016-2024 Timothy "popisfizzy" Reilly

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.