BitMask(bitmask::Integer)

Structure used internally by FlagSets for default constructor of subtypes of FlagSet.

FlagSet{FlagType,BaseType<:Integer} <: AbstractSet{FlagType}

Supertype of sets which are subsets of a finite universe of objects (flags), where each set is encoded as an integer of type BaseType. Flag sets are implemented similarly to BitSets.

If T <: FlagSet{B,F}, then typemax(T) is a finite set of flags of type F. If set isa T, then set is a subset of typemax(T).

See @flagset and @flagset_type for more information.

flags(T)

Return the set of flags of type T as a Tuple.

Examples

julia> @flagset RoundingFlags RoundDown RoundUp RoundNearest

julia> flags(RoundingFlags)
(RoundingMode{:Down}(), RoundingMode{:Up}(), RoundingMode{:Nearest}())

flags(x::FlagSet)

Return the set of flags in x as a Tuple.

Examples

julia> @symbol_flagset FontFlags bold=1 italic=2 large=4

julia> flags(FontFlags(3))
(:bold, :italic)

@flagset T [key_1 =] [bit_1 -->] flag_1 [key_2 =] [bit_2 -->] flag_2...

Create a FlagSet subtype with name T and the flags supplied (evaluated). Each instance of the created type represents a subset of {flag_1, flag_2, ...}. The associated bit_1,bit_2, etc, if provided, must be distinct positive powers of 2.

The following constructors are provided: - T(itr): construct a set of the flags from the given iterable object. Each flag must be one of flag_1, flag_2, etc; - T(): construct an empty set; - T(bitmask::Integer): construct a set of flags associated with each bit in mask; - T(; kwargs...): each key_i can be given as a keyword with boolean value (key_i = true includes flag_i, key_i = false excludes it).

It should be safe to new constructor methods and/or overriding the methods provided (except the default which is defined for the internal struct FlagSets.BitMask).

Examples

julia> @flagset RoundingFlags begin
    down = RoundDown
    up = RoundUp
    near = 16 --> RoundNearest
    64 --> RoundNearestTiesUp  # No key
end

julia> RoundingFlags([RoundDown,RoundUp])
RoundingFlags with 2 elements:
  RoundingMode{:Down}()
  RoundingMode{:Up}()

julia> RoundingFlags(near = true, up = false, RoundNearestTiesUp = true)
RoundingFlags with 2 elements:
  RoundingMode{:Nearest}()
  RoundingMode{:NearestTiesUp}()

julia> RoundingFlags(1)
RoundingFlags with 1 element:
  RoundingMode{:Down}()

julia> for flag in RoundingFlags(3); println(flag) end
RoundingMode{:Down}()
RoundingMode{:Up}()

julia> RoundingFlags(3) | RoundingFlags(16)
RoundingFlags with 3 elements:
  RoundingMode{:Down}()
  RoundingMode{:Up}()
  RoundingMode{:Nearest}()

julia> eltype(RoundingFlags)
RoundingMode

julia> typemax(RoundingFlags)
RoundingFlags with 4 elements:
  RoundingMode{:Down}()
  RoundingMode{:Up}()
  RoundingMode{:Nearest}()
  RoundingMode{:NearestTiesUp}()

julia> typemin(RoundingFlags)
RoundingFlags([])

If some flag_i is a Symbol and key_i is not explicitly given, key_i is set to flag_i. Therefore, both macros below are equivalent:

@flagset FontFlags :bold :italic 8 --> :large
@flagset FontFlags begin
    bold = :bold
    italic = :italic
    large = 8 --> :large
end

The following syntaxes can be used to provide FlagType and/or BaseType:

@flagset T {FlagType,BaseType} ... # Use supplied types
@flagset T {FlagType} ...          # Detect BaseType
@flagset T {FlagType,_} ...        # Detect BaseType too
@flagset T {_,BaseType} ...        # Detect FlagType
@flagset T {} ...                  # Braces are ignored

If FlagType is not provided or is _, it is inferred from the flag values (like array constructors do). Otherwise, flag_1, flag_2, etc, must be of type FlagType.

If BaseType is not provided or is _, some convenient integer type is inferred (UInt32 is used if possible, for maximum compatibility with C code). Otherwise, it must be an Integer type big enough to represent each bit_i.

Each instance of T can be converted to BaseType, where each bit set in the converted BaseType corresponds to a flag in the flag set. read and write perform these conversions automatically. In case the flagset is created with a non-default BaseType, Integer(flagset) will return the integer flagset with the type BaseType.

julia> convert(Int, RoundingFlags(up = true, near = true))
6

julia> convert(Integer, RoundingFlags(up = true, near = true))
0x00000006

To list flags of a flag set type or instance, use flags, e.g.

julia> flags(RoundingFlags)
(RoundingMode{:Down}(), RoundingMode{:Up}(), RoundingMode{:Nearest}())

julia> flags(RoundingFlags(3))
(RoundingMode{:Down}(), RoundingMode{:Up}())

@symbol_flagset T[::BaseType] flag_1[=bit_1] flag_2[=bit_2] ...

Create a FlagSet{Symbol,BaseType} subtype with name T and the flags supplied. Each instance of T represents a subset of {:flag1, :flag2, ...}. The associated bit_1,bit_2, etc, if provided, must be distinct positive powers of 2.

The following constructors are provided: - T(itr): construct a set of the symbols from the given iterable object. Each symbol must be one of :flag_1, :flag_2, etc; - T(): construct an empty set; - T(sym1::Symbol, syms::Symbol...): equivalent to T([sym1, syms...]) - T(bitmask::Integer): construct a set of flags associated with each bit in mask; - T(; kwargs...): each flag_i can be supplied as a boolean value (flag_i = true includes :flag_i, flag_i = false excludes it).

It should be safe to new constructor methods and/or overriding the methods provided (except the default using an internal struct, i.e., T(::FlagSets.BitMask)).

To construct sets of non-Symbol constants, use the macro @flagset.

Examples

julia> @symbol_flagset FontFlags bold=1 italic=2 large=4

julia> FontFlags(1)
FontFlags with 1 element:
  :bold

julia> FontFlags(:bold, :italic)
FontFlags with 2 elements:
  :bold
  :italic

julia> FontFlags(bold=true, italic=false)
FontFlags with 1 element:
  :bold

julia> for flag in FontFlags(3); println(flag) end
bold
italic

julia> FontFlags(3) | FontFlags(4)
FontFlags with 3 elements:
  :bold
  :italic
  :large

julia> eltype(FontFlags)
Symbol

julia> typemax(FontFlags)
FontFlags with 3 elements:
  :bold
  :italic
  :large

julia> typemin(FontFlags)
FontFlags([])

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

@symbol_flagset T begin
    flag_1 [= x]
    flag_2 [= y]
end

If BaseType is provided, it must be an Integer type big enough to represent each bit_i. Otherwise, some convenient integer type is inferred (UInt32 is used if possible, to guarantee compatibility with C code). Each instance of T can be converted to BaseType, where each bit set in the converted BaseType corresponds to a flag in the flag set. read and write perform these conversions automatically. In case the flagset is created with a non-default BaseType, Integer(flagset) will return the integer flagset with the type BaseType.

julia> convert(Int, FontFlags(bold=true, italic=false))
1

julia> convert(Integer, FontFlags(bold=true, italic=false))
0x00000001

To list flags of a flag set type or instance, use flags, e.g.

julia> flags(FontFlags)
(:bold, :italic, :large)

julia> flags(FontFlags(3))
(:bold, :italic)