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