<?php

namespace Arma\Internal;

/**
 * Interface for matrices.
 *
 * @package Arma\Internal
 */
interface Matrix
{
    // Characteristics

    /**
     * Get number of rows.
     *
     * @return int
     */
    function nRows();

    /**
     * Get number of columns.
     *
     * @return int
     */
    function nCols();

    /**
     * Check whether the matrix has exactly one column or one row.
     *
     * @return bool
     */
    function isVec();

    /**
     * Check whether the matrix has exactly one column.
     *
     * @return bool
     */
    function isCol();

    /**
     * Check whether the matrix has exactly one row.
     *
     * @return bool
     */
    function isRow();

    /**
     * Check whether the matrix is square.
     *
     * @return bool
     */
    function isSquare();

    /**
     * Check whether the matrix is symmetric.
     *
     * @param number $tol[optional]
     * @return bool
     */
    function isSymmetric($tol);

    /**
     * Check whether the matrix is hermitian.
     *
     * @param number $tol[optional]
     * @return bool
     */
    function isHermitian($tol);

    // Subview

    /**
     * If $j is not specified, access the n-th element. Otherwise, access the element stored at the i-th row
     * and j-th column.
     *
     * @param int $i
     * @param int $j[optional]
     * @return Scalar
     */
    function __invoke($i, $j);

    /**
     * If $j is not specified, access the n-th element. Otherwise, access the element stored at the i-th row
     * and j-th column.
     *
     * Without a bounds check. Not recommended for use unless your code has been thoroughly debugged.
     *
     * @param int $i
     * @param int $j[optional]
     * @return Scalar
     */
    function at($i, $j);

    /**
     * Read/write access to a certain column of the object.
     *
     * @param int $col_number
     * @return Subview
     */
    function col($col_number);

    /**
     * Read/write access to a certain row of the object.
     *
     * @param int $row_number
     * @return Subview
     */
    function row($row_number);

    /**
     * Read/write access to certain columns of the object.
     *
     * @param int $first_col
     * @param int $last_col
     * @return Subview
     */
    function cols($first_col, $last_col);

    /**
     * Read/write access to certain rows of the object.
     *
     * @param int $first_row
     * @param int $last_row
     * @return Subview
     */
    function rows($first_row, $last_row);

    /**
     * Read/write access to a matrix subview.
     *
     * @param int $first_row
     * @param int $first_col
     * @param int $last_row
     * @param int $last_col
     * @return Subview
     */
    function submat($first_row, $first_col, $last_row, $last_col);

    /**
     * Read/write access to a matrix subview of first specified columns.
     *
     * @param int $n_cols
     * @return Subview
     */
    function headCols($n_cols);

    /**
     * Read/write access to a matrix subview of first specified rows.
     *
     * @param int $n_rows
     * @return Subview
     */
    function headRows($n_rows);

    /**
     * Read/write access to a matrix subview of last specified columns.
     *
     * @param int $n_cols
     * @return Subview
     */
    function tailCols($n_cols);

    /**
     * Read/write access to a matrix subview of last specified rows.
     *
     * @param int $n_rows
     * @return Subview
     */
    function tailRows($n_rows);

    /**
     * Read/write access to a diagonal in a matrix.
     *
     * For k=0 the main diagonal is accessed. For k > 0, the k-th super-diagonal is accessed (top-right corner).
     * For k < 0, the k-th sub-diagonal is accessed (bottom-left corner).
     *
     * @param int $k[optional]
     * @return Subview
     */
    function diag($k = 0);

    // Swap

    /**
     * Swap the contents of specified rows.
     *
     * @param int $row_1
     * @param int $row_2
     * @return void
     */
    function swapRows($row_1, $row_2);

    /**
     * Swap the contents of specified columns.
     *
     * @param int $col_1
     * @param int $col_2
     * @return void
     */
    function swapCols($col_1, $col_2);

    // Transform

    /**
     * Returns a transposed copy of the matrix.
     *
     * For complex matrices, $conj indicates whether the conjugate of the elements is taken during the transpose.
     *
     * @param bool $conj[optional]
     * @return Matrix
     */
    function t($conj = true);
}