TupleTools.jl

TupleTools contains a bunch of tools for using tuples (mostly homogeneous tuples NTuple{N}) as a collection and performing a number of operations with an inferrable result, typically also an NTuple{M} with inferable length M. Chosen implementations are typically faster than the corresponding functions in base for those small tuple lengths, but can be slower for larger tuples. Inference breaks down for most functions in case of inhomogeneous tuples.

Note that none of the following functions are exported, since their name often collides with the equivalent functions (with different implementations) in Base. Some functions here provided just have an equivalent in Base that doesn't work for tuples at all, like sort or cumsum and cumprod. Some functions also provide reasonable defaults assuming that they are used for tuples of Ints, i.e. TupleTools.sum(()) = 0 or TupleTools.prod(()) = 1 (whereas the corresponding Base functions would error). This originates from the assumption that these methods are used to operate on tuples of e.g. sizes, indices or strides of multidimensional arrays.

Types

TupleTools.StaticLengthType
struct StaticLength{N} end

Like Val{N}, StaticLength can be used to construct a tuple of inferrable length using ntuple(f, StaticLength(N)). Here, StaticLength(N) creates StaticLength{N}() using a Base.@pure constructor. Furthermore, one can add and subtract StaticLength objects, such that

StaticLength(N₁) + StaticLength(N₂) == StaticLength(N₁+N₂)

and

StaticLength(N₁) - StaticLength(N₂) == StaticLength(max(0, N₁-N₂))
source

Functions

TupleTools.tail2Function
tail2(t::Tuple) -> ::Tuple

Returns a tuple with the first two elements stripped, equivalent to tail(tail(t))

source
TupleTools.unsafe_tailFunction
unsafe_tail(t::Tuple) -> ::Tuple

Returns a tuple with the first element stripped, similar to tail(t), but does not error on an empty tuple (instead returning an empty tuple again). An empty tuple is thus the fixed point of this function.

source
TupleTools.unsafe_frontFunction
unsafe_front(t::Tuple) -> ::Tuple

Returns a tuple with the last element stripped, similar to front(t), but does not error on an empty tuple (instead returning an empty tuple again). An empty tuple is thus the fixed point of this function.

source
TupleTools.getindicesFunction
getindices(t::Tuple, I::Tuple{Vararg{Int}}) -> ::Tuple

Get the indices t[i] for i in I, again as tuple.

source
TupleTools.deleteatFunction
deleteat(t::Tuple, i::Int) -> ::Tuple
deleteat(t::Tuple, I::Tuple{Vararg{Int}}) -> ::Tuple

Delete the element at location i in t; if a list I of indices is specified (again as a tuple), the elements of these different positions are deleted.

source
TupleTools.insertatFunction
insertat(t::Tuple, i::Int, t2::Tuple) -> ::Tuple

Insert the elements of tuple t2 at location i in t, i.e. the output tuple will look as (t[1:i-1]..., t2..., t[i+1:end]). Note that element t[i] is deleted. Use setindex for setting a single value at position i, or insertafter(t, i, t2) to insert the contents of t2 in between element i and i+1 in t.

source
TupleTools.insertafterFunction
insertafter(t::Tuple, i::Int, t2::Tuple) -> ::Tuple

Insert the elements of tuple t2 after location i in t, i.e. the output tuple will look as (t[1:i]..., t2..., t[i+1:end]). Use index i=0 or just (t2..., t...) to insert t2 in front of t; also see insertat to overwrite the element at position i.

source
TupleTools.vcatFunction
vcat(args...) -> ::Tuple

Like vcat for tuples, concatenates a combination of tuple arguments and non-tuple arguments into a single tuple. Only works one level deep, i.e. tuples in tuples are not expanded.

source
TupleTools.flattenFunction
flatten(args...) -> ::Tuple

Flatten one or more tuples into a single tuple, such that every element of that tuple is itself not a tuple, otherwise it would also be expanded (i.e. flattened).

source
TupleTools.sumFunction
sum(t::Tuple)

Returns the sum of the element of a tuple, or 0 for an empty tuple.

source
TupleTools.cumsumFunction
cumsum(t::Tuple)

Returns the cumulative sum of the elements of a tuple, or () for an empty tuple.

source
TupleTools.prodFunction
prod(t::Tuple)

Returns the product of the elements of a tuple, or 1 for an empty tuple.

source
TupleTools.cumprodFunction
cumprod(t::Tuple)

Returns the cumulative product of the elements of a tuple, or () for an empty tuple.

source
TupleTools.findminFunction
findmin(t::Tuple)

Returns the value and index of the minimum element in a tuple. If there are multiple minimal elements, then the first one will be returned.

source
TupleTools.findmaxFunction
findmax(t::Tuple)

Returns the value and index of the maximum element in a tuple. If there are multiple maximal elements, then the first one will be returned.

source
TupleTools.argminFunction
argmin(t::Tuple)

Returns the index of the minimum element in a tuple. If there are multiple minimal elements, then the first one will be returned.

source
TupleTools.argmaxFunction
argmax(t::Tuple)

Returns the index of the maximum element in a tuple. If there are multiple minimal elements, then the first one will be returned.

source
TupleTools.sortFunction
sort(t::Tuple; lt=isless, by=identity, rev::Bool=false) -> ::Tuple

Sorts the tuple t.

source
TupleTools.sortpermFunction
sortperm(t::Tuple; lt=isless, by=identity, rev::Bool=false) -> ::Tuple

Computes a tuple that contains the permutation required to sort t.

source
TupleTools.ispermFunction
isperm(p) -> ::Bool

A non-allocating alternative to Base.isperm(p) that is much faster for small permutations.

source
TupleTools.invpermFunction
invperm(p::NTuple{N,Int}) -> ::NTuple{N,Int}

Inverse permutation of a permutation p.

source
TupleTools.permuteFunction
permute(t::Tuple, p) -> ::Tuple

Permute the elements of tuple t according to the permutation in p.

source