1 package org.opentrafficsim.road.gtu.lane.perception;
2
3 import java.util.Iterator;
4 import java.util.function.Supplier;
5
6 import org.djunits.value.vdouble.scalar.Length;
7 import org.opentrafficsim.road.gtu.lane.perception.headway.Headway;
8
9 /**
10 * Iterable that additionally provides support for PerceptionCollectors. These gather raw data, to only 'perceive' the result.
11 * <p>
12 * Copyright (c) 2013-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
13 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
14 * <p>
15 * @version $Revision$, $LastChangedDate$, by $Author$, initial version 1 mrt. 2018 <br>
16 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
17 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
18 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
19 * @param <H> headway type
20 * @param <U> underlying object type
21 */
22 public interface PerceptionCollectable<H extends Headway, U> extends PerceptionIterable<H>
23 {
24
25 /**
26 * Collect the underlying objects in to a perceived result. This methodology is loosely based on Stream.collect().
27 * @param collector PerceptionCollector<C, ? super U, I>; collector
28 * @param <C> collection result type
29 * @param <I> intermediate type
30 * @return C; collection result
31 */
32 default <C, I> C collect(final PerceptionCollector<C, ? super U, I> collector)
33 {
34 return collect(collector.getIdentity(), collector.getAccumulator(), collector.getFinalizer());
35 }
36
37 /**
38 * Collect the underlying objects in to a perceived result. This methodology is loosely based on Stream.collect().
39 * @param identity Supplier<I>; the initial intermediate result value
40 * @param accumulator PerceptionAccumulator<? super U, I>; accumulator
41 * @param finalizer PerceptionFinalizer<C, I>; finalizer
42 * @param <C> collection result type
43 * @param <I> intermediate type
44 * @return C; collection result
45 */
46 <C, I> C collect(Supplier<I> identity, PerceptionAccumulator<? super U, I> accumulator,
47 PerceptionFinalizer<C, I> finalizer);
48
49 /**
50 * Returns an iterator over the underlying objects.
51 * @return Iterator<U>; iterator
52 */
53 Iterator<U> underlying();
54
55 /**
56 * Combination of an accumulator and a finalizer.
57 * <p>
58 * Copyright (c) 2013-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
59 * <br>
60 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
61 * <p>
62 * @version $Revision$, $LastChangedDate$, by $Author$, initial version 28 feb. 2018 <br>
63 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
64 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
65 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
66 * @param <C> collection result type
67 * @param <U> underlying object type
68 * @param <I> intermediate result type
69 */
70 public interface PerceptionCollector<C, U, I>
71 {
72 /**
73 * Returns the identity value, the initial intermediate value.
74 * @return I; identity value, the initial intermediate value
75 */
76 Supplier<I> getIdentity();
77
78 /**
79 * Returns the accumulator.
80 * @return PerceptionAccumulator; accumulator
81 */
82 PerceptionAccumulator<U, I> getAccumulator();
83
84 /**
85 * Returns the finalizer.
86 * @return PerceptionFinalizer; finalizer
87 */
88 PerceptionFinalizer<C, I> getFinalizer();
89 }
90
91 /**
92 * Accumulates an object one at a time in to an accumulating intermediate result.
93 * <p>
94 * Copyright (c) 2013-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
95 * <br>
96 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
97 * <p>
98 * @version $Revision$, $LastChangedDate$, by $Author$, initial version 28 feb. 2018 <br>
99 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
100 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
101 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
102 * @param <U> underlying object type
103 * @param <I> intermediate result type
104 */
105 public interface PerceptionAccumulator<U, I>
106 {
107 /**
108 * Accumulate the next object to intermediate result.
109 * @param intermediate Intermediate<I>; intermediate result before accumulation of object
110 * @param object U; next object to include
111 * @param distance Length; distance to the considered object
112 * @return I; intermediate result after accumulation of object
113 */
114 Intermediate<I> accumulate(Intermediate<I> intermediate, U object, Length distance);
115 }
116
117 /**
118 * Translates the last intermediate result of an accumulator in to the collection output.
119 * <p>
120 * Copyright (c) 2013-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
121 * <br>
122 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
123 * <p>
124 * @version $Revision$, $LastChangedDate$, by $Author$, initial version 28 feb. 2018 <br>
125 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
126 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
127 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
128 * @param <C> collection result type
129 * @param <I> intermediate result type
130 */
131 public interface PerceptionFinalizer<C, I>
132 {
133 /**
134 * Translate the last intermediate result in to a final result.
135 * @param intermediate I; last intermediate result
136 * @return C; final result
137 */
138 C collect(I intermediate);
139 }
140
141 /**
142 * Wrapper of intermediate result with info for the iterator algorithm.
143 * <p>
144 * Copyright (c) 2013-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
145 * <br>
146 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
147 * <p>
148 * @version $Revision$, $LastChangedDate$, by $Author$, initial version 3 apr. 2018 <br>
149 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
150 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
151 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>]
152 * @param <I> intermediate result type
153 */
154 class Intermediate<I>
155 {
156 /** Number of underlying object being iterated. */
157 private int number = 0;
158
159 /** Intermediate object. */
160 private I object;
161
162 /** Whether to stop accumulating. */
163 private boolean stop = false;
164
165 /**
166 * Constructor.
167 * @param object I; identity value
168 */
169 public Intermediate(final I object)
170 {
171 this.object = object;
172 }
173
174 /**
175 * Get intermediate object.
176 * @return I; intermediate object
177 */
178 public I getObject()
179 {
180 return this.object;
181 }
182
183 /**
184 * Set intermediate object.
185 * @param object I; intermediate object
186 */
187 public void setObject(final I object)
188 {
189 this.object = object;
190 }
191
192 /**
193 * Returns the number of the underlying object currently being accumulated, starts at 0 for the first.
194 * @return int; number of the underlying object currently being accumulated
195 */
196 public int getNumber()
197 {
198 return this.number;
199 }
200
201 /**
202 * Method for the iterator to increase the underlying object number.
203 */
204 public void step()
205 {
206 this.number++;
207 }
208
209 /**
210 * Method for the accumulator to indicate the iterator can stop.
211 */
212 public void stop()
213 {
214 this.stop = true;
215 }
216
217 /**
218 * Method for the iterator to check if it can stop.
219 * @return boolean; whether the iterator can stop
220 */
221 public boolean isStop()
222 {
223 return this.stop;
224 }
225 }
226
227 }