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    }