/src/lib/iterator/iterator.e

  1-- This file is part of a Liberty Eiffel library.
  2-- See the full copyright at the end.
  3--
  4deferred class ITERATOR[E_]
  5   --
  6   -- The iterator pattern at work: this abstract class defines a
  7   -- traversal interface for any kind of aggregates data structure.
  8   -- An iterator can be used when you need to do something on all
  9   -- elements in the data structure, but there is no order concept.
 10   --
 11   -- To create a new iterator, use `new_iterator' in the
 12   -- corresponding data structure.
 13   --
 14   -- See examples in directory tutorial/iterator.
 15   --
 16
 17feature {ANY}
 18   frozen is_valid: BOOLEAN
 19      do
 20         Result := generation = iterable_generation
 21      end
 22
 23   start
 24         -- Positions the iterator to the first object in the
 25         -- aggregate to be traversed.
 26      deferred
 27      ensure
 28         is_valid
 29      end
 30
 31   is_off: BOOLEAN
 32         -- Returns True when there are no more objects in the
 33         -- sequence.
 34      require
 35         is_valid
 36      deferred
 37      ensure
 38         generation = old generation
 39         is_valid
 40      end
 41
 42   item: E_
 43         -- Returns the object at the current position in the
 44         -- sequence.
 45      require
 46         is_valid
 47         not is_off
 48      deferred
 49      ensure
 50         generation = old generation
 51         is_valid
 52      end
 53
 54   next
 55         -- Positions the iterator to the next object in the
 56         -- sequence.
 57      require
 58         is_valid
 59         not is_off
 60      deferred
 61      ensure
 62         generation = old generation
 63         is_valid
 64      end
 65
 66feature {ANY} -- Check that the underlying traversable has not changed
 67   iterable_generation: INTEGER
 68      deferred
 69      end
 70
 71   generation: INTEGER
 72      deferred
 73      end
 74
 75feature {ANY} -- Agent-based features:
 76   for_each (action: PROCEDURE[TUPLE[E_]])
 77         -- Apply `action' to every item of `Current'.
 78         --
 79         -- See also `for_all', `exists', `aggregate'.
 80      do
 81         from
 82            start
 83         invariant
 84            is_valid
 85         until
 86            is_off
 87         loop
 88            action.call([item])
 89            next
 90         end
 91      end
 92
 93   for_all (test: PREDICATE[TUPLE[E_]]): BOOLEAN
 94         -- Do all items satisfy `test'?
 95         --
 96         -- See also `for_each', `exists', `aggregate'.
 97      do
 98         from
 99            Result := True
100            start
101         invariant
102            is_valid
103         until
104            not Result or else is_off
105         loop
106            Result := test.item([item])
107            next
108         end
109      end
110
111   exists (test: PREDICATE[TUPLE[E_]]): BOOLEAN
112         -- Does at least one item satisfy `test'?
113         --
114         -- See also `for_each', `for_all', `aggregate'.
115      do
116         from
117            start
118         invariant
119            is_valid
120         until
121            Result or else is_off
122         loop
123            Result := test.item([item])
124            next
125         end
126      end
127
128   aggregate (action: FUNCTION[TUPLE[E_, E_], E_]; initial: E_): E_
129         -- Aggregate all the elements starting from the initial value.
130         --
131         -- See also `for_each', `for_all', `exists'.
132      do
133         from
134            Result := initial
135            start
136         invariant
137            is_valid
138         until
139            is_off
140         loop
141            Result := action.item([Result, item])
142            next
143         end
144      end
145
146feature {} -- Invariant on `generation` dynamics
147   generation_for_invariant: INTEGER
148
149   generation_only_grows: BOOLEAN
150      do
151         Result := generation >= generation_for_invariant
152         generation_for_invariant := generation
153      end
154
155invariant
156   generation_only_grows
157
158end -- class ITERATOR
159--
160-- Copyright (C) 2009-2017: by all the people cited in the AUTHORS file.
161--
162-- Permission is hereby granted, free of charge, to any person obtaining a copy
163-- of this software and associated documentation files (the "Software"), to deal
164-- in the Software without restriction, including without limitation the rights
165-- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
166-- copies of the Software, and to permit persons to whom the Software is
167-- furnished to do so, subject to the following conditions:
168--
169-- The above copyright notice and this permission notice shall be included in
170-- all copies or substantial portions of the Software.
171--
172-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
173-- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
174-- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
175-- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
176-- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
177-- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
178-- THE SOFTWARE.