Add column.sorted_indices (#184)

* add column.sorted_indices

* typo

Author: MarcoGorelli

spec/API_specification/dataframe_api/column_object.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any, NoReturn, Sequence, TYPE_CHECKING
+from typing import Any,NoReturn, Sequence, TYPE_CHECKING, Literal
 
 if TYPE_CHECKING:
     from ._types import Scalar
@@ -98,6 +98,36 @@ def get_value(self, row_number: int) -> Scalar:
         """
         ...
 
+    def sorted_indices(
+        self,
+        *,
+        ascending: bool = True,
+        nulls_position: Literal['first', 'last'] = 'last',
+    ) -> Column[int]:
+        """
+        Return row numbers which would sort column.
+
+        If you need to sort the Column, you can simply do::
+
+            col.get_rows(col.sorted_indices())
+
+        Parameters
+        ----------
+        ascending : bool
+            If `True`, sort in ascending order.
+            If `False`, sort in descending order.
+        nulls_position : ``{'first', 'last'}``
+            Whether null values should be placed at the beginning
+            or at the end of the result.
+            Note that the position of NaNs is unspecified and may
+            vary based on the implementation.
+
+        Returns
+        -------
+        Column[int]
+        """
+        ...
+
     def __eq__(self, other: Column | Scalar) -> Column:
         """
         Compare for equality.