Adds intersect() method to Period class

Author: sdispater

CHANGELOG.md

@@ -7,7 +7,8 @@
 - Adds an option to control transition normalization behavior.
 - Adds a separator keyword argument to `Interval.in_words()` method.
 - Adds an alternative formatter.
-- Adds support for pytz tzinfo in `instance()` method
+- Adds support for pretty much any `tzinfo` instance in the `instance()` method.
+- Adds an `intersect()` method to the `Period` class.
 
 ### Changed
 

docs/index.rst

@@ -1631,3 +1631,59 @@ You can check if a ``Pendulum`` instance is inside a period using the ``in`` key
 
     dt in period
     True
+
+Intersection
+------------
+
+.. versionadded:: 0.6.0
+
+    The ``intersect()`` method has been added.
+
+You can get the intersection of the current ``Period`` instance with others by
+using the ``intersect()`` method.
+
+.. code-block:: python
+
+    import pendulum
+
+
+    monday = pendulum.create(2016, 9, 12)
+    wednesday = monday.next(pendulum.WEDNESDAY)
+    friday = monday.next(pendulum.FRIDAY)
+    saturday = monday.next(pendulum.SATURDAY)
+
+    period = pendulum.period(monday, friday)
+
+    period.intersect(pendulum.period(wednesday, saturday))
+    # <Period [2016-09-14T00:00:00+00:00 -> 2016-09-16T00:00:00+00:00]>
+
+You can also pass multiple period to ``intersect()``.
+
+.. code-block:: python
+
+    import pendulum
+
+
+    monday = pendulum.create(2016, 9, 12)
+    wednesday = monday.next(pendulum.WEDNESDAY)
+    thursday = monday.next(pendulum.THURSDAY)
+    friday = monday.next(pendulum.FRIDAY)
+    saturday = monday.next(pendulum.SATURDAY)
+    sunday = monday.next(pendulum.SUNDAY)
+
+    period = pendulum.period(monday, friday)
+    wednesday_to_saturday = pendulum.period(wednesday, saturday)
+    thursday_to_sunday = pendulum.period(thursday, sunday)
+
+    period.intersect(
+        wednesday_to_saturday,
+        thursday_to_sunday
+    )
+    # <Period [2016-09-15T00:00:00+00:00 -> 2016-09-16T00:00:00+00:00]>
+
+If no intersection exists, ``intersect()`` will return ``None``:
+
+.. code-block:: python
+
+    period.intersect(pendulum.period(saturday, sunday))
+    None

pendulum/period.py

@@ -103,6 +103,30 @@ def xrange(self, unit):
 
             start = getattr(start, method)(**{unit: 1})
 
+    def intersect(self, *periods):
+        """
+        Return the Period intersection of the current Period
+        and the given periods.
+
+        :type periods: tuple of Period
+
+        :rtype: Period
+        """
+        start, end = self.start, self.end
+        has_intersection = False
+        for period in periods:
+            if period.end < start or period.start > end:
+                continue
+
+            has_intersection = True
+            start = max(start, period.start)
+            end = min(end, period.end)
+
+        if not has_intersection:
+            return None
+
+        return self.__class__(start, end)
+
     def as_interval(self):
         """
         Return the Period as an Interval.

tests/period_tests/test_intersect.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+
+from pendulum import Period, Pendulum
+
+from .. import AbstractTestCase
+
+
+class IntersectTestCase(AbstractTestCase):
+
+    def test_intersect_included(self):
+        start = Pendulum(2016, 8, 7)
+        end = start.add(weeks=1)
+        p1 = Period(start, end)
+        intersection = p1.intersect(Period(start.add(days=2), start.add(days=4)))
+
+        self.assertPendulum(intersection.start, 2016, 8, 9)
+        self.assertPendulum(intersection.end, 2016, 8, 11)
+
+    def test_intersect_overlap(self):
+        start = Pendulum(2016, 8, 7)
+        end = start.add(weeks=1)
+        p1 = Period(start, end)
+        intersection = p1.intersect(Period(start.add(days=-2), start.add(days=2)))
+
+        self.assertPendulum(intersection.start, 2016, 8, 7)
+        self.assertPendulum(intersection.end, 2016, 8, 9)
+
+    def test_intersect_multiple(self):
+        start = Pendulum(2016, 8, 7)
+        end = start.add(weeks=1)
+        p1 = Period(start, end)
+        intersection = p1.intersect(
+            Period(start.add(days=-2), start.add(days=2)),
+            Period(start.add(days=1), start.add(days=2))
+        )
+
+        self.assertPendulum(intersection.start, 2016, 8, 8)
+        self.assertPendulum(intersection.end, 2016, 8, 9)
+
+    def test_intersect_excluded(self):
+        start = Pendulum(2016, 8, 7)
+        end = start.add(weeks=1)
+        p1 = Period(start, end)
+        intersection = p1.intersect(
+            Period(start.add(days=-2), start.add(days=-1))
+        )
+
+        self.assertIsNone(intersection)
+
+    def test_intersect_same(self):
+        start = Pendulum(2016, 8, 7)
+        end = start.add(weeks=1)
+        p1 = Period(start, end)
+        intersection = p1.intersect(
+            Period(start.copy(), end.copy())
+        )
+
+        self.assertPendulum(intersection.start, 2016, 8, 7)
+        self.assertPendulum(intersection.end, 2016, 8, 14)