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 org.ujmp.core.exceptions.MatrixException; 027 028 /** 029 * This interface defines functions on a Matrix that have to do with the 030 * coordinates of the entries. 031 * 032 * @author Holger Arndt 033 * 034 */ 035 public interface CoordinateFunctions { 036 037 public Iterable<long[]> nonZeroCoordinates() throws MatrixException; 038 039 /** 040 * Returns an Iterator that goes over all coordinates in the Matrix. It goes 041 * from 0,0 to the size of the Matrix. 042 * 043 * @return Iterable over all coordinates within a Matrix. 044 */ 045 public Iterable<long[]> allCoordinates() throws MatrixException; 046 047 /** 048 * Returns an Iterator that only goes over the coordinates in the Matrix 049 * that are stored. For most Matrices, this is the same as allCoordinates(). 050 * For sparse Matrices, it iterates only over the entries in it. 051 * 052 * @return Iterable over the saved entries in a Matrix. 053 */ 054 public Iterable<long[]> availableCoordinates() throws MatrixException; 055 056 /** 057 * Returns an Iterator that goes only over the Coordinates defined by the 058 * selection. The selection is a Matlab/Octave style String, to define what 059 * rows or columns should be considered. E.g. "(2:5,[1,3,5,7:9])" to select 060 * rows 2 to 5 and the columns 1, 3, 5, 7, 8 and 9. Note that, in UJMP 061 * numbering starts at 0 unlike in Matlab and Octave 062 * 063 * @param selection 064 * The String defining the selection of rows or columns 065 * @return Iterable over the desired Coordinates 066 */ 067 public Iterable<long[]> selectedCoordinates(String selection) throws MatrixException; 068 069 /** 070 * Returns an Iterator that goes only over the Coordinates defined by the 071 * selection. The selections consists of a list of long arrays, one for each 072 * dimension. The first array contains the row numbers that should be 073 * selected, the second the column numbers, and so on. 074 * 075 * @param selection 076 * A list of long arrays defining the desired rows or columns 077 * @return Iterable over the desired Coordinates 078 * @throws MatrixException 079 */ 080 public Iterable<long[]> selectedCoordinates(long[]... selection) throws MatrixException; 081 082 /** 083 * Returns the position of the maximum value in a Matrix. If there is more 084 * than one equal maximum values, the first that is found is returned (not 085 * necessarily with the lowest coordinates). If no maximum can be found 086 * (because there are no numbers in the matrix or all numbers are NaN), the 087 * coordinates -1,-1 are returned. 088 * 089 * @return Coordinates of the maximum value 090 * @throws MatrixException 091 */ 092 public long[] getCoordinatesOfMaximum() throws MatrixException; 093 094 /** 095 * Returns the position of the minimum value in a Matrix. If there is more 096 * than one equal minimum values, the first that is found is returned (not 097 * necessarily with the lowest coordinates). If no minimum can be found 098 * (because there are no numbers in the matrix or all numbers are NaN), the 099 * coordinates -1,-1 are returned. 100 * 101 * @return Coordinates of the minimum value 102 * @throws MatrixException 103 */ 104 public long[] getCoordinatesOfMinimum() throws MatrixException; 105 106 /** 107 * Determines if the given Coordinates are part of the Matrix. If the Matrix 108 * is dense, true is returned for all Coordinates smaller than the Matrix's 109 * size. For sparse Matrices, this function checks if the coordinates are 110 * actually stored in the matrix or not. 111 * 112 * @param coordinates 113 * The coordinates to check 114 * @return a boolean stating if the coordinates are part of the Matrix 115 */ 116 public boolean contains(long... coordinates) throws MatrixException; 117 118 }