API Reference
Supported Iterators
The exported functions support the following statically sized iterators:
Tuples andNamedTuples.SVectors andMVectors fromStaticArrays.- Lazy iterators from
Basethat wrap statically sized iterators:Iterators.map(Base.Generator),Iterators.reverse,enumerate, andzip. StaticOneToandStaticBitVector, which are defined in this package. The User Guide explains when to use them.
Other iterator types can be supported through the interface described in the Developer Guide.
Output Container Types
Functions that return containers infer the container type from their inputs:
Tuples and lazy iterators giveTuples.SVectors andMVectors giveSVectors andMVectors.NamedTuples keep their field names. A function that would change the number of items, such asunrolled_filterorunrolled_push, throws anArgumentErrorfor aNamedTuple; passTuple(nt)orvalues(nt)to it to get aTuple.StaticBitVectors giveStaticBitVectors when every item of the output is aBool, andTuples otherwise. SeveralStaticBitVectors with the same word type combine into aStaticBitVector.StaticOneTos giveTuples, except inunrolled_take.- Inputs with different container types give
Tuples, except that aStaticOneToadopts the container type of the other inputs.
Constant Folding and Bounds Checks
All exported functions are inlined, so that their results constant-fold whenever the compiler knows their inputs, as it does for Vals and for Tuples of Symbols that are constant-propagated. Results that constant-fold can be used as type parameters.
All exported functions propagate @inbounds from their call sites to iterator indexing and to callables that are marked with Base.@propagate_inbounds. @inbounds also elides the checks of compile-time indices, such as N in unrolled_take(itr, Val(N)).
Static Iterator Types
UnrolledUtilities.StaticSequence — Type
StaticSequence{N}Abstract supertype for indexable iterators with a compile-time constant length N.
Subtypes:
StaticOneTo: the integers from1toN, without storage.StaticBitVector:NBools packed into unsigned integers.
Subtypes implement generic_getindex(itr, n) for 1 ≤ n ≤ N and inherit length, firstindex, lastindex, getindex, and iterate.
UnrolledUtilities.StaticOneTo — Type
StaticOneTo{N} <: StaticSequence{N}
StaticOneTo(N)Analogue of Base.OneTo(N) for the integers 1:N that stores N as a type parameter.
The items are known during compilation, so unrolled functions pass constant indices to their callables. Unrolled functions return Tuples for a StaticOneTo, except unrolled_take, which returns a StaticOneTo.
Examples
r = StaticOneTo(4)
unrolled_take(r, Val(2)) # StaticOneTo{2}()
unrolled_map(abs2, r) # (1, 4, 9, 16)See also StaticSequence, StaticBitVector.
UnrolledUtilities.StaticBitVector — Type
StaticBitVector{N, U, I} <: StaticSequence{N}
StaticBitVector{N, [U]}(bits::NTuple{N, Bool})
StaticBitVector{N, [U]}(ints::Tuple)
StaticBitVector{N, [U]}(f)
StaticBitVector{N, [U]}([bit])Analogue of BitVector with N Bools packed into words of the Unsigned type U, which defaults to UInt8. The bits are set from a Tuple of Bools bits, from a Tuple of cld(N, 8 * sizeof(U)) words ints, from f(n) for n in 1:N, or to the constant bit, which defaults to false.
Unrolled functions have word-level implementations for StaticBitVectors. They return a StaticBitVector when every item of the result is a Bool, and a Tuple otherwise.
Fields
ints::I:Tupleof thecld(N, 8 * sizeof(U))words of typeU.
Examples
bv = StaticBitVector{3}(isodd) # StaticBitVector{3, UInt8}((true, false, true))
unrolled_count(bv) # 2
unrolled_push(bv, true) # StaticBitVector{4, UInt8}((true, false, true, true))
unrolled_push(bv, 42) # (true, false, true, 42)See also StaticSequence, StaticOneTo.
Container Modification and Slicing
UnrolledUtilities.unrolled_push — Function
unrolled_push(itr, items...)Return a container with items appended to itr, as a non-mutating analogue of push!.
Examples
unrolled_push((1, 2), 3, 4) # (1, 2, 3, 4)
unrolled_push((1, 2), (3,)) # (1, 2, (3,))See also unrolled_append, unrolled_insert.
UnrolledUtilities.unrolled_append — Function
unrolled_append(itr, itrs...)Return a container with the items of itr followed by the items of itrs, as a non-mutating analogue of append!.
Examples
unrolled_append((1, 2), (3, 4), (5,)) # (1, 2, 3, 4, 5)See also unrolled_prepend, unrolled_flatten.
UnrolledUtilities.unrolled_prepend — Function
unrolled_prepend(itr, itrs...)Return unrolled_append(itrs..., itr), as a non-mutating analogue of prepend!.
Examples
unrolled_prepend((3, 4), (1, 2)) # (1, 2, 3, 4)See also unrolled_append.
UnrolledUtilities.unrolled_take — Function
unrolled_take(itr, ::Val{N})Return a container with the first N items of itr, as an analogue of itr[1:N] with a compile-time constant N. Throws a BoundsError unless 0 ≤ N ≤ length(itr).
For a StaticOneTo, the result is StaticOneTo(N).
Examples
unrolled_take((a = 10, b = 20, c = 30), Val(2)) # (a = 10, b = 20)
unrolled_take(StaticOneTo(5), Val(3)) # StaticOneTo{3}()See also unrolled_drop, unrolled_partition.
UnrolledUtilities.unrolled_drop — Function
unrolled_drop(itr, ::Val{N})Return a container with all but the first N items of itr, as an analogue of itr[(N + 1):end] with a compile-time constant N. Throws a BoundsError unless 0 ≤ N ≤ length(itr).
Examples
unrolled_drop((a = 10, b = 20, c = 30), Val(1)) # (b = 20, c = 30)
unrolled_drop((1, 2, 3, 4), Val(2)) # (3, 4)See also unrolled_take, unrolled_partition.
UnrolledUtilities.unrolled_setindex — Function
unrolled_setindex(itr, item, ::Val{N})Return a copy of itr whose N-th item is item, as an analogue of Base.setindex with a compile-time constant N. Throws a BoundsError unless 1 ≤ N ≤ length(itr).
Examples
unrolled_setindex((a = 1, b = 2, c = 3), 10, Val(2)) # (a = 1, b = 10, c = 3)See also unrolled_insert.
UnrolledUtilities.unrolled_insert — Function
unrolled_insert(itr, item, ::Val{N})Return a container with item inserted into itr at index N, as a non-mutating analogue of insert! with a compile-time constant N. Throws a BoundsError unless 1 ≤ N ≤ length(itr) + 1.
Examples
unrolled_insert((10, 20, 30), 99, Val(2)) # (10, 99, 20, 30)See also unrolled_setindex, unrolled_push.
Mapping, Iteration, and Reductions
UnrolledUtilities.unrolled_map — Function
unrolled_map(f, itrs...)Apply f to corresponding items of itrs, as an analogue of map. The result has length(zip(itrs...)) items.
Examples
unrolled_map(x -> 2x, (a = 1, b = 2)) # (a = 2, b = 4)
unrolled_map(+, (1, 2, 3), (10, 20, 30)) # (11, 22, 33)See also unrolled_foreach, unrolled_mapreduce, unrolled_flatmap.
UnrolledUtilities.unrolled_foreach — Function
unrolled_foreach(f, itrs...)Call f on corresponding items of itrs for its side effects and return nothing, as an analogue of foreach. Stops after length(zip(itrs...)) items.
Examples
acc = Ref(0)
unrolled_foreach(x -> (acc[] += x), (1, 2, 3)) # acc[] == 6See also unrolled_map.
UnrolledUtilities.unrolled_any — Function
unrolled_any(itr)
unrolled_any(f, itr)Return whether any item of itr (or any value of f(item)) is true, as an analogue of any. Returns false for an empty itr, and stops evaluating at the first true.
Examples
unrolled_any((false, true, false)) # true
unrolled_any(iseven, (1, 3, 4, 7)) # trueSee also unrolled_all, unrolled_in, unrolled_count.
UnrolledUtilities.unrolled_all — Function
unrolled_all(itr)
unrolled_all(f, itr)Return whether every item of itr (or every value of f(item)) is true, as an analogue of all. Returns true for an empty itr, and stops evaluating at the first false.
Examples
unrolled_all((true, true, false)) # false
unrolled_all(isodd, (1, 3, 5)) # trueSee also unrolled_any, unrolled_allequal, unrolled_allunique.
UnrolledUtilities.unrolled_reduce — Function
unrolled_reduce(op, itr, [init])
unrolled_reduce(op, itr; [init])Reduce itr from left to right with the binary operator op, as an analogue of foldl. The initial value init can be passed positionally or as a keyword argument; without it, an empty itr throws an error.
Examples
unrolled_reduce(+, (1, 2, 3, 4)) # 10
unrolled_reduce(+, (), 0) # 0
unrolled_reduce(+, (1, 2, 3); init = 10) # 16See also unrolled_mapreduce, unrolled_accumulate.
UnrolledUtilities.unrolled_mapreduce — Function
unrolled_mapreduce(f, op, itrs...; [init])Apply f to corresponding items of itrs and reduce the results from left to right with op, as an analogue of mapreduce. Without init, an empty zip(itrs...) throws an error.
Examples
unrolled_mapreduce(abs2, +, (1, 2, 3)) # 14
unrolled_mapreduce(*, +, (1, 2), (10, 20); init = 5) # 55See also unrolled_reduce, unrolled_map, unrolled_sum.
UnrolledUtilities.unrolled_accumulate — Function
unrolled_accumulate(op, itr, [init])
unrolled_accumulate(op, itr; [init])Return the running reduction of itr from left to right with op, as an analogue of accumulate. The initial value init can be passed positionally or as a keyword argument.
Examples
unrolled_accumulate(+, (a = 1, b = 2, c = 3)) # (a = 1, b = 3, c = 6)
unrolled_accumulate(+, (1, 2, 3), 10) # (11, 13, 16)See also unrolled_cumsum, unrolled_cumprod, unrolled_reduce.
UnrolledUtilities.unrolled_sum — Function
unrolled_sum(itr; [init])
unrolled_sum(f, itr; [init])Return the sum of the items of itr (or of the values of f(item)), as an analogue of sum. The sum starts from init when it is given; an empty itr sums to init, or to 0 without it. As in sum, Bools and signed (unsigned) integers narrower than Int are added as Ints (UInts).
Examples
unrolled_sum((1, 2, 3, 4)) # 10
unrolled_sum(abs2, (1, 2, 3); init = 5) # 19
unrolled_sum(Int8.((100, 100))) # 200See also unrolled_prod, unrolled_cumsum, unrolled_count.
UnrolledUtilities.unrolled_prod — Function
unrolled_prod(itr; [init])
unrolled_prod(f, itr; [init])Return the product of the items of itr (or of the values of f(item)), as an analogue of prod. The product starts from init when it is given; an empty itr multiplies to init, or to 1 without it. As in prod, signed (unsigned) integers narrower than Int are multiplied as Ints (UInts).
Examples
unrolled_prod((2, 3, 4)) # 24
unrolled_prod(abs, (-2, 3); init = 2) # 12See also unrolled_sum, unrolled_cumprod.
UnrolledUtilities.unrolled_cumsum — Function
unrolled_cumsum(itr)
unrolled_cumsum(f, itr)Return the running sums of the items of itr (or of the values of f(item)), as an analogue of cumsum. As in cumsum, Bools and signed (unsigned) integers narrower than Int are added as Ints (UInts), so the running sums of a StaticBitVector are a Tuple of Ints.
Examples
unrolled_cumsum((a = 1, b = 2, c = 3)) # (a = 1, b = 3, c = 6)
unrolled_cumsum(abs, (-1, -2, 3)) # (1, 3, 6)
unrolled_cumsum((true, true, true)) # (1, 2, 3)See also unrolled_cumprod, unrolled_accumulate.
UnrolledUtilities.unrolled_cumprod — Function
unrolled_cumprod(itr)
unrolled_cumprod(f, itr)Return the running products of the items of itr (or of the values of f(item)), as an analogue of cumprod. As in cumprod, signed (unsigned) integers narrower than Int are multiplied as Ints (UInts), and the running products of a StaticBitVector are a StaticBitVector.
Examples
unrolled_cumprod((2, 3, 4)) # (2, 6, 24)
unrolled_cumprod(abs, (-2, -3, 4)) # (2, 6, 24)See also unrolled_cumsum, unrolled_accumulate.
UnrolledUtilities.unrolled_count — Function
unrolled_count(itr)
unrolled_count(f, itr)Return the number of items of itr for which f(item) (or the item itself) is true, as an analogue of count. The result is always an Int.
Examples
unrolled_count((true,)) # 1
unrolled_count(iseven, (1, 2, 4, 5)) # 2See also unrolled_sum, unrolled_any.
Extrema, Searching, and Indexing
UnrolledUtilities.unrolled_maximum — Function
unrolled_maximum(itr)
unrolled_maximum(f, itr)Return the largest item of itr (or the largest value of f(item)) under max, as an analogue of maximum. An empty itr throws an error.
Examples
unrolled_maximum((3, 1, 4, 2)) # 4
unrolled_maximum(abs, (-5, 2, -3)) # 5See also unrolled_minimum, unrolled_extrema, unrolled_findmax.
UnrolledUtilities.unrolled_minimum — Function
unrolled_minimum(itr)
unrolled_minimum(f, itr)Return the smallest item of itr (or the smallest value of f(item)) under min, as an analogue of minimum. An empty itr throws an error.
Examples
unrolled_minimum((3, 1, 4, 2)) # 1
unrolled_minimum(abs, (-5, 2, -3)) # 2See also unrolled_maximum, unrolled_extrema, unrolled_findmin.
UnrolledUtilities.unrolled_extrema — Function
unrolled_extrema(itr)
unrolled_extrema(f, itr)Return the Tuple (minimum, maximum) of the items of itr (or of the values of f(item)), as an analogue of extrema. Calls f once per item, and throws an error for an empty itr.
Examples
unrolled_extrema((3, 1, 4, 2)) # (1, 4)
unrolled_extrema(abs, (-5, 2, -3)) # (2, 5)See also unrolled_minimum, unrolled_maximum.
UnrolledUtilities.unrolled_findmax — Function
unrolled_findmax(itr)
unrolled_findmax(f, itr)Return the Tuple (value, index) of the largest value of f(item) (or the largest item) and the index of its first occurrence in itr, as an analogue of findmax. Values are ordered with isless, so NaN and missing are selected over all other values, and missing over NaN, as in Base. An empty itr throws an error.
Examples
unrolled_findmax((10, 30, 20)) # (30, 2)
unrolled_findmax(abs, (-4, 2, -4)) # (4, 1)See also unrolled_findmin, unrolled_argmax, unrolled_maximum.
UnrolledUtilities.unrolled_findmin — Function
unrolled_findmin(itr)
unrolled_findmin(f, itr)Return the Tuple (value, index) of the smallest value of f(item) (or the smallest item) and the index of its first occurrence in itr, as an analogue of findmin. As in Base, NaN and missing are selected over all other values, and missing over NaN. An empty itr throws an error.
Examples
unrolled_findmin((30, 10, 20)) # (10, 2)
unrolled_findmin(abs, (4, -2, 2)) # (2, 2)See also unrolled_findmax, unrolled_argmin, unrolled_minimum.
UnrolledUtilities.unrolled_argmax — Function
unrolled_argmax(itr)
unrolled_argmax(f, itr)Return the index of the largest item of itr, or the item with the largest value of f(item), as an analogue of argmax. Values are ordered as in unrolled_findmax, and an empty itr throws an error.
Examples
unrolled_argmax((10, 30, 20)) # 2
unrolled_argmax(abs, (1, -5, 3)) # -5See also unrolled_argmin, unrolled_findmax.
UnrolledUtilities.unrolled_argmin — Function
unrolled_argmin(itr)
unrolled_argmin(f, itr)Return the index of the smallest item of itr, or the item with the smallest value of f(item), as an analogue of argmin. Values are ordered as in unrolled_findmin, and an empty itr throws an error.
Examples
unrolled_argmin((30, 10, 20)) # 2
unrolled_argmin(abs, (-5, -2, 3)) # -2See also unrolled_argmax, unrolled_findmin.
UnrolledUtilities.unrolled_findfirst — Function
unrolled_findfirst(itr)
unrolled_findfirst(f, itr)Return the index of the first item of itr for which f(item) (or the item itself) is true, or nothing if there is none, as an analogue of findfirst.
Examples
unrolled_findfirst((false, true, true)) # 2
unrolled_findfirst(iseven, (1, 3, 5)) # nothingSee also unrolled_findlast, unrolled_argfirst.
UnrolledUtilities.unrolled_findlast — Function
unrolled_findlast(itr)
unrolled_findlast(f, itr)Return the index of the last item of itr for which f(item) (or the item itself) is true, or nothing if there is none, as an analogue of findlast.
Examples
unrolled_findlast((false, true, true)) # 3
unrolled_findlast(iseven, (2, 4, 5)) # 2See also unrolled_findfirst, unrolled_arglast.
UnrolledUtilities.unrolled_argfirst — Function
unrolled_argfirst(f, itr)Return the first item of itr for which f(item) is true, and throw an error if there is none.
Each item is returned from its own branch, which keeps the result type-stable for heterogeneous itr when the values of f are known during compilation.
Examples
unrolled_argfirst(x -> x isa Float64, (1, 2.5, 3)) # 2.5See also unrolled_arglast, unrolled_findfirst, unrolled_applyat.
UnrolledUtilities.unrolled_arglast — Function
unrolled_arglast(f, itr)Return the last item of itr for which f(item) is true, and throw an error if there is none. Equivalent to unrolled_argfirst(f, Iterators.reverse(itr)).
Examples
unrolled_arglast(iseven, (2, 4, 5)) # 4See also unrolled_argfirst, unrolled_findlast.
UnrolledUtilities.unrolled_applyat — Function
unrolled_applyat(f, n, itrs...)Return f(itr1[n], itr2[n], ...) for a run-time index n, with a separate branch for every index in 1:length(zip(itrs...)). Throws a BoundsError when n is outside that range.
Each branch is compiled for the types of the items at its index, so the result is type-stable for heterogeneous itrs when f returns the same type for every index. The branches compile to a switch instruction.
Examples
unrolled_applyat(Float64, 2, (1, 2.0, 3.0f0)) # 2.0See also unrolled_argfirst, unrolled_findfirst.
Membership, Uniqueness, and Filtering
UnrolledUtilities.unrolled_in — Function
unrolled_in(item, itr)Return whether item is === to an item of itr, as an analogue of in. Comparing with === keeps the result inferrable for singletons.
Examples
unrolled_in(:b, (:a, :b, :c)) # true
unrolled_in(2, (1, 2.0, 3)) # false, since 2 !== 2.0See also unrolled_any.
UnrolledUtilities.unrolled_unique — Function
unrolled_unique(itr)
unrolled_unique(f, itr)Return a container with the items of itr whose values of f(item) (or the items themselves) do not appear earlier in itr, compared with ===, as an analogue of unique. A singleton f is called repeatedly and constant folded; any other callable is called once per item.
The number of items in the result depends on the values of f, so the result is only inferrable when those values are known during compilation, as they are for singleton items and for constant-folded f.
Examples
unrolled_unique((:a, :b, :a, :c)) # (:a, :b, :c)
unrolled_unique(abs, (1, -1, 2, -2, 3)) # (1, 2, 3)See also unrolled_allunique, unrolled_filter.
UnrolledUtilities.unrolled_allunique — Function
unrolled_allunique(itr)
unrolled_allunique(f, itr)Return whether the values of f(item) (or the items themselves) are pairwise distinct under ===, as an analogue of allunique.
Examples
unrolled_allunique((:a, :b, :c)) # true
unrolled_allunique(abs, (1, -1, 2)) # falseSee also unrolled_unique, unrolled_allequal.
UnrolledUtilities.unrolled_allequal — Function
unrolled_allequal(itr)
unrolled_allequal(f, itr)Return whether all values of f(item) (or all items) are === to the first one, as an analogue of allequal. Returns true when length(itr) ≤ 1.
Examples
unrolled_allequal((2, 2, 2)) # true
unrolled_allequal(abs, (-3, 3, -3)) # trueSee also unrolled_allunique.
UnrolledUtilities.unrolled_filter — Function
unrolled_filter(f, itr)Return a container with the items of itr for which f(item) is true, as an analogue of filter.
The number of items in the result depends on the values of f, so the result is only inferrable when those values are known during compilation. This is the case for predicates on item types, such as x -> x isa Int.
Examples
unrolled_filter(x -> x isa Int, (1, 2.0, 3, 4.0)) # (1, 3)See also unrolled_split, unrolled_unique.
UnrolledUtilities.unrolled_split — Function
unrolled_split(f, itr)Return the Tuple (unrolled_filter(f, itr), unrolled_filter(!f, itr)), calling f once per item. The result is inferrable under the same conditions as for unrolled_filter.
Examples
unrolled_split(x -> x isa Int, (1, 2.0, 3, 4.0)) # ((1, 3), (2.0, 4.0))See also unrolled_filter, unrolled_partition.
Combinators and Partitioning
UnrolledUtilities.unrolled_flatten — Function
unrolled_flatten(itr)Return a container with the items of the iterators in itr, as an analogue of Iterators.flatten. The container type is promoted across the iterators in itr, as in unrolled_append.
Examples
unrolled_flatten(((1, 2), (), (3, 4, 5))) # (1, 2, 3, 4, 5)See also unrolled_flatmap, unrolled_append.
UnrolledUtilities.unrolled_flatmap — Function
unrolled_flatmap(f, itrs...)Return unrolled_flatten(unrolled_map(f, itrs...)), as an analogue of Iterators.flatmap.
Examples
unrolled_flatmap(x -> (x, -x), (1, 2, 3)) # (1, -1, 2, -2, 3, -3)See also unrolled_flatten, unrolled_map.
UnrolledUtilities.unrolled_product — Function
unrolled_product(itrs...)Return a Tuple with every combination of one item from each of itrs, in the column-major order of Iterators.product. The container type of each combination is promoted across itrs, as in unrolled_append, except that NamedTuples give Tuples.
Examples
unrolled_product((1, 2), (:a, :b)) # ((1, :a), (2, :a), (1, :b), (2, :b))See also unrolled_cycle.
UnrolledUtilities.unrolled_cycle — Function
unrolled_cycle(itr, ::Val{N})Return a container with the items of itr repeated N times, as an analogue of Iterators.cycle(itr, N).
Examples
unrolled_cycle((1, 2), Val(3)) # (1, 2, 1, 2, 1, 2)See also unrolled_flatten, unrolled_partition.
UnrolledUtilities.unrolled_partition — Function
unrolled_partition(itr, ::Val{N})Return a Tuple of containers with N consecutive items of itr each, and fewer in the last one when N does not divide length(itr), as an analogue of Iterators.partition.
Examples
unrolled_partition((1, 2, 3, 4, 5), Val(2)) # ((1, 2), (3, 4), (5,))
unrolled_partition((a = 1, b = 2, c = 3), Val(2)) # ((a = 1, b = 2), (c = 3,))See also unrolled_take, unrolled_drop, unrolled_split.