Skip to content

QList

Bases: list

QList is a python list extension that adds several chainable, lazy evaluated methods to the standard list.

Found in qwlist.QList

Source code in src\qwlist\qwlist.py
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
class QList(list):
    """
    `QList` is a python list extension that adds several chainable, lazy
    evaluated methods to the standard `list`.

    Found in `qwlist.QList`
    """

    @overload
    def __getitem__(self, item: slice) -> "QList[T]":
        ...

    @overload
    def __getitem__(self, item: int) -> T:
        ...

    def __getitem__(self, item):
        if isinstance(item, slice):
            return QList(super().__getitem__(item))
        return super().__getitem__(item)

    def get(self, index: int, default: Optional[T] = None) -> Optional[T]:
        """
        Safely gets the element on the specified index. If the index is out of bounds `default` is returned.

        Args:
            index (int): index of the element to take
            default (Optional[T]): value to return if the index is out of bounds. Defaults to `None`

        Returns:
            Element at the specified index or `default` if index is out of bounds.

        """
        if index < 0 or index >= self.len():
            return default
        return self[index]

    def iter(self) -> Iterator[T]:
        """
        Changes `self` into `Iterator[T]` by calling the `iter()` function.

        Returns:
            iterator over the elements of `self`.
        """
        return iter(self)

    def slice(self, s: slice) -> Lazy[T]:
        """
        Calling this method with `s` equal to `slice(3)` works similarly to
        `list[:3]` but is lazy evaluated.

        Args:
            s: slice object

        Returns:
            `Lazy[T]`
        """
        assert isinstance(s, slice), f"slice method argument must be a slice object. Got {type(s)}."

        def inner():
            for elem in self[s]:
                yield elem
        return Lazy(inner())

    def list(self) -> List[T]:
        """
        Changes `QList` into standard Python `list`.

        Returns:
            Standard Python `list`.
        """
        return list(self)

    def eager(self) -> "EagerQList[T]":
        """
        Changes `QList` into `EagerQList`.

        Returns:
            Eagerly evaluated version of `QList`.
        """
        from .eager import EagerQList
        return EagerQList(self)

    def filter(self, pred: Callable[[T], bool]) -> Lazy[T]:
        """
        Returns a `Lazy` object containing all values from `self` for which
        the predicate holds true.

        Args:
            pred: `function: (T) -> bool`

        Returns:
            New `Lazy[T]` with elements for which the predicate holds true.

        Examples:
            >>> QList([0, 1, 2, 3]).filter(lambda x: x < 2).collect()
            [0, 1]
        """
        def inner():
            for elem in self:
                if pred(elem):
                    yield elem
        return Lazy(inner())

    def map(self, mapper: Callable[[T], K]) -> Lazy[K]:
        """
        Returns a `Lazy` object containing all values from `self` with
        the mapping function applied on them.

        Args:
            mapper: `function: (T) -> K`

        Returns:
            New `Lazy[K]` with mapped elements from `self`.
        """
        def inner():
            for elem in self:
                yield mapper(elem)
        return Lazy(inner())

    def foreach(self, action: Callable[[T], None]):
        """
        Applies the given function to each of the `QList` elements.

        Args:
            action: `function: (T) -> None`

        Returns:
            `None`
        """
        for elem in self:
            action(elem)

    def fold(self, operation: Callable[[K, T], K], init: K) -> K:
        """
        Given the combination operator reduces `self` by processing
        its constituent parts, building up the final value.

        **Other names:** fold_left, reduce, accumulate, aggregate.

        Args:
            operation: `function: (K, T) -> K`. Given the initial value `init` applies the
                given combination operator on each element yielded by `self`,
                treating the result as the first argument in the next step.
            init (K): initial value for the combination operator.

        Returns:
            The final value created from calling the `operation` on consecutive elements of `self`.

        Examples:
            >>> QList([1, 2, 3]).fold(lambda acc, x: acc + x, 0)
            6
        """
        acc = init
        for elem in self:
            acc = operation(acc, elem)
        return acc

    def fold_right(self, operation: Callable[[K, T], K], init: K) -> K:
        """
        Given the combination operator reduces `self` by processing
        its constituent parts, building up the final value.

        Args:
            operation: `function: (K, T) -> K`
                Given the initial value `init` applies the
                given combination operator on each element of `self`, starting from the
                last element, treating the result as a first argument in the next step.
            init: initial value for the combination operator.

        Returns:
            The final value created from calling the `operation` on consecutive elements of `self`
             starting from the last element.

        Examples:
            >>> QList([1, 2, 3]).fold_right(lambda acc, x: acc + x, 0)
            6
        """
        acc = init
        for elem in self[::-1]:
            acc = operation(acc, elem)
        return acc

    def scan(self, operation: Callable[[K, T], K], state: K) -> "Lazy[K]":
        """
        Given the combination operator creates a `Lazy[K]` object by processing
        constituent parts of `self`, yielding intermediate steps and building up the final value.
        Scan is similar to fold but returns all intermediate states instead of just the final result.

        Args:
            operation: `function: (K, T) -> K`. Given the initial `state` applies the given
             combination operator on each element yielded by the `Lazy` object, yielding the result and
             then treating it as the first argument in the next step.
            state (K): initial value for the state.

        Returns:
            New `Lazy[K]` with all intermediate steps of the `operation`.

        Examples:
            >>> QList([1, 2, 3]).scan(lambda acc, x: acc + x, 0).collect()
            [1, 3, 6]
        """
        def inner(s):
            for elem in self:
                s = operation(s, elem)
                yield s
        return Lazy(inner(state))

    def len(self) -> int:
        """
        Returns the length of `self`.

        (time complexity: `O(1)`)

        Returns:
            Length of the `QList`
        """
        return len(self)

    def flatmap(self, mapper: Callable[[T], Iterable[K]]) -> Lazy[K]:
        """
        Applies the mapper function to each of the yielded elements and flattens the results.

        Args:
            mapper: `function: (T) -> Iterable[K]`.

        Returns:
            New `Lazy` with elements from `self` mapped to an iterable and then flattened.

        Examples:
            >>> QList([1, 2]).flatmap(lambda x: [x, x]).qlist()
            [1, 1, 2, 2]
        """
        def inner():
            for elem in self:
                yield from mapper(elem)
        return Lazy(inner())

    def zip(self, other: Iterable[K]) -> Lazy[tuple[T, K]]:
        """
        Combines `self` with the given `Iterable` elementwise as tuples.
         The returned `Lazy` objects yields at most the number of elements of
         the shorter sequence (`self` or `other`).

        Args:
            other (Iterable[K]): iterable to zip with `self`.

        Returns:
            New `Lazy` with pairs of elements from `self` and `other`.

        Examples:
            >>> Lazy([1, 2, 3]).zip(['a', 'b', 'c']).collect()
            [(1, 'a'), (2, 'b'), (3, 'c')]
        """
        return Lazy(zip(self, other))

    def sorted(self, key: Callable[[T], SupportsLessThan] = None, reverse: bool = False) -> "QList[T]":
        """
        Returns a new `QList` containing all items from the original list in ascending order.

        A custom key function can be supplied to customize the sort order, and the reverse
        flag can be set to request the result in descending order.

        Args:
            key (Callable[[T], SupportsLessThan]): `function: (T) -> SupportsLessThan`. Defaults to `None`.
            reverse (bool): if set to `True` sorts values in descending order. Defaults to `False`.

        Returns:
            Sorted `QList`.
        """
        return QList(sorted(self, key=key, reverse=reverse))

    def skip(self, n: int) -> Lazy[T]:
        """
        Skips `n` first elements of `self`.

        Args:
            n (int): numbers of elements to skip. Should be non-negative.

        Returns:
            New `Lazy` with `n` first elements of `self` skipped.

        Examples:
            >>> QList(range(10)).skip(2).collect()
            [2, 3, 4, 5, 6, 7, 8, 9]
        """
        def inner():
            for i, elem in enumerate(self):
                if i >= n:
                    yield elem
        return Lazy(inner())

    def take(self, n: int) -> Lazy[T]:
        """
        Takes `n` first elements of `self`.

        Args:
            n (int): numbers of elements to take. Should be non-negative.

        Returns:
            New `Lazy` with only `n` first elements from `self`.

        Examples:
            >>> QList(range(10)).take(2).collect()
            [0, 1]
        """
        def inner():
            for i, elem in enumerate(self):
                if i >= n:
                    return None
                yield elem
        return Lazy(inner())

    def flatten(self) -> Lazy[T]:
        """
        If `self` is a `QList` object of `Iterable[T]`, flatten concatenates all iterables into a
        single list and returns a `Lazy[T]` object.

        Returns:
            Concatenation of all elements from `self`.

        Raises:
            TypeError: when elements of Lazy are not iterables.

        Examples:
            >>> QList([[1, 2], [3, 4]]).flatten().collect()
            [1, 2, 3, 4]
        """
        def inner():
            for elem in self:
                if not isinstance(elem, Iterable):
                    type_name = type(elem).__name__
                    raise TypeError(f'could not flatten {self.__class__.__name__}[{type_name}] because {type_name} is not iterable.')
                yield from elem
        return Lazy(inner())

    def cycle(self) -> Lazy[T]:
        """
        Returns a `Lazy[T]` that cycles through the elements of `self`, which means
        on achieving the last element the iteration starts from the beginning. The
        returned `Lazy` object has no end (infinite iterator) unless `self` is empty
        in which case cycle returns an empty `Lazy` object (empty iterator).

        Returns:
            Infinite `Lazy` that loops through elements of `self`, or empty iterator if `self` is emtpy.

        Examples:
            >>> QList([1, 2, 3]).cycle().take(7).collect()
            [1, 2, 3, 1, 2, 3, 1]
        """
        def inner():
            saved = []
            for elem in self:
                saved.append(elem)
                yield elem
            while saved:
                for elem in saved:
                    yield elem
        return Lazy(inner())

    def enumerate(self, start: int = 0) -> Lazy[tuple[int, T]]:
        """
        Returns a `Lazy` object with index-value pairs as its elements. Index starts at
        the given position `start` (defaults to 0).

        Args:
            start (int): starting index. Defaults to 0.

        Returns:
            New `Lazy` with pairs of index and value.

        Examples:
            >>> QList(['a', 'b', 'c']).enumerate().collect()
            [(0, 'a'), (1, 'b'), (2, 'c')]
        """
        def inner():
            for i, elem in enumerate(self, start=start):
                yield i, elem
        return Lazy(inner())

    def batch(self, size: int) -> Lazy["QList[T]"]:
        """
        Groups elements into batches of given `size`. The last batch may have fewer elements.

        Args:
            size (int): size of one batch.

        Returns:
            New `Lazy` of batches (`QList`) of given `size`. Last batch may have fewer elements.

        Examples:
            >>> QList(range(5)).batch(2).collect()
            [[0, 1], [2, 3], [4]]
        """
        assert size > 0, f'batch size must be greater then 0 but got {size}'
        def inner():
            for i in range(0, self.len(), size):
                yield QList(self[i:i+size])
        return Lazy(inner())

    def batch_by(self, grouper: Callable[[T], SupportsEq]) -> "Lazy[QList[T]]":
        """
        Batches elements of `self` based on the output of the grouper function. Elements are thrown
        to the same group as long as the grouper function returns the same key (keys must support equality checks).
        When a new key is returned a new batch (group) is created.

        Args:
            grouper (Callable[[T], SupportsEq]): `function: (T) -> SupportsEq` that provides the keys
             used to group elements, where the key type must support equality comparisons.

        Returns:
            New `Lazy[QList[T]]` with elements batched based on the `grouper` key.

        Examples:
            >>> QList(['a1', 'b1', 'b2', 'a2', 'a3', 'b3']).batch_by(lambda s: s[0]).collect()
            [['a1'], ['b1', 'b2'], ['a2', 'a3'], ['b3']]
            >>> QList(['a1', 'b1', 'b2', 'a2', 'a3', 'b3']).batch_by(lambda s: s[1]).collect()
            [['a1', 'b1'], ['b2', 'a2'], ['a3', 'b3']]
        """
        def inner():
            if self.len() == 0:
                return
            batch = QList([self[0]])
            key = grouper(self[0])
            for elem in self[1:]:
                new_key = grouper(elem)
                if new_key == key:
                    batch.append(elem)
                else:
                    yield batch
                    batch = QList([elem])
                    key = new_key
            if batch:
                yield batch
        return Lazy(inner())

    def group_by(self, grouper: Callable[[T], Hashable]) -> Lazy["QList[T]"]:
        """
        Groups elements of `self` based on the output of the grouper function.
        Elements that produce the same key when passed to the grouper function are grouped together.
        The keys generated by the grouper function must be hashable,
        as they are used as dictionary keys to organize the groups.

        Args:
            grouper (Callable[[T], Hashable]): `function: (T) -> Hashable` that provides the keys
             used to group elements, where the key type must be hashable and be able to serve as a dict key.

        Returns:
            New `Lazy[QList[T]]` object containing `QList` instances, where each list
             represents a group of elements that share the same key.
        """
        def inner():
            groups = {}
            for elem in self:
                key = grouper(elem)
                if key not in groups:
                    groups[key] = QList()
                groups[key].append(elem)
            yield from (value for value in groups.values())
        return Lazy(inner())

    def chain(self, other: Iterable[T]) -> Lazy[T]:
        """
        Chains `self` with `other`, returning a new `Lazy[T]` with all elements from both iterables.

        Args:
            other (Iterable[T]):  an iterable of elements to be "attached" after `self` is exhausted.

        Returns:
            New `Lazy` with elements from `self` and `other`.

        Examples:
            >>> QList(range(0, 3)).chain(range(3, 6)).collect()
            [0, 1, 2, 3, 4, 5]
        """
        def inner():
            yield from self
            yield from other
        return Lazy(inner())

    def merge(self, other: Iterable[T], merger: Callable[[T, T], bool]) -> Lazy[T]:
        """
        Merges `self` with `other`, maintaining the order of elements based on the merger function. It starts by
         taking the first elements from `self` and `other`, calling the merger function with these elements as arguments.
         If the output is True, the first element is yielded; otherwise, the second element is yielded. If `self` is
         empty, the remaining elements from `other` are yielded, and vice versa.

        Args:
            other (Iterable[T]): an iterable to be merged with `self`.
            merger (Callable[[T, T], bool]): `function: (T, T) -> bool` that takes two arguments (left and right).
             If the output is True, the left argument is yielded; otherwise, the right argument is yielded.

        Returns:
            New `Lazy` containing the merged elements.

        Examples:
            >>> QList([1, 3, 5]).merge([2, 4, 6], lambda left, right: left < right).collect()
            [1, 2, 3, 4, 5, 6]
        """
        it1 = iter(self)
        it2 = iter(other)

        try:
            elem1 = next(it1)
        except StopIteration:
            return Lazy(it2)
        try:
            elem2 = next(it2)
        except StopIteration:
            return Lazy([elem1]).chain(it1)

        def inner():
            left = elem1
            right = elem2
            while True:
                if merger(left, right):
                    yield left
                    try:
                        left = next(it1)
                    except StopIteration:
                        yield right
                        yield from it2
                        return
                else:
                    yield right
                    try:
                        right = next(it2)
                    except StopIteration:
                        yield left
                        yield from it1
                        return
        return Lazy(inner())

    def all(self, mapper: Optional[Callable[[T], Booly]] = None) -> bool:
        """
        Goes through the entire generator and checks if all elements are `Truthy`.
        `Booly` is a type that evaluates to something that is either `True` (`Truthy`) or `False` (`Falsy`).
        For example in Python an empty list evaluates to `False` (empty list is `Falsy`).

        Args:
            mapper (Optional[Callable[[T], Booly]]): `function: (T) -> Booly` that maps `T` to `Booly` which is a type that
             can be interpreted as either True or False. If not passed, identity function is used.

        Returns:
            `True` if all elements of `self` are `Truthy`. `False` otherwise.
        """
        def identity(x):
            return x
        mapper = identity if mapper is None else mapper
        for elem in self:
            if not mapper(elem):
                return False
        return True

    def any(self, mapper: Optional[Callable[[T], Booly]] = None) -> bool:
        """
        Goes through the entire generator and checks if any element is `Truthy`.
        `Booly` is a type that evaluates to something that is either `True` (`Truthy`) or `False` (`Falsy`).
        For example in Python an empty list evaluates to `False` (empty list is `Falsy`).

        Args:
            mapper (Optional[Callable[[T], Booly]]): `function: (T) -> Booly` that maps `T` to `Booly` which is a type that
             can be interpreted as either True or False. If not passed, identity function is used.

        Returns:
            `True` if there is at least one element in `self` that is `Truthy`. `False` otherwise.
        """
        def identity(x):
            return x

        mapper = identity if mapper is None else mapper
        for elem in self:
            if mapper(elem):
                return True
        return False

    def min(self, key: Optional[Callable[[T], SupportsLessThan]] = None) -> Optional[T]:
        """
        Returns the smallest element from `self`. If the key function is not passed, identity
        function is used in which case `T` must support `LessThan` operator.

        Args:
            key (Optional[Callable[[T], SupportsLessThan]): `function: (T) -> SupportsLessThan` that represents
             the relation of partial order between elements.

        Returns:
            The smallest element from `self` or `None` if `self` is empty.
        """
        def identity(x):
            return x
        key = identity if key is None else key

        if self.len() == 0:
            return None
        best = self[0]
        for elem in self[1:]:
            if key(elem) < key(best):
                best = elem
        return best

    def max(self, key: Optional[Callable[[T], SupportsLessThan]] = None) -> Optional[T]:
        """
        Returns the biggest element from `self`. If the key function is not passed, identity
        function is used in which case `T` must support `LessThan` operator.

        Args:
            key (Optional[Callable[[T], SupportsLessThan]): `function: (T) -> SupportsLessThan` that represents
             the relation of partial order between elements.

        Returns:
            the biggest element from `self` or `None` if `self` is empty.
        """

        def identity(x):
            return x
        key = identity if key is None else key

        if self.len() == 0:
            return None
        best = self[0]
        for elem in self[1:]:
            if key(best) < key(elem):
                best = elem
        return best

    def full_flatten(self, break_str: bool = True, preserve_type: Optional[Type] = None) -> Lazy[T]:
        """
        When `self` is an iterable of nested iterables, all the iterables are flattened to a single iterable.
        Recursive type annotation of `self` may be imagined to look like this: `QList[T | Iterable[T | Iterable[T | ...]]].`


        Args:
            break_str (bool): If `True`, strings are flattened into individual characters. Defaults to `True`.
            preserve_type (Optional[Type]): Type to exclude from flattening (i.e., treated as non-iterable). For example,
             setting this to `str` makes `break_str` effectively `False`. Defaults to `None`.

        Returns:
            New `Lazy` with all nested iterables flattened to a single iterable.

        Examples:
            >>> QList(['abc', ['def', 'ghi']]).full_flatten().collect()
            ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i']

            >>> QList(['abc', ['def', 'ghi']]).full_flatten(break_str=False).collect()
            ['abc', 'def', 'ghi']

            >>> QList(['abc', ['def', 'ghi']]).full_flatten(preserve_type=list).collect()
            ['a', 'b', 'c', ['def', 'ghi']]
        """

        def inner():
            for elem in self:
                if preserve_type is not None and isinstance(elem, preserve_type):
                    yield elem
                elif isinstance(elem, str):
                    if break_str:
                        if len(elem) == 1:
                            yield elem
                        else:
                            yield from Lazy(elem).full_flatten(break_str=break_str, preserve_type=preserve_type)
                    else:
                        yield elem
                elif isinstance(elem, Iterable):
                    yield from Lazy(elem).full_flatten(break_str=break_str, preserve_type=preserve_type)
                else:
                    yield elem
        return Lazy(inner())

    def take_while(self, pred: Callable[[T], bool]) -> "Lazy[T]":
        """
        Creates a `Lazy` that yields elements based on a predicate. Takes a function as an argument.
        It will call this function on each element of `self`, and yield elements while the function
        returns `True`. After `False` is returned, iteration stops, and the rest of the elements is ignored.

        Args:
            pred (Callable[[T], bool]): `function: (T) -> bool`

        Returns:
            New `Lazy` containing elements from the original sequence, stopping at the first element for which the
             predicate returns `False`.
        """
        def inner():
            for elem in self:
                if not pred(elem):
                    return
                yield elem
        return Lazy(inner())

    def sum(self) -> Optional[SupportsAdd]:
        """
        Sums all the elements and returns the sum. Returns `None` if `self` is empty.
        Elements of `self` must support addition.

        Returns:
            The sum of all elements of `self`.
        """
        it = self.iter()
        acc = None
        try:
            acc = next(it)
        except StopIteration:
            return acc
        for elem in it:
            acc = acc + elem
        return acc

    def window(self, window_size: int) -> "Lazy[QList[T]]":
        """
        Creates a `Lazy` of sliding windows of size `window_size`. If `window_size`
        is greater than the total length of `self` an empty iterator is returned.

        Args:
            window_size (int): the size of the sliding window. Must be greater than 0.

        Returns:
            New `Lazy` of all sliding windows.
        """
        assert window_size > 0, f'window size must be greater than 0 but got {window_size}.'
        def inner(n: int):
            if self.len() < n:
                return
            if self.len() == n:
                yield self
                return
            window = deque(maxlen=n)
            for elem in self[:n]:
                window.append(elem)
            yield QList(window)
            for elem in self[n:]:
                window.append(elem)
                yield QList(window)
        return Lazy(inner(n=window_size))

    def flat_fold(self, combination: Callable[[K, T], Iterable[K]], init: K) -> Lazy[K]:
        """
        This method reduces `self` by repeatedly applying a `combination` function
        to each element and an accumulated intermediate result. The `combination` function
        returns a sequence of intermediate results (flattened before the next iteration),
        which are used as inputs for subsequent steps.

        **Other names:** foldM, monadic_fold.

        Args:
            combination (Callable[[K, T], Iterable[K]]): `function (K, T) -> Iterable[K]` that takes the
             current accumulated value and the next element of the collection, and returns a list
             of intermediate results. In the first step, `init` and the first element of the collection
             are passed to the `combination`. In subsequent steps, each intermediate result from the previous
             step is paired with the next element of the collection until it is fully processed.
            init (K): initial value for the combination operator.

        Returns:
            Lazy[K]: The final value obtained by repeatedly applying `combination` across all elements
             of the collection, with intermediate results flattened at each step.

        Examples:
            In this example the resulting list is a list of all possible scores achieved
            either by suming or multiplying the numbers. For example one of the elements would
            be a sum of all elements, another element would be the product of all elements,
            another will be a combination of the two operations and so on. If the initial list
            has *n* elements and the result of the combination operator is a list of 2 elements
            the total length of the resulting sequence would be of length 2^n.

            >>> QList([2, 3]).flat_fold(lambda acc, x: [acc + x, acc * x], 1).collect()
            [6, 9, 5, 6]

            Mapping to a list with a single element works the same way as standard fold would work
            and the resulting value would be a `Lazy` object with only one element:
            >>> QList([2, 3]).flat_fold(lambda acc, x: [acc + x], 1).collect()
            [6]
            >>> QList([2, 3]).fold(lambda acc, x: acc + x, 1)
            6
        """
        acc = QList([init])
        for elem in self:
            acc = acc.flatmap(lambda x, e=elem: combination(x, e))
        return acc

    def product(self, other: Iterable[K]) -> Lazy[Tuple[T, K]]:
        """
        Computes the Cartesian product of `self` and `other`.

        Args:
            other (Iterable[K]): iterable to make the cartesian product with.

        Returns:
            A new Lazy of pairs from Cartesian product.
        """
        def inner():
            for t in self:
                for k in other:
                    yield t, k
        return Lazy(inner())

    def product_with(self, other: Iterable[K], operation: Callable[[T, K], R]) -> Lazy[R]:
        """
        Applies a given operation to every pair of elements from the Cartesian product
        of `self` and `other`, returning a new Lazy iterable of the results.
        This method "lifts" the provided `operation` from working on individual elements
        to working on pairs of elements produced from the Cartesian product. It is equivalent
        to calling `self.product(other).map(lambda pair: operation(*pair))`.

        Args:
            other (Iterable[T]): The iterable to combine with `self` in a Cartesian product.
            operation (Callable[[T, K], R]): `function: (T, K) -> R` that takes a pair of elements,
             one from `self` and one from `other`, and returns a result of type `R`.

        Returns:
            A new Lazy containing the results of applying `operation`
            to each pair in the Cartesian product.

        Examples:
            >>> qlist1 = QList([1, 2])
            >>> qlist2 = QList(['a', 'b'])
            >>> qlist1.product_with(qlist2, lambda x, y: f"{x}{y}").collect()
            ['1a', '1b', '2a', '2b']
        """
        def inner():
            for t in self:
                for k in other:
                    yield operation(t, k)
        return Lazy(inner())

    def zip_with(self, other: Iterable[K], operation: Callable[[T, K], R]) -> Lazy[R]:
        """
        Applies a given `operation` to pairs of elements from `self` and `other`, created by zipping them together.

        This method "lifts" the provided `operation` from working on individual elements
        to working on pairs of elements formed by zipping the two iterables. It is equivalent
        to calling `self.zip(other).map(lambda pair: operation(*pair))`.

        Args:
            other (Iterable[K]): The iterable to zip with `self`.
            operation (Callable[[T, K], R]): `function: (T, K) -> R` that takes a pair of elements,
            one from `self` and one from `other`, and returns a result of type `R`.

        Returns:
            Lazy[R]: A new Lazy containing the results of applying `operation`
            to each pair in the zipped iterables.

        Examples:
            >>> qlist1 = QList([1, 2, 3])
            >>> qlist2 = QList(['a', 'b'])
            >>> qlist1.zip_with(qlist2, lambda x, y: f"{x}{y}").collect()
            ['1a', '2b']
        """
        def inner():
            for t, k in self.zip(other):
                yield operation(t, k)
        return Lazy(inner())

all(mapper=None)

Goes through the entire generator and checks if all elements are Truthy. Booly is a type that evaluates to something that is either True (Truthy) or False (Falsy). For example in Python an empty list evaluates to False (empty list is Falsy).

Parameters:

Name Type Description Default
mapper Optional[Callable[[T], Booly]]

function: (T) -> Booly that maps T to Booly which is a type that can be interpreted as either True or False. If not passed, identity function is used.

None

Returns:

Type Description
bool

True if all elements of self are Truthy. False otherwise.

Source code in src\qwlist\qwlist.py
def all(self, mapper: Optional[Callable[[T], Booly]] = None) -> bool:
    """
    Goes through the entire generator and checks if all elements are `Truthy`.
    `Booly` is a type that evaluates to something that is either `True` (`Truthy`) or `False` (`Falsy`).
    For example in Python an empty list evaluates to `False` (empty list is `Falsy`).

    Args:
        mapper (Optional[Callable[[T], Booly]]): `function: (T) -> Booly` that maps `T` to `Booly` which is a type that
         can be interpreted as either True or False. If not passed, identity function is used.

    Returns:
        `True` if all elements of `self` are `Truthy`. `False` otherwise.
    """
    def identity(x):
        return x
    mapper = identity if mapper is None else mapper
    for elem in self:
        if not mapper(elem):
            return False
    return True

any(mapper=None)

Goes through the entire generator and checks if any element is Truthy. Booly is a type that evaluates to something that is either True (Truthy) or False (Falsy). For example in Python an empty list evaluates to False (empty list is Falsy).

Parameters:

Name Type Description Default
mapper Optional[Callable[[T], Booly]]

function: (T) -> Booly that maps T to Booly which is a type that can be interpreted as either True or False. If not passed, identity function is used.

None

Returns:

Type Description
bool

True if there is at least one element in self that is Truthy. False otherwise.

Source code in src\qwlist\qwlist.py
def any(self, mapper: Optional[Callable[[T], Booly]] = None) -> bool:
    """
    Goes through the entire generator and checks if any element is `Truthy`.
    `Booly` is a type that evaluates to something that is either `True` (`Truthy`) or `False` (`Falsy`).
    For example in Python an empty list evaluates to `False` (empty list is `Falsy`).

    Args:
        mapper (Optional[Callable[[T], Booly]]): `function: (T) -> Booly` that maps `T` to `Booly` which is a type that
         can be interpreted as either True or False. If not passed, identity function is used.

    Returns:
        `True` if there is at least one element in `self` that is `Truthy`. `False` otherwise.
    """
    def identity(x):
        return x

    mapper = identity if mapper is None else mapper
    for elem in self:
        if mapper(elem):
            return True
    return False

batch(size)

Groups elements into batches of given size. The last batch may have fewer elements.

Parameters:

Name Type Description Default
size int

size of one batch.

required

Returns:

Type Description
Lazy[QList[T]]

New Lazy of batches (QList) of given size. Last batch may have fewer elements.

Examples:

>>> QList(range(5)).batch(2).collect()
[[0, 1], [2, 3], [4]]
Source code in src\qwlist\qwlist.py
def batch(self, size: int) -> Lazy["QList[T]"]:
    """
    Groups elements into batches of given `size`. The last batch may have fewer elements.

    Args:
        size (int): size of one batch.

    Returns:
        New `Lazy` of batches (`QList`) of given `size`. Last batch may have fewer elements.

    Examples:
        >>> QList(range(5)).batch(2).collect()
        [[0, 1], [2, 3], [4]]
    """
    assert size > 0, f'batch size must be greater then 0 but got {size}'
    def inner():
        for i in range(0, self.len(), size):
            yield QList(self[i:i+size])
    return Lazy(inner())

batch_by(grouper)

Batches elements of self based on the output of the grouper function. Elements are thrown to the same group as long as the grouper function returns the same key (keys must support equality checks). When a new key is returned a new batch (group) is created.

Parameters:

Name Type Description Default
grouper Callable[[T], SupportsEq]

function: (T) -> SupportsEq that provides the keys used to group elements, where the key type must support equality comparisons.

required

Returns:

Type Description
Lazy[QList[T]]

New Lazy[QList[T]] with elements batched based on the grouper key.

Examples:

>>> QList(['a1', 'b1', 'b2', 'a2', 'a3', 'b3']).batch_by(lambda s: s[0]).collect()
[['a1'], ['b1', 'b2'], ['a2', 'a3'], ['b3']]
>>> QList(['a1', 'b1', 'b2', 'a2', 'a3', 'b3']).batch_by(lambda s: s[1]).collect()
[['a1', 'b1'], ['b2', 'a2'], ['a3', 'b3']]
Source code in src\qwlist\qwlist.py
def batch_by(self, grouper: Callable[[T], SupportsEq]) -> "Lazy[QList[T]]":
    """
    Batches elements of `self` based on the output of the grouper function. Elements are thrown
    to the same group as long as the grouper function returns the same key (keys must support equality checks).
    When a new key is returned a new batch (group) is created.

    Args:
        grouper (Callable[[T], SupportsEq]): `function: (T) -> SupportsEq` that provides the keys
         used to group elements, where the key type must support equality comparisons.

    Returns:
        New `Lazy[QList[T]]` with elements batched based on the `grouper` key.

    Examples:
        >>> QList(['a1', 'b1', 'b2', 'a2', 'a3', 'b3']).batch_by(lambda s: s[0]).collect()
        [['a1'], ['b1', 'b2'], ['a2', 'a3'], ['b3']]
        >>> QList(['a1', 'b1', 'b2', 'a2', 'a3', 'b3']).batch_by(lambda s: s[1]).collect()
        [['a1', 'b1'], ['b2', 'a2'], ['a3', 'b3']]
    """
    def inner():
        if self.len() == 0:
            return
        batch = QList([self[0]])
        key = grouper(self[0])
        for elem in self[1:]:
            new_key = grouper(elem)
            if new_key == key:
                batch.append(elem)
            else:
                yield batch
                batch = QList([elem])
                key = new_key
        if batch:
            yield batch
    return Lazy(inner())

chain(other)

Chains self with other, returning a new Lazy[T] with all elements from both iterables.

Parameters:

Name Type Description Default
other Iterable[T]

an iterable of elements to be "attached" after self is exhausted.

required

Returns:

Type Description
Lazy[T]

New Lazy with elements from self and other.

Examples:

>>> QList(range(0, 3)).chain(range(3, 6)).collect()
[0, 1, 2, 3, 4, 5]
Source code in src\qwlist\qwlist.py
def chain(self, other: Iterable[T]) -> Lazy[T]:
    """
    Chains `self` with `other`, returning a new `Lazy[T]` with all elements from both iterables.

    Args:
        other (Iterable[T]):  an iterable of elements to be "attached" after `self` is exhausted.

    Returns:
        New `Lazy` with elements from `self` and `other`.

    Examples:
        >>> QList(range(0, 3)).chain(range(3, 6)).collect()
        [0, 1, 2, 3, 4, 5]
    """
    def inner():
        yield from self
        yield from other
    return Lazy(inner())

cycle()

Returns a Lazy[T] that cycles through the elements of self, which means on achieving the last element the iteration starts from the beginning. The returned Lazy object has no end (infinite iterator) unless self is empty in which case cycle returns an empty Lazy object (empty iterator).

Returns:

Type Description
Lazy[T]

Infinite Lazy that loops through elements of self, or empty iterator if self is emtpy.

Examples:

>>> QList([1, 2, 3]).cycle().take(7).collect()
[1, 2, 3, 1, 2, 3, 1]
Source code in src\qwlist\qwlist.py
def cycle(self) -> Lazy[T]:
    """
    Returns a `Lazy[T]` that cycles through the elements of `self`, which means
    on achieving the last element the iteration starts from the beginning. The
    returned `Lazy` object has no end (infinite iterator) unless `self` is empty
    in which case cycle returns an empty `Lazy` object (empty iterator).

    Returns:
        Infinite `Lazy` that loops through elements of `self`, or empty iterator if `self` is emtpy.

    Examples:
        >>> QList([1, 2, 3]).cycle().take(7).collect()
        [1, 2, 3, 1, 2, 3, 1]
    """
    def inner():
        saved = []
        for elem in self:
            saved.append(elem)
            yield elem
        while saved:
            for elem in saved:
                yield elem
    return Lazy(inner())

eager()

Changes QList into EagerQList.

Returns:

Type Description
EagerQList[T]

Eagerly evaluated version of QList.

Source code in src\qwlist\qwlist.py
def eager(self) -> "EagerQList[T]":
    """
    Changes `QList` into `EagerQList`.

    Returns:
        Eagerly evaluated version of `QList`.
    """
    from .eager import EagerQList
    return EagerQList(self)

enumerate(start=0)

Returns a Lazy object with index-value pairs as its elements. Index starts at the given position start (defaults to 0).

Parameters:

Name Type Description Default
start int

starting index. Defaults to 0.

0

Returns:

Type Description
Lazy[tuple[int, T]]

New Lazy with pairs of index and value.

Examples:

>>> QList(['a', 'b', 'c']).enumerate().collect()
[(0, 'a'), (1, 'b'), (2, 'c')]
Source code in src\qwlist\qwlist.py
def enumerate(self, start: int = 0) -> Lazy[tuple[int, T]]:
    """
    Returns a `Lazy` object with index-value pairs as its elements. Index starts at
    the given position `start` (defaults to 0).

    Args:
        start (int): starting index. Defaults to 0.

    Returns:
        New `Lazy` with pairs of index and value.

    Examples:
        >>> QList(['a', 'b', 'c']).enumerate().collect()
        [(0, 'a'), (1, 'b'), (2, 'c')]
    """
    def inner():
        for i, elem in enumerate(self, start=start):
            yield i, elem
    return Lazy(inner())

filter(pred)

Returns a Lazy object containing all values from self for which the predicate holds true.

Parameters:

Name Type Description Default
pred Callable[[T], bool]

function: (T) -> bool

required

Returns:

Type Description
Lazy[T]

New Lazy[T] with elements for which the predicate holds true.

Examples:

>>> QList([0, 1, 2, 3]).filter(lambda x: x < 2).collect()
[0, 1]
Source code in src\qwlist\qwlist.py
def filter(self, pred: Callable[[T], bool]) -> Lazy[T]:
    """
    Returns a `Lazy` object containing all values from `self` for which
    the predicate holds true.

    Args:
        pred: `function: (T) -> bool`

    Returns:
        New `Lazy[T]` with elements for which the predicate holds true.

    Examples:
        >>> QList([0, 1, 2, 3]).filter(lambda x: x < 2).collect()
        [0, 1]
    """
    def inner():
        for elem in self:
            if pred(elem):
                yield elem
    return Lazy(inner())

flat_fold(combination, init)

This method reduces self by repeatedly applying a combination function to each element and an accumulated intermediate result. The combination function returns a sequence of intermediate results (flattened before the next iteration), which are used as inputs for subsequent steps.

Other names: foldM, monadic_fold.

Parameters:

Name Type Description Default
combination Callable[[K, T], Iterable[K]]

function (K, T) -> Iterable[K] that takes the current accumulated value and the next element of the collection, and returns a list of intermediate results. In the first step, init and the first element of the collection are passed to the combination. In subsequent steps, each intermediate result from the previous step is paired with the next element of the collection until it is fully processed.

required
init K

initial value for the combination operator.

required

Returns:

Type Description
Lazy[K]

Lazy[K]: The final value obtained by repeatedly applying combination across all elements of the collection, with intermediate results flattened at each step.

Examples:

In this example the resulting list is a list of all possible scores achieved either by suming or multiplying the numbers. For example one of the elements would be a sum of all elements, another element would be the product of all elements, another will be a combination of the two operations and so on. If the initial list has n elements and the result of the combination operator is a list of 2 elements the total length of the resulting sequence would be of length 2^n.

>>> QList([2, 3]).flat_fold(lambda acc, x: [acc + x, acc * x], 1).collect()
[6, 9, 5, 6]

Mapping to a list with a single element works the same way as standard fold would work and the resulting value would be a Lazy object with only one element:

>>> QList([2, 3]).flat_fold(lambda acc, x: [acc + x], 1).collect()
[6]
>>> QList([2, 3]).fold(lambda acc, x: acc + x, 1)
6
Source code in src\qwlist\qwlist.py
def flat_fold(self, combination: Callable[[K, T], Iterable[K]], init: K) -> Lazy[K]:
    """
    This method reduces `self` by repeatedly applying a `combination` function
    to each element and an accumulated intermediate result. The `combination` function
    returns a sequence of intermediate results (flattened before the next iteration),
    which are used as inputs for subsequent steps.

    **Other names:** foldM, monadic_fold.

    Args:
        combination (Callable[[K, T], Iterable[K]]): `function (K, T) -> Iterable[K]` that takes the
         current accumulated value and the next element of the collection, and returns a list
         of intermediate results. In the first step, `init` and the first element of the collection
         are passed to the `combination`. In subsequent steps, each intermediate result from the previous
         step is paired with the next element of the collection until it is fully processed.
        init (K): initial value for the combination operator.

    Returns:
        Lazy[K]: The final value obtained by repeatedly applying `combination` across all elements
         of the collection, with intermediate results flattened at each step.

    Examples:
        In this example the resulting list is a list of all possible scores achieved
        either by suming or multiplying the numbers. For example one of the elements would
        be a sum of all elements, another element would be the product of all elements,
        another will be a combination of the two operations and so on. If the initial list
        has *n* elements and the result of the combination operator is a list of 2 elements
        the total length of the resulting sequence would be of length 2^n.

        >>> QList([2, 3]).flat_fold(lambda acc, x: [acc + x, acc * x], 1).collect()
        [6, 9, 5, 6]

        Mapping to a list with a single element works the same way as standard fold would work
        and the resulting value would be a `Lazy` object with only one element:
        >>> QList([2, 3]).flat_fold(lambda acc, x: [acc + x], 1).collect()
        [6]
        >>> QList([2, 3]).fold(lambda acc, x: acc + x, 1)
        6
    """
    acc = QList([init])
    for elem in self:
        acc = acc.flatmap(lambda x, e=elem: combination(x, e))
    return acc

flatmap(mapper)

Applies the mapper function to each of the yielded elements and flattens the results.

Parameters:

Name Type Description Default
mapper Callable[[T], Iterable[K]]

function: (T) -> Iterable[K].

required

Returns:

Type Description
Lazy[K]

New Lazy with elements from self mapped to an iterable and then flattened.

Examples:

>>> QList([1, 2]).flatmap(lambda x: [x, x]).qlist()
[1, 1, 2, 2]
Source code in src\qwlist\qwlist.py
def flatmap(self, mapper: Callable[[T], Iterable[K]]) -> Lazy[K]:
    """
    Applies the mapper function to each of the yielded elements and flattens the results.

    Args:
        mapper: `function: (T) -> Iterable[K]`.

    Returns:
        New `Lazy` with elements from `self` mapped to an iterable and then flattened.

    Examples:
        >>> QList([1, 2]).flatmap(lambda x: [x, x]).qlist()
        [1, 1, 2, 2]
    """
    def inner():
        for elem in self:
            yield from mapper(elem)
    return Lazy(inner())

flatten()

If self is a QList object of Iterable[T], flatten concatenates all iterables into a single list and returns a Lazy[T] object.

Returns:

Type Description
Lazy[T]

Concatenation of all elements from self.

Raises:

Type Description
TypeError

when elements of Lazy are not iterables.

Examples:

>>> QList([[1, 2], [3, 4]]).flatten().collect()
[1, 2, 3, 4]
Source code in src\qwlist\qwlist.py
def flatten(self) -> Lazy[T]:
    """
    If `self` is a `QList` object of `Iterable[T]`, flatten concatenates all iterables into a
    single list and returns a `Lazy[T]` object.

    Returns:
        Concatenation of all elements from `self`.

    Raises:
        TypeError: when elements of Lazy are not iterables.

    Examples:
        >>> QList([[1, 2], [3, 4]]).flatten().collect()
        [1, 2, 3, 4]
    """
    def inner():
        for elem in self:
            if not isinstance(elem, Iterable):
                type_name = type(elem).__name__
                raise TypeError(f'could not flatten {self.__class__.__name__}[{type_name}] because {type_name} is not iterable.')
            yield from elem
    return Lazy(inner())

fold(operation, init)

Given the combination operator reduces self by processing its constituent parts, building up the final value.

Other names: fold_left, reduce, accumulate, aggregate.

Parameters:

Name Type Description Default
operation Callable[[K, T], K]

function: (K, T) -> K. Given the initial value init applies the given combination operator on each element yielded by self, treating the result as the first argument in the next step.

required
init K

initial value for the combination operator.

required

Returns:

Type Description
K

The final value created from calling the operation on consecutive elements of self.

Examples:

>>> QList([1, 2, 3]).fold(lambda acc, x: acc + x, 0)
6
Source code in src\qwlist\qwlist.py
def fold(self, operation: Callable[[K, T], K], init: K) -> K:
    """
    Given the combination operator reduces `self` by processing
    its constituent parts, building up the final value.

    **Other names:** fold_left, reduce, accumulate, aggregate.

    Args:
        operation: `function: (K, T) -> K`. Given the initial value `init` applies the
            given combination operator on each element yielded by `self`,
            treating the result as the first argument in the next step.
        init (K): initial value for the combination operator.

    Returns:
        The final value created from calling the `operation` on consecutive elements of `self`.

    Examples:
        >>> QList([1, 2, 3]).fold(lambda acc, x: acc + x, 0)
        6
    """
    acc = init
    for elem in self:
        acc = operation(acc, elem)
    return acc

fold_right(operation, init)

Given the combination operator reduces self by processing its constituent parts, building up the final value.

Parameters:

Name Type Description Default
operation Callable[[K, T], K]

function: (K, T) -> K Given the initial value init applies the given combination operator on each element of self, starting from the last element, treating the result as a first argument in the next step.

required
init K

initial value for the combination operator.

required

Returns:

Type Description
K

The final value created from calling the operation on consecutive elements of self starting from the last element.

Examples:

>>> QList([1, 2, 3]).fold_right(lambda acc, x: acc + x, 0)
6
Source code in src\qwlist\qwlist.py
def fold_right(self, operation: Callable[[K, T], K], init: K) -> K:
    """
    Given the combination operator reduces `self` by processing
    its constituent parts, building up the final value.

    Args:
        operation: `function: (K, T) -> K`
            Given the initial value `init` applies the
            given combination operator on each element of `self`, starting from the
            last element, treating the result as a first argument in the next step.
        init: initial value for the combination operator.

    Returns:
        The final value created from calling the `operation` on consecutive elements of `self`
         starting from the last element.

    Examples:
        >>> QList([1, 2, 3]).fold_right(lambda acc, x: acc + x, 0)
        6
    """
    acc = init
    for elem in self[::-1]:
        acc = operation(acc, elem)
    return acc

foreach(action)

Applies the given function to each of the QList elements.

Parameters:

Name Type Description Default
action Callable[[T], None]

function: (T) -> None

required

Returns:

Type Description

None

Source code in src\qwlist\qwlist.py
def foreach(self, action: Callable[[T], None]):
    """
    Applies the given function to each of the `QList` elements.

    Args:
        action: `function: (T) -> None`

    Returns:
        `None`
    """
    for elem in self:
        action(elem)

full_flatten(break_str=True, preserve_type=None)

When self is an iterable of nested iterables, all the iterables are flattened to a single iterable. Recursive type annotation of self may be imagined to look like this: QList[T | Iterable[T | Iterable[T | ...]]].

Parameters:

Name Type Description Default
break_str bool

If True, strings are flattened into individual characters. Defaults to True.

True
preserve_type Optional[Type]

Type to exclude from flattening (i.e., treated as non-iterable). For example, setting this to str makes break_str effectively False. Defaults to None.

None

Returns:

Type Description
Lazy[T]

New Lazy with all nested iterables flattened to a single iterable.

Examples:

>>> QList(['abc', ['def', 'ghi']]).full_flatten().collect()
['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i']
>>> QList(['abc', ['def', 'ghi']]).full_flatten(break_str=False).collect()
['abc', 'def', 'ghi']
>>> QList(['abc', ['def', 'ghi']]).full_flatten(preserve_type=list).collect()
['a', 'b', 'c', ['def', 'ghi']]
Source code in src\qwlist\qwlist.py
def full_flatten(self, break_str: bool = True, preserve_type: Optional[Type] = None) -> Lazy[T]:
    """
    When `self` is an iterable of nested iterables, all the iterables are flattened to a single iterable.
    Recursive type annotation of `self` may be imagined to look like this: `QList[T | Iterable[T | Iterable[T | ...]]].`


    Args:
        break_str (bool): If `True`, strings are flattened into individual characters. Defaults to `True`.
        preserve_type (Optional[Type]): Type to exclude from flattening (i.e., treated as non-iterable). For example,
         setting this to `str` makes `break_str` effectively `False`. Defaults to `None`.

    Returns:
        New `Lazy` with all nested iterables flattened to a single iterable.

    Examples:
        >>> QList(['abc', ['def', 'ghi']]).full_flatten().collect()
        ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i']

        >>> QList(['abc', ['def', 'ghi']]).full_flatten(break_str=False).collect()
        ['abc', 'def', 'ghi']

        >>> QList(['abc', ['def', 'ghi']]).full_flatten(preserve_type=list).collect()
        ['a', 'b', 'c', ['def', 'ghi']]
    """

    def inner():
        for elem in self:
            if preserve_type is not None and isinstance(elem, preserve_type):
                yield elem
            elif isinstance(elem, str):
                if break_str:
                    if len(elem) == 1:
                        yield elem
                    else:
                        yield from Lazy(elem).full_flatten(break_str=break_str, preserve_type=preserve_type)
                else:
                    yield elem
            elif isinstance(elem, Iterable):
                yield from Lazy(elem).full_flatten(break_str=break_str, preserve_type=preserve_type)
            else:
                yield elem
    return Lazy(inner())

get(index, default=None)

Safely gets the element on the specified index. If the index is out of bounds default is returned.

Parameters:

Name Type Description Default
index int

index of the element to take

required
default Optional[T]

value to return if the index is out of bounds. Defaults to None

None

Returns:

Type Description
Optional[T]

Element at the specified index or default if index is out of bounds.

Source code in src\qwlist\qwlist.py
def get(self, index: int, default: Optional[T] = None) -> Optional[T]:
    """
    Safely gets the element on the specified index. If the index is out of bounds `default` is returned.

    Args:
        index (int): index of the element to take
        default (Optional[T]): value to return if the index is out of bounds. Defaults to `None`

    Returns:
        Element at the specified index or `default` if index is out of bounds.

    """
    if index < 0 or index >= self.len():
        return default
    return self[index]

group_by(grouper)

Groups elements of self based on the output of the grouper function. Elements that produce the same key when passed to the grouper function are grouped together. The keys generated by the grouper function must be hashable, as they are used as dictionary keys to organize the groups.

Parameters:

Name Type Description Default
grouper Callable[[T], Hashable]

function: (T) -> Hashable that provides the keys used to group elements, where the key type must be hashable and be able to serve as a dict key.

required

Returns:

Type Description
Lazy[QList[T]]

New Lazy[QList[T]] object containing QList instances, where each list represents a group of elements that share the same key.

Source code in src\qwlist\qwlist.py
def group_by(self, grouper: Callable[[T], Hashable]) -> Lazy["QList[T]"]:
    """
    Groups elements of `self` based on the output of the grouper function.
    Elements that produce the same key when passed to the grouper function are grouped together.
    The keys generated by the grouper function must be hashable,
    as they are used as dictionary keys to organize the groups.

    Args:
        grouper (Callable[[T], Hashable]): `function: (T) -> Hashable` that provides the keys
         used to group elements, where the key type must be hashable and be able to serve as a dict key.

    Returns:
        New `Lazy[QList[T]]` object containing `QList` instances, where each list
         represents a group of elements that share the same key.
    """
    def inner():
        groups = {}
        for elem in self:
            key = grouper(elem)
            if key not in groups:
                groups[key] = QList()
            groups[key].append(elem)
        yield from (value for value in groups.values())
    return Lazy(inner())

iter()

Changes self into Iterator[T] by calling the iter() function.

Returns:

Type Description
Iterator[T]

iterator over the elements of self.

Source code in src\qwlist\qwlist.py
def iter(self) -> Iterator[T]:
    """
    Changes `self` into `Iterator[T]` by calling the `iter()` function.

    Returns:
        iterator over the elements of `self`.
    """
    return iter(self)

len()

Returns the length of self.

(time complexity: O(1))

Returns:

Type Description
int

Length of the QList

Source code in src\qwlist\qwlist.py
def len(self) -> int:
    """
    Returns the length of `self`.

    (time complexity: `O(1)`)

    Returns:
        Length of the `QList`
    """
    return len(self)

list()

Changes QList into standard Python list.

Returns:

Type Description
List[T]

Standard Python list.

Source code in src\qwlist\qwlist.py
def list(self) -> List[T]:
    """
    Changes `QList` into standard Python `list`.

    Returns:
        Standard Python `list`.
    """
    return list(self)

map(mapper)

Returns a Lazy object containing all values from self with the mapping function applied on them.

Parameters:

Name Type Description Default
mapper Callable[[T], K]

function: (T) -> K

required

Returns:

Type Description
Lazy[K]

New Lazy[K] with mapped elements from self.

Source code in src\qwlist\qwlist.py
def map(self, mapper: Callable[[T], K]) -> Lazy[K]:
    """
    Returns a `Lazy` object containing all values from `self` with
    the mapping function applied on them.

    Args:
        mapper: `function: (T) -> K`

    Returns:
        New `Lazy[K]` with mapped elements from `self`.
    """
    def inner():
        for elem in self:
            yield mapper(elem)
    return Lazy(inner())

max(key=None)

Returns the biggest element from self. If the key function is not passed, identity function is used in which case T must support LessThan operator.

Parameters:

Name Type Description Default
key Optional[Callable[[T], SupportsLessThan]

function: (T) -> SupportsLessThan that represents the relation of partial order between elements.

None

Returns:

Type Description
Optional[T]

the biggest element from self or None if self is empty.

Source code in src\qwlist\qwlist.py
def max(self, key: Optional[Callable[[T], SupportsLessThan]] = None) -> Optional[T]:
    """
    Returns the biggest element from `self`. If the key function is not passed, identity
    function is used in which case `T` must support `LessThan` operator.

    Args:
        key (Optional[Callable[[T], SupportsLessThan]): `function: (T) -> SupportsLessThan` that represents
         the relation of partial order between elements.

    Returns:
        the biggest element from `self` or `None` if `self` is empty.
    """

    def identity(x):
        return x
    key = identity if key is None else key

    if self.len() == 0:
        return None
    best = self[0]
    for elem in self[1:]:
        if key(best) < key(elem):
            best = elem
    return best

merge(other, merger)

Merges self with other, maintaining the order of elements based on the merger function. It starts by taking the first elements from self and other, calling the merger function with these elements as arguments. If the output is True, the first element is yielded; otherwise, the second element is yielded. If self is empty, the remaining elements from other are yielded, and vice versa.

Parameters:

Name Type Description Default
other Iterable[T]

an iterable to be merged with self.

required
merger Callable[[T, T], bool]

function: (T, T) -> bool that takes two arguments (left and right). If the output is True, the left argument is yielded; otherwise, the right argument is yielded.

required

Returns:

Type Description
Lazy[T]

New Lazy containing the merged elements.

Examples:

>>> QList([1, 3, 5]).merge([2, 4, 6], lambda left, right: left < right).collect()
[1, 2, 3, 4, 5, 6]
Source code in src\qwlist\qwlist.py
def merge(self, other: Iterable[T], merger: Callable[[T, T], bool]) -> Lazy[T]:
    """
    Merges `self` with `other`, maintaining the order of elements based on the merger function. It starts by
     taking the first elements from `self` and `other`, calling the merger function with these elements as arguments.
     If the output is True, the first element is yielded; otherwise, the second element is yielded. If `self` is
     empty, the remaining elements from `other` are yielded, and vice versa.

    Args:
        other (Iterable[T]): an iterable to be merged with `self`.
        merger (Callable[[T, T], bool]): `function: (T, T) -> bool` that takes two arguments (left and right).
         If the output is True, the left argument is yielded; otherwise, the right argument is yielded.

    Returns:
        New `Lazy` containing the merged elements.

    Examples:
        >>> QList([1, 3, 5]).merge([2, 4, 6], lambda left, right: left < right).collect()
        [1, 2, 3, 4, 5, 6]
    """
    it1 = iter(self)
    it2 = iter(other)

    try:
        elem1 = next(it1)
    except StopIteration:
        return Lazy(it2)
    try:
        elem2 = next(it2)
    except StopIteration:
        return Lazy([elem1]).chain(it1)

    def inner():
        left = elem1
        right = elem2
        while True:
            if merger(left, right):
                yield left
                try:
                    left = next(it1)
                except StopIteration:
                    yield right
                    yield from it2
                    return
            else:
                yield right
                try:
                    right = next(it2)
                except StopIteration:
                    yield left
                    yield from it1
                    return
    return Lazy(inner())

min(key=None)

Returns the smallest element from self. If the key function is not passed, identity function is used in which case T must support LessThan operator.

Parameters:

Name Type Description Default
key Optional[Callable[[T], SupportsLessThan]

function: (T) -> SupportsLessThan that represents the relation of partial order between elements.

None

Returns:

Type Description
Optional[T]

The smallest element from self or None if self is empty.

Source code in src\qwlist\qwlist.py
def min(self, key: Optional[Callable[[T], SupportsLessThan]] = None) -> Optional[T]:
    """
    Returns the smallest element from `self`. If the key function is not passed, identity
    function is used in which case `T` must support `LessThan` operator.

    Args:
        key (Optional[Callable[[T], SupportsLessThan]): `function: (T) -> SupportsLessThan` that represents
         the relation of partial order between elements.

    Returns:
        The smallest element from `self` or `None` if `self` is empty.
    """
    def identity(x):
        return x
    key = identity if key is None else key

    if self.len() == 0:
        return None
    best = self[0]
    for elem in self[1:]:
        if key(elem) < key(best):
            best = elem
    return best

product(other)

Computes the Cartesian product of self and other.

Parameters:

Name Type Description Default
other Iterable[K]

iterable to make the cartesian product with.

required

Returns:

Type Description
Lazy[Tuple[T, K]]

A new Lazy of pairs from Cartesian product.

Source code in src\qwlist\qwlist.py
def product(self, other: Iterable[K]) -> Lazy[Tuple[T, K]]:
    """
    Computes the Cartesian product of `self` and `other`.

    Args:
        other (Iterable[K]): iterable to make the cartesian product with.

    Returns:
        A new Lazy of pairs from Cartesian product.
    """
    def inner():
        for t in self:
            for k in other:
                yield t, k
    return Lazy(inner())

product_with(other, operation)

Applies a given operation to every pair of elements from the Cartesian product of self and other, returning a new Lazy iterable of the results. This method "lifts" the provided operation from working on individual elements to working on pairs of elements produced from the Cartesian product. It is equivalent to calling self.product(other).map(lambda pair: operation(*pair)).

Parameters:

Name Type Description Default
other Iterable[T]

The iterable to combine with self in a Cartesian product.

required
operation Callable[[T, K], R]

function: (T, K) -> R that takes a pair of elements, one from self and one from other, and returns a result of type R.

required

Returns:

Type Description
Lazy[R]

A new Lazy containing the results of applying operation

Lazy[R]

to each pair in the Cartesian product.

Examples:

>>> qlist1 = QList([1, 2])
>>> qlist2 = QList(['a', 'b'])
>>> qlist1.product_with(qlist2, lambda x, y: f"{x}{y}").collect()
['1a', '1b', '2a', '2b']
Source code in src\qwlist\qwlist.py
def product_with(self, other: Iterable[K], operation: Callable[[T, K], R]) -> Lazy[R]:
    """
    Applies a given operation to every pair of elements from the Cartesian product
    of `self` and `other`, returning a new Lazy iterable of the results.
    This method "lifts" the provided `operation` from working on individual elements
    to working on pairs of elements produced from the Cartesian product. It is equivalent
    to calling `self.product(other).map(lambda pair: operation(*pair))`.

    Args:
        other (Iterable[T]): The iterable to combine with `self` in a Cartesian product.
        operation (Callable[[T, K], R]): `function: (T, K) -> R` that takes a pair of elements,
         one from `self` and one from `other`, and returns a result of type `R`.

    Returns:
        A new Lazy containing the results of applying `operation`
        to each pair in the Cartesian product.

    Examples:
        >>> qlist1 = QList([1, 2])
        >>> qlist2 = QList(['a', 'b'])
        >>> qlist1.product_with(qlist2, lambda x, y: f"{x}{y}").collect()
        ['1a', '1b', '2a', '2b']
    """
    def inner():
        for t in self:
            for k in other:
                yield operation(t, k)
    return Lazy(inner())

scan(operation, state)

Given the combination operator creates a Lazy[K] object by processing constituent parts of self, yielding intermediate steps and building up the final value. Scan is similar to fold but returns all intermediate states instead of just the final result.

Parameters:

Name Type Description Default
operation Callable[[K, T], K]

function: (K, T) -> K. Given the initial state applies the given combination operator on each element yielded by the Lazy object, yielding the result and then treating it as the first argument in the next step.

required
state K

initial value for the state.

required

Returns:

Type Description
Lazy[K]

New Lazy[K] with all intermediate steps of the operation.

Examples:

>>> QList([1, 2, 3]).scan(lambda acc, x: acc + x, 0).collect()
[1, 3, 6]
Source code in src\qwlist\qwlist.py
def scan(self, operation: Callable[[K, T], K], state: K) -> "Lazy[K]":
    """
    Given the combination operator creates a `Lazy[K]` object by processing
    constituent parts of `self`, yielding intermediate steps and building up the final value.
    Scan is similar to fold but returns all intermediate states instead of just the final result.

    Args:
        operation: `function: (K, T) -> K`. Given the initial `state` applies the given
         combination operator on each element yielded by the `Lazy` object, yielding the result and
         then treating it as the first argument in the next step.
        state (K): initial value for the state.

    Returns:
        New `Lazy[K]` with all intermediate steps of the `operation`.

    Examples:
        >>> QList([1, 2, 3]).scan(lambda acc, x: acc + x, 0).collect()
        [1, 3, 6]
    """
    def inner(s):
        for elem in self:
            s = operation(s, elem)
            yield s
    return Lazy(inner(state))

skip(n)

Skips n first elements of self.

Parameters:

Name Type Description Default
n int

numbers of elements to skip. Should be non-negative.

required

Returns:

Type Description
Lazy[T]

New Lazy with n first elements of self skipped.

Examples:

>>> QList(range(10)).skip(2).collect()
[2, 3, 4, 5, 6, 7, 8, 9]
Source code in src\qwlist\qwlist.py
def skip(self, n: int) -> Lazy[T]:
    """
    Skips `n` first elements of `self`.

    Args:
        n (int): numbers of elements to skip. Should be non-negative.

    Returns:
        New `Lazy` with `n` first elements of `self` skipped.

    Examples:
        >>> QList(range(10)).skip(2).collect()
        [2, 3, 4, 5, 6, 7, 8, 9]
    """
    def inner():
        for i, elem in enumerate(self):
            if i >= n:
                yield elem
    return Lazy(inner())

slice(s)

Calling this method with s equal to slice(3) works similarly to list[:3] but is lazy evaluated.

Parameters:

Name Type Description Default
s slice

slice object

required

Returns:

Type Description
Lazy[T]

Lazy[T]

Source code in src\qwlist\qwlist.py
def slice(self, s: slice) -> Lazy[T]:
    """
    Calling this method with `s` equal to `slice(3)` works similarly to
    `list[:3]` but is lazy evaluated.

    Args:
        s: slice object

    Returns:
        `Lazy[T]`
    """
    assert isinstance(s, slice), f"slice method argument must be a slice object. Got {type(s)}."

    def inner():
        for elem in self[s]:
            yield elem
    return Lazy(inner())

sorted(key=None, reverse=False)

Returns a new QList containing all items from the original list in ascending order.

A custom key function can be supplied to customize the sort order, and the reverse flag can be set to request the result in descending order.

Parameters:

Name Type Description Default
key Callable[[T], SupportsLessThan]

function: (T) -> SupportsLessThan. Defaults to None.

None
reverse bool

if set to True sorts values in descending order. Defaults to False.

False

Returns:

Type Description
QList[T]

Sorted QList.

Source code in src\qwlist\qwlist.py
def sorted(self, key: Callable[[T], SupportsLessThan] = None, reverse: bool = False) -> "QList[T]":
    """
    Returns a new `QList` containing all items from the original list in ascending order.

    A custom key function can be supplied to customize the sort order, and the reverse
    flag can be set to request the result in descending order.

    Args:
        key (Callable[[T], SupportsLessThan]): `function: (T) -> SupportsLessThan`. Defaults to `None`.
        reverse (bool): if set to `True` sorts values in descending order. Defaults to `False`.

    Returns:
        Sorted `QList`.
    """
    return QList(sorted(self, key=key, reverse=reverse))

sum()

Sums all the elements and returns the sum. Returns None if self is empty. Elements of self must support addition.

Returns:

Type Description
Optional[SupportsAdd]

The sum of all elements of self.

Source code in src\qwlist\qwlist.py
def sum(self) -> Optional[SupportsAdd]:
    """
    Sums all the elements and returns the sum. Returns `None` if `self` is empty.
    Elements of `self` must support addition.

    Returns:
        The sum of all elements of `self`.
    """
    it = self.iter()
    acc = None
    try:
        acc = next(it)
    except StopIteration:
        return acc
    for elem in it:
        acc = acc + elem
    return acc

take(n)

Takes n first elements of self.

Parameters:

Name Type Description Default
n int

numbers of elements to take. Should be non-negative.

required

Returns:

Type Description
Lazy[T]

New Lazy with only n first elements from self.

Examples:

>>> QList(range(10)).take(2).collect()
[0, 1]
Source code in src\qwlist\qwlist.py
def take(self, n: int) -> Lazy[T]:
    """
    Takes `n` first elements of `self`.

    Args:
        n (int): numbers of elements to take. Should be non-negative.

    Returns:
        New `Lazy` with only `n` first elements from `self`.

    Examples:
        >>> QList(range(10)).take(2).collect()
        [0, 1]
    """
    def inner():
        for i, elem in enumerate(self):
            if i >= n:
                return None
            yield elem
    return Lazy(inner())

take_while(pred)

Creates a Lazy that yields elements based on a predicate. Takes a function as an argument. It will call this function on each element of self, and yield elements while the function returns True. After False is returned, iteration stops, and the rest of the elements is ignored.

Parameters:

Name Type Description Default
pred Callable[[T], bool]

function: (T) -> bool

required

Returns:

Type Description
Lazy[T]

New Lazy containing elements from the original sequence, stopping at the first element for which the predicate returns False.

Source code in src\qwlist\qwlist.py
def take_while(self, pred: Callable[[T], bool]) -> "Lazy[T]":
    """
    Creates a `Lazy` that yields elements based on a predicate. Takes a function as an argument.
    It will call this function on each element of `self`, and yield elements while the function
    returns `True`. After `False` is returned, iteration stops, and the rest of the elements is ignored.

    Args:
        pred (Callable[[T], bool]): `function: (T) -> bool`

    Returns:
        New `Lazy` containing elements from the original sequence, stopping at the first element for which the
         predicate returns `False`.
    """
    def inner():
        for elem in self:
            if not pred(elem):
                return
            yield elem
    return Lazy(inner())

window(window_size)

Creates a Lazy of sliding windows of size window_size. If window_size is greater than the total length of self an empty iterator is returned.

Parameters:

Name Type Description Default
window_size int

the size of the sliding window. Must be greater than 0.

required

Returns:

Type Description
Lazy[QList[T]]

New Lazy of all sliding windows.

Source code in src\qwlist\qwlist.py
def window(self, window_size: int) -> "Lazy[QList[T]]":
    """
    Creates a `Lazy` of sliding windows of size `window_size`. If `window_size`
    is greater than the total length of `self` an empty iterator is returned.

    Args:
        window_size (int): the size of the sliding window. Must be greater than 0.

    Returns:
        New `Lazy` of all sliding windows.
    """
    assert window_size > 0, f'window size must be greater than 0 but got {window_size}.'
    def inner(n: int):
        if self.len() < n:
            return
        if self.len() == n:
            yield self
            return
        window = deque(maxlen=n)
        for elem in self[:n]:
            window.append(elem)
        yield QList(window)
        for elem in self[n:]:
            window.append(elem)
            yield QList(window)
    return Lazy(inner(n=window_size))

zip(other)

Combines self with the given Iterable elementwise as tuples. The returned Lazy objects yields at most the number of elements of the shorter sequence (self or other).

Parameters:

Name Type Description Default
other Iterable[K]

iterable to zip with self.

required

Returns:

Type Description
Lazy[tuple[T, K]]

New Lazy with pairs of elements from self and other.

Examples:

>>> Lazy([1, 2, 3]).zip(['a', 'b', 'c']).collect()
[(1, 'a'), (2, 'b'), (3, 'c')]
Source code in src\qwlist\qwlist.py
def zip(self, other: Iterable[K]) -> Lazy[tuple[T, K]]:
    """
    Combines `self` with the given `Iterable` elementwise as tuples.
     The returned `Lazy` objects yields at most the number of elements of
     the shorter sequence (`self` or `other`).

    Args:
        other (Iterable[K]): iterable to zip with `self`.

    Returns:
        New `Lazy` with pairs of elements from `self` and `other`.

    Examples:
        >>> Lazy([1, 2, 3]).zip(['a', 'b', 'c']).collect()
        [(1, 'a'), (2, 'b'), (3, 'c')]
    """
    return Lazy(zip(self, other))

zip_with(other, operation)

Applies a given operation to pairs of elements from self and other, created by zipping them together.

This method "lifts" the provided operation from working on individual elements to working on pairs of elements formed by zipping the two iterables. It is equivalent to calling self.zip(other).map(lambda pair: operation(*pair)).

Parameters:

Name Type Description Default
other Iterable[K]

The iterable to zip with self.

required
operation Callable[[T, K], R]

function: (T, K) -> R that takes a pair of elements,

required

Returns:

Type Description
Lazy[R]

Lazy[R]: A new Lazy containing the results of applying operation

Lazy[R]

to each pair in the zipped iterables.

Examples:

>>> qlist1 = QList([1, 2, 3])
>>> qlist2 = QList(['a', 'b'])
>>> qlist1.zip_with(qlist2, lambda x, y: f"{x}{y}").collect()
['1a', '2b']
Source code in src\qwlist\qwlist.py
def zip_with(self, other: Iterable[K], operation: Callable[[T, K], R]) -> Lazy[R]:
    """
    Applies a given `operation` to pairs of elements from `self` and `other`, created by zipping them together.

    This method "lifts" the provided `operation` from working on individual elements
    to working on pairs of elements formed by zipping the two iterables. It is equivalent
    to calling `self.zip(other).map(lambda pair: operation(*pair))`.

    Args:
        other (Iterable[K]): The iterable to zip with `self`.
        operation (Callable[[T, K], R]): `function: (T, K) -> R` that takes a pair of elements,
        one from `self` and one from `other`, and returns a result of type `R`.

    Returns:
        Lazy[R]: A new Lazy containing the results of applying `operation`
        to each pair in the zipped iterables.

    Examples:
        >>> qlist1 = QList([1, 2, 3])
        >>> qlist2 = QList(['a', 'b'])
        >>> qlist1.zip_with(qlist2, lambda x, y: f"{x}{y}").collect()
        ['1a', '2b']
    """
    def inner():
        for t, k in self.zip(other):
            yield operation(t, k)
    return Lazy(inner())