dhii/iterator-interface

Interfaces for standard iterators

v0.1-alpha1 2018-04-24 19:28 UTC

Requires

• php: ^5.3 | ^7.0
• dhii/data-hierarchy-interface: ^0.1
• dhii/data-key-value-aware-interface: ^0.1
• dhii/data-path-aware-interface: ^0.1
• dhii/exception-interface: ^0.1 | ^0.2

Requires (Dev)

• codeclimate/php-test-reporter: <=0.3.2
• dhii/php-cs-fixer-config: dev-php-5.3
• phpunit/phpunit: ^4.8
• ptrofimov/xpmock: ^1.1

MIT

• Dhii Team

README

Details

An iterator standard, which aims to provide more information about each iteration by exposing an immutable iteration object. This object can be safely passed to other methods, even those which save the reference to it, as a new object is created for every iteration. That object can provide additional information besides the current key and value. This makes implementations of this standard easier to work with than other iterator implementations, such as DirectoryIterator, which expose iteration data through the iterator itself, instead of a separate object, making it hard to keep iteration data immutable. The fact that its manipulator methods are allowed to throw a specific type of exception make it possible to create more reliable consumers with meaningful error reporting.

Features

• All standards-compliant iterators are PHP iterators.
• Iteration information provided via immutable and extensible iteration objects.
• Easier to keep track of iteration information: each iteration produces a separate iteration object.
• Specialized iterator types can be created on interface level by promising custom iteration types.

Interfaces

• IteratorInterface - Extends the native Iterator by exposing a disposable iteration object. Also promises to throw a specific kind of meaningful exception when rewinding or advancing.
• IterationInterface - Exposes the key and the value of an iteration.
• IteratorAwareInterface - Exposes an iterator.
• RecursiveIteratorInterface - An iterator that iterates over other iterators recursively.
• RecursiveIterationInterface - An iteration of a recursive iterator. Exposes the depth of the iterator hierarchy, and the path to the current iteration in that hierarchy.
• DepthAwareIterationInterface - An iteration that can tell how deep it is in a hierarchy.
• PathSegmentsAwareIterationInterface - An iteration that can tell the path to itself in a hierarchy.
• IteratingExceptionInterface - An exception that can occur during iteration.
• IterationExceptionInterface - An iterating exception that relates to an iteration.
• IteratorExceptionInterface - An iteration exception that relates to an iterator.