Metadata-Version: 2.1
Name: IteratorAlgorithms
Version: 0.0.3
Summary: A collection of iterator algorithms for Python3.
Home-page: UNKNOWN
Author: Robert Sharp
Author-email: webmaster@sharpdesigndigital.com
License: UNKNOWN
Description: # Iterator Algorithms
        #### Robert Sharp, Library Author
        
        IA is a collection of iterator algorithms for Python3, inspired by the C++ 
        algorithms library with ranges.
        
        Many of the algorithms are the same as those found in the standard library, but 
        extended in some way. For example: the IA.symmetric_difference function can 
        accept an arbitrary number of sets as input. The built in set method of the same 
        name can only compare 2 sets. The abstraction is raised from - 
        "What's not in both sets." to "What's not in all sets." It's the exact opposite 
        of the intersection of multiple sets.
        
        A few of the IA algorithms are exactly the same as those found in itertools, but 
        with slightly different signatures and/or better names. IA.fork, for example, 
        is exactly the same as itertools.tee. While the choice of one name over another 
        is largely subjective, it is the author's opinion that the name 'tee' is 
        especially bad, in addition - it's quite possible that 'fork' is only 
        marginally better. If you have suggestions - please make a pull request, 
        lets build this together.
        
        ### Quick Install:
        ```
        $ python3 -m pip install IteratorAlgorithms
        ```
        
        ### Run Test Suite:
        ```
        $ python3 -m IteratorAlgorithms
        ... # Test Output
        Test passed.
        $ 
        ```
        Tests are verbose by default. Tests are only run when the module is executed as a script, as above.
        
        ### Standard Import:
        ```
        $ python3
        >>> import IteratorAlgorithms as ia
        # No Test Output. Ready for work!
        >>>
        ```
        None of the standard import styles should trigger the tests.
        
        ### Help Features
        All of the features of this module have full help support built in.
        ```
        $ python3
        >>> from IteratorAlgorithms import fork
        >>> help(fork)
        ```
        ```
        Help on function fork in module IteratorAlgorithms:
        
        fork(array: Iterable, forks: int = 2) -> tuple
            Fork
            Iterator Duplicator.
            
            # DocTest:
            >>> it = iter(range(10))
            >>> a, b, c = fork(it, 3)
            >>> list(c)
            [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
            >>> a == b
            False
            >>> list(a) == list(b)
            True
            
            @param array: Iterable to be forked.
            @param forks: Optional Integer. Default is 2. Represents the number of forks.
            @return: tuple of N Iterators where N is the number of forks.
        ```
        
        ## Table of Contents:
        - Generators
            - iota
            - generate
            - generate_n
        - Expansions
            - fork
            - exclusive_scan
            - inclusive_scan
        - Transforms
            - transform
            - adjacent_difference
            - partial_sum
        - Permutations
            - partition
        - Reductions
            - reduce
            - accumulate
            - product
        - Queries
            - all_of
            - any_of
            - none_of
        - Transform & Reduction
            - transform_reduce
            - inner_product
        - Multidimensional Reductions
            - zip_transform
            - transposed_sums
        - Multi-Set Operations
            - union
            - intersection
            - difference
            - symmetric_difference
        
        ---
        
        
        ## Generators
        
        ### Iota
        ```
        Help on function iota in module IteratorAlgorithms:
        
        iota(start, stop=None, step=1, stride=1) -> Iterator
            Iota
            Iterator of a given range with stride grouping.
            
            DocTests:
            >>> list(iota(11))
            [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
            >>> list(iota(start=1, stop=11))
            [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
            >>> list(iota(start=2, stop=21, step=2))
            [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]
            >>> list(iota(start=2, stop=21, step=2, stride=2))
            [(2, 4), (6, 8), (10, 12), (14, 16), (18, 20)]
            
            @param start: Beginning
            @param stop: Ending
            @param step: Stepping
            @param stride: Number of groups.
            @return: Iterator of a given multidimensional range.
        
        ```
        ### Generate
        ```
        Help on function generate in module IteratorAlgorithms:
        
        generate(transformer: Callable, *args, **kwargs)
            Generate
            Abstract generator function. Infinite Iterator.
            
            DocTests:
            >>> counter = itertools.count(1)
            >>> gen = generate(next, counter)
            >>> list(next(gen) for _ in range(10))
            [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
            
            @param transformer: Functor.
            @param args: Positional arguments for the functor.
            @param kwargs: Keyword arguments for the functor.
        
        ```
        ### Generate_N
        ```
        Help on function generate_n in module IteratorAlgorithms:
        
        generate_n(n: int, transformer: Callable, *args, **kwargs)
            Generate N
            Abstract generator function. Finite.
            
            DocTests:
            >>> counter = itertools.count(1)
            >>> list(generate_n(10, next, counter))
            [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
            
            @param n: Maximum number of elements.
            @param transformer: Functor.
            @param args: Positional arguments for the functor.
            @param kwargs: Keyword arguments for the functor.
        
        ```
        
        ## Expansions
        
        ### Fork
        ```
        Help on function fork in module IteratorAlgorithms:
        
        fork(array: Iterable, forks: int = 2) -> tuple
            Fork
            Iterator Duplicator.
            
            DocTests:
            >>> it = iter(range(10))
            >>> a, b, c = fork(it, 3)
            >>> list(c)
            [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
            >>> a == b
            False
            >>> list(a) == list(b)
            True
            
            @param array: Iterable to be forked.
            @param forks: Optional Integer. Default is 2. Represents the number of forks.
            @return: Tuple of N Iterators where N is the number of forks.
        
        ```
        ### Exclusive_Scan
        ```
        Help on function exclusive_scan in module IteratorAlgorithms:
        
        exclusive_scan(array: Iterable, init) -> Iterator
            Exclusive Scan Pairs
            Inserts an initial value at the beginning and ignores the last value.
            
            DocTests:
            >>> list(exclusive_scan(range(1, 10), 0))
            [(0, 1), (1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 7), (7, 8)]
            >>> list(exclusive_scan(range(1, 10), 10))
            [(10, 1), (1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 7), (7, 8)]
            
            @param array: Iterable to be scanned.
            @param init: Initial Value.
            @return: Iterator of Pairs.
        
        ```
        ### Inclusive_Scan
        ```
        Help on function inclusive_scan in module IteratorAlgorithms:
        
        inclusive_scan(array: Iterable) -> Iterator
            Inclusive Scan Pairs
            
            DocTests:
            >>> list(inclusive_scan(range(1, 6)))
            [(1, 2), (2, 3), (3, 4), (4, 5)]
            >>> list(inclusive_scan(range(1, 10)))
            [(1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 7), (7, 8), (8, 9)]
            
            @param array: Iterable to be scanned.
            @return: Iterator of Pairs.
        
        ```
        
        ## Transforms
        
        ### Transform
        ```
        Help on function transform in module IteratorAlgorithms:
        
        transform(array: Iterable, func: Callable) -> Iterator
            Transform
            Similar to map but with a reversed signature.
            
            DocTests:
            >>> list(transform(range(1, 10), add_one))
            [2, 3, 4, 5, 6, 7, 8, 9, 10]
            >>> list(transform(range(1, 10), square))
            [1, 4, 9, 16, 25, 36, 49, 64, 81]
            
            @param array: Iterable of Values.
            @param func: Unary Functor. F(x) -> Value
            @return: Iterator of transformed Values.
        
        ```
        ### Adjacent_Difference
        ```
        Help on function adjacent_difference in module IteratorAlgorithms:
        
        adjacent_difference(array: Iterable) -> Iterator
            Adjacent Difference
            Calculates the difference between adjacent pairs.
            This is the opposite of Partial Sum.
            The first iteration compares with zero for proper offset.
            
            DocTests:
            >>> list(adjacent_difference(range(1, 10)))
            [1, 1, 1, 1, 1, 1, 1, 1, 1]
            >>> list(adjacent_difference(partial_sum(range(1, 10))))
            [1, 2, 3, 4, 5, 6, 7, 8, 9]
            
            @param array: Iterable of Numeric Values.
            @return: Iterable of adjacent differences.
        
        ```
        ### Partial_Sum
        ```
        Help on function partial_sum in module IteratorAlgorithms:
        
        partial_sum(array: Iterable) -> Iterator
            Partial Sum
            Calculates the sum of adjacent pairs.
            This is the opposite of Adjacent Difference.
            
            DocTests:
            >>> list(partial_sum(range(1, 10)))
            [1, 3, 6, 10, 15, 21, 28, 36, 45]
            >>> list(partial_sum([1, 1, 1, 1, 1, 1, 1, 1, 1, 1]))
            [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
            
            @param array: Iterable of Numeric Values.
            @return: Iterator of adjacent sums.
        
        ```
        
        ## Permutations
        
        ### Partition
        ```
        Help on function partition in module IteratorAlgorithms:
        
        partition(array: Iterable, predicate: Callable[[Any], bool]) -> Iterator
            Stable Partition
            
            DocTests:
            >>> list(partition(range(1, 10), is_even))
            [2, 4, 6, 8, 1, 3, 5, 7, 9]
            >>> list(partition(range(1, 10), is_odd))
            [1, 3, 5, 7, 9, 2, 4, 6, 8]
            
            @param array: Iterable of values to be partitioned.
            @param predicate: Unary functor. F(element) -> bool
            @return: Partitioned Iterator.
        
        ```
        
        ## Reductions
        
        ### Reduce
        ```
        Help on function reduce in module IteratorAlgorithms:
        
        reduce(array: Iterable, func: Callable, initial=None)
            Reduce
            Similar to accumulate but allows any binary functor and/or an initial value.
            
            DocTests:
            >>> reduce(range(1, 5), operator.add)
            10
            >>> reduce(range(1, 5), operator.mul)
            24
            
            @param array: Iterable of Values to be reduced.
            @param func: Binary Functor.
            @param initial: Initial value. Typically 0 for add or 1 for multiply.
            @return: Reduced Value.
        
        ```
        ### Accumulate
        ```
        Help on function accumulate in module IteratorAlgorithms:
        
        accumulate(array: Iterable)
            Accumulate
            Sums up a range of elements. Same as Reduce with operator.add
            
            DocTests:
            >>> accumulate(range(5))
            10
            >>> accumulate(range(11))
            55
            
            @param array: Iterable of Values to be summed.
            @return: Sum of Values.
        
        ```
        ### Product
        ```
        Help on function product in module IteratorAlgorithms:
        
        product(array: Iterable)
            Product
            Reduce with multiply.
            For counting numbers from 1 to N: returns the factorial of N.
            
            DocTests:
            >>> product(range(1, 5))
            24
            >>> product(range(5, 10))
            15120
            
            @param array: Iterable of Values to be reduced.
            @return: Product of all elements multiplied together.
        
        ```
        
        ## Queries
        
        ### All_Of
        ```
        Help on function all_of in module IteratorAlgorithms:
        
        all_of(array: Iterable, predicate: Callable) -> bool
            All of These
            
            DocTests:
            >>> all_of([], is_even)
            True
            >>> all_of([2, 4, 6], is_even)
            True
            >>> all_of([1, 4, 6], is_even)
            False
            >>> all_of([1, 3, 5], is_even)
            False
            
            @param array: Iterable to inspect.
            @param predicate: Callable. f(x) -> bool
            @return: Boolean.
        
        ```
        ### Any_Of
        ```
        Help on function any_of in module IteratorAlgorithms:
        
        any_of(array: Iterable, predicate: Callable) -> bool
            Any of These
            
            DocTests:
            >>> any_of([], is_even)
            False
            >>> any_of([2, 4, 6], is_even)
            True
            >>> any_of([1, 4, 6], is_even)
            True
            >>> any_of([1, 3, 5], is_even)
            False
            
            @param array: Iterable to inspect.
            @param predicate: Callable. f(x) -> bool
            @return: Boolean.
        
        ```
        ### None_Of
        ```
        Help on function none_of in module IteratorAlgorithms:
        
        none_of(array: Iterable, predicate: Callable) -> bool
            None Of These
            
            DocTests:
            >>> none_of([], is_even)
            True
            >>> none_of([2, 4, 6], is_even)
            False
            >>> none_of([1, 4, 6], is_even)
            False
            >>> none_of([1, 3, 5], is_even)
            True
            
            @param array: Iterable to inspect.
            @param predicate: Callable. f(x) -> bool
            @return: Boolean.
        
        ```
        
        ## Transform & Reduce
        
        ### Transform_Reduce
        ```
        Help on function transform_reduce in module IteratorAlgorithms:
        
        transform_reduce(lhs: Iterable, rhs: Iterable, transformer: Callable, reducer: Callable)
            Transform Reduce
            Pairwise transform and reduction.
            
            DocTests:
            >>> transform_reduce(range(1, 6), range(1, 6), operator.mul, sum)
            55
            >>> transform_reduce(range(1, 6), range(1, 6), operator.add, product)
            3840
            
            @param lhs: Left Iterator
            @param rhs: Right Iterator
            @param transformer: Binary Functor F(x, y) -> Value
            @param reducer: Reduction Functor F(Iterable) -> Value
            @return: Reduced Value
        
        ```
        ### Inner_Product
        ```
        Help on function inner_product in module IteratorAlgorithms:
        
        inner_product(lhs: Iterable, rhs: Iterable)
            Inner Product
            Preforms pairwise multiplication across the iterables,
                then returns the sum of the products.
            
            DocTests:
            >>> inner_product(range(1, 6), range(1, 6))
            55
            >>> inner_product(range(11), range(11))
            385
            
            @param lhs: Left Iterator
            @param rhs: Right Iterator
            @return: Sum of the products.
        
        ```
        
        ## Multidimensional Reductions
        
        ### Zip_Transform
        ```
        Help on function zip_transform in module IteratorAlgorithms:
        
        zip_transform(transformer: Callable, *args: Iterable) -> Iterator
            Zip Transform
            The transformer should take the same number of arguments as there are iterators.
            Each iteration will call the transformer on the ith elements.
                F(a[i], b[i], c[i]...) ... for each i.
            
            DocTests:
            >>> l1 = (0, 1, 2, 3)
            >>> l2 = (8, 7, 6, 5)
            >>> l3 = (1, 1, 1, 1)
            >>> list(zip_transform(add_all, l1, l2, l3))
            [9, 9, 9, 9]
            
            @param transformer: Functor: F(*args) -> Value
            @param args: Any number of Iterators.
            @return: Iterator of transformed Values.
        
        ```
        ### Transposed_Sums
        ```
        Help on function transposed_sums in module IteratorAlgorithms:
        
        transposed_sums(*args: Iterable) -> Iterator
            Transposed Sums - Column Sums
            The size of the output iterator will be the same as
                the smallest input iterator.
            
            DocTests:
            >>> l1 = (0, 1, 2, 3)
            >>> l2 = (8, 7, 6, 5)
            >>> l3 = (1, 1, 1, 1)
            >>> list(transposed_sums(l1, l2, l3))
            [9, 9, 9, 9]
            
            @param args: Arbitrary number of Iterators of numeric values.
            @return: Iterator of transposed sums aka column sums.
        
        ```
        
        ## Multi-Set Operations
        
        ### Union
        ```
        Help on function union in module IteratorAlgorithms:
        
        union(*args: set) -> set
            Multiple Set Union
            Includes all elements of every set passed in.
            
            DocTests:
            >>> s1 = {0, 2, 4, 6, 8}
            >>> s2 = {1, 2, 3, 4, 5}
            >>> s3 = {2, 8, 9, 1, 7}
            >>> union(s1, s2, s3)
            {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}
            
            @param args: Arbitrary number of sets.
            @return: Unified set
        
        ```
        ### Intersection
        ```
        Help on function intersection in module IteratorAlgorithms:
        
        intersection(*args: set) -> set
            Multiple Set Intersection
            Includes all elements that are common to every set passed in.
            If there is no intersection, it will return the empty set.
            If all sets are the same, it will return the union of all sets.
            Opposite of symmetric_difference.
            
            DocTests:
            >>> s1 = {0, 2, 4, 6, 8}
            >>> s2 = {1, 2, 3, 4, 5}
            >>> s3 = {2, 8, 9, 1, 7}
            >>> intersection(s1, s2, s3)
            {2}
            
            @param args: Arbitrary number of sets.
            @return: Set of common elements
        
        ```
        ### Difference
        ```
        Help on function difference in module IteratorAlgorithms:
        
        difference(*args: set) -> set
            Multiple Set Difference
            Includes every element in the first set that isn't in one of the others.
            If there is no difference, it will return the empty set.
            
            DocTests:
            >>> s1 = {0, 2, 4, 6, 8}
            >>> s2 = {1, 2, 3, 4, 5}
            >>> s3 = {2, 8, 9, 1, 7}
            >>> difference(s1, s2, s3)
            {0, 6}
            
            @param args: Arbitrary number of sets.
            @return: Difference between the first set and the rest.
        
        ```
        ### Symmetric_Difference
        ```
        Help on function symmetric_difference in module IteratorAlgorithms:
        
        symmetric_difference(*args: set) -> set
            Multiple Set Symmetric Difference
            Includes all elements that are not common to every set passed in.
            If there is no intersection, it will return the union of all sets.
            If all sets are the same, it will return the empty set.
            Opposite of intersection.
            
            DocTests:
            >>> s1 = {0, 2, 4, 6, 8}
            >>> s2 = {1, 2, 3, 4, 5}
            >>> s3 = {2, 8, 9, 1, 7}
            >>> symmetric_difference(s1, s2, s3)
            {0, 1, 3, 4, 5, 6, 7, 8, 9}
            
            @param args: Arbitrary number of sets.
            @return: Symmetric difference considering all sets.
        
        ```
        
        ## Test Summary
        ```
        35 items passed all tests:
           4 tests in __main__
           2 tests in __main__.accumulate
           4 tests in __main__.add_all
           2 tests in __main__.add_one
           2 tests in __main__.adjacent_difference
           4 tests in __main__.all_of
           9 tests in __main__.analytic_continuation
           4 tests in __main__.any_of
           4 tests in __main__.difference
           2 tests in __main__.exclusive_scan
           3 tests in __main__.flatten
           5 tests in __main__.fork
           3 tests in __main__.generate
           2 tests in __main__.generate_n
           2 tests in __main__.inclusive_scan
           2 tests in __main__.inner_product
           4 tests in __main__.intersection
           4 tests in __main__.iota
           5 tests in __main__.is_even
           5 tests in __main__.is_odd
           1 tests in __main__.min_max
           4 tests in __main__.none_of
           2 tests in __main__.partial_sum
           2 tests in __main__.partition
           2 tests in __main__.product
           2 tests in __main__.random_below
           4 tests in __main__.range_test
           2 tests in __main__.reduce
           3 tests in __main__.square
           4 tests in __main__.symmetric_difference
           2 tests in __main__.transform
           2 tests in __main__.transform_reduce
           4 tests in __main__.transposed_sums
           4 tests in __main__.union
           4 tests in __main__.zip_transform
        114 tests in 35 items.
        114 passed and 0 failed.
        Test passed.
        ```
        
Keywords: accumulate,adjacent_difference,all_of,analytic_continuation,any_of,difference,exclusive_scan,flatten,fork,generate,generate_n,inclusive_scan,inner_product,intersection,iota,min_max,none_of,partial_sum,partition,product,reduce,symmetric_difference,transform,transform_reduce,transposed_sums,union,zip_transform
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.6
Description-Content-Type: text/markdown
