1 package org.djunits.vecmat.def;
2
3 import java.util.Iterator;
4
5 import org.djunits.formatter.VectorFormat;
6 import org.djunits.formatter.VectorFormatter;
7 import org.djunits.quantity.SIQuantity;
8 import org.djunits.quantity.def.Quantity;
9 import org.djunits.unit.Unit;
10 import org.djunits.value.Value;
11 import org.djunits.vecmat.operations.Normed;
12
13 /**
14 * Vector contains the contract for Vector classes that contain relative quantity values.
15 * <p>
16 * Copyright (c) 2025-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
17 * for project information <a href="https://djunits.org" target="_blank">https://djunits.org</a>. The DJUNITS project is
18 * distributed under a <a href="https://djunits.org/docs/license.html" target="_blank">three-clause BSD-style license</a>.
19 * @author Alexander Verbraeck
20 * @param <Q> the quantity type
21 * @param <V> the vector type
22 * @param <SI> the vector type with generics <SIQuantity, SIUnit<
23 * @param <H> the generic vector type with generics <?, ?< for Hadamard operations
24 * @param <VT> the type of the transposed version of the vector
25 */
26 public abstract class Vector<Q extends Quantity<Q>, V extends Vector<Q, V, SI, H, VT>,
27 SI extends Vector<SIQuantity, SI, ?, ?, ?>, H extends Vector<?, ?, ?, ?, ?>, VT extends Vector<Q, VT, ?, ?, V>>
28 extends VectorMatrix<Q, V, SI, H, VT> implements Iterable<Q>, Normed<Q>
29 {
30 /** */
31 private static final long serialVersionUID = 600L;
32
33 /**
34 * Create a new Vector with a unit, as an extension of Matrix.
35 * @param displayUnit the display unit to use
36 */
37 public Vector(final Unit<?, Q> displayUnit)
38 {
39 super(displayUnit);
40 }
41
42 /**
43 * Retrieve the size of the vector.
44 * @return the size of the vector
45 */
46 public abstract int size();
47
48 /**
49 * Return whether this vector is a column vector.
50 * @return whether this vector is a column vector
51 */
52 public abstract boolean isColumnVector();
53
54 /**
55 * Return whether this vector is a row vector.
56 * @return whether this vector is a row vector
57 */
58 public boolean isRowVector()
59 {
60 return !isColumnVector();
61 }
62
63 /**
64 * Retrieve an si-value from the vector.
65 * @param index the index (0-based) to retrieve the value from
66 * @return the value as a Scalar
67 * @throws IndexOutOfBoundsException in case index is out of bounds
68 */
69 public abstract double si(int index) throws IndexOutOfBoundsException;
70
71 /**
72 * Retrieve an si-value from the vector, based on a 1-valued index.
73 * @param mIndex the index (1-based) to retrieve the value from
74 * @return the value as a Scalar
75 * @throws IndexOutOfBoundsException in case index is out of bounds
76 */
77 public double msi(final int mIndex) throws IndexOutOfBoundsException
78 {
79 return si(mIndex - 1);
80 }
81
82 /**
83 * Retrieve a value from the vector.
84 * @param index the index (0-based) to retrieve the value from
85 * @return the value as a Scalar
86 * @throws IndexOutOfBoundsException in case index is out of bounds
87 */
88 public Q get(final int index) throws IndexOutOfBoundsException
89 {
90 return getDisplayUnit().ofSi(si(index)).setDisplayUnit(getDisplayUnit());
91 }
92
93 /**
94 * Retrieve a value from the vector, based on a 1-valued index.
95 * @param mIndex the index (1-based) to retrieve the value from
96 * @return the value as a Scalar
97 * @throws IndexOutOfBoundsException in case index is out of bounds
98 */
99 public Q mget(final int mIndex) throws IndexOutOfBoundsException
100 {
101 return getDisplayUnit().ofSi(si(mIndex - 1)).setDisplayUnit(getDisplayUnit());
102 }
103
104 /**
105 * Return the vector as an array of scalars.
106 * @return the vector as an array of scalars
107 */
108 public abstract Q[] getScalarArray();
109
110 /**
111 * Create and return an iterator over the scalars in this vector in proper sequence.
112 * @return an iterator over the scalars in this vector in proper sequence
113 */
114 @Override
115 public abstract Iterator<Q> iterator();
116
117 /* *********************************************************************************/
118 /* ************************** STRING AND FORMATTING METHODS ************************/
119 /* *********************************************************************************/
120
121 /**
122 * Formatting methods for column vector.
123 * @param <V> the vector type
124 * @param <Q> the quantity type
125 */
126 public interface Col<V extends Value<V, Q>, Q extends Quantity<Q>> extends Value<V, Q>
127 {
128 /**
129 * Concise description of this vector.
130 * @return a String with the vector, with the unit attached.
131 */
132 @Override
133 default String format()
134 {
135 return format(VectorFormat.Col.defaults());
136 }
137
138 /**
139 * String representation of this vector after applying the format.
140 * @param format the format to apply for the vector
141 * @return a String representation of this vector, formatted according to the given format
142 */
143 default String format(final VectorFormat<?> format)
144 {
145 return VectorFormatter.format((Vector<?, ?, ?, ?, ?>) this, format);
146 }
147
148 /**
149 * String representation of this vector, expressed in the specified unit.
150 * @param targetUnit the unit into which the values of the vector are converted for display
151 * @return printable string with the vector's values expressed in the specified unit
152 */
153 @Override
154 default String format(final Unit<?, Q> targetUnit)
155 {
156 return format(VectorFormat.Col.defaults().setDisplayUnit(targetUnit));
157 }
158 }
159
160 /**
161 * Formatting methods for row vector.
162 * @param <V> the vector type
163 * @param <Q> the quantity type
164 */
165 public interface Row<V extends Value<V, Q>, Q extends Quantity<Q>> extends Value<V, Q>
166 {
167 /**
168 * Concise description of this vector.
169 * @return a String with the vector, with the unit attached.
170 */
171 @Override
172 default String format()
173 {
174 return format(VectorFormat.Row.defaults());
175 }
176
177 /**
178 * String representation of this vector after applying the format.
179 * @param format the format to apply for the vector
180 * @return a String representation of this vector, formatted according to the given format
181 */
182 default String format(final VectorFormat<?> format)
183 {
184 return VectorFormatter.format((Vector<?, ?, ?, ?, ?>) this, format);
185 }
186
187 /**
188 * String representation of this vector, expressed in the specified unit.
189 * @param targetUnit the unit into which the values of the vector are converted for display
190 * @return printable string with the vector's values expressed in the specified unit
191 */
192 @Override
193 default String format(final Unit<?, Q> targetUnit)
194 {
195 return format(VectorFormat.Row.defaults().setDisplayUnit(targetUnit));
196 }
197 }
198
199 }