BlockEnums.jl

module BlockEnums

BlockEnums is a package (and module) providing the type BlockEnum. Concrete subtypes are created with the @blockenum macro, which is similar to Enums.@enum.

BlockEnum{T<:Integer}

The abstract supertype of all enumerated types defined with @blockenum.

@blockenum EnumName[::BaseType] value1[=x] value2[=y]
@blockenum (EnumName[::BaseType], [keyword=val,...]) [value1, value2,...]

Create a BlockEnum{BaseType} subtype with name EnumName and enum member values of value1 and value2 with optional assigned values of x and y, respectively.

Keywords

• mod=Modname – EnumName and its instances will be namespaced in a module Modname, which will be created.
• blocklength=n – n is a literal Int. The common length of each "block" of enums.
• numblocks=m – m is a literal Int. The intial number of blocks to create.
• compactshow – a literal Bool. If true, then do not print the equivalent BaseType value of instances.

EnumName can be used just like other types and enum member values as regular values, such as

Examples

julia> @blockenum Fruit apple=1 orange=2 kiwi=3

julia> f(x::Fruit) = "I'm a Fruit with value: $(Int(x))"
f (generic function with 1 method)

julia> f(apple)
"I'm a Fruit with value: 1"

julia> Fruit(1)
apple::Fruit = 1

Add more instances like this

julia> @add Fruit banana lemon

Values can also be specified inside a begin block, e.g.

@blockenum EnumName begin
    value1
    value2
end

BaseType, which defaults to Int32, must be a primitive subtype of Integer. Member values can be converted between the enum type and BaseType. read and write perform these conversions automatically. In case the enum is created with a non-default BaseType, Integer(value1) will return the integer value1 with the type BaseType.

To list all the instances of an enum use instances, e.g.

julia> instances(Fruit)
(apple, orange, kiwi, banana, lemon)

It is possible to construct a symbol from an enum instance:

julia> Symbol(apple)
:apple

Examples of adding instances to blocks.

julia> using BlockEnums

julia> @blockenum (Myenum, mod=MyenumMod, blocklength=100, numblocks=10, compactshow=false)

julia> @addinblock Myenum 1 a b c
c::Myenum = 3

julia> @addinblock Myenum 3 x y z
z::Myenum = 203

julia> BlockEnums.blockindex(MyenumMod.y)
3

See @add, @addinblock

namemap(::Type{<:BlockEnum})

Return the Dict mapping all values to name symbols.

This is not a method of of the function of the same name with methods defined on Base.Enum. Rather it is a function in the BlockEnums module. Perhaps this should not be advertized or exposed.

basetype(V::Type{<:BlockEnum{T}})

Return T, which is the bitstype whose values are bitcast to the type V. This is the type of the value returned by Integer(x::V). The type is in a sense the underlying type of V.

val(x::BlockEnum{T})

Return x bitcast to type T.

getmodule(t::Type{<:BlockEnum})

Get the module in which t is defined.

compact_show(t::Type{<:BlockEnum})

Return true if compact show was set when t was defined. This omits printing the corresponding integer when printing. To enable compact show, include the key/val pair compactshow=true when defining t.

instances(t::Type{<:BlockEnum})

Return a Tuple of all of the named values of t.

length(T::Type{<:BlockEnum})

Return the number of instances of type T.

addblocks!(t::Type{<:BlockEnum}), nblocks::Integer)

Add and initialize nblocks blocks to the bookkeeping for t. The number of active blocks for the type is returned.

maxvalind(t::Type{<:BlockEnum}, block_num::Integer)

Return the largest index for which a name has been assigned in the block_numth block t. This number is constrained to be within the values in the block.

numblocks(t::Type{<:BlockEnum{T}}) where T <: Integer

Return the number of blocks for which bookkeeping has been set up. The set of values of t is the nonzero values of T, which is typically very large. Bookkeeping of blocks requires storage. So you can only set up some of the blocks for use.

blocklength(t::Type{<:BlockEnum})

Get the length of blocks that the range of values of t is partitioned into.

blockindex(v::BlockEnum)

Get the index of the block of values v belongs to.

blockrange(t::Type{<:BlockEnum}, blockind)

Return the range of values of t in block number blockind.

add!(enumname, syms...)

Add symbols syms to BlockEnum enumname. This function is called by the macro @add.

@add enunmame syms...

Add symbols syms to BlockEnum named enumname.

Examples

@blockenum MyEnum
@add MyEnum a b

julia> a
a::MyEnum = 0

julia> b
b::MyEnum = 1

add_in_block!(a, _block::Union{Integer, BlockEnum}, syms...)

This is the function called by @addinblock.

@addinblock EnumName blocknum sym1 [sym2,..]

Add symbols sym1, sym2, etc. to block number blocknum of BlockEnum named EnunName.

inblock(benum::BlockEnum, blockind)

Return true if benum is in block number blockind of the type of benum.

gtblock(benum::BlockEnum, blockind)

Return true if benum is in a block number of the type of benum larger than blockind.

ltblock(benum::BlockEnum, blockind)

Return true if benum is in a block number of the type of benum smaller than blockind.