<?php

namespace Arma\Internal;

use Arma\Complex;
use Countable;

/**
 * Interface for all container objects.
 *
 * @package Arma\Internal
 */
interface Base extends Countable
{
    /**
     * Get number of elements.
     * 
     * @return int
     */
    function nElem();

    /**
     * Addition of two objects.
     *
     * @param static|number|Complex $other
     * @return static
     */
    function add($other);

    /**
     * Subtraction of two objects.
     *
     * @param static|number|Complex $other
     * @return static
     */
    function sub($other);

    /**
     * Negation of the object.
     *
     * @return static
     */
    function neg();

    /**
     * Matrix multiplication of two objects.
     *
     * @param static|number|Complex $other
     * @return static
     */
    function mul($other);

    /**
     * Element-wise multiplication of two objects.
     *
     * @param static $other
     * @return static
     */
    function dotMul($other);

    /**
     * Element-wise division of an object by another object or a scalar.
     *
     * @param static|number|Complex $other
     * @return static
     */
    function div($other);

    /**
     * For all elements equal to $old_value, set them to $new_value.
     *
     * For SpMat, replacement is not done when $old_value == 0.
     *
     * @param number|Complex $old_value
     * @param number|Complex $new_value
     * @return void
     */
    function replace($old_value, $new_value);

    /**
     * Transform each element using a callback function.
     *
     * Transformation is done column-by-column, and for SpMat only non-zero elements will be transformed.
     *
     * @param callable $transform (number|Complex) => $new_value
     * @return void
     */
    function transform($transform);

    /**
     * For each element, pass its reference to a callback function.
     *
     * Processing is done column-by-column, and for SpMat only non-zero elements will be passed to callback.
     *
     * @param callable $action (Scalar) -> void
     * @return void
     */
    function forEach($action);

    /**
     * Returns the minimum value within this object.
     *
     * @return number|Complex
     */
    function min();

    /**
     * Returns the maximum value within this object.
     *
     * @return number|Complex
     */
    function max();

    /**
     * Return the linear index of the minimum value within this object.
     *
     * For objects with complex numbers, absolute values are used for comparison.
     *
     * @return int
     */
    function indexMin();

    /**
     * Return the linear index of the maximum value within this object.
     *
     * @return int
     */
    function indexMax();

    /**
     * Checks whether the object contains no elements.
     *
     * @return bool
     */
    function isEmpty();

    /**
     * Checks whether all elements of the object are finite.
     *
     * @return bool
     */
    function isFinite();

    /**
     * Checks whether all elements of the object are zero (value <= tolerance).
     * 
     * For objects with complex numbers, real and imaginary part are checked separately.
     * 
     * @param number $tol[optional]
     * @return bool
     */
    function isZero($tol);

    /**
     * Checks whether at least one of the elements of the object is ±infinity.
     *
     * @return bool
     */
    function hasInf();

    /**
     * Checks whether at least one of the elements of the object is NaN.
     *
     * @return bool
     */
    function hasNan();

    /**
     * Print the contents of the object to a stream resource.
     * 
     * Feature\STREAM_RES must be true if $stream is specified.
     *
     * @param resource $stream[optional]
     * @return void
     */
    function print($stream = STDOUT);

    /**
     * Similar to the print() member function, with the difference that no formatting of the output is done.
     * 
     * Feature\STREAM_RES must be true if $stream is specified.
     *
     * @param resource $stream[optional]
     * @return void
     */
    function rawPrint($stream = STDOUT);

    /**
     * Returns a string of all elements in this object.
     *
     * @return string
     */
    function __toString();
}