package flare.util.math
{
	/**
	 * Interface for a matrix of real-valued numbers.
	 */
	public interface IMatrix
	{
		/** The number of rows. */
		function get rows():int;
		/** The number of columns. */
		function get cols():int;
		/** The number of non-zero values. */
		function get nnz():int;
		/** The sum of all the entries in this matrix. */
		function get sum():Number;
		/** The sum of squares of all the entries in this matrix. */
		function get sumsq():Number;
		
		/** Creates a copy of this matrix. */
		function clone():IMatrix;
		
		/**
		 * Creates a new matrix of the same type.
		 * @param rows the number of rows in the new matrix
		 * @param cols the number of columns in the new matrix
		 * @return a new matrix
		 */
		function like(rows:int, cols:int):IMatrix;
		
		/** 
		 * Initializes the matrix to desired dimensions. This method also
		 * resets all values in the matrix to zero.
		 * @param rows the number of rows in this matrix
		 * @param cols the number of columns in this matrix
		 */
		function init(rows:int, cols:int):void;
		
		/**
		 * Returns the value at the given indices. 
		 * @param i the row index
		 * @param j the column index
		 * @return the value at position i,j
		 */
		function get(i:int, j:int):Number;
		
		/**
		 * Sets the value at the given indices. 
		 * @param i the row index
		 * @param j the column index
		 * @param v the value to set
		 * @return the input value v
		 */
		function set(i:int, j:int, v:Number):Number;
		
		/**
		 * Multiplies all values in this matrix by the input scalar.
		 * @param s the scalar to multiply by.
		 */
		function scale(s:Number):void;
		
		/**
		 * Multiplies this matrix by another. The number of rows in this matrix
		 * must match the number of columns in the input matrix.
		 * @param b the matrix to multiply by.
		 * @return a new matrix that is the product of this matrix with the
		 *  input matrix. The new matrix will be of the same type as this one.
		 */
		function multiply(b:IMatrix):IMatrix;
		
		/**
		 * Visit all non-zero values in the matrix.
		 * The input function is expected to take three arguments--the row
		 * index, the column index, and the cell value--and return a number
		 * which then becomes the new value for the cell.
		 * @param f the function to invoke for each non-zero value
		 */
		function visitNonZero(f:Function):void;
		
		/**
		 * Visit all values in the matrix.
		 * The input function is expected to take three arguments--the row
		 * index, the column index, and the cell value--and return a number
		 * which then becomes the new value for the cell.
		 * @param f the function to invoke for each value
		 */
		function visit(f:Function):void;
		
	} // end of interface IMatrix
}