KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jscience > mathematics > vectors > Vector


1 /*
2  * JScience - Java(TM) Tools and Libraries for the Advancement of Sciences.
3  * Copyright (C) 2006 - JScience (http://jscience.org/)
4  * All rights reserved.
5  *
6  * Permission to use, copy, modify, and distribute this software is
7  * freely granted, provided that this notice is preserved.
8  */
9 package org.jscience.mathematics.vectors;
10
11 import java.util.Comparator JavaDoc;
12 import javolution.lang.Immutable;
13 import javolution.text.Text;
14 import javolution.text.TextBuilder;
15 import javolution.context.RealtimeObject;
16 import javolution.util.FastTable;
17 import org.jscience.mathematics.structures.Field;
18 import org.jscience.mathematics.structures.VectorSpace;
19
20 /**
21  * <p> This class represents an immutable element of a vector space.</p>
22  *
23  * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
24  * @version 3.3, January 2, 2007
25  * @see <a HREF="http://en.wikipedia.org/wiki/Vector_space">
26  * Wikipedia: Vector Space</a>
27  */
28 public abstract class Vector<F extends Field<F>> extends RealtimeObject
29         implements VectorSpace<Vector<F>, F>, Immutable {
30
31     /**
32      * Returns a vector implementation holding the specified elements
33      * (convenience method equivalent to <code>DenseVector.valueOf(elements)
34      * </code>)
35      *
36      * @param elements the vector elements.
37      * @return the dense vector having the specified elements.
38      * @deprecated Since 3.3 - Replaced by {@link DenseVector#valueOf(Field[])}
39      */
40     public static <F extends Field<F>> Vector<F> valueOf(F... elements) {
41         return DenseVector.valueOf(elements);
42     }
43
44     /**
45      * Returns a vector implementation holding the specified <code>double</code>
46      * values (convenience method equivalent to
47      * <code>Float64Vector.valueOf(values)</code>).
48      *
49      * @param values the values of the vector elements.
50      * @return the vector having the specified elements values.
51      * @deprecated Since 3.3 - Replaced by {@link Float64Vector#valueOf(double[])}
52      */
53     public static Float64Vector valueOf(double... values) {
54         return Float64Vector.valueOf(values);
55     }
56
57     /**
58      * Default constructor (for sub-classes).
59      */
60     protected Vector() {
61     }
62
63     /**
64      * Returns the number of elements held by this vector.
65      *
66      * @return this vector dimension.
67      */
68     public abstract int getDimension();
69
70     /**
71      * Returns a single element from this vector.
72      *
73      * @param i the element index (range [0..n[).
74      * @return the element at <code>i</code>.
75      * @throws IndexOutOfBoundsException <code>(i < 0) || (i >= size())</code>
76      */
77     public abstract F get(int i);
78
79     /**
80      * Returns the negation of this vector.
81      *
82      * @return <code>-this</code>.
83      */
84     public abstract Vector<F> opposite();
85
86     /**
87      * Returns the sum of this vector with the one specified.
88      *
89      * @param that the vector to be added.
90      * @return <code>this + that</code>.
91      * @throws DimensionException is vectors dimensions are different.
92      */
93     public abstract Vector<F> plus(Vector<F> that);
94
95     /**
96      * Returns the difference between this vector and the one specified.
97      *
98      * @param that the vector to be subtracted.
99      * @return <code>this - that</code>.
100      */
101     public Vector<F> minus(Vector<F> that) {
102         return this.plus(that.opposite());
103     }
104
105     /**
106      * Returns the product of this vector with the specified coefficient.
107      *
108      * @param k the coefficient multiplier.
109      * @return <code>this · k</code>
110      */
111     public abstract Vector<F> times(F k);
112     
113     /**
114      * Returns the dot product of this vector with the one specified.
115      *
116      * @param that the vector multiplier.
117      * @return <code>this · that</code>
118      * @throws DimensionException if <code>this.dimension() != that.dimension()</code>
119      * @see <a HREF="http://en.wikipedia.org/wiki/Dot_product">
120      * Wikipedia: Dot Product</a>
121      */
122     public abstract F times(Vector<F> that);
123     
124     /**
125      * Returns the cross product of two 3-dimensional vectors.
126      *
127      * @param that the vector multiplier.
128      * @return <code>this x that</code>
129      * @throws DimensionException if
130      * <code>(this.getDimension() != 3) && (that.getDimension() != 3)</code>
131      */
132     public DenseVector<F> cross(Vector<F> that) {
133         if ((this.getDimension() != 3) || (that.getDimension() != 3))
134             throw new DimensionException(
135                     "The cross product of two vectors requires "
136                             + "3-dimensional vectors");
137         FastTable<F> elements = FastTable.newInstance();
138         elements.add((this.get(1).times(that.get(2))).plus((this.get(2).times(that
139                 .get(1))).opposite()));
140         elements.add((this.get(2).times(that.get(0))).plus((this.get(0).times(that
141                 .get(2))).opposite()));
142         elements.add((this.get(0).times(that.get(1))).plus((this.get(1).times(that
143                 .get(0))).opposite()));
144         DenseVector<F> V = DenseVector.valueOf(elements);
145         FastTable.recycle(elements);
146         return V;
147     }
148
149     /**
150      * Returns the text representation of this vector.
151      *
152      * @return the text representation of this vector.
153      */
154     public Text toText() {
155         final int dimension = this.getDimension();
156         TextBuilder tmp = TextBuilder.newInstance();
157         tmp.append('{');
158         for (int i = 0; i < dimension; i++) {
159             tmp.append(get(i).toText());
160             if (i != dimension - 1) {
161                 tmp.append(", ");
162             }
163         }
164         tmp.append('}');
165         Text txt = tmp.toText();
166         TextBuilder.recycle(tmp);
167         return txt;
168     }
169
170     /**
171      * Indicates if this vector can be considered equals to the one
172      * specified using the specified comparator when testing for
173      * element equality. The specified comparator may allow for some
174      * tolerance in the difference between the vector elements.
175      *
176      * @param that the vector to compare for equality.
177      * @param cmp the comparator to use when testing for element equality.
178      * @return <code>true</code> if this vector and the specified matrix are
179      * both vector with equal elements according to the specified
180      * comparator; <code>false</code> otherwise.
181      */
182     public boolean equals(Vector<F> that, Comparator JavaDoc<F> cmp) {
183         if (this == that)
184             return true;
185         final int dimension = this.getDimension();
186         if (that.getDimension() != dimension)
187             return false;
188         for (int i = dimension; --i >= 0;) {
189             if (cmp.compare(this.get(i), that.get(i)) != 0)
190                 return false;
191         }
192         return true;
193     }
194
195     /**
196      * Indicates if this vector is equal to the object specified.
197      *
198      * @param that the object to compare for equality.
199      * @return <code>true</code> if this vector and the specified object are
200      * both vectors with equal elements; <code>false</code> otherwise.
201      */
202     public boolean equals(Object JavaDoc that) {
203         if (this == that)
204             return true;
205         if (!(that instanceof Vector))
206             return false;
207         final int dimension = this.getDimension();
208         Vector v = (Vector) that;
209         if (v.getDimension() != dimension)
210             return false;
211         for (int i = dimension; --i >= 0;) {
212             if (!this.get(i).equals(v.get(i)))
213                 return false;
214         }
215         return true;
216     }
217
218     /**
219      * Returns a hash code value for this vector.
220      * Equals objects have equal hash codes.
221      *
222      * @return this vector hash code value.
223      * @see #equals
224      */
225     public int hashCode() {
226         final int dimension = this.getDimension();
227         int code = 0;
228         for (int i = dimension; --i >= 0;) {
229             code += get(i).hashCode();
230         }
231         return code;
232     }
233 }
Popular Tags