1 package org.djunits.value.base;
2
3 import java.util.Iterator;
4
5 import org.djunits.unit.AbsoluteLinearUnit;
6 import org.djunits.unit.Unit;
7 import org.djunits.value.Absolute;
8 import org.djunits.value.IndexedValue;
9 import org.djunits.value.Relative;
10 import org.djunits.value.ValueRuntimeException;
11
12 /**
13 * Vector to distinguish a vector from vectors and matrices. A possible way to implement this interface is:
14 *
15 * <pre>
16 * class LengthVector implements Vector<LengthUnit, Length, LengthVector>
17 * </pre>
18 *
19 * Copyright (c) 2019-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
20 * BSD-style license. See <a href="https://djunits.org/docs/license.html">DJUNITS License</a>. <br>
21 * @author <a href="https://www.tudelft.nl/averbraeck" target="_blank">Alexander Verbraeck</a>
22 * @param <U> the unit
23 * @param <S> the scalar type belonging to the vector type
24 * @param <V> the vector type with the given unit
25 */
26 public interface Vector<U extends Unit<U>, S extends Scalar<U, S>, V extends Vector<U, S, V>> extends IndexedValue<U, S, V>
27 {
28 /**
29 * Retrieve the size of the vector.
30 * @return int; the size of the vector
31 */
32 int size();
33
34 /**
35 * Retrieve a value from the vector.
36 * @param index int; the index to retrieve the value at
37 * @return S; the value as a Scalar
38 * @throws ValueRuntimeException in case index is out of bounds
39 */
40 S get(int index) throws ValueRuntimeException;
41
42 /**
43 * Return the vector as an array of scalars.
44 * @return S[]; the vector as an array of scalars
45 */
46 S[] getScalars();
47
48 /**
49 * Create and return an iterator over the scalars in this vector in proper sequence.
50 * @return Iterator<S>; an iterator over the scalars in this vector in proper sequence
51 */
52 Iterator<S> iterator();
53
54 /**
55 * Methods for Relative Vector. A possible way to implement this interface is:
56 *
57 * <pre>
58 * class AreaVector implements Vector.Rel<AreaUnit, Area, AreaVector>
59 * </pre>
60 *
61 * Copyright (c) 2019-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
62 * <br>
63 * BSD-style license. See <a href="https://djunits.org/docs/license.html">DJUNITS License</a>. <br>
64 * @author <a href="https://www.tudelft.nl/averbraeck" target="_blank">Alexander Verbraeck</a>
65 * @param <U> the unit
66 * @param <S> the scalar type belonging to the vector type
67 * @param <RV> the relative vector type with this unit
68 */
69 public interface Rel<U extends Unit<U>, S extends Scalar<U, S>, RV extends Vector.Rel<U, S, RV>>
70 extends Vector<U, S, RV>, Relative<U, RV>
71 {
72 /**
73 * Add a relative vector to this relative mutable vector. A new vector is returned. When the vector itself needs to be
74 * changed, use the increaseBy(V) method instead. The addition is done value by value and the result is stored in a new
75 * vector. If both operands are sparse, the result is a sparse vector, otherwise the result is a dense vector.
76 * @param increment RV; the relative vector (mutable or immutable, sparse or dense) to add
77 * @return RMV; the sum of this vector and the operand as a new relative, mutable vector
78 * @throws ValueRuntimeException in case this vector and the operand have a different size
79 */
80 RV plus(RV increment) throws ValueRuntimeException;
81
82 /**
83 * Subtract a relative vector from this relative mutable vector. The display unit of the result is the display unit of
84 * this absolute vector. The subtraction is done value by value and the result is stored in a new vector. If both
85 * operands are sparse, the result is a sparse vector, otherwise the result is a dense vector.
86 * @param decrement RV; the value to subtract
87 * @return RMV; the difference of this vector and the operand as a new relative, mutable vector
88 * @throws ValueRuntimeException in case this vector and the operand have a different size
89 */
90 RV minus(RV decrement) throws ValueRuntimeException;
91
92 /**
93 * Multiply all values of this vector by the multiplier. This only works if the vector is mutable.
94 * @param multiplier double; the factor by which to multiply all values
95 * @return V; this modified vector
96 * @throws ValueRuntimeException in case the vector is immutable
97 */
98 RV multiplyBy(double multiplier);
99
100 /**
101 * Divide all values of this vector by the divisor. This only works if the vector is mutable.
102 * @param divisor double; the value by which to divide all values
103 * @return V; this modified vector
104 * @throws ValueRuntimeException in case the vector is immutable
105 */
106 RV divideBy(double divisor);
107 }
108
109 /**
110 * Additional methods for Relative Vector that has a corresponding Absolute Vector. An example is the relative vector Length
111 * that has a corresponding absolute vector Position. A possible way to implement this interface is:
112 *
113 * <pre>
114 * class LengthVector implements Vector.RelWithAbs<
115 * PositionUnit, Position, PositionVector, LengthUnit, Length, LengthVector>
116 * </pre>
117 *
118 * Copyright (c) 2019-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
119 * <br>
120 * BSD-style license. See <a href="https://djunits.org/docs/license.html">DJUNITS License</a>. <br>
121 * @author <a href="https://www.tudelft.nl/averbraeck" target="_blank">Alexander Verbraeck</a>
122 * @param <AU> the absolute unit belonging to the relative unit
123 * @param <A> the absolute scalar type belonging to the absolute vector type
124 * @param <AV> the absolute vector type
125 * @param <RU> the relative unit belonging to the absolute unit
126 * @param <R> the relative scalar type belonging to the relative vector type
127 * @param <RV> the relative vector type with this unit
128 */
129 public interface RelWithAbs<AU extends AbsoluteLinearUnit<AU, RU>, A extends Scalar<AU, A>,
130 AV extends Vector.Abs<AU, A, AV, RU, R, RV>, RU extends Unit<RU>, R extends Scalar<RU, R>,
131 RV extends Vector.RelWithAbs<AU, A, AV, RU, R, RV>> extends Rel<RU, R, RV>
132 {
133 /**
134 * Add an absolute vector to this relative vector. A new vector is returned. When the vector itself needs to be changed,
135 * use the increaseBy(V) method instead. The addition is done value by value and the result is stored in a new vector.
136 * If both operands are sparse, the result is a sparse vector, otherwise the result is a dense vector.
137 * @param increment AV; the absolute vector (mutable or immutable, sparse or dense) to add to this relative vector
138 * @return AMV; the sum of this vector and the operand as a new absolute, mutable vector
139 * @throws ValueRuntimeException in case this vector and the operand have a different size
140 */
141 AV plus(AV increment);
142 }
143
144 /**
145 * Methods for Absolute Vector. An example is the absolute vector Position that has a corresponding relative vector Length.
146 * A possible way to implement this interface is:
147 *
148 * <pre>
149 * class PositionVector implements Vector.Abs<
150 * PositionUnit, Position, PositionVector, LengthUnit, Length, LengthVector>
151 * </pre>
152 *
153 * Copyright (c) 2019-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
154 * <br>
155 * BSD-style license. See <a href="https://djunits.org/docs/license.html">DJUNITS License</a>. <br>
156 * @author <a href="https://www.tudelft.nl/averbraeck" target="_blank">Alexander Verbraeck</a>
157 * @param <AU> the absolute unit belonging to the relative unit
158 * @param <A> the absolute scalar type belonging to the absolute vector type
159 * @param <AV> the absolute vector type
160 * @param <RU> the relative unit belonging to the absolute unit
161 * @param <R> the relative scalar type belonging to the relative vector type
162 * @param <RV> the relative vector type with this unit
163 */
164 public interface Abs<AU extends AbsoluteLinearUnit<AU, RU>, A extends Scalar<AU, A>,
165 AV extends Vector.Abs<AU, A, AV, RU, R, RV>, RU extends Unit<RU>, R extends Scalar<RU, R>,
166 RV extends Vector.RelWithAbs<AU, A, AV, RU, R, RV>> extends Vector<AU, A, AV>, Absolute
167 {
168 /**
169 * Add a relative vector to this absolute vector. A new absolute vector is returned. The display unit of the new vector
170 * is the display unit of this absolute vector. The addition is done value by value and the result is stored in a new
171 * vector. If both operands are sparse, the result is a sparse vector, otherwise the result is a dense vector.
172 * @param increment RV; the relative vector (mutable or immutable, sparse or dense) to add to this absolute vector
173 * @return AIV; the sum of this value and the operand as a new absolute, immutable vector
174 * @throws ValueRuntimeException in case this vector and the operand have a different size
175 */
176 AV plus(RV increment) throws ValueRuntimeException;
177
178 /**
179 * Subtract a relative vector from this absolute vector. A new absolute vector is returned. The display unit of the new
180 * vector is the display unit of this absolute vector. The subtraction is done value by value and the result is stored
181 * in a new vector. If both operands are sparse, the result is a sparse vector, otherwise the result is a dense vector.
182 * @param decrement RV; the relative vector (mutable or immutable, sparse or dense) to subtract from this absolute
183 * vector
184 * @return AIV; the difference of this value and the operand as a new absolute, immutable vector
185 * @throws ValueRuntimeException in case this vector and the operand have a different size
186 */
187 AV minus(RV decrement) throws ValueRuntimeException;
188
189 /**
190 * Subtract an absolute vector from this absolute vector. A new relative vector is returned. The display unit of the new
191 * vector is the display unit of relative counterpart of the display unit of this absolute vector. The subtraction is
192 * done value by value and the result is stored in a new vector. If both operands are sparse, the result is a sparse
193 * vector, otherwise the result is a dense vector.
194 * @param decrement AV; the absolute vector (mutable or immutable, sparse or dense) to subtract from this absolute
195 * vector
196 * @return RIV; the difference of this value and the operand as a new relative, immutable vector
197 * @throws ValueRuntimeException in case this vector and the operand have a different size
198 */
199 RV minus(AV decrement) throws ValueRuntimeException;
200 }
201
202 }