Home

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

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
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
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
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.diffFunction.
diff(v::Tuple) -> Tuple

Finite difference operator of tuple v.

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.minimumFunction.
minimum(t::Tuple)

Returns the smallest element of a tuple

source
TupleTools.maximumFunction.
maximum(t::Tuple)

Returns the largest element of a 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