/src/lib/abilities/indexable.e

  1-- This file is part of a Liberty Eiffel library.
  2-- See the full copyright at the end.
  3--
  4deferred class INDEXABLE[E_]
  5   --
  6   -- An `INDEXABLE[E_]' is a finite readable sequence of objects of type E_.
  7   --
  8   -- A good performance should always be obtained by sequentially accessing an `INDEXABLE' with increasing
  9   -- indexes (from `lower' to `upper'), as demonstrated in the following code snippet :
 10   --
 11   --  from
 12   --     i := a_indexable.lower
 13   --  until
 14   --     i > a_indexable.upper
 15   --  loop
 16   --     do_something_with(a_indexable.item(i))
 17   --     i := i + 1
 18   --  end
 19   --
 20   -- Other accessing methods (including random access and sequential access from `upper' to `lower') may or
 21   -- may not lead to acceptable performance, depending on the particular implementation of `INDEXABLE'.
 22   --
 23
 24inherit
 25   HOARD[E_]
 26      redefine
 27         out_in_tagged_out_memory
 28      end
 29
 30feature {ANY} -- Indexing:
 31   lower: INTEGER
 32         -- Minimum index.
 33         --
 34         -- See also `upper', `valid_index', `item'.
 35      deferred
 36      end
 37
 38   upper: INTEGER
 39         -- Maximum index.
 40         --
 41         -- See also `lower', `valid_index', `item'.
 42      deferred
 43      end
 44
 45   valid_index (i: INTEGER): BOOLEAN
 46         -- True when `i' is valid (i.e., inside actual bounds).
 47         --
 48         -- See also `lower', `upper', `item'.
 49      do
 50         Result := lower <= i and then i <= upper
 51      ensure
 52         definition: Result = (lower <= i and i <= upper)
 53      end
 54
 55feature {ANY} -- Accessing:
 56   item (i: INTEGER): E_
 57         -- Item at the corresponding index `i'.
 58         --
 59         -- See also `lower', `upper', `valid_index'.
 60      require
 61         valid_index(i)
 62      deferred
 63      end
 64
 65   first: like item
 66         -- The very `first' item.
 67         --
 68         -- See also `last', `item'.
 69      require
 70         not is_empty
 71      deferred
 72      ensure
 73         definition: Result = item(lower)
 74      end
 75
 76   last: like item
 77         -- The `last' item.
 78         --
 79         -- See also `first', `item'.
 80      require
 81         not is_empty
 82      deferred
 83      ensure
 84         definition: Result = item(upper)
 85      end
 86
 87feature {ANY} -- Agent-based features:
 88   for_each (action: PROCEDURE[TUPLE[E_]])
 89         -- Apply `action' to every item of `Current'.
 90         --
 91         -- See also `for_all', `exists', `aggregate'.
 92      local
 93         i: INTEGER
 94      do
 95         from
 96            i := lower
 97         until
 98            i > upper
 99         loop
100            action.call([item(i)])
101            i := i + 1
102         end
103      end
104
105   for_all (test: PREDICATE[TUPLE[E_]]): BOOLEAN
106         -- Do all items satisfy `test'?
107         --
108         -- See also `for_each', `exists', `aggregate'.
109      local
110         i: INTEGER
111      do
112         from
113            Result := True
114            i := lower
115         until
116            not Result or else i > upper
117         loop
118            Result := test.item([item(i)])
119            i := i + 1
120         end
121      end
122
123   exists (test: PREDICATE[TUPLE[E_]]): BOOLEAN
124         -- Does at least one item satisfy `test'?
125         --
126         -- See also `for_each', `for_all', `aggregate'.
127      local
128         i: INTEGER
129      do
130         from
131            i := lower
132         until
133            Result or else i > upper
134         loop
135            Result := test.item([item(i)])
136            i := i + 1
137         end
138      end
139
140   aggregate (action: FUNCTION[TUPLE[E_, E_], E_]; initial: E_): E_
141         -- Aggregate all the elements starting from the initial value.
142         --
143         -- See also `for_each', `for_all', `exists'.
144      local
145         i: INTEGER
146      do
147         from
148            Result := initial
149            i := lower
150         until
151            i > upper
152         loop
153            Result := action.item([Result, item(i)])
154            i := i + 1
155         end
156      end
157
158feature {ANY} -- Printing:
159   out_in_tagged_out_memory
160      local
161         i: INTEGER; v: like item
162      do
163         tagged_out_memory.extend('{')
164         tagged_out_memory.append(generating_type)
165         tagged_out_memory.append(once ":[")
166         from
167            i := lower
168         until
169            i > upper
170         loop
171            v := item(i)
172            if v = Void then
173               tagged_out_memory.append(once "Void")
174            else
175               v.out_in_tagged_out_memory
176            end
177            if i < upper then
178               tagged_out_memory.extend(' ')
179            end
180            i := i + 1
181         end
182         tagged_out_memory.append(once "]}")
183      end
184
185end -- class INDEXABLE
186--
187-- Copyright (C) 2009-2017: by all the people cited in the AUTHORS file.
188--
189-- Permission is hereby granted, free of charge, to any person obtaining a copy
190-- of this software and associated documentation files (the "Software"), to deal
191-- in the Software without restriction, including without limitation the rights
192-- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
193-- copies of the Software, and to permit persons to whom the Software is
194-- furnished to do so, subject to the following conditions:
195--
196-- The above copyright notice and this permission notice shall be included in
197-- all copies or substantial portions of the Software.
198--
199-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
200-- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
201-- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
202-- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
203-- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
204-- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
205-- THE SOFTWARE.