Non-exported names

SmallCollections.default(::Type{T}) where T -> T
SmallCollections.default(::T) where T -> T

Return the default value of type T used for filling unused elements of an AbstractSmallVector. This must be defined as zero(T) if T supports algebraic operations. Otherwise it can be any value of type T.

This function has methods for number types, bits types, Symbol, AbstractChar, AbstractString, Tuple, NamedTuple, AbstractFixedVector, AbstractSmallVector und SmallBitSet. Methods for other types must be defined explicitly, see the examples below.

See also Base.isbitstype.

Examples

We start by defining a default value for an immutable struct.

julia> import SmallCollections: default

julia> struct A x::Int end

julia> default(::Type{A}) = A(0);

For a mutable struct one needs to create an object first.

julia> mutable struct B x::Int end

julia> const b0 = B(0);

julia> default(::Type{B}) = b0;

For mutable parametric types one can use a generated function.

julia> mutable struct C{T} x::T end

julia> @generated default(::Type{C{T}}) where T = C(default(T));

julia> default(C{Bool})
C{Bool}(false)

julia> default(C{Bool}) === default(C{Bool})  # do we always get the same object?
true

SmallCollections.isfasttype(::Type{T}) where T -> Bool

Return true if elements of type T permit fast (for instance, vectorized) operations.

By default, Base.HWReal, Bool, Char, and Enum types are considered fast, as well as Complex, Pair, Tuple, NamedTuple and Ref with fast components.

See Base.HWReal.

SmallCollections.MapStyle

MapStyle(f, types::Type...) -> MapStyle

A MapStyle determines how SmallCollections evaluates certain functions like map or findfirst that take a function f as argument. The available subtypes of MapStyle are as follows, from the least to the most efficient:

• LazyStyle: the function f is only evaluated when strictly necessary, and it is not assumed to be defined for default values. This is the default MapStyle for unknown functions.

• EagerStyle: f may be evaluated more often than strictly necessary, and it is assumed to be defined for default values. However, it need not map default values to default values.

• RigidStyle: f may be evaluated more often than strictly necessary. It is assumed to be defined for default values and to return a default value if all arguments are default values.

• StrictStyle: f may be evaluated more often than strictly necessary. It is assumed to be defined for default values and to return a default value if at least one argument is a default value. (This is the same as RigidStyle for functions with a single argument.)

The MapStyle is predefined for many functions from Base as well as for operations that produce new functions out of old. Unnamed functions are not recognized. However, several functions from SmallCollections allow to specify a MapStyle as keyword argument. In addition, users can define a MapStyle for their own types.

See also SmallCollections.default, SmallCollections.isfasttype.

Examples

julia> using SmallCollections: MapStyle

julia> MapStyle(iszero, Int)   # not RigidStyle: iszero(0) is true, not false
SmallCollections.EagerStyle()

julia> MapStyle(+, Int, Int)
SmallCollections.RigidStyle()

julia> MapStyle(*, Int, Float64)   # not StrictStyle: 0 * Inf is NaN, not 0.0
SmallCollections.RigidStyle()

julia> MapStyle(*, Int, Int)
SmallCollections.StrictStyle()

julia> MapStyle(-, Int)
SmallCollections.StrictStyle()

julia> MapStyle(x -> -x, Int)   # not StrictStyle: anonymous function not recognized
SmallCollections.LazyStyle()

julia> MapStyle(-, Int128)   # Int128 is not a fast type, so better be lazy
SmallCollections.LazyStyle()

julia> MapStyle(isfinite∘inv, Float64)   # function composition is recognized
SmallCollections.EagerStyle()

julia> MapStyle(!isodd, Int)  # function composition again
SmallCollections.EagerStyle()

julia> MapStyle(!iszero, Int)   # separately defined to override EagerStyle
SmallCollections.StrictStyle()

julia> MapStyle(>=(1), Int)   # >=(1) is Base.Fix2(>=, 1), which is recognized
SmallCollections.EagerStyle()

SmallCollections.FixedVectorStyle <: Broadcast.AbstractArrayStyle{1}

The broadcasting style used for AbstractFixedVector.

See also AbstractFixedVector, Broadcast.AbstractArrayStyle.

SmallCollections.SmallVectorStyle <: Broadcast.AbstractArrayStyle{1}

The broadcasting style used for AbstractSmallVector.

See also AbstractSmallVector, Broadcast.AbstractArrayStyle.

SmallCollections.padtail(v::AbstractFixedVector{N,T}, i::Integer, x = default(T)) where {N,T} -> FixedVector{N,T}

Replace the elements of v after the i-th position by x and return the new vector. Providing an out-of-bounds index i does not produce an error.

Example

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

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

julia> SmallCollections.padtail(v, 2, -1)
4-element FixedVector{4, Int64}:
  1
  2
 -1
 -1

SmallCollections.bitsize(T::Type) -> Int
SmallCollections.bitsize(x::T) where T -> Int

Return the size of the internal binary representation of T in bits. For Bool the function returns 1.

See also Base.sizeof.

SmallCollections.unsafe_shl(x::U, i::Integer) where U <: AbstractBitInteger -> U

This is a fast, but unsafe version of the left bit shift operator x << i. The shift i is assumed to be between 0 and bitsize(x)-1.

See also SmallCollections.bitsize, SmallCollections.AbstractBitInteger.

SmallCollections.unsafe_lshr(x::U, i::Integer) where U <: AbstractBitInteger -> U

This is a fast, but unsafe version of the logical (or unsigned) right bit shift operator x >>> i. The shift i is assumed to be between 0 and bitsize(x)-1.

See also SmallCollections.bitsize, SmallCollections.AbstractBitInteger.

SmallCollections.blsi(x::T) where T <: Integer -> T

Extract the lowest set bit of x. For hardware integers, this compiles to a single BLSI instruction from the BMI1 instruction set on x86_64 and i686 machines.

See also SmallCollections.blsr, SmallCollections.blsmsk.

SmallCollections.blsr(x::T) where T <: Integer -> T

Reset the lowest set bit of x. For hardware integers, this compiles to a single BLSR instruction from the BMI1 instruction set on x86_64 and i686 machines.

See also SmallCollections.blsi, SmallCollections.blsmsk.

SmallCollections.blsmsk(x::T) where T <: Integer -> T

Get the bit mask up to lowest set bit of x. For hardware integers, this compiles to a single BLSMSK instruction from the BMI1 instruction set on x86_64 and i686 machines.

See also SmallCollections.blsi, SmallCollections.blsr.

SmallCollections.pdep(x::Unsigned, y::U) where U <: Unsigned -> U

Assume that y has exactly m 1-bits. Then pdep(x, y) replaces these bits by the m lowest bits of x (in order) and returns the result. The remaining bits of x are ignored.

On x86_64 and i686 machines, this function uses the corresponding instruction from the BMI2 instruction set if possible. Without hardware support it is much slower.

SmallCollections.pext(x::Unsigned, y::U) where U <: Union{UInt8,UInt16,UInt32,UInt} -> U

The bits in x corresponding to the 1-bits in y are compressed to the lowest bits of the result; the higher bits are set to 0.

This function is only available on x86_64 and i686 machines and uses the corresponding instruction from the BMI2 instruction set.

SmallCollections.element_type(itr) -> Type
SmallCollections.element_type(::Type) -> Type

Return the element type of an iterator or its type. This differs from eltype in that the element type of a Tuple or NamedTuple is determined via promote_type instead of promote_typejoin. For all other iterators there is no difference.

See also Base.eltype, Base.promote_type, Base.promote_typejoin.

Example

julia> eltype((1, 2, 3.0))
Real

julia> SmallCollections.element_type((1, 2, 3.0))
Float64

SmallCollections.AbstractBitInteger

This type is the union of Base.BitInteger, BitIntegers.AbstractBitSigned and BitIntegers.AbstractBitUnsigned.

SmallCollections.top_set_bit(x::AbstractBitInteger) -> Int

Return the position of the highest set bit in x (counting from 1), or return 0 if x is 0.

This function is analogous to Julia's internal function Base.top_set_bit, but it is also fast and correct for bit integers defined by BitIntegers.jl.

See also Base.top_set_bit, SmallCollections.AbstractBitInteger.