001    /*
002     * Copyright (C) 2008-2010 by Holger Arndt
003     *
004     * This file is part of the Universal Java Matrix Package (UJMP).
005     * See the NOTICE file distributed with this work for additional
006     * information regarding copyright ownership and licensing.
007     *
008     * UJMP is free software; you can redistribute it and/or modify
009     * it under the terms of the GNU Lesser General Public License as
010     * published by the Free Software Foundation; either version 2
011     * of the License, or (at your option) any later version.
012     *
013     * UJMP is distributed in the hope that it will be useful,
014     * but WITHOUT ANY WARRANTY; without even the implied warranty of
015     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
016     * GNU Lesser General Public License for more details.
017     *
018     * You should have received a copy of the GNU Lesser General Public
019     * License along with UJMP; if not, write to the
020     * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
021     * Boston, MA  02110-1301  USA
022     */
023    
024    package org.ujmp.core.interfaces;
025    
026    import java.math.BigDecimal;
027    import java.math.BigInteger;
028    import java.util.Date;
029    
030    import org.ujmp.core.Matrix;
031    import org.ujmp.core.exceptions.MatrixException;
032    
033    /**
034     * This interface declares the getters and setters for the entries in the Matrix
035     * for the most important Java types: boolean, int, char, float, double, long,
036     * Date, Object and String.
037     * <p>
038     * The matrix will try to convert its content to the desired format as good as
039     * possible. For example, a Matrix with String entries will try to parse each
040     * String to a Double when you invoke getDoubleValue(). Note, that there will be
041     * no exception if the entry cannot be converted. Instead, the result will be
042     * either null, 0, false or Double.NaN depending on the method.
043     */
044    public interface GettersAndSetters {
045    
046            /**
047             * Returns a double representation of an entry in the matrix. The stored
048             * value will be converted to a double as good as possible.
049             * 
050             * @param coordinates
051             *            location of the entry
052             * @return a double representation of the entry
053             * @throws MatrixException
054             */
055            public double getAsDouble(long... coordinates) throws MatrixException;
056    
057            /**
058             * Sets an entry in the matrix to a double value. If the matrix cannot store
059             * double values, the value will be represented as good as possible.
060             * 
061             * @param value
062             *            double value
063             * @param coordinates
064             *            location of the entry
065             * @throws MatrixException
066             */
067            public void setAsDouble(double value, long... coordinates) throws MatrixException;
068    
069            /**
070             * Returns a raw entry in the matrix as it is stored. If the matrix supports
071             * Generics, the return type will match the type that is stored.
072             * 
073             * @param coordinates
074             *            location of the entry
075             * @return entry object
076             * @throws MatrixException
077             */
078            public Object getAsObject(long... coordinates) throws MatrixException;
079    
080            /**
081             * Sets an entry in the matrix to an object. If the matrix cannot store this
082             * object type, the value will be represented as good as possible.
083             * 
084             * @param o
085             *            the object to store
086             * @param coordinates
087             *            location of the entry
088             * @throws MatrixException
089             */
090            public void setAsObject(Object o, long... coordinates) throws MatrixException;
091    
092            /**
093             * Returns a String representation of an entry in the matrix. The stored
094             * value will be converted to a String as good as possible.
095             * 
096             * @param coordinates
097             *            location of the entry
098             * @return a String representation of the entry
099             * @throws MatrixException
100             */
101            public String getAsString(long... coordinates) throws MatrixException;
102    
103            /**
104             * Sets an entry in the matrix to a String value. If the matrix cannot store
105             * Strings, the value will be represented as good as possible.
106             * 
107             * @param value
108             *            String value
109             * @param coordinates
110             *            location of the entry
111             * @throws MatrixException
112             */
113            public void setAsString(String string, long... coordinates) throws MatrixException;
114    
115            /**
116             * Converts the content of a matrix into a 2-dimensional array of double
117             * values.
118             * 
119             * @return double array with matrix entries
120             * @throws MatrixException
121             */
122            public double[][] toDoubleArray() throws MatrixException;
123    
124            /**
125             * Returns a byte representation of an entry in the matrix. The stored value
126             * will be converted to a byte as good as possible.
127             * 
128             * @param coordinates
129             *            location of the entry
130             * @return a byte representation of the entry
131             * @throws MatrixException
132             */
133            public byte getAsByte(long... coordinates) throws MatrixException;
134    
135            /**
136             * Sets an entry in the matrix to a byte value. If the matrix cannot store
137             * byte values, the value will be represented as good as possible.
138             * 
139             * @param value
140             *            byte value
141             * @param coordinates
142             *            location of the entry
143             * @throws MatrixException
144             */
145            public void setAsByte(byte value, long... coordinates) throws MatrixException;
146    
147            /**
148             * Converts the content of a matrix into a 2-dimensional array of boolean
149             * values.
150             * 
151             * @return boolean array with matrix entries
152             * @throws MatrixException
153             */
154            public boolean[][] toBooleanArray() throws MatrixException;
155    
156            public BigDecimal[][] toBigDecimalArray() throws MatrixException;
157    
158            public BigInteger[][] toBigIntegerArray() throws MatrixException;
159    
160            /**
161             * Converts the content of a matrix into a 2-dimensional array of byte
162             * values.
163             * 
164             * @return byte array with matrix entries
165             * @throws MatrixException
166             */
167            public byte[][] toByteArray() throws MatrixException;
168    
169            /**
170             * Returns a byte representation of an entry in the matrix. The stored value
171             * will be converted to a boolean as good as possible.
172             * 
173             * @param coordinates
174             *            location of the entry
175             * @return a boolean representation of the entry
176             * @throws MatrixException
177             */
178            public boolean getAsBoolean(long... coordinates) throws MatrixException;
179    
180            public BigInteger getAsBigInteger(long... coordinates) throws MatrixException;
181    
182            public BigDecimal getAsBigDecimal(long... coordinates) throws MatrixException;
183    
184            /**
185             * Sets an entry in the matrix to a boolean value. If the matrix cannot
186             * store byte values, the value will be represented as good as possible.
187             * 
188             * @param value
189             *            boolean value
190             * @param coordinates
191             *            location of the entry
192             * @throws MatrixException
193             */
194            public void setAsBoolean(boolean value, long... coordinates) throws MatrixException;
195    
196            public void setAsBigInteger(BigInteger value, long... coordinates) throws MatrixException;
197    
198            public void setAsBigDecimal(BigDecimal value, long... coordinates) throws MatrixException;
199    
200            /**
201             * Returns a char representation of an entry in the matrix. The stored value
202             * will be converted to a char as good as possible.
203             * 
204             * @param coordinates
205             *            location of the entry
206             * @return a char representation of the entry
207             * @throws MatrixException
208             */
209            public char getAsChar(long... coordinates) throws MatrixException;
210    
211            /**
212             * Sets an entry in the matrix to a char value. If the matrix cannot store
213             * char values, the value will be represented as good as possible.
214             * 
215             * @param value
216             *            char value
217             * @param coordinates
218             *            location of the entry
219             * @throws MatrixException
220             */
221            public void setAsChar(char value, long... coordinates) throws MatrixException;
222    
223            /**
224             * Converts the content of a matrix into a 2-dimensional array of char
225             * values.
226             * 
227             * @return char array with matrix entries
228             * @throws MatrixException
229             */
230            public char[][] toCharArray() throws MatrixException;
231    
232            /**
233             * Returns a Date representation of an entry in the matrix. The stored value
234             * will be converted to a Date object as good as possible.
235             * 
236             * @param coordinates
237             *            location of the entry
238             * @return a String representation of the entry
239             * @throws MatrixException
240             */
241            public Date getAsDate(long... coordinates) throws MatrixException;
242    
243            /**
244             * Sets an entry in the matrix to a Date value. If the matrix cannot store
245             * Date objects, the value will be represented as good as possible.
246             * 
247             * @param value
248             *            Date object to store
249             * @param coordinates
250             *            location of the entry
251             * @throws MatrixException
252             */
253            public void setAsDate(Date date, long... coordinates) throws MatrixException;
254    
255            /**
256             * Converts the content of a matrix into a 2-dimensional array of Date
257             * values.
258             * 
259             * @return Date array with matrix entries
260             * @throws MatrixException
261             */
262            public Date[][] toDateArray() throws MatrixException;
263    
264            /**
265             * Returns a float representation of an entry in the matrix. The stored
266             * value will be converted to a float as good as possible.
267             * 
268             * @param coordinates
269             *            location of the entry
270             * @return a float representation of the entry
271             * @throws MatrixException
272             */
273            public float getAsFloat(long... coordinates) throws MatrixException;
274    
275            /**
276             * Sets an entry in the matrix to a float value. If the matrix cannot store
277             * float values, the value will be represented as good as possible.
278             * 
279             * @param value
280             *            float value
281             * @param coordinates
282             *            location of the entry
283             * @throws MatrixException
284             */
285            public void setAsFloat(float value, long... coordinates) throws MatrixException;
286    
287            /**
288             * Converts the content of a matrix into a 2-dimensional array of float
289             * values.
290             * 
291             * @return float array with matrix entries
292             * @throws MatrixException
293             */
294            public float[][] toFloatArray() throws MatrixException;
295    
296            /**
297             * Returns an int representation of an entry in the matrix. The stored value
298             * will be converted to an int as good as possible.
299             * 
300             * @param coordinates
301             *            location of the entry
302             * @return an int representation of the entry
303             * @throws MatrixException
304             */
305            public int getAsInt(long... coordinates) throws MatrixException;
306    
307            /**
308             * Sets an entry in the matrix to an int value. If the matrix cannot store
309             * int values, the value will be represented as good as possible.
310             * 
311             * @param value
312             *            int value
313             * @param coordinates
314             *            location of the entry
315             * @throws MatrixException
316             */
317            public void setAsInt(int value, long... coordinates) throws MatrixException;
318    
319            /**
320             * Converts the content of a matrix into a 2-dimensional array of int
321             * values.
322             * 
323             * @return int array with matrix entries
324             * @throws MatrixException
325             */
326            public int[][] toIntArray() throws MatrixException;
327    
328            /**
329             * Returns a long representation of an entry in the matrix. The stored value
330             * will be converted to a long as good as possible.
331             * 
332             * @param coordinates
333             *            location of the entry
334             * @return a long representation of the entry
335             * @throws MatrixException
336             */
337            public long getAsLong(long... coordinates) throws MatrixException;
338    
339            /**
340             * Sets an entry in the matrix to a long value. If the matrix cannot store
341             * long values, the value will be represented as good as possible.
342             * 
343             * @param value
344             *            long value
345             * @param coordinates
346             *            location of the entry
347             * @throws MatrixException
348             */
349            public void setAsLong(long value, long... coordinates) throws MatrixException;
350    
351            /**
352             * Converts the content of a matrix into a 2-dimensional array of long
353             * values.
354             * 
355             * @return long array with matrix entries
356             * @throws MatrixException
357             */
358            public long[][] toLongArray() throws MatrixException;
359    
360            /**
361             * Converts the content of a matrix into a 2-dimensional array of Objects.
362             * 
363             * @return Object array with matrix entries
364             * @throws MatrixException
365             */
366            public Object[][] toObjectArray() throws MatrixException;
367    
368            /**
369             * Returns a short representation of an entry in the matrix. The stored
370             * value will be converted to a short as good as possible.
371             * 
372             * @param coordinates
373             *            location of the entry
374             * @return a short representation of the entry
375             * @throws MatrixException
376             */
377            public short getAsShort(long... coordinates) throws MatrixException;
378    
379            /**
380             * Sets an entry in the matrix to a short value. If the matrix cannot store
381             * short values, the value will be represented as good as possible.
382             * 
383             * @param value
384             *            short value
385             * @param coordinates
386             *            location of the entry
387             * @throws MatrixException
388             */
389            public void setAsShort(short value, long... coordinates) throws MatrixException;
390    
391            /**
392             * Converts the content of a matrix into a 2-dimensional array of short
393             * values.
394             * 
395             * @return short array with matrix entries
396             * @throws MatrixException
397             */
398            public short[][] toShortArray() throws MatrixException;
399    
400            /**
401             * Converts the content of a matrix into a 2-dimensional array of Strings.
402             * 
403             * @return String array with matrix entries
404             * @throws MatrixException
405             */
406            public String[][] toStringArray() throws MatrixException;
407    
408            /**
409             * Returns a representation of the entry in the matrix that reflects the
410             * true object best. E.g. if the entry is a String "-5.3", this method
411             * returns a double with the equivalent value. For a String "text" the
412             * string itself is returned.
413             * 
414             * @param coordinates
415             *            location of the entry
416             * @return object that represents the matrix entry best
417             * @throws MatrixException
418             */
419            public Object getPreferredObject(long... coordinates) throws MatrixException;
420    
421            public Matrix getAsMatrix(long... coordinates) throws MatrixException;
422    
423            public void setAsMatrix(Matrix m, long... coordinates) throws MatrixException;
424    
425    }