get dt index for time unit

README.md

@@ -105,6 +105,55 @@ for dt in Quarter(date(1958, 3, 25)):
 
 we can also convert such collection to a list.
 
+### Subscripting
+
+The `Day`, `Week`, `Month, etc. classes have `.get_index_for_date(..)` and `.get_date_from_index(..)` methods, which allow to determine how many days, weeks, months, quarters and years are between `date.min` and the date given, and convert this back to a date. For example:
+
+```
+Week.get_index_for_date(date(1958, 3, 25))  # 102123
+Week.get_date_from_index(102123)  # date(1958, 3, 24)
+```
+
+so 1958-03-25 is the 102'123 week since 0001-01-01, and that week starts the 24<sup>th</sup> of March, 1958.
+
+We can also use the index to get a `TimUnit` with:
+
+```
+Week[102123]  # Week(date(1958, 3, 24))
+```
+
+moreover a week itself can be subscripted, for example:
+
+```
+Week(date(1958, 3, 24))[2]  # date(1958, 3, 26)
+```
+
+one can also slice to created an object that is a sliced "view" that generates `Week`s or `date`s in the week respectively. This view can then be sliced or indexed further. For example:
+
+```
+Week[102123:105341:2]
+```
+
+is a collection of `Week` objects between `1958-03-24` and `2019-11-25` each time with one week in between.
+
+
+The `Week` class itself is also iterable, for example:
+
+```
+for week in Week:
+    print(week)
+```
+
+will start enumerating over all weeks since 0001-01-01.
+
+A time unit also has a length: the number of time units that can be represented, so:
+
+```
+len(Week)  # 521722
+``
+
+means the software can represent 521'722 weeks from 0001-01-01 to 9999-12-26.
+
 ### Shifting units of time
 
 The units of time can also be shifted, for example:

timetest.py

@@ -21,24 +21,50 @@ def truncate(cls, dt):
         """
         return date(10 * (dt.year // 10), 1, 1)
 
+    @classmethod
+    def get_index_for_date(cls, dt):
+        """
+        Return the zero-based decade index for the given date.
+
+        Parameters:
+            dt (date or datetime): The date for which to compute the decade index.
+
+        Returns:
+            int: The decade index equal to the calendar year divided by 10 using integer division (year // 10).
+        """
+        return dt.year // 10
+
+    @classmethod
+    def get_date_from_index(cls, idx):
+        """
+        Return the start date (January 1) of the decade represented by the given index.
+
+        Parameters:
+            idx (int): Decade index; the corresponding year is 10 * idx.
+
+        Returns:
+            datetime.date: January 1 of the year 10 * idx.
+        """
+        return date(10 * idx, 1, 1)
+
     @classmethod
     def last_day(cls, dt):
         """
-        Return the last day of the decade containing the given date.
+        Return the last date of the decade that contains the given date.
 
         Parameters:
-                dt (date or datetime): The date for which to determine the last day of its decade.
+            dt (date | datetime): Date or datetime within the target decade.
 
         Returns:
-                date: The last day of the decade as a date object.
+            date: The last day of that decade.
         """
         dt = cls.truncate(dt)
         return date(dt.year + 10, 1, 1) - timedelta(days=1)
 
 
 TIME_UNITS = [Decade, Year, Quarter, Month, Week, Day]
-START_DATE = date(1302, 7, 11)
-END_DATE = date(2019, 11, 25)
+START_DATE = date(902, 7, 11)
+END_DATE = date(1019, 11, 25)
 
 
 class TimeUnitTest(unittest.TestCase):
@@ -99,6 +125,15 @@ def test_to_int(self):
                     self.assertLess(tu, tu.next)
                     self.assertLessEqual(tu.previous, tu)
                     self.assertLessEqual(tu, tu.next)
+                    idx = kind.get_index_for_date(tu.dt)
+                    self.assertEqual(
+                        idx,
+                        kind.get_index_for_date(tu.next.dt) - 1,
+                    )
+                    self.assertEqual(tu.dt, kind.get_date_from_index(idx))
+                    self.assertEqual(tu, kind[idx])
+                    for dt2 in tu:
+                        self.assertEqual(idx, kind.get_index_for_date(dt2))
                     self.assertGreater(tu, tu.previous)
                     self.assertGreater(tu.next, tu)
                     self.assertGreaterEqual(tu, tu.previous)
@@ -197,7 +232,9 @@ def test_kinds(self):
             self.assertEqual(kind, kind.kind_int)
             self.assertEqual(kind.kind_int, kind)
             self.assertEqual(d[kind], kind in seen)
+            self.assertEqual(kind.get_index_for_date(date.min), 0)
             d[kind] = True
+            self.assertEqual(list(kind[10:110:10][5:9:2]), list(kind[60:100:20]))
             self.assertNotIn(kind, seen)
             seen.add(kind)
             for kind2 in TIME_UNITS[i:]: