refactor: add contracts for determining comparability and equality

Author: Thorsten Suckow-Homberg

src/Core/Contract/Comparable.php

@@ -0,0 +1,50 @@
+<?php
+
+/**
+ * conjoon
+ * php-lib-conjoon
+ * Copyright (C) 2022 Thorsten Suckow-Homberg https://github.com/conjoon/php-lib-conjoon
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+ * USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+declare(strict_types=1);
+
+namespace Conjoon\Core\Contract;
+
+use Conjoon\Core\Exception\InvalidTypeException;
+
+/**
+ * Provides a contract for the ordering of an instance of the implementing class.
+ */
+interface Comparable
+{
+    /**
+     * Compares this instance with the $target and returns -1, 0 or 1 if this instance is
+     * less than, equal, or greater than the $target.
+     *
+     * @param object $target
+     *
+     * @return int
+     *
+     * @throws InvalidTypeException if the specified $target cannot be compared with an instance of this class.
+     */
+    public function compareTo(object $target): int;
+}

src/Core/Contract/Equatable.php

@@ -0,0 +1,51 @@
+<?php
+
+/**
+ * conjoon
+ * php-lib-conjoon
+ * Copyright (C) 2022 Thorsten Suckow-Homberg https://github.com/conjoon/php-lib-conjoon
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+ * USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+declare(strict_types=1);
+
+namespace Conjoon\Core\Contract;
+
+use Conjoon\Core\Exception\InvalidTypeException;
+
+/**
+ * Provides a contract for comparing instances of implementing classes for equality.
+ */
+interface Equatable
+{
+    /**
+     * Compares this instance with the $target for equality and returns true if both instances should
+     * be treated as equal, otherwise false.
+     *
+     * @param object $target
+     *
+     * @return bool
+     *
+     * @throws InvalidTypeException if the specified $target cannot be compared for equality with an instance
+     * of this class.
+     */
+    public function equals(object $target): bool;
+}