Fixed-length vectors

AbstractFixedVector{N,T} <: AbstractVector{T}

AbstractFixedVector{N,T} is the supertype of FixedVector{N,T} and MutableFixedVector{N,T}.

See also FixedVector, MutableFixedVector.

FixedVector{N,T} <: AbstractFixedVector{N,T}

FixedVector{N,T}(iter)
FixedVector{N}(iter)
FixedVector(iter)

FixedVector{N,T} is an immutable vector type that holds exactly N elements of type T. (It is analogous to StaticArrays.SVector and StaticVectors.Values.) The size N can be any (small) positive integer. However, at least for bit integer and hardware float types, one usually takes N to be a power of 2.

If the element type T or the size N are omitted, they are determined from the iterator given as argument. Performance degrades if this is not possible at compile time. (For tuples, the element type is determined via promote_type.) As a rule of thumb, the size should only be omitted for Tuple arguments.

See also MutableFixedVector, Base.promote_type.

FixedVector(v::StaticVector{N,T}) where {N,T} -> FixedVector{N,T}
MutableFixedVector(v::StaticVector{N,T}) where {N,T} -> MutableFixedVector{N,T}

Convert a StaticVector to a FixedVector or MutableFixedVector. The length N is inferred from the given vector v. For example, v can be an SVector or MVector.

These methods are only available if the package StaticArrays.jl is loaded.

See also AbstractFixedVector, StaticArrays.StaticVector.

MutableFixedVector{N,T} <: AbstractFixedVector{N,T}

MutableFixedVector{N,T}(iter)
MutableFixedVector{N}(iter)
MutableFixedVector(iter)

MutableFixedVector{N,T}(undef)

MutableFixedVector{N,T} is a mutable vector type that holds exactly N elements of type T. (It is analogous to StaticArrays.MVector and StaticVectors.Variables.) The size N can be any (small) positive integer. However, at least for bit integer and hardware float types, one usually takes N to be a power of 2.

If the element type T or the size N are omitted, they are determined from the iterator given as argument. Performance degrades if this is not possible at compile time. As a rule of thumb, the size should only be omitted for Tuple arguments.

Note that setting individual vector elements (via setindex!) is only supported for isbits element types.

The special form MutableFixedVector{N,T}(undef) returns a non-initialized vector.

See also FixedVector, Base.isbitstype.

FixedVector(v::StaticVector{N,T}) where {N,T} -> FixedVector{N,T}
MutableFixedVector(v::StaticVector{N,T}) where {N,T} -> MutableFixedVector{N,T}

Convert a StaticVector to a FixedVector or MutableFixedVector. The length N is inferred from the given vector v. For example, v can be an SVector or MVector.

These methods are only available if the package StaticArrays.jl is loaded.

See also AbstractFixedVector, StaticArrays.StaticVector.

capacity(::Type{<:AbstractFixedVector{N}}) where N -> N
capacity(v::AbstractFixedVector{N}) where N -> N

Return the number N of elements this vector type holds. This function is useful when writing code that works for both AbstractFixedVector and AbstractSmallVector.

See also capacity(::AbstractSmallVector).

fixedvector(v::AbstractFixedVector{N,T}) where {N,T} -> FixedVector{N,T}

Returns the argument as a FixedVector. The purpose of this function is to make is easier to write code that works for both AbstractFixedVector and AbstractSmallVector.

See also fixedvector(::AbstractSmallVector).

bits(v::AbstractFixedVector{N,T}) where {N, T <: Union{Base.HWReal, Bool, Char, Enum}} -> Unsigned

Convert the given vector to an unsigned integer.

For bit integers, hardware floats, Char and Enum types this is the same as reinterpret(U, Tuple(v)) provided that U is an unsigned integer type with N*bitsize(T) bits, possibly defined by the package BitIntegers. Otherwise the result will be zero-extended to the next unsigned integer type U whose bit length is a power of 2.

If the element type is Bool, then each element only takes one bit in the return value. If N is less than 8 or not a power of 2, then the result will again be zero-extended.

The inverse operation can be done with convert.

See also Base.convert, SmallCollections.bitsize, Base.HWReal, Base.reinterpret, BitIntegers.

Examples

julia> FixedVector{4,Int8}(1:4) |> bits
0x04030201

julia> FixedVector{3}('a':'c') |> bits
0x00000000630000006200000061000000

julia> m = FixedVector{6,UInt32}(1:6) |> bits
0x0000000000000000000000060000000500000004000000030000000200000001

julia> typeof(m)
BitIntegers.UInt256

julia> FixedVector{22}(map(isodd, 1:22)) |> bits
0x00155555

convert(::Type{V}, x::Unsigned) where {N, T <: Union{Base.HWReal, Bool, Char, Enum}, V <: AbstractFixedVector{N,T}}

Convert the unsigned integer x to a FixedVector{N,T} or MutableFixedVector{N,T}. The bits of x are split into groups of size bitsize(T) and reinterpreted as elements of type T. Unused bits are ignored and missing bits are taken as 0. This is the inverse operation to bits.

See also bits, SmallCollections.bitsize, Base.HWReal, BitIntegers.

Examples

julia> v = convert(FixedVector{4,Int8}, 0x030201)
4-element FixedVector{4, Int8}:
 1
 2
 3
 0

julia> bits(v)
0x00030201

julia> convert(FixedVector{6,Bool}, 0xf0)
6-element FixedVector{6, Bool}:
 0
 0
 0
 0
 1
 1

julia> x = FixedVector{2,Char}('a':'b') |> bits
0x6200000061000000

julia> convert(FixedVector{2,Char}, x)
2-element FixedVector{2, Char}:
 'a': ASCII/Unicode U+0061 (category Ll: Letter, lowercase)
 'b': ASCII/Unicode U+0062 (category Ll: Letter, lowercase)

julia> using BitIntegers

julia> convert(FixedVector{4,Int64}, uint256"0x300000000000000020000000000000001")
4-element FixedVector{4, Int64}:
 1
 2
 3
 0

fasthash(v::AbstractFixedVector [, h0::UInt]) -> UInt

Return a hash for v that may be computed faster than the standard hash for vectors. This new hash is consistent across all AbstractFixedVectors of the same element type, but it may not be compatible with hash or with fasthash for a AbstractFixedVector having a different element type.

Currently, fasthash differs from hash only if the element type of v is a bit integer type with at most 32 bits, Bool or Char.

See also Base.hash.

setindex(v::AbstractFixedVector{N,T}, x, i::Integer) where {N,T} -> FixedVector{N,T}

Substitute x for the i-th component of v and return the result. The vector v is not modified.

See also Base.setindex, addindex.

addindex(v::AbstractFixedVector{N,T}, x, i::Integer) where {N,T} -> FixedVector{N,T}

Add x to the i-th component of v and return the result. The vector v is not modified.

See also setindex.

circshift(v::AbstractFixedVector{N,T}, k::Integer) where {N,T} -> FixedVector{N,T}
circshift(v::AbstractFixedVector{N,T}, ::Val{k}) where {N,T,k} -> FixedVector{N,T}

Rotate v by k positions towards higher indices and return the result. A negative value of k corresponds to a rotation towards lower indices.

See also circshift!.

Examples

julia> v = FixedVector{4}(1:4);

julia> circshift(v, 1)
4-element FixedVector{4, Int64}:
 4
 1
 2
 3

julia> circshift(v, Val(-1))
4-element FixedVector{4, Int64}:
 2
 3
 4
 1

circshift!(v::MutableFixedVector, k::Integer) -> v
circshift!(v::MutableFixedVector, ::Val{k}) where k -> v

Rotate v in-place by k positions towards higher indices and return v. A negative value of k corresponds to a rotation towards lower indices.

See also circshift.

Examples

julia> v = MutableFixedVector{4}(1:4);

julia> circshift!(v, 1)
4-element MutableFixedVector{4, Int64}:
 4
 1
 2
 3

julia> circshift!(v, Val(-1))  # undo previous step
4-element MutableFixedVector{4, Int64}:
 1
 2
 3
 4

unsafe_circshift(v::AbstractFixedVector{N,T}, k::Integer) where {N,T} -> FixedVector{N,T}
unsafe_circshift!(v::MutableFixedVector, k::Integer) -> v

These are faster versions of circshift and circshift!. They assume -N ≤ k < N. This avoids the comparatively costly integer division with remainder.

See also circshift, circshift!.

sum_fast(v::AbstractFixedVector)

Return the @fastmath sum of the elements of v. Unlike for sum, the return value always is of the element type of v, even for small bit integers.

See also Base.sum, Base.@fastmath.

extrema_fast(v::AbstractFixedVector; [init])

Return the @fastmath minimum and maximum of the elements of v. The init keyword argument may not be used.

See also Base.extrema, Base.@fastmath.

extrema_fast(f, v::AbstractFixedVector; [init])

Return the @fastmath minimum and maximum of the values of f applied to the elements of v. The init keyword argument may not be used.

See also Base.extrema, Base.@fastmath.

any(f::Function, v::AbstractFixedVector; dims = :, [style::MapStyle])
all(f::Function, v::AbstractFixedVector; dims = :, [style::MapStyle])
allequal(f, v::AbstractFixedVector; [style::MapStyle})
allunique(f, v::AbstractFixedVector; [style::MapStyle])
findfirst(f::Function, v::AbstractFixedVector; [style::MapStyle])
findlast(f::Function, v::AbstractFixedVector; [style::MapStyle])
findnext(f::Function, v::AbstractFixedVector, k::Integer; [style::MapStyle])
findprev(f::Function, v::AbstractFixedVector, k::Integer; [style::MapStyle])

With an AbstractFixedVector v as second argument, these functions accept the additional keyword argument style. If it equals LazyStyle(), then the function f is only evaluated until the result has been determined. For any other value of style, f is evaluated on all elements of v. This is often faster for simple functions.

As discussed under MapStyle, the default value for style is based on a list of known functions.

See also SmallCollections.MapStyle.

support(v::AbstractFixedVector) -> SmallBitSet

Return the SmallBitSet with the indices of the non-zero elements of v. If v has Bool elements, then this means the elements that are true.

See also SmallBitSet, support(::Any, ::AbstractFixedVector).

Example

julia> v = FixedVector{4,Int8}([1, 0, 0, 3]);

julia> support(v)
SmallBitSet{UInt8} with 2 elements:
  1
  4

support(f, v::AbstractFixedVector) -> SmallBitSet

Return the SmallBitSet with the indices of the elements x of v for which f(x) is non-zero. If f has Bool values, then this means that f(x) has to be true.

See also SmallBitSet, support(::AbstractFixedVector).

Example

julia> v = FixedVector{4,Int8}(3:6);

julia> support(isodd, v)
SmallBitSet{UInt8} with 2 elements:
  1
  3

SVector(v::AbstractFixedVector{N,T}) where {N,T} -> SVector{N,T}
MVector(v::AbstractFixedVector{N,T}) where {N,T} -> MVector{N,T}

Convert an AbstractFixedVector to an SVector or MVector. The length N is inferred from the argument.

These methods are only available if the package StaticArrays.jl is loaded.

See also StaticArrays.SVector, StaticArrays.MVector, AbstractFixedVector.