Add Matrix implementation, short README

Author: lisachenko

README.md

@@ -0,0 +1,48 @@
+Native matrix library
+-----------------
+
+For a long time, PHP developers dreamed of being able to overload operators. And now, finally, this moment has come. 
+Thanks to the PHP7.4 and the [lisachenko/z-engine](https://github.com/lisachenko/z-engine) package, we can overload the
+operators of comparison, addition, multiplication, casting and much more!
+
+This library is first ever userland PHP extension, that implements operator overloading for the `Matrix` class.
+
+[![GitHub release](https://img.shields.io/github/release/lisachenko/native-matrix.svg)](https://github.com/lisachenko/native-matrix/releases/latest)
+[![Minimum PHP Version](http://img.shields.io/badge/php-%3E%3D%207.4-8892BF.svg)](https://php.net/)
+[![License](https://img.shields.io/packagist/l/lisachenko/native-matrix.svg)](https://packagist.org/packages/lisachenko/native-matrix)
+
+
+Pre-requisites and initialization
+--------------
+
+As this library depends on `FFI`, it requires PHP>=7.4 and `FFI` extension to be enabled. Also, current limitations of
+[lisachenko/z-engine](https://github.com/lisachenko/z-engine) are also applied (x64, NTS)
+
+To install this library, simply add it via `composer`:
+```bash
+composer require lisachenko/native-types
+```
+
+Now you can test it with following example:
+```php
+<?php
+declare(strict_types=1);
+
+use Native\Type\Matrix;
+
+$first  = new Matrix([[10, 20, 30]]);
+$second = new Matrix([[2, 4, 6]]);
+$value  = $first * 2 + $second; // Matrix([[22, 44, 66]])
+```
+
+Supported features:
+ - [x] Matrices addition (`$matrixA + $matrixB`)
+ - [x] Matrices subtraction (`$matrixA - $matrixB`)
+ - [x] Matrices multiplication (`$matrixA * $matrixB`)
+ - [x] Matrices division (`$matrixA / $matrixB`)
+ - [x] Matrices division (`$matrixA / $matrixB`)
+ - [x] Matrices equality check (`$matrixA == $matrixB`)
+ 
+For the future versions, I would like to implement native SSE/AVX assembly methods to improve the performance of calculation.
+
+ 

composer.json

@@ -1,6 +1,6 @@
 {
-    "name": "lisachenko/native-matrix",
-    "description": "PHP Library that provides an implementation of userland Matrix, powered with overloaded operators",
+    "name": "lisachenko/native-types",
+    "description": "PHP Library that provides an implementation of userland types, powered with overloaded operators",
     "type": "library",
     "license": "MIT",
     "authors": [
@@ -10,6 +10,12 @@
         }
     ],
     "require": {
-        "lisachenko/z-engine": "^0.6.0"
+        "lisachenko/z-engine": "^0.6.0",
+        "php": "~7.4"
+    },
+    "autoload": {
+        "psr-4" : {
+            "ZEngine\\Type\\" : "src/"
+        }
     }
 }

src/Matrix.php

@@ -0,0 +1,267 @@
+<?php
+/**
+ * Native matrix library
+ *
+ * @copyright Copyright 2019, Lisachenko Alexander <[email protected]>
+ *
+ * This source file is subject to the license that is bundled
+ * with this source code in the file LICENSE.
+ */
+declare(strict_types = 1);
+
+namespace Native\Type;
+
+use InvalidArgumentException;
+use ZEngine\ClassExtension\ObjectCompareValuesInterface;
+use ZEngine\ClassExtension\ObjectCreateInterface;
+use ZEngine\ClassExtension\ObjectCreateTrait;
+use ZEngine\ClassExtension\ObjectDoOperationInterface;
+use ZEngine\System\OpCode;
+use function count, is_numeric;
+
+/**
+ * Simple class Matrix powered by custom operator handlers
+ */
+class Matrix implements ObjectCreateInterface, ObjectDoOperationInterface, ObjectCompareValuesInterface
+{
+    use ObjectCreateTrait;
+
+    private array $matrix = [];
+    private int $rows = 0;
+    private int $columns = 0;
+
+    /**
+     * Matrix constructor.
+     *
+     * @param array $matrix
+     */
+    public function __construct(array $matrix)
+    {
+        $this->matrix  = $matrix;
+        $this->rows    = count($matrix);
+        $this->columns = count($matrix[0]);
+    }
+
+    public function getRows(): int
+    {
+        return $this->rows;
+    }
+
+    public function getColumns(): int
+    {
+        return $this->columns;
+    }
+
+    public function isSquare(): bool
+    {
+        return $this->columns === $this->rows;
+    }
+
+    /**
+     * Performs multiplication of two matrices
+     *
+     * @param Matrix $multiplier
+     *
+     * @todo: Implement SSE/AVX support for multiplication
+     *
+     * @return $this Product of two matrices
+     */
+    public function multiply(self $multiplier): self
+    {
+        if ($this->columns !== $multiplier->rows) {
+            throw new InvalidArgumentException('Inconsistent matrix supplied');
+        }
+
+        $totalColumns = $multiplier->columns;
+        $result       = [];
+        foreach ($this->matrix as $row => $rowItems) {
+            for ($column = 0; $column < $totalColumns; ++$column) {
+                $columnItems = array_column($multiplier->matrix, $column);
+                $cellValue   = 0;
+                foreach ($rowItems as $key => $value) {
+                    $cellValue += $value * $columnItems[$key];
+                }
+
+                $result[$row][$column] = $cellValue;
+            }
+        }
+
+        return new static($result);
+    }
+
+    /**
+     * Performs division by scalar value
+     *
+     * @param int|float $value Divider
+     *
+     * @return $this
+     */
+    public function divideByScalar($value): self
+    {
+        if (!is_numeric($value)) {
+            throw new \InvalidArgumentException("Divide accepts only numeric values");
+        }
+        $result = [];
+        for ($i = 0; $i < $this->rows; ++$i) {
+            for ($j = 0; $j < $this->columns; ++$j) {
+                $result[$i][$j] = $this->matrix[$i][$j] / $value;
+            }
+        }
+
+        return new static($result);
+    }
+
+    /**
+     * Performs multiplication by scalar value
+     *
+     * @param int|float $value Multiplier
+     *
+     * @return $this
+     */
+    public function multiplyByScalar($value): self
+    {
+        if (!is_numeric($value)) {
+            throw new \InvalidArgumentException("Multiply accepts only numeric values");
+        }
+        $result = [];
+        for ($i = 0; $i < $this->rows; ++$i) {
+            for ($j = 0; $j < $this->columns; ++$j) {
+                $result[$i][$j] = $this->matrix[$i][$j] * $value;
+            }
+        }
+
+        return new static($result);
+    }
+
+    /**
+     * Performs addition of two matrices
+     *
+     * @param Matrix $value
+     *
+     * @return $this Sum of two matrices
+     * @todo: Implement SSE/AVX support for addition
+     */
+    public function sum(self $value): self
+    {
+        $result = [];
+        for ($i = 0; $i < $this->rows; ++$i) {
+            for ($k = 0; $k < $this->columns; ++$k) {
+                $result[$i][$k] = $this->matrix[$i][$k] + $value->matrix[$i][$k];
+            }
+        }
+
+        return new static($result);
+    }
+
+    /**
+     * Performs subtraction of two matrices
+     *
+     * @param Matrix $value
+     *
+     * @todo: Implement SSE/AVX support for addition
+     *
+     * @return $this Subtraction of two matrices
+     */
+    public function subtract(self $value): self
+    {
+        $result = [];
+        for ($i = 0; $i < $this->rows; ++$i) {
+            for ($k = 0; $k < $this->columns; ++$k) {
+                $result[$i][$k] = $this->matrix[$i][$k] - $value->matrix[$i][$k];
+            }
+        }
+
+        return new static($result);
+    }
+
+    /**
+     * Checks if the given matrix equals to another one
+     *
+     * @param Matrix $another Another matrix
+     *
+     * @return bool
+     */
+    public function equals(Matrix $another): bool
+    {
+        if ($another->rows !== $this->rows || $another->columns !== $this->columns) {
+            return false;
+        }
+        for ($i = 0; $i < $this->rows; ++$i) {
+            for ($k = 0; $k < $this->columns; ++$k) {
+                $equals = $this->matrix[$i][$k] === $another->matrix[$i][$k];
+                if (!$equals) {
+                    return false;
+                }
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Performs operation on given object
+     *
+     * @param int $opCode Operation code
+     * @param Matrix|int|float $left left side of operation
+     * @param Matrix|int|float $right Right side of operation
+     *
+     * @return Matrix Result of operation value
+     */
+    public static function __doOperation(int $opCode, $left, $right): Matrix
+    {
+        $isLeftMatrix   = $left instanceof Matrix;
+        $isRightMatrix  = $right instanceof Matrix;
+        $isLeftNumeric  = is_numeric($left);
+        $isRightNumeric = is_numeric($right);
+
+        switch ($opCode) {
+            case OpCode::ADD:
+                if ($isLeftMatrix && $isRightMatrix) {
+                    return $left->sum($right);
+                }
+                break;
+            case OpCode::SUB:
+                if ($isLeftMatrix && $isRightMatrix) {
+                    return $left->subtract($right);
+                }
+                break;
+            case OpCode::MUL:
+                if ($isLeftMatrix && $isRightMatrix) {
+                    return $left->multiply($right);
+                } elseif ($isLeftMatrix && $isRightNumeric) {
+                    return $left->multiplyByScalar($right);
+                } elseif ($isLeftNumeric && $isRightMatrix) {
+                    return $right->multiplyByScalar($left);
+                }
+                break;
+            case OpCode::DIV:
+                if ($isLeftMatrix && $isRightNumeric) {
+                    return $left->divideByScalar($right);
+                }
+                break;
+        }
+
+        throw new \LogicException('Unsupported ' . OpCode::name($opCode). ' operation or invalid arguments');
+    }
+
+    /**
+     * Performs comparison of given object with another value
+     *
+     * @param mixed $one     First side of operation
+     * @param mixed $another Another side of operation
+     *
+     * @return int Result of comparison: 1 is greater, -1 is less, 0 is equal
+     */
+    public static function __compare($one, $another): int
+    {
+        if (!($one instanceof Matrix) || !($another instanceof Matrix)) {
+            throw new \InvalidArgumentException('Matrix can be compared only with another matrix');
+        }
+
+        if ($one->equals($another)) {
+            return 0;
+        }
+
+        return -2;
+    }
+}