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 }