API Reference

@bitflags [mutable] struct MyFlags
    flagA
    flagB
    _ # padding
    flagC
end

Construct a struct representing various boolean flags, stored in a compact format where each flag takes up a single bit. Field access gives a Bool, explicit padding can be declared by naming a field _. Field names (other than padding) need to be unique. The struct can optionally be marked mutable.

See also @bitfield.

Examples

julia> @bitflags mutable struct MyFlags
           flagA
           flagB
           _ # padding
           flagC
       end

julia> flags = MyFlags(true, false, true)
MyFlags(flagA: true, flagB: false, flagC: true)

julia> flags.flagA
true

julia> flags.flagB
false

julia> flags.flagB = true
true

julia> flags.flagB
true

julia> sizeof(flags)
1

@bitfield [mutable] struct MyBits
    a:2
    b:3
    _[:3] # padding; width is assumed 1 bit if the length is omitted
    c:1
end

Construct a struct representing various fields, with their size specified in bits. The struct can optionally be marked mutable.

See also @bitflags.

Extended Help

The fields are stored in a compact format where each field only takes up the specified number of bits. Field access gives an unsigned integer, whose lower bits are the bits of the accessed field. The upper bits are zeroed. As a special case, fields with size 1 return a Bool. Explicit padding can be specified by naming a field _, with freely chosen width. Field names (other than padding) need to be unique. The specified number of bits must be >= 0.

The order the fields are given in is the order the fields are stored in. The first field occupies the least significant bits, followed by the second field, up to the last field, which is stored in the most significant bits.

For example, the struct given above has this layout:

where _ is padding, with undefined value.

The constructor created for structs defined with @bitfield takes any type in Union{Int128, Int16, Int32, Int64, Int8, UInt128, UInt16, UInt32, UInt64, UInt8, Bool} and converts it to the correct size by truncating the upper bits, before storing the truncated value in the object. This truncation also occurs when writing to a field of a mutable object.

Examples

julia> @bitfield struct MyBits
           a:2
           b:3
           _:3 # padding
           c:1
       end

julia> bits = MyBits(1,2,3)
MyBits(a: 0x1, b: 0x2, c: true)

julia> bits.a
0x01

julia> bits.b
0x02

julia> bits.c
true

propertyoffset(::Type{T}, s::Symbol) -> Int

Gives the offset (in bits) the field s is placed at in objects of type T.

See also FieldFlags.fieldsize.

julia> @bitflags mutable struct MyFlags
           flagA
           _ # padding
           flagB
       end

julia> FieldFlags.propertyoffset(MyFlags, :flagA)
0

julia> FieldFlags.propertyoffset(MyFlags, :flagB)
2

fieldsize(::Type{T}, s::Symbol) -> Int

Gives the size (in bits) the field s takes up in objects of type T.

See also FieldFlags.propertyoffset.

julia> @bitfield mutable struct MyBits
           a:2
           _ # padding
           b:3
       end

julia> FieldFlags.fieldsize(MyBits, :a)
2

julia> FieldFlags.fieldsize(MyBits, :b)
3

bitfieldnames(::Type{T}) -> NTuple{N, Symbol}
bitfieldnames(::T) -> NTuple{N, Symbol}

Gives the field names of the given bitfield object or type.

julia> @bitfield mutable struct MyBits
           a:2
           _ # padding
           b:3
       end

julia> FieldFlags.bitfieldnames(MyBits)
(:a, :b)

julia> FieldFlags.bitfieldnames(MyBits(1,2))
(:a, :b)

bitflags(::Expr)

The given `Expr(:struct) has the following format

struct MyFlags
    a
    b
    _
end

which is turned into

struct MyFlags
    a:1
    b:1
    _:1
end

before being passed to FieldFlags.bitfield.

Some minimal expression filtering is performed.

See also @bitflags, @bitfield.

bitfield(expr::Expr)

Takes an Expr(:struct) of the form

struct MyStruct
    a:x
    b:y
    _
    _:z
end

where a, b are potential field names, x, y, and z are desired bitwidths for those fields as integer literals, _ is padding and returns the following expression:

Expr(:block,
    typedefs,
    typefuncs,
    conv,
    eqhash,
    shows,
    propsize,
    propoffset,
    getprop,
    setprop
)

Where typedefs are the new user-facing type definition and the internal type definitions, typefuncs are type related functions from Base for the new types, conv are convert methods to those types, propsize is the implementation for FieldFlags.fieldsize, propoffset is the implementation for FieldFlags.propertyoffset, getprop is the definition for the getproperty overload for the user facing type and setprop is the definition for the setproperty! overloda for the user facing type.

See also FieldFlags.bitflags.

cast_extend_truncate(T::DataType, x) -> T

Takes an object x of a primitive type and either bitcasts it to type T (if their sizes are egal), zero extends the bitrepresentation of x to the size of T, or truncates the bitrepresentation of x to sizeof(T).

Returns a T.

See also FieldFlags.cast_or_extend.

cast_or_extend(T::DataType, x) -> T

Takes an object x of a primitive type and either bitcasts it to T (if their sizes are egal) or zero-extends the bitrepresentation of x to the size of T. sizeof(x) <= sizeof(T) must hold.

Returns a T.

See also FieldFlags.cast_extend_truncate.