add column.shift (#317)

* add column.shift

* extra docs

* formatting, remove fill_value

Author: MarcoGorelli

spec/API_specification/dataframe_api/column_object.py

@@ -811,6 +811,23 @@ def rename(self, name: str) -> Self:
         """
         ...
 
+    def shift(self, offset: int) -> Self:
+        """Shift values by `offset` positions, filling missing values with `null`.
+
+        For example, if the original column contains values `[1, 4, 2]`, then:
+
+        - `.shift(1)` will return `[null, 1, 4]`,
+        - `.shift(-1)` will return `[4, 2, null]`,
+    
+        Parameters
+        ----------
+        offset
+            How many positions to shift by.
+        """
+        ...
+
+    # --- temporal methods ---
+
     def year(self) -> Self:
         """Return 'year' component of each element of `Date` and `Datetime` columns.