Small vectors

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

AbstractSmallVector{N,T} is the supertype of SmallVector{N,T} and MutableSmallVector{N,T}.

See also SmallVector, MutableSmallVector.

SmallVector{N,T} <: AbstractSmallVector{N,T}

SmallVector{N,T}()
SmallVector{N,T}(iter)
SmallVector{N}(iter)
SmallVector(v::PackedVector)
SmallVector(v::Union{AbstractSmallVector, AbstractFixedVector})

SmallVector{N,T} is an immutable vector type that can hold up to N elements of type T. Here 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.

The element type T can be omitted when creating the SmallVector from an iterator that has an element type, for example from an AbstractVector or a tuple. In the latter case, T is determined by promoting the element types of the tuple. If no argument is given, then an empty vector is returned. If the SmallVector is created from an AbstractSmallVector, AbstractFixedVector or PackedVector v and the parameter N is omitted, then it is set to capacity of v.

The unused elements of a SmallVector{N,T} are filled with the value default(T), which is predefined for several types including Number. Default values for other types must be defined explicitly.

Addition and subtraction of two SmallVectors is possible even if the vectors have different capacity. (Of course, their lengths must agree.) The capacity of the result is the smaller of the arguments' capacities in this case.

See also MutableSmallVector, capacity, SmallCollections.default, Base.IteratorEltype, promote_type.

Examples

julia> v = SmallVector{8,Int8}(2*x for x in 1:3)
3-element SmallVector{8, Int8}:
 2
 4
 6

julia> w = SmallVector{9}((1, 2.5, 4))
3-element SmallVector{9, Float64}:
 1.0
 2.5
 4.0

julia> v+w
3-element SmallVector{8, Float64}:
  3.0
  6.5
 10.0

MutableSmallVector{N,T} <: AbstractSmallVector{N,T}

MutableSmallVector{N,T}()
MutableSmallVector{N,T}(iter)
MutableSmallVector{N}(iter)
MutableSmallVector(v::PackedVector)
MutableSmallVector(v::Union{AbstractSmallVector, AbstractFixedVector})

MutableSmallVector{N,T}(undef, n::Integer)

MutableSmallVector{N,T} is a mutable vector type that can hold up to N elements of type T. It is the mutable analog of SmallVector{N,T}.

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

The special form MutableSmallVector{N,T}(undef, n) returns a non-initialized vector of length n.

See also SmallVector, Base.isbitstype.

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

Return the largest number of elements this vector type can hold.

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

Return the FixedVector underlying v. It agrees with v at all positions up to length(v); the remaining elements are equal to default(T).

See also SmallCollections.default, fixedvector(::AbstractFixedVector).

Example

julia> v = SmallVector{4}(1:2)
2-element SmallVector{4, Int64}:
 1
 2

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

bits(v::AbstractSmallVector) -> Unsigned

Return the bit representation of fixedvector(v).

See also fixedvector, bits(::AbstractFixedVector).

Example

julia> SmallVector{4,Int8}(1:3) |> bits
0x00030201

fasthash(v::AbstractSmallVector [, 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 AbstractSmallVectors of the same element type, but it may not be compatible with hash or with fasthash for a AbstractSmallVector 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.

Examples

julia> v = SmallVector{8,Int8}([1, 5, 6]);

julia> fasthash(v)
0x6466067ab41d0916

julia> fasthash(v) == hash(v)
false

julia> w = SmallVector{16,Int8}(v); fasthash(v) == fasthash(w)
true

julia> w = SmallVector{8,Int16}(v); fasthash(v) == fasthash(w)
false

unsafe_copyto!(w::MutableSmallVector{N}, v::AbstractSmallVector{N}) where N -> w

Copy the vector v to w. Both are assumed to have the same length.

See also unsafe_copyto!(::MutableSmallVector{N}, ::Union{AbstractFixedVector{N},NTuple{N}}) where N

unsafe_copyto!(w::MutableSmallVector{N}, v::Union{AbstractFixedVector{N},NTuple{N}}) where N -> w

Copy the vector or tuple v to w. The length of w is not changed. The elements in v past the length of w are assumed to be default values.

See also unsafe_copyto!(::MutableSmallVector{N}, ::AbstractSmallVector{N}) where N, SmallCollections.default.

resize(v::AbstractSmallVector{N,T}, n::Integer) -> SmallVector{N,T}

Return a vector of length n by making v longer or shorter. If the new vector is longer, then the new elements are initialized with default(T).

See also Base.resize!, SmallCollections.default.

empty(v::V) where V <: AbstractSmallVector -> V
empty(v::AbstractSmallVector{N}, T::Type) where {N,T} -> AbstractSmallVector{N,T}

In the first form, return an empty AbstractSmallVector of the same type as v. In the second form, the capacity is the same as for v, but the element type is T.

getindex(v::Union{AbstractFixedVector{N,T}, AbstractSmallVector{N,T}}, s::SmallBitSet) where {N,T} -> SmallVector{N,T}

Returns the vector with elements v[i] where i runs through the elements of s in increasing order. This operation is analogous to v[collect(s)], but faster.

Example

julia> v = SmallVector{8}('a':'f'); s = SmallBitSet{UInt16}(1:2:5)
SmallBitSet{UInt16} with 3 elements:
  1
  3
  5

julia> v[s]
3-element SmallVector{8, Char}:
 'a': ASCII/Unicode U+0061 (category Ll: Letter, lowercase)
 'c': ASCII/Unicode U+0063 (category Ll: Letter, lowercase)
 'e': ASCII/Unicode U+0065 (category Ll: Letter, lowercase)

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

Substitute x for the i-th component of v and return the new vector.

See also Base.setindex, addindex.

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

Add x to the i-th component of v and return the new vector.

See also setindex.

push(v::AbstractSmallVector{N,T}, xs...) where {N,T} -> SmallVector{N,T}

Return the SmallVector obtained from v by appending the arguments xs.

See also Base.push!, BangBang.push!!.

pop(v::AbstractSmallVector{N,T}) where {N,T} -> Tuple{SmallVector{N,T}, T}

Return the tuple (w, x) where x is the last element of v and w obtained from v by dropping this element. The vector v must not be empty.

See also Base.pop!, BangBang.pop!!.

pushfirst(v::AbstractSmallVector{N,T}, xs...) where {N,T} -> SmallVector{N,T}

Return the SmallVector obtained from v by prepending the arguments xs.

See also Base.pushfirst!, BangBang.pushfirst!!.

popfirst(v::AbstractSmallVector{N,T}) where {N,T} -> Tuple{SmallVector{N,T}, T}

Return the tuple (w, x) where x is the first element of v and w obtained from v by dropping this element. The vector v must not be empty.

See also Base.popfirst!, BangBang.popfirst!!.

unsafe_circshift(v::AbstractSmallVector{N,T}, k::Integer) where {N,T} -> SmallVector{N,T}
unsafe_circshift!(v::MutableSmallVector, k::Integer) -> v

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

See also Base.circshift, Base.circshift!.

insert(v::AbstractSmallVector{N,T}, i::Integer, x) where {N,T} -> SmallVector{N,T}

Return the SmallVector obtained from v by inserting x at position i. The position i must be between 1 and length(v)+1.

This is the non-mutating analog of Base.insert!.

See also duplicate.

duplicate(v::AbstractSmallVector{N,T}, i::Integer) where {N,T} -> SmallVector{N,T}

Duplicate the i-th entry of v by inserting it at position i+1 and return the new vector.

See also insert.

Example

julia> v = SmallVector{8,Int8}(1:3)
3-element SmallVector{8, Int8}:
 1
 2
 3

julia> duplicate(v, 2)
4-element SmallVector{8, Int8}:
 1
 2
 2
 3

deleteat(v::AbstractSmallVector{N,T}, i::Integer) where {N,T} -> SmallVector{N,T}

Return the SmallVector obtained from v by deleting the element at position i. The latter must be between 1 and length(v).

See also Base.deleteat!, BangBang.deleteat!!.

popat(v::AbstractSmallVector{N,T}, i::Integer) where {N,T} -> Tuple{SmallVector{N,T}, T}

Return the tuple (w, x) where w obtained from v by deleting the element x at position i. The latter must be between 1 and length(v).

See also Base.popat!, BangBang.popat!!.

append(v::AbstractSmallVector{N,T}, ws...) where {N,T} -> SmallVector{N,T}

Append all elements of the collections ws to v and return the new vector. Note that the resulting SmallVector has the same capacity as v.

See also Base.append!, BangBang.append!!.

prepend(v::AbstractSmallVector{N,T}, ws...) where {N,T} -> SmallVector{N,T}

Prepend all elements of the collections ws to v and return the new vector. Note that the resulting SmallVector has the same capacity as v.

See also Base.prepend!.

zeros(::Type{V}, n::Integer) where V <: AbstractSmallVector -> V

Return an AbstractSmallVector of type V containing n zeros.

See also ones.

ones(::Type{V}, n::Integer) where V <: AbstractSmallVector -> V

Return an AbstractSmallVector of type V containing n ones.

See also zeros.

sum_fast(v::AbstractSmallVector{N,T}) where {N,T}

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.

Example

julia> v = SmallVector{4}([-0.0, -0.0])
2-element SmallVector{4, Float64}:
 -0.0
 -0.0

julia> sum(v), sum_fast(v)
(-0.0, 0.0)

julia> v = SmallVector{4}(Int8[80, 90])
2-element SmallVector{4, Int8}:
 80
 90

julia> sum(v), sum_fast(v)
(170, -86)

extrema_fast(v::AbstractSmallVector; [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.

any(f::Function, v::AbstractSmallVector; dims = :, [style::MapStyle])
all(f::Function, v::AbstractSmallVector; dims = :, [style::MapStyle])
allequal(f, v::AbstractSmallVector; [style::MapStyle})
allunique(f, v::AbstractSmallVector; [style::MapStyle])
findall(f::Function, v::AbstractSmallVector; [style::MapStyle])
findfirst(f::Function, v::AbstractSmallVector; [style::MapStyle])
findlast(f::Function, v::AbstractSmallVector; [style::MapStyle])
findnext(f::Function, v::AbstractSmallVector, k::Integer; [style::MapStyle])
findprev(f::Function, v::AbstractSmallVector, k::Integer; [style::MapStyle])
count(f, v::AbstractSmallVector; dims = :, init = 0, [style::MapStyle])
filter(f, v::AbstractSmallVector; [style::MapStyle])
filter!(f, v::MutableSmallVector; [style::MapStyle])

With an AbstractSmallVector 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 as well as on the default values used for padding. 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.default, SmallCollections.MapStyle.

map(f, v::AbstractSmallVector...; [style::MapStyle]) -> SmallVector

Apply f to the argument vectors elementwise and stop when one of them is exhausted. Note that the capacity of the resulting SmallVector is the minimum of the argument vectors' capacities.

The style keyword argument determines how map treats the padding used for AbstractSmallVector. As discussed under MapStyle, the default value is based on a list of known functions.

See also capacity, Base.map(f, v::AbstractVector...), SmallCollections.MapStyle, Section "Broadcasting".

Examples

julia> v = SmallVector{8}(1:3); w = SmallVector{4}(2.0:4.0); map(*, v, w)
3-element SmallVector{4, Float64}:
  2.0
  6.0
 12.0

julia> v = SmallVector{8}('a':'e'); w = SmallVector{4}('x':'z'); map(*, v, w)
3-element SmallVector{4, String}:
 "ax"
 "by"
 "cz"

support(v::AbstractSmallVector) -> 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, ::AbstractSmallVector).

Example

julia> v = SmallVector{8,Int8}([1, 0, 2, 0, 0, 3]);

julia> support(v)
SmallBitSet{UInt8} with 3 elements:
  1
  3
  6

support(f, v::AbstractSmallVector; [style::MapStyle]) -> 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.

The style keyword argument determines how the padding used for AbstractSmallVector is treated. As discussed under MapStyle, the default value is based on a list of known functions.

See also SmallBitSet, support(::AbstractSmallVector), SmallCollections.MapStyle.

Example

julia> v = SmallVector{8,Int8}(3:8);

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