feat: sort_rows of a Table

src/safeds/data/tabular/containers/_table.py

@@ -853,34 +853,62 @@ def slice(
 
     def sort_columns(
         self,
-        query: Callable[[Column, Column], int] = lambda col1, col2: (
+        comparator: Callable[[Column, Column], int] = lambda col1, col2: (
             col1.name > col2.name
         )
         - (col1.name < col2.name),
     ) -> Table:
         """
-        Sort a table with the given lambda function.
-        If no function is given the columns will be sorted alphabetically.
-        This function uses the default python sort algorithm.
-        The query returns
-        0, if both columns are equal.
-        < 0, if the first column should be ordered after the second column.
-        > 0, if the first column should be ordered before the second column.
+        Sort the columns of a `Table` with the given comparator and return a new `Table`. The original table is not
+        modified.
+
+        The comparator is a function that takes two columns `col1` and `col2` and returns an integer:
+
+        * If `col1` should be ordered before `col2`, the function should return a negative number.
+        * If `col1` should be ordered after `col2`, the function should return a positive number.
+        * If the original order of `col1` and `col2` should be kept, the function should return 0.
+
+        If no comparator is given, the columns will be sorted alphabetically by their name.
 
         Parameters
         ----------
-        query : a lambda function
-            The lambda function used to sort the columns.
+        comparator : Callable[[Column, Column], int]
+            The function used to compare two columns.
 
         Returns
         -------
         new_table : Table
             A new table with sorted columns.
         """
         columns = self.to_columns()
-        columns.sort(key=functools.cmp_to_key(query))
+        columns.sort(key=functools.cmp_to_key(comparator))
         return Table.from_columns(columns)
 
+    def sort_rows(self, comparator: Callable[[Row, Row], int]) -> Table:
+        """
+        Sort the rows of a `Table` with the given comparator and return a new `Table`. The original table is not
+        modified.
+
+        The comparator is a function that takes two rows `row1` and `row2` and returns an integer:
+
+        * If `col1` should be ordered before `col2`, the function should return a negative number.
+        * If `col1` should be ordered after `col2`, the function should return a positive number.
+        * If the original order of `col1` and `col2` should be kept, the function should return 0.
+
+        Parameters
+        ----------
+        comparator : Callable[[Row, Row], int]
+            The function used to compare two rows.
+
+        Returns
+        -------
+        new_table : Table
+            A new table with sorted rows.
+        """
+        rows = self.to_rows()
+        rows.sort(key=functools.cmp_to_key(comparator))
+        return Table.from_rows(rows)
+
     def split(self, percentage_in_first: float) -> typing.Tuple[Table, Table]:
         """
         Split the table into two new tables.

tests/safeds/data/tabular/containers/_table/test_sort_rows.py

@@ -0,0 +1,49 @@
+from typing import Callable
+
+import pytest
+from safeds.data.tabular.containers import Column, Row, Table
+
+
+class TestSortRows:
+    @pytest.mark.parametrize(
+        ("table", "comparator", "expected"),
+        [
+            # Activate when https://github.com/Safe-DS/Stdlib/issues/75 is fixed.
+            # (
+            #     Table.from_columns([Column([], "col1")]),
+            #     lambda row1, row2: row1["col1"] - row2["col1"],
+            #     Table.from_columns([Column([], "col1")]),
+            # ),
+            (
+                Table.from_columns([Column([3, 2, 1], "col1")]),
+                lambda row1, row2: row1["col1"] - row2["col1"],
+                Table.from_columns([Column([1, 2, 3], "col1")]),
+            ),
+        ],
+    )
+    def test_should_return_sorted_table(
+        self, table: Table, comparator: Callable[[Row, Row], int], expected: Table
+    ) -> None:
+        assert table.sort_rows(comparator) == expected
+
+    @pytest.mark.parametrize(
+        ("table", "comparator", "expected"),
+        [
+            # Activate when https://github.com/Safe-DS/Stdlib/issues/75 is fixed.
+            # (
+            #     Table.from_columns([Column([], "col1")]),
+            #     lambda row1, row2: row1["col1"] - row2["col1"],
+            #     Table.from_columns([Column([], "col1")])
+            # ),
+            (
+                Table.from_columns([Column([3, 2, 1], "col1")]),
+                lambda row1, row2: row1["col1"] - row2["col1"],
+                Table.from_columns([Column([3, 2, 1], "col1")]),
+            ),
+        ],
+    )
+    def test_should_not_modify_original_table(
+        self, table: Table, comparator: Callable[[Row, Row], int], expected: Table
+    ) -> None:
+        table.sort_rows(comparator)
+        assert table == expected