Add .dt.floor

spec/API_specification/dataframe_api/column_object.py

@@ -819,3 +819,131 @@ def rename(self, name: str) -> Self:
             New column - this does not operate in-place.
         """
         ...
+
+
+    def year(self) -> Self:
+        """
+        Return 'year' component of each element of `Date` and `Datetime` columns.
+
+        For example, return 1981 for 1981-01-02T12:34:56.123456.
+
+        Return column should be of (signed) integer dtype.
+        """
+        ...
+
+    def month(self) -> Self:
+        """
+        Return 'month' component of each element of `Date` and `Datetime` columns.
+
+        For example, return 1 for 1981-01-02T12:34:56.123456.
+
+        Return column should be of integer dtype (signed or unsigned).
+        """
+        ...
+
+    def day(self) -> Self:
+        """
+        Return 'day' component of each element of `Date` and `Datetime` columns.
+
+        For example, return 2 for 1981-01-02T12:34:56.123456.
+
+        Return column should be of integer dtype (signed or unsigned).
+        """
+        ...
+
+    def hour(self) -> Self:
+        """
+        Return 'hour' component of each element of `Date` and `Datetime` columns.
+
+        For example, return 12 for 1981-01-02T12:34:56.123456.
+
+        Return column should be of integer dtype (signed or unsigned).
+        """
+        ...
+
+    def minute(self) -> Self:
+        """
+        Return 'minute' component of each element of `Date` and `Datetime` columns.
+
+        For example, return 34 for 1981-01-02T12:34:56.123456.
+
+        Return column should be of integer dtype (signed or unsigned).
+        """
+        ...
+
+    def second(self) -> Self:
+        """
+        Return 'second' component of each element of `Date` and `Datetime` columns.
+
+        For example, return 56 for 1981-01-02T12:34:56.123456.
+
+        Return column should be of integer dtype (signed or unsigned).
+        """
+        ...
+
+    def microsecond(self) -> Self:
+        """
+        Return number of microseconds since last second, for each element of `Date` and `Datetime` columns.
+
+        For example, return 123456 for 1981-01-02T12:34:56.123456.
+
+        Return column should be of integer dtype (signed or unsigned).
+        """
+        ...
+
+    def iso_weekday(self) -> Self:
+        """
+        Return ISO weekday for each element of `Date` and `Datetime` columns.
+
+        Note that Monday=1, ..., Sunday=7.
+
+        Return column should be of integer dtype (signed or unsigned).
+        """
+        ...
+
+    def floor(self, frequency: str) -> Self:
+        """
+        Return floor of each element according to the specified frequency.
+
+        Flooring is done according to local time. For example,
+        for a ``Datetime('us', 'Europe/London')`` column,
+        ``"2020-10-25T00:30:00 BST"`` floored by ``"1day"`` gives
+        ``"2020-10-25T00:00:00 BST"``.
+        Behaviours in the face of ambiguous and non-existent times are
+        currently unspecified and may vary across implementations.
+
+        Flooring by non-fixed durations (e.g. calendar month) are not supported.
+        Note that flooring by ``timedelta(days=1)`` is equivalent to flooring
+        by ``timedelta(hours=24)``.
+
+        Parameters
+        ----------
+        freq : str
+            Frequency to floor by. Can be constructed using the following string
+            language:
+
+            - "<n>day(s)"
+            - "<n>hour(s)"
+            - "<n>minute(s)"
+            - "<n>second(s)"
+            - "<n>millisecond(s)"
+            - "<n>microsecond(s)"
+
+            where ``<n>`` is a positive integer and the trailing (s) is
+            optional.
+            Multiple frequencies can be specified, separated by blank spaces.
+
+            Examples of valid inputs are:
+
+            - "1day"
+            - "1day 1hour"
+            - "1day 2hours 3minutes 4seconds 5milliseconds 6microseconds"
+
+        Examples
+        --------
+        Roll each datetime back to the beginning of the day:
+
+        >>> column: Column
+        >>> column.dt.floor("1day")
+        """
+        ...