Add isSame, isContainedIn, contains, isSameOrContains, isSameOrContai…

…nedIn methods (#7)

README.md

@@ -19,7 +19,7 @@ composer require mlocati/comuni-italiani
 
 This library provides the following Italian Administrative divisions:
 
-- **Geographical Subdivisions** (*ripartizioni geografiche*)  
+- **Geographical Subdivisions** (*ripartizioni geografiche*)
   For example "Nord-ovest", "Centro", "Sud"
 - **Regions** (*regioni*)
   For example "Piemonte", "Lazio", "Campania"
@@ -80,7 +80,7 @@ This library provides the following data:
   - the second level of the current Nomenclature of Territorial Units for Statistics (NUTS2) (example: `'ITC1'`)
   - the third level of the current Nomenclature of Territorial Units for Statistics (NUTS3) (example: `'ITC11'`)
 
-### Retrieving territories
+### Retrieving Territories
 
 You can have a list of all the Geographical Subdivisions, Regions, Provinces/UTS, and Municipalities using the `Factory` class.
 
@@ -110,7 +110,7 @@ $province = $finder->getProvinceByID('201');
 $municipality = $finder->getMunicipalityByID('001272');
 ```
 
-### Finding territories by name
+### Finding Territories by Name
 
 You can use the `Finder` class to find Geographical Subdivisions, Regions, Provinces/UTS, and Municipalities by name.
 
@@ -146,3 +146,37 @@ $regions = $finder->findRegionsByName('ampania', true);
 $provinces = $finder->findProvincesByName('ozen', true);
 $municipalities = $finder->findMunicipalitiesByName('oma ombard', true);
 ```
+
+### Testing Hierarchy
+
+Given two territories, you can check if they are the same by using the `isSame()` method:
+
+```php
+if ($territory1->isSame($territory2)) {
+    echo 'Same territory';
+}
+```
+
+You can also check if a territory is contained in another territory:
+
+```php
+if ($territory1->isContainedIn($territory2)) {
+    echo "{$territory1} is contained in {$territory2}";
+}
+if ($territory1->isSameOrContainedIn($territory2)) {
+    echo "{$territory1} is contained in {$territory2} (or they are the same)";
+}
+```
+
+For Geographical Subdivisions, Regions, and Provinces/UTS (which are containers of other territories) you can also use the `contains()` and `isSameOrContains()` methods.
+
+```php
+// $region is an instance of Region here
+if ($region->contains($territory)) {
+    echo "{$region} contains {$terrtory}";
+}
+
+if ($region->isSameOrContains($territory)) {
+    echo "{$region} is same (or contains) {$terrtory}";
+}
+```

src/GeographicalSubdivision.php

@@ -9,6 +9,8 @@
  */
 final class GeographicalSubdivision implements TerritoryWithChildren
 {
+    use Service\TerritoryWithChildrenTrait;
+
     private array $data;
 
     private ?array $regions = null;

src/Municipality.php

@@ -9,6 +9,8 @@
  */
 final class Municipality implements Territory
 {
+    use Service\TerritoryTrait;
+
     private array $data;
 
     private Province $province;

src/Province.php

@@ -9,6 +9,8 @@
  */
 final class Province implements TerritoryWithChildren
 {
+    use Service\TerritoryWithChildrenTrait;
+
     private array $data;
 
     private Region $region;

src/Region.php

@@ -9,6 +9,8 @@
  */
 final class Region implements TerritoryWithChildren
 {
+    use Service\TerritoryWithChildrenTrait;
+
     private array $data;
 
     private GeographicalSubdivision $geographicalSubdivision;

src/Service/MultibyteTrait.php

@@ -4,6 +4,9 @@
 
 namespace MLocati\ComuniItaliani\Service;
 
+/**
+ * @internal
+ */
 trait MultibyteTrait
 {
     protected static function getMultibyteToAsciiMap(): array

src/Service/SorterTrait.php

@@ -7,6 +7,9 @@
 use Collator;
 use MLocati\ComuniItaliani\Territory;
 
+/**
+ * @internal
+ */
 trait SorterTrait
 {
     use MultibyteTrait;

src/Service/TerritoryTrait.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MLocati\ComuniItaliani\Service;
+
+use MLocati\ComuniItaliani\Territory;
+use MLocati\ComuniItaliani\TerritoryWithChildren;
+
+/**
+ * @internal
+ */
+trait TerritoryTrait
+{
+    /**
+     * {@inheritdoc}
+     *
+     * @see \MLocati\ComuniItaliani\Territory::isSame()
+     */
+    public function isSame(Territory $territory): bool
+    {
+        return $this->getID() === $territory->getID();
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @see \MLocati\ComuniItaliani\Territory::isContainedIn()
+     */
+    public function isContainedIn(Territory $territory): bool
+    {
+        return $territory instanceof TerritoryWithChildren && $territory->contains($this);
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @see \MLocati\ComuniItaliani\Territory::isContainedIn()
+     */
+    public function isSameOrContainedIn(Territory $territory): bool
+    {
+        return $this->isSame($territory) || $this->isContainedIn($territory);
+    }
+}

src/Service/TerritoryWithChildrenTrait.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MLocati\ComuniItaliani\Service;
+
+use MLocati\ComuniItaliani\Territory;
+use MLocati\ComuniItaliani\TerritoryWithChildren;
+
+/**
+ * @internal
+ */
+trait TerritoryWithChildrenTrait
+{
+    use TerritoryTrait;
+
+    /**
+     * {@inheritdoc}
+     *
+     * @see \MLocati\ComuniItaliani\TerritoryWithChildren::contains()
+     */
+    public function contains(Territory $territory): bool
+    {
+        foreach ($this->getChildren() as $child) {
+            if ($child instanceof TerritoryWithChildren) {
+                if ($child->isSameOrContains($territory)) {
+                    return true;
+                }
+            } elseif ($child->isSame($territory)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @see \MLocati\ComuniItaliani\TerritoryWithChildren::isSameOrContains()
+     */
+    public function isSameOrContains(Territory $territory): bool
+    {
+        return $this->isSame($territory) || $this->contains($territory);
+    }
+}

src/Territory.php

@@ -26,6 +26,21 @@ public function getParent(): ?TerritoryWithChildren;
      */
     public function getName(): string;
 
+    /**
+     * Check if a territory instance is the same as this.
+     */
+    public function isSame(Territory $territory): bool;
+
+    /**
+     * Check if this territory is a child/grandchild/great-grandchild/... of another territory.
+     */
+    public function isContainedIn(Territory $territory): bool;
+
+    /**
+     * Check if this territory is a child/grandchild/great-grandchild/... of another territory, of if they are the same
+     */
+    public function isSameOrContainedIn(Territory $territory): bool;
+
     /**
      * Get a string representation that uniquely represents the territory.
      */

src/TerritoryWithChildren.php

@@ -15,4 +15,14 @@ interface TerritoryWithChildren extends Territory
      * @return \MLocati\ComuniItaliani\Territory[]
      */
     public function getChildren(): array;
+
+    /**
+     * Check if this territory contains another territory.
+     */
+    public function contains(Territory $territory): bool;
+
+    /**
+     * Check if this territory contains another territory, or if it's the same as this.
+     */
+    public function isSameOrContains(Territory $territory): bool;
 }

test/tests/HierarchyTest.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MLocati\ComuniItaliani\Test;
+
+use PHPUnit\Framework\TestCase;
+use MLocati\ComuniItaliani\Factory;
+use MLocati\ComuniItaliani\Territory;
+use MLocati\ComuniItaliani\TerritoryWithChildren;
+
+class HierarchyTest extends TestCase
+{
+    public function testHierarchy(): void
+    {
+        $factory1 = new Factory();
+        $factory2 = new Factory();
+
+        $this->testHierarchyFor($factory1->getGeographicalSubdivisions()[0], $factory2->getGeographicalSubdivisions()[0]);
+    }
+
+    private function testHierarchyFor(Territory $territory, Territory $equalsNotSame, ?Territory $ascending = null): void
+    {
+        $this->assertNotSame($territory, $equalsNotSame);
+        $this->assertTrue($territory->isSame($territory));
+        $this->assertTrue($territory->isSame($equalsNotSame));
+        $this->assertFalse($territory->isContainedIn($territory));
+        $this->assertTrue($territory->isSameOrContainedIn($territory));
+        if ($ascending !== null) {
+            $this->assertTrue($ascending->contains($territory));
+        }
+        if ($territory instanceof TerritoryWithChildren) {
+            if ($ascending !== null) {
+                $this->assertFalse($territory->contains($ascending));
+            }
+            $this->assertFalse($territory->contains($territory));
+            $this->assertFalse($territory->contains($equalsNotSame));
+            $this->assertTrue($territory->isSameOrContains($territory));
+            $this->assertTrue($territory->isSameOrContains($equalsNotSame));
+            $child = $territory->getChildren()[0];
+            $this->assertFalse($child->isSame($territory));
+            $this->assertFalse($territory->isSame($child));
+            $this->assertTrue($child->isContainedIn($territory));
+            $this->assertTrue($child->isSameOrContainedIn($territory));
+            $this->assertTrue($territory->contains($child));
+            $this->assertTrue($territory->isSameOrContains($child));
+            if ($child instanceof TerritoryWithChildren) {
+                $this->assertFalse($child->contains($territory));
+                $this->assertFalse($child->isSameOrContains($territory));
+                $this->testHierarchyFor($child, $equalsNotSame->getChildren()[0], $ascending ?? $territory);
+            }
+        }
+    }
+}