add max_by() and min_by()

this is similar to maxima_by, but according to .net 6 doc this function only returns one value

Author: cleoold

doc/api/types_linq.enumerable.rst

@@ -1223,6 +1223,43 @@ Example
 
 ----
 
+instancemethod ``max_by[TSupportsLessThan](key_selector)``
+------------------------------------------------------------
+
+Parameters
+  - `key_selector` (``Callable[[TSource_co], TSupportsLessThan]``)
+
+Returns
+  - ``TSource_co``
+
+Returns the maximal element of the sequence based on the given key selector. Raises
+`InvalidOperationError` if there is no value.
+
+Example
+    >>> strs = ['aaa', 'bb', 'c', 'dddd']
+    >>> Enumerable(strs).max_by(len)
+    'dddd'
+
+----
+
+instancemethod ``max_by[TKey](key_selector, __comparer)``
+-----------------------------------------------------------
+
+Parameters
+  - `key_selector` (``Callable[[TSource_co], TKey]``)
+  - `__comparer` (``Callable[[TKey, TKey], int]``)
+
+Returns
+  - ``TSource_co``
+
+Returns the maximal element of the sequence based on the given key selector and the comparer.
+Raises `InvalidOperationError` if there is no value.
+
+Such comparer takes two values and return positive ints when lhs > rhs, negative ints
+if lhs < rhs, and 0 if they are equal.
+
+----
+
 instancemethod ``min[TSupportsLessThan]()``
 ---------------------------------------------
 
@@ -1280,6 +1317,38 @@ resulting values. Returns the default one if there is no value.
 
 ----
 
+instancemethod ``min_by[TSupportsLessThan](key_selector)``
+------------------------------------------------------------
+
+Parameters
+  - `key_selector` (``Callable[[TSource_co], TSupportsLessThan]``)
+
+Returns
+  - ``TSource_co``
+
+Returns the minimal element of the sequence based on the given key selector. Raises
+`InvalidOperationError` if there is no value.
+
+----
+
+instancemethod ``min_by[TKey](key_selector, __comparer)``
+-----------------------------------------------------------
+
+Parameters
+  - `key_selector` (``Callable[[TSource_co], TKey]``)
+  - `__comparer` (``Callable[[TKey, TKey], int]``)
+
+Returns
+  - ``TSource_co``
+
+Returns the minimal element of the sequence based on the given key selector and the comparer.
+Raises `InvalidOperationError` if there is no value.
+
+Such comparer takes two values and return positive ints when lhs > rhs, negative ints
+if lhs < rhs, and 0 if they are equal.
+
+----
+
 instancemethod ``of_type[TResult](t_result)``
 -----------------------------------------------
 

doc/api_spec.py

@@ -71,8 +71,10 @@ class ClassSpec(TypedDict):
                     'last2',
                     'max',
                     'max2',
+                    'max_by',
                     'min',
                     'min2',
+                    'min_by',
                     'of_type',
                     'order_by',
                     'order_by_descending',

doc/to-start/differences.rst

@@ -32,6 +32,10 @@ and its .NET counterpart.
   objects, construct hashmaps, etc. While in Python such identities are often solely determined by object's
   magic methods such as ``__hash__()``, ``__eq__()``, ``__lt__()``, etc. So method overloads that involve such
   comparer interfaces are omitted in this library, or implemented in another form.
+* In C#, there are nullable types and default values for a type. For example, ``default(int) == 0`` and ``default(int?) == null``.
+  Some C# methods return such default values if the source sequence is empty, or skip ``null``'s if the source sequence contains
+  concrete data too. There are no such notions in Python and the C#-like default semantics are non-existent. So, this usage is
+  not supported by this library (Can ``None`` be considered a default value for all cases? Hmm..).
 * All classes in this library are concrete. There are no interfaces like what are usually done in C#.
 
 Limitations:

tests/test_usage.py

@@ -712,6 +712,30 @@ def test_max2_overload2(self):
         en = Enumerable(lst)
         assert en.max2(lambda x: x[0], object) == 4
 
+
+class TestMaxByMethod:
+    def test_overload1(self):
+        strings = ['aaa', 'bb', 'c', 'dddd']
+        en = Enumerable(strings)
+        assert en.max_by(len) == 'dddd'
+
+    def test_overload1_empty(self):
+        strings: List[str] = []
+        en = Enumerable(strings)
+        with pytest.raises(InvalidOperationError):
+            en.max_by(len)
+
+    def test_dup_choose_first(self):
+        strings = ['foo', 'cheese', 'baz', 'spam', 'orange', 'string']
+        en = Enumerable(strings)
+        assert en.max_by(len) == 'cheese'
+
+    def test_overload2(self):
+        lst = [['foo'], ['cheese'], ['baz'], ['spam'], ['string']]
+        en = Enumerable(lst)
+        assert en.max_by(lambda x: x[0], lambda x, y: len(x) - len(y)) == ['cheese']
+
+
 class TestMinMethod:
     def test_min_overload1(self):
         nums = (1, 0.4, 2.2, 5, 1, 2)
@@ -757,6 +781,32 @@ def test_min2_overload2(self):
         assert en.min2(lambda x: x[0], object) == -11
 
 
+class TestMinByMethod:
+    def test_overload1(self):
+        strings = ['aaa', 'bb', 'c', 'dddd']
+        en = Enumerable(strings)
+        assert en.min_by(len) == 'c'
+
+    def test_overload1_empty(self):
+        strings: List[str] = []
+        en = Enumerable(strings)
+        with pytest.raises(InvalidOperationError):
+            en.min_by(len)
+
+    def test_dup_choose_first(self):
+        class MyType:
+            def __init__(self, x: int): self.x = x
+        lst = [MyType(2), MyType(7), MyType(19), MyType(1), MyType(7), MyType(1)]
+        en = Enumerable(lst)
+        assert en.min_by(lambda x: x.x) == lst[3]
+        assert en.min_by(lambda x: x.x) != lst[-1]
+
+    def test_overload2(self):
+        lst = [['foo'], ['cheese'], ['baz'], ['spam'], ['string']]
+        en = Enumerable(lst)
+        assert en.min_by(lambda x: x[0], lambda x, y: len(x) - len(y)) == ['foo']
+
+
 class TestOfTypeMethod:
     def test_of_type(self):
         lst = [1, 5, 4.4, object(), 5.6, -12.2, [], 2.2, False]

types_linq/enumerable.py

@@ -447,6 +447,20 @@ def _minmax_helper(self, result_selector, op, when_empty) -> Any:
             curr = mapped if op(curr, mapped) else curr
         return curr
 
+    def _minmax_by_helper(self, key_selector, op) -> Any:
+        iterator = iter(self)
+        try:
+            curr = next(iterator)
+        except StopIteration:
+            self._raise_empty_sequence()
+        curr_key = key_selector(curr)
+        for elem in iterator:
+            elem_key = key_selector(elem)
+            if op(curr_key, elem_key):
+                curr = elem
+                curr_key = elem_key
+        return curr
+
     def max(self, *args: Callable[[TSource_co], Any]) -> Any:
         if len(args) == 0:
             result_selector: Any = lambda x: x
@@ -469,6 +483,17 @@ def max2(self, *args) -> Any:
             lambda: default,
         )
 
+    def max_by(self,
+        key_selector: Callable[[TSource_co], Any],
+        *args: Callable[[Any, Any], int],
+    ) -> Any:
+        if len(args) == 0:
+            op = lambda l, r: l < r
+        else:  # len(args) == 1
+            comp = args[0]
+            op = lambda l, r: comp(l, r) < 0
+        return self._minmax_by_helper(key_selector, op)
+
     def min(self, *args: Callable[[TSource_co], Any]) -> Any:
         if len(args) == 0:
             result_selector: Any = lambda x: x
@@ -491,6 +516,17 @@ def min2(self, *args) -> Any:
             lambda: default,
         )
 
+    def min_by(self,
+        key_selector: Callable[[TSource_co], Any],
+        *args: Callable[[Any, Any], int],
+    ) -> Any:
+        if len(args) == 0:
+            op = lambda l, r: r < l
+        else:  # len(args) == 1
+            comp = args[0]
+            op = lambda l, r: comp(l, r) > 0
+        return self._minmax_by_helper(key_selector, op)
+
     def of_type(self, t_result: Type[TResult]) -> Enumerable[TResult]:
         return self.where(lambda e: isinstance(e, t_result)).cast(t_result)
 

types_linq/enumerable.pyi

@@ -924,6 +924,31 @@ class Enumerable(Sequence[TSource_co], Generic[TSource_co]):
             1
         '''
 
+    @overload
+    def max_by(self, key_selector: Callable[[TSource_co], TSupportsLessThan]) -> TSource_co:
+        '''
+        Returns the maximal element of the sequence based on the given key selector. Raises
+        `InvalidOperationError` if there is no value.
+
+        Example
+            >>> strs = ['aaa', 'bb', 'c', 'dddd']
+            >>> Enumerable(strs).max_by(len)
+            'dddd'
+        '''
+
+    @overload
+    def max_by(self,
+        key_selector: Callable[[TSource_co], TKey],
+        __comparer: Callable[[TKey, TKey], int],
+    ) -> TSource_co:
+        '''
+        Returns the maximal element of the sequence based on the given key selector and the comparer.
+        Raises `InvalidOperationError` if there is no value.
+
+        Such comparer takes two values and return positive ints when lhs > rhs, negative ints
+        if lhs < rhs, and 0 if they are equal.
+        '''
+
     @overload
     def min(self: Enumerable[TSupportsLessThan]) -> TSupportsLessThan:
         '''
@@ -955,6 +980,26 @@ class Enumerable(Sequence[TSource_co], Generic[TSource_co]):
         resulting values. Returns the default one if there is no value.
         '''
 
+    @overload
+    def min_by(self, key_selector: Callable[[TSource_co], TSupportsLessThan]) -> TSource_co:
+        '''
+        Returns the minimal element of the sequence based on the given key selector. Raises
+        `InvalidOperationError` if there is no value.
+        '''
+
+    @overload
+    def min_by(self,
+        key_selector: Callable[[TSource_co], TKey],
+        __comparer: Callable[[TKey, TKey], int],
+    ) -> TSource_co:
+        '''
+        Returns the minimal element of the sequence based on the given key selector and the comparer.
+        Raises `InvalidOperationError` if there is no value.
+
+        Such comparer takes two values and return positive ints when lhs > rhs, negative ints
+        if lhs < rhs, and 0 if they are equal.
+        '''
+
     def of_type(self, t_result: Type[TResult]) -> Enumerable[TResult]:
         '''
         Filters elements based on the specified type.