enummify 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16f397e8462e592ee835ac563f64ed9b5f5ae9166b051effe5c397b908ecfdcf
-  data.tar.gz: d71a579357f34609457fb66c55535aa096a785e78d8361f1b14d96c891330b6d
+  metadata.gz: 18c5b92dafe4aae8f25c5389749bbf671cf17facc883ec20da917d3f8750f786
+  data.tar.gz: f7becca7d6149d08d7be46e67a541117e11ab892258b16286d9820b50eb48e29
 SHA512:
-  metadata.gz: a6529db8dfa09dee22f886333559ba379da3ca7d9940210e117ad8cb5edf69a830915be4b923aea00cc9bfa38723a6c4a0c340e94a412cbdd7246873df652e0a
-  data.tar.gz: 012263c4cf3610fde962d10315ef6ea487bd00edfcab29fa264e992ac681ae9cfcd54d1cf2169979edfdf4d8aa59451a16a9ce31553c6449bff95eb3e81a1844
+  metadata.gz: 55776b3e75d317357a17c8985571e98df46b3c99647de0f4ebc7ec2481a1b35cf68cf567342defcc18bad39b016f0d21231cc94914fa176021bcd5f0024d4792
+  data.tar.gz: 0502c8821c91c4157658ebe143ac7936e9a2d542a33d2eeb6feb7c382885c2551457b31eb0bc43fe040d2951c9993cb5c3d7b440de394b3a5f0c2c92bb18f6d2

data/lib/enummify/enum.rb

@@ -7,13 +7,15 @@ module Enummify
     @serialized_to_value = {} #: Hash[String, Enum]
     @values = nil #: Array[Enum]?
 
-    # Register direct constants so only named members belong to the enum.
+    # Register each constant as a member, which assumes every constant in the class body is one.
+    # Groupings such as sets belong outside the enum class.
     #: (Symbol) -> void
     def self.const_added(constant)
       super
 
-      member = const_get(constant, false) #: as Enum
-      serialized = member.send(:finalize, constant)
+      member = const_get(constant, false)
+      # The registry size is the member's declaration index, which EnumSet and EnumHash rely on.
+      serialized = member.send(:finalize, constant, @serialized_to_value.size) #: as String
       if @serialized_to_value.key?(serialized)
         raise ArgumentError, "Duplicate serialized value for #{name}: #{serialized.inspect} is already used"
       end
@@ -32,6 +34,17 @@ module Enummify
       alias _load deserialize
     end
 
+    # Build a set of this enum's members, backed by a bitmask.
+    # The attached class cannot appear in a parameter, so the member type is taken from the arguments instead.
+    # Mixing enums therefore yields a set of the wrong member type, which is rejected wherever that set is used.
+    # At least one member is required, because an empty set has nothing to take the member type from.
+    # Use EnumSet.none for that.
+    #: [M] (M & Enum, *(M & Enum)) -> EnumSet[M]
+    def self.set(member, *members)
+      # A set is unordered, so the first member goes on the end of the rest rather than paying to shift them along.
+      EnumSet.from(self, members.push(member)) #: as EnumSet[M]
+    end
+
     # Look up a member, returning nil for an unknown string.
     #: (String) -> instance?
     def self.try_deserialize(serialized)
@@ -59,6 +72,15 @@ module Enummify
       serialize
     end
 
+    # The member's bit in EnumSet and EnumHash masks, which is 1 shifted left by the ordinal.
+    # It is public only so those classes can read it without a slower private lookup, and is not meant for use
+    # outside Enummify.
+    # It is computed once because shifting at every use measured slower, both when building a mask and when testing
+    # one that is an immediate Integer.
+    # Like the ordinal, it changes when members are inserted or reordered.
+    #: Integer
+    attr_reader :bit
+
     # Enum members are immutable singletons, including copies requested as unfrozen.
     # rubocop:disable Lint/UnusedMethodArgument
     #: (?freeze: bool?) -> self
@@ -77,6 +99,13 @@ module Enummify
       "#<#{self.class.name}: #{serialize.inspect}>"
     end
 
+    # The member's 0-based position in declaration order, which EnumHash uses as its slot.
+    # It is public only so EnumSet and EnumHash can read it without a slower private lookup, and is not meant for use
+    # outside Enummify.
+    # It changes when members are inserted or reordered, so persist serialize rather than this.
+    #: Integer
+    attr_reader :ordinal
+
     #: () -> String
     def serialize
       @serialized || raise(ArgumentError, 'Enum members must be assigned to a constant before serialization')
@@ -90,8 +119,15 @@ module Enummify
     private
 
     # The constant name is only available after construction has returned.
-    #: (Symbol) -> String
-    def finalize(constant)
+    # The ordinal and bit must be assigned here rather than by the caller because this method freezes the member.
+    # Assigning conditionally leaves an already registered member untouched, so aliasing one reaches the caller's
+    # duplicate check rather than failing to write to a frozen member.
+    #: (Symbol, Integer) -> String
+    def finalize(constant, ordinal)
+      unless frozen?
+        @ordinal = ordinal
+        @bit = 1 << ordinal
+      end
       @serialized ||= constant.name
       freeze
       @serialized
@@ -99,6 +135,11 @@ module Enummify
 
     #: (?String?) -> void
     def initialize(serialized = nil)
+      # Declaration order and its bit, assigned during registration.
+      # They start as Integers rather than nil so the readers need no check, because every EnumSet and EnumHash
+      # operation reads one of them.
+      @bit = 0 #: Integer
+      @ordinal = -1 #: Integer
       @serialized = serialized&.dup&.freeze #: String?
     end
   end

data/lib/enummify/enum_hash.rb

@@ -0,0 +1,330 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Enummify
+  # A mutable map keyed by members of a single enum, stored as an array indexed by declaration order.
+  #
+  # A member's ordinal is its slot, so a lookup is an array index rather than a hash of the key.
+  # Keys are held in a bitmask alongside the values, which keeps a stored nil distinct from an absent key and makes
+  # the key set free to compute.
+  #
+  # Keys are checked statically, so nothing is re-checked at runtime.
+  # A key of another enum is a type error, and a consumer that defeats the type checker overwrites an unrelated slot.
+  #
+  # Entries are yielded in declaration order, not insertion order.
+  #: [Key, Value]
+  class EnumHash
+    # The type of NO_DEFAULT, which lets fetch narrow an omitted default away from a given one.
+    class NoDefault; end
+
+    # The default for an omitted fetch default, which is distinct from every value, including nil.
+    NO_DEFAULT = NoDefault.new.freeze #: NoDefault
+
+    private_constant :NO_DEFAULT, :NoDefault
+
+    # Accept type arguments at runtime without depending on sorbet-runtime.
+    # This matches T::Generic#[], which also ignores its arguments and returns self, so a consumer can write
+    # EnumHash[Status, Integer] inside a sig.
+    #: (*untyped) -> singleton(EnumHash)
+    def self.[](*)
+      self
+    end
+
+    # Build a map from a Hash whose type is already declared, which infers both the key and the value type.
+    # Sorbet cannot solve a type parameter out of a Hash literal, so a literal written at the call site yields an
+    # untyped map and its keys go unchecked.
+    # EnumHash.of infers from a literal, so prefer it unless the Hash is already typed.
+    #: [K < Enummify::Enum, V] (Class[K] & singleton(Enummify::Enum), Hash[K, V]) -> EnumHash[K, V]
+    def self.from(enum_class, entries)
+      result = new(enum_class) #: EnumHash[K, V]
+      result.merge!(entries)
+      result
+    end
+
+    # Build a map from key and value pairs, which infers both types even when they are written at the call site.
+    #: [K < Enummify::Enum, V] (Class[K] & singleton(Enummify::Enum), *[K & Enummify::Enum, V]) -> EnumHash[K, V]
+    def self.of(enum_class, *entries)
+      result = new(enum_class) #: EnumHash[K, V]
+      entries.each { |member, value| result[member] = value }
+      result
+    end
+
+    #: (Key & Enummify::Enum) -> Value?
+    def [](member)
+      @entries[member.ordinal]
+    end
+
+    # The slot is written first, so a write to a frozen map raises from its frozen slots before anything changes.
+    # Writing the presence mask first would raise from the map itself, but measured 6 ns slower per overwrite in the
+    # interpreter.
+    #: (Key & Enummify::Enum, Value) -> void
+    def []=(member, value)
+      @entries[member.ordinal] = value
+      bit = member.bit
+      # Overwriting a present key changes neither the key set nor the size, so both stay cached.
+      return if @present & bit != 0
+
+      @present |= bit
+      @size += 1
+      @keys = nil
+    end
+
+    # Equality accepts any object, so unlike the keyed operations it checks what it was given.
+    #: (untyped) -> bool
+    def ==(other)
+      same_enum_and_keys?(other) && other.entries == @entries
+    end
+
+    # Remove every entry, keeping the capacity already allocated for this enum.
+    #: () -> self
+    def clear
+      @entries = Array.new(@entries.length)
+      @present = 0
+      @size = 0
+      @keys = nil
+      self
+    end
+
+    # Remove an entry and return the value it held, or nil when the key was absent.
+    #: (Key & Enummify::Enum) -> Value?
+    def delete(member)
+      ordinal = member.ordinal
+      return nil unless @present[ordinal] == 1
+
+      value = @entries[ordinal]
+      @entries[ordinal] = nil
+      # The key is present, so subtracting its bit clears it.
+      # Subtracting measured faster than ^ in the interpreter, because subtraction has a specialized instruction and ^
+      # is an ordinary method call.
+      @present -= member.bit
+      @size -= 1
+      @keys = nil
+      value
+    end
+
+    # Yield each present key and its value in declaration order.
+    # A while loop over the cached key array measured faster than a block inside the key array's each, because it
+    # skips a block call per entry.
+    #: () { (Key & Enummify::Enum, Value) -> void } -> self
+    def each(&)
+      members = keys.to_a
+      entries = @entries
+      index = 0
+      while index < members.length
+        member = members[index] #: as !nil
+        # Only present keys are yielded, so the slot holds a value that was written rather than an empty slot.
+        value = entries[member.ordinal] #: as Value
+        yield(member, value)
+        index += 1
+      end
+      self
+    end
+
+    #: () -> bool
+    def empty?
+      @present.zero?
+    end
+
+    # Like Hash#eql?, this compares values with eql? rather than ==, so a map holding 1 is not eql? to one holding 1.0.
+    #: (untyped) -> bool
+    def eql?(other)
+      same_enum_and_keys?(other) && other.entries.eql?(@entries)
+    end
+
+    # Return the value for a member.
+    # When the key is absent, return the block's result or else the default, and raise KeyError when given neither.
+    # As in Hash#fetch, a block takes precedence over a default.
+    # Hash#fetch also warns when given both, which the exported RBI's overloads reject statically instead.
+    # The optional default measured about 5 ns slower per call in the interpreter whether it defaulted to a constant
+    # or to nil, so the cost is the optional parameter itself, and under YJIT it measured within noise.
+    #: [D] (Key & Enummify::Enum, ?(D | NoDefault)) ?{ (Key & Enummify::Enum) -> D } -> (Value | D)
+    def fetch(member, default = NO_DEFAULT, &block)
+      ordinal = member.ordinal
+      if @present[ordinal] == 1
+        # A present key was written, so the slot holds a value rather than an empty slot.
+        value = @entries[ordinal] #: as Value
+        return value
+      end
+      return block.call(member) if block
+
+      # Matching on the class rather than comparing with NO_DEFAULT narrows the default to its type parameter.
+      case default
+      when NoDefault then raise KeyError, "key not found: #{member.inspect}"
+      else default
+      end
+    end
+
+    # Freeze the map, first caching its keys and freezing its slots.
+    #: () -> self
+    def freeze
+      prepare_to_freeze
+      super
+    end
+
+    # Maps that are eql? hash alike, so a map can be a Hash key.
+    # Like a Hash, a map that changes while it is a key is no longer found under it.
+    #: () -> Integer
+    def hash
+      [@enum_class, @present, @entries].hash
+    end
+
+    #: () -> String
+    def inspect
+      "#<Enummify::EnumHash[#{@enum_class.name}]: #{to_h.inspect}>"
+    end
+
+    # Masking by the member's bit rather than indexing by ordinal matches EnumSet#include?, for the same reason.
+    #: (Key & Enummify::Enum) -> bool
+    def key?(member)
+      @present & member.bit != 0
+    end
+
+    # Return the present keys as a set, which makes key algebra across two maps a single Integer operation.
+    #: () -> EnumSet[Key & Enummify::Enum]
+    def keys
+      cached = @keys
+      return cached if cached
+
+      built = EnumSet.new(@enum_class, @present)
+      # Marshal.load with freeze: true freezes a map without calling freeze, so such a map builds its keys every time.
+      @keys = built unless frozen?
+      built
+    end
+
+    # A copy starts with this map's slots, size and keys, so only the other entries are stored.
+    #: (EnumHash[Key, Value] | Hash[Key, Value]) -> EnumHash[Key, Value]
+    def merge(entries)
+      dup.merge!(entries)
+    end
+
+    #: (EnumHash[Key, Value] | Hash[Key, Value]) -> self
+    def merge!(entries)
+      # Another map's slots line up with this map's, so they are copied directly rather than stored entry by entry.
+      if entries.is_a?(EnumHash)
+        overlay(entries)
+      else
+        entries.each do |member, value|
+          # A key is always an enum member, which a type member on its own does not carry into the body.
+          key = member #: as Key & Enummify::Enum
+          self[key] = value
+        end
+      end
+      self
+    end
+
+    # The number of present keys, which is counted as keys are added and removed so that reading it walks nothing.
+    #: Integer
+    attr_reader :size
+
+    #: () -> Hash[Key, Value]
+    def to_h
+      result = {} #: Hash[Key, Value]
+      each { |member, value| result[member] = value }
+      result
+    end
+
+    #: () -> String
+    def to_s
+      inspect
+    end
+
+    # Return the values of the present keys, in declaration order of their keys.
+    #: () -> Array[Value]
+    def values
+      result = [] #: Array[Value]
+      each { |_member, value| result << value }
+      result
+    end
+
+    alias each_pair each
+    alias has_key? key?
+    alias include? key?
+    alias length size
+    alias member? key?
+    alias store []=
+
+    protected
+
+    # Exposed to sibling maps so equality can compare state without widening the public API.
+    #: Array[Value?]
+    attr_reader :entries
+
+    #: singleton(Enummify::Enum)
+    attr_reader :enum_class
+
+    #: Integer
+    attr_reader :present
+
+    private
+
+    # new is public only for the reason given at EnumSet#initialize, and is not meant for use outside Enummify.
+    # The capacity is read once, which is sound because members are declared in the class body and never added later.
+    #: (singleton(Enummify::Enum)) -> void
+    def initialize(enum_class)
+      @enum_class = enum_class
+      @entries = Array.new(enum_class.values.length) #: Array[Value?]
+      @present = 0 #: Integer
+      @size = 0 #: Integer
+      @keys = nil #: EnumSet[Key & Enummify::Enum]?
+    end
+
+    # Kernel#clone freezes the copy without calling freeze, so a copy that will be frozen prepares for it here.
+    #: (EnumHash[Key, Value], ?freeze: bool?) -> void
+    def initialize_clone(source, freeze: nil)
+      super
+      prepare_to_freeze if freeze.nil? ? source.frozen? : freeze
+    end
+
+    # A copy gets its own slots, so writing to it leaves the source alone.
+    #: (EnumHash[Key, Value]) -> void
+    def initialize_copy(source)
+      super
+      @entries = @entries.dup
+    end
+
+    # Copy another map's present slots over this map's, then take the union of both key sets.
+    # A while loop over the other map's cached key array measured faster than storing its entries one by one.
+    # Counting the added keys while copying replaced counting the bits of a newly built key set.
+    # It measured about a quarter faster for 8 members, and for larger enums a tenth faster under YJIT but up to 5%
+    # slower in the interpreter.
+    # The slots are written first, so a frozen map raises from its frozen slots before its keys change.
+    #: (EnumHash[Key, Value]) -> void
+    def overlay(other)
+      entries = @entries
+      other_entries = other.entries
+      present = @present
+      size = @size
+      members = other.keys.to_a
+      index = 0
+      while index < members.length
+        member = members[index] #: as !nil
+        ordinal = member.ordinal
+        entries[ordinal] = other_entries[ordinal]
+        size += 1 unless present[ordinal] == 1
+        index += 1
+      end
+      return if size == @size
+
+      @present = present | other.present
+      @size = size
+      @keys = nil
+    end
+
+    # Cache the keys and freeze the slots, which a frozen map could no longer do.
+    # A write stores its value in a slot before it changes the map itself, so frozen slots are what make a write to a
+    # frozen map raise before anything changes.
+    #: () -> void
+    def prepare_to_freeze
+      keys
+      @entries.freeze
+    end
+
+    # Check that another object is a map over the same enum with the same keys, which both == and eql? require.
+    #: (untyped) -> bool
+    def same_enum_and_keys?(other)
+      return false unless other.is_a?(EnumHash)
+
+      other.enum_class.equal?(@enum_class) && other.present == @present
+    end
+  end
+end

data/lib/enummify/enum_set.rb

@@ -0,0 +1,314 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Enummify
+  # An immutable set of members of a single enum, stored as one Integer bitmask.
+  #
+  # Each member occupies the bit at its declaration index, so union, intersection, difference and subset tests are
+  # single Integer operations rather than hash walks.
+  # A mask for an enum with 62 or fewer members is an immediate value, so such a set holds no heap-allocated storage.
+  #
+  # Operations take a set of the same enum and are checked statically, so nothing is re-checked at runtime.
+  # Two enums number their members independently, so combining sets of different enums is a type error, and a
+  # consumer that defeats the type checker gets a meaningless result rather than an exception.
+  #
+  # Sets are immutable: every operation returns a new set.
+  # They are not frozen, because the member array and size are computed on first use and cached.
+  # Materializing eagerly instead would cost far more than the bitmask saves.
+  # Freezing a set caches both first, so a frozen set reads them as quickly as one that is not frozen.
+  #
+  # The type parameter is named Elem so that including Enumerable supplies map, select and friends with the member
+  # type already bound.
+  #: [Elem]
+  class EnumSet
+    include Enumerable
+
+    # Accept type arguments at runtime without depending on sorbet-runtime.
+    # This matches T::Generic#[], which also ignores its arguments and returns self, so a consumer can write
+    # EnumSet[Status] inside a sig.
+    #: (*untyped) -> singleton(EnumSet)
+    def self.[](*)
+      self
+    end
+
+    # Build the set of every member of the enum.
+    #: [M < Enummify::Enum] (Class[M] & singleton(Enummify::Enum)) -> EnumSet[M]
+    def self.all(enum_class)
+      new(enum_class, (1 << enum_class.values.length) - 1)
+    end
+
+    # Build a set from a collection of members, for callers that already have one.
+    # Enumerable is covariant in its element, so an Array of a specific member type is accepted here.
+    #: [M < Enummify::Enum] (Class[M] & singleton(Enummify::Enum), Enumerable[M & Enummify::Enum]) -> EnumSet[M]
+    def self.from(enum_class, members)
+      new(enum_class, mask_for(members))
+    end
+
+    # Build the empty set for the enum.
+    #: [M < Enummify::Enum] (Class[M] & singleton(Enummify::Enum)) -> EnumSet[M]
+    def self.none(enum_class)
+      new(enum_class, 0)
+    end
+
+    # Build a set from the given members.
+    #: [M < Enummify::Enum] (Class[M] & singleton(Enummify::Enum), *(M & Enummify::Enum)) -> EnumSet[M]
+    def self.of(enum_class, *members)
+      new(enum_class, mask_for(members))
+    end
+
+    # Fold members into a bitmask.
+    #: (Enumerable[Enummify::Enum]) -> Integer
+    def self.mask_for(members)
+      mask = 0
+      members.each do |member|
+        mask |= member.bit
+      end
+      mask
+    end
+
+    private_class_method :mask_for
+
+    #: (EnumSet[Elem]) -> EnumSet[Elem]
+    def &(other)
+      derive(@mask & other.mask)
+    end
+
+    #: (EnumSet[Elem]) -> EnumSet[Elem]
+    def +(other)
+      derive(@mask | other.mask)
+    end
+
+    #: (EnumSet[Elem]) -> EnumSet[Elem]
+    def -(other)
+      derive(@mask & ~other.mask)
+    end
+
+    # Equality accepts any object, so unlike the set operations it checks what it was given.
+    #: (untyped) -> bool
+    def ==(other)
+      return false unless other.is_a?(EnumSet)
+
+      other.enum_class.equal?(@enum_class) && other.mask == @mask
+    end
+
+    # Support `case member when SOME_SET`.
+    #: (untyped) -> bool
+    def ===(member)
+      include?(member)
+    end
+
+    #: (EnumSet[Elem]) -> EnumSet[Elem]
+    def ^(other)
+      derive(@mask ^ other.mask)
+    end
+
+    #: (EnumSet[Elem]) -> EnumSet[Elem]
+    def |(other)
+      derive(@mask | other.mask)
+    end
+
+    # Return the set of this enum's members that this set does not contain.
+    #: () -> EnumSet[Elem]
+    def ~
+      derive(((1 << @enum_class.values.length) - 1) ^ @mask)
+    end
+
+    # Return a set that also contains the member.
+    #: (Elem & Enummify::Enum) -> EnumSet[Elem]
+    def add(member)
+      derive(@mask | member.bit)
+    end
+
+    # Return a set without the member.
+    #: (Elem & Enummify::Enum) -> EnumSet[Elem]
+    def delete(member)
+      derive(@mask & ~member.bit)
+    end
+
+    #: (EnumSet[Elem]) -> EnumSet[Elem]
+    def difference(other)
+      derive(@mask & ~other.mask)
+    end
+
+    #: (EnumSet[Elem]) -> bool
+    def disjoint?(other)
+      (@mask & other.mask).zero?
+    end
+
+    # Reading the cached members directly rather than through to_a measured faster in the interpreter, because it
+    # skips two method calls.
+    # @override
+    #: () { (Elem) -> void } -> self
+    def each(&)
+      cached = @members || members #: as Array[Elem]
+      cached.each(&)
+      self
+    end
+
+    #: () -> bool
+    def empty?
+      @mask.zero?
+    end
+
+    #: (untyped) -> bool
+    def eql?(other)
+      self == other
+    end
+
+    # Freeze the set, first caching its members and size.
+    #: () -> self
+    def freeze
+      members
+      size
+      super
+    end
+
+    #: () -> Integer
+    def hash
+      [@enum_class, @mask].hash
+    end
+
+    # Masking by the member's bit measured faster than Set#include? for every enum of 62 or fewer members, whose masks
+    # are immediate Integers, and indexing the mask by ordinal did not in the interpreter.
+    # Enumerable#include? takes any member type, so narrowing the parameter is declared incompatible rather than cast
+    # inside, because the local that a cast needs measured 7 ns slower in the interpreter.
+    # Enums of more than 62 members are not a performance target, so masking is kept even though masking their Bignum
+    # masks allocates, which indexing by ordinal would not.
+    # @override(allow_incompatible: true)
+    #: (Elem & Enummify::Enum) -> bool
+    def include?(member)
+      @mask & member.bit != 0
+    end
+
+    #: () -> String
+    def inspect
+      "#<Enummify::EnumSet[#{@enum_class.name}]: #{members.map(&:serialize).inspect}>"
+    end
+
+    #: (EnumSet[Elem]) -> bool
+    def intersect?(other)
+      !(@mask & other.mask).zero?
+    end
+
+    #: (EnumSet[Elem]) -> EnumSet[Elem]
+    def intersection(other)
+      derive(@mask & other.mask)
+    end
+
+    # Mapping the cached members directly measured faster than Enumerable#map, which yields every member through each.
+    # Called without a block, Array#map returns an Enumerator just as Enumerable#map does.
+    # Sorbet allows overloads only in RBI files, so the blockless form is typed by Enumerable#map in the exported RBI.
+    # @override
+    #: [U] () { (Elem) -> U } -> Array[U]
+    def map(&)
+      cached = @members || members #: as Array[Elem]
+      cached.map(&)
+    end
+
+    #: () -> Integer
+    def size
+      @size || count_members
+    end
+
+    #: (EnumSet[Elem]) -> bool
+    def subset?(other)
+      @mask & other.mask == @mask
+    end
+
+    #: (EnumSet[Elem]) -> bool
+    def superset?(other)
+      mask = other.mask
+      @mask & mask == mask
+    end
+
+    # @override
+    #: () -> Array[Elem]
+    def to_a
+      members #: as Array[Elem]
+    end
+
+    #: () -> String
+    def to_s
+      inspect
+    end
+
+    #: (EnumSet[Elem]) -> EnumSet[Elem]
+    def union(other)
+      derive(@mask | other.mask)
+    end
+
+    alias collect map
+    alias complement ~
+    alias length size
+    alias member? include?
+
+    protected
+
+    # Exposed to sibling sets so operations can read the other side without widening the public API.
+    #: singleton(Enummify::Enum)
+    attr_reader :enum_class
+
+    #: Integer
+    attr_reader :mask
+
+    private
+
+    # Count the members and cache the count.
+    # Ruby has no popcount. Counting "1" in the binary representation measured fastest for small and large masks.
+    #: () -> Integer
+    def count_members
+      counted = @mask.to_s(2).count('1')
+      # Kernel#clone and Marshal.load with freeze: true freeze a set without calling freeze, so such a set counts every
+      # time.
+      return counted if frozen?
+
+      @size = counted
+    end
+
+    # Build a sibling set over the same enum.
+    #: (Integer) -> EnumSet[Elem]
+    def derive(mask)
+      EnumSet.new(@enum_class, mask)
+    end
+
+    # new is public only because hiding it with private_class_method adds a visibility override that Ruby 4.0's
+    # opt_new instruction does not recognize.
+    # Every new set then took the slow path, which measured about twice as slow in the interpreter and three times as
+    # slow under YJIT.
+    # It is not meant for use outside Enummify, and the exported RBI declares no initialize, so Sorbet rejects a
+    # consumer's call to new that passes it an enum and a mask.
+    #: (singleton(Enummify::Enum), Integer) -> void
+    def initialize(enum_class, mask)
+      @enum_class = enum_class
+      @mask = mask
+      @members = nil #: Array[Enummify::Enum]?
+      @size = nil #: Integer?
+    end
+
+    # Materialize the members once and cache them.
+    # Walking the mask is slower than iterating an Array, so every iteration after the first reads the cache.
+    # Extracting the lowest set bit costs one step per present member and yields declaration order.
+    # Negating as 0 - remaining and clearing by subtraction measured faster than -remaining and ^, because binary
+    # minus has a specialized instruction while unary minus and ^ are ordinary method calls.
+    #: () -> Array[Enummify::Enum]
+    def members
+      cached = @members
+      return cached if cached
+
+      materialized = []
+      values = @enum_class.values
+      remaining = @mask
+      while remaining != 0
+        lowest = remaining & (0 - remaining)
+        materialized << values[lowest.bit_length - 1]
+        remaining -= lowest
+      end
+      materialized.freeze
+      # Kernel#clone and Marshal.load with freeze: true freeze a set without calling freeze, so such a set materializes
+      # every time.
+      return materialized if frozen?
+
+      @members = materialized
+    end
+  end
+end

data/lib/enummify/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Enummify
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/enummify.rb

@@ -2,4 +2,6 @@
 # frozen_string_literal: true
 
 require_relative 'enummify/enum'
+require_relative 'enummify/enum_hash'
+require_relative 'enummify/enum_set'
 require_relative 'enummify/version'

data/rbi/enummify.rbi

@@ -13,6 +13,16 @@ module Enummify
       alias _load deserialize
     end
 
+    sig do
+      type_parameters(:M)
+        .params(
+          member: T.all(T.type_parameter(:M), Enummify::Enum),
+          members: T.all(T.type_parameter(:M), Enummify::Enum)
+        )
+        .returns(EnumSet[T.type_parameter(:M)])
+    end
+    def self.set(member, *members); end
+
     sig { params(serialized: String).returns(T.nilable(T.attached_class)) }
     def self.try_deserialize(serialized); end
 
@@ -22,6 +32,11 @@ module Enummify
     sig { params(_depth: Integer).returns(String) }
     def _dump(_depth); end
 
+    # The member's bit in EnumSet and EnumHash masks.
+    # It is public only so those classes can read it quickly, and is not meant for use outside Enummify.
+    sig { returns(Integer) }
+    def bit; end
+
     sig { params(freeze: T.nilable(T::Boolean)).returns(T.self_type) }
     def clone(freeze: true); end
 
@@ -31,6 +46,11 @@ module Enummify
     sig { returns(String) }
     def inspect; end
 
+    # The member's 0-based position in declaration order.
+    # It is public only so EnumSet and EnumHash can read it quickly, and is not meant for use outside Enummify.
+    sig { returns(Integer) }
+    def ordinal; end
+
     sig { returns(String) }
     def serialize; end
 
@@ -42,4 +62,240 @@ module Enummify
     sig { params(serialized: T.nilable(String)).void }
     def initialize(serialized = nil); end
   end
+
+  # A mutable map keyed by members of a single enum, stored as an array indexed by declaration order.
+  # new is public at runtime only for speed, and initialize is deliberately not declared here, so Sorbet rejects a
+  # call to new with arguments.
+  class EnumHash
+    extend T::Generic
+    extend T::Sig
+
+    Key = type_member
+    Value = type_member
+
+    sig do
+      type_parameters(:K, :V)
+        .params(
+          enum_class: T.all(T::Class[T.type_parameter(:K)], T.class_of(Enummify::Enum)),
+          entries: T::Hash[T.type_parameter(:K), T.type_parameter(:V)]
+        )
+        .returns(EnumHash[T.type_parameter(:K), T.type_parameter(:V)])
+    end
+    def self.from(enum_class, entries); end
+
+    sig do
+      type_parameters(:K, :V)
+        .params(
+          enum_class: T.all(T::Class[T.type_parameter(:K)], T.class_of(Enummify::Enum)),
+          entries: [T.all(T.type_parameter(:K), Enummify::Enum), T.type_parameter(:V)]
+        )
+        .returns(EnumHash[T.type_parameter(:K), T.type_parameter(:V)])
+    end
+    def self.of(enum_class, *entries); end
+
+    sig { params(member: T.all(Key, Enummify::Enum)).returns(T.nilable(Value)) }
+    def [](member); end
+
+    sig { params(member: T.all(Key, Enummify::Enum), value: Value).void }
+    def []=(member, value); end
+
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def ==(other); end
+
+    sig { returns(T.self_type) }
+    def clear; end
+
+    sig { params(member: T.all(Key, Enummify::Enum)).returns(T.nilable(Value)) }
+    def delete(member); end
+
+    sig { params(block: T.proc.params(member: T.all(Key, Enummify::Enum), value: Value).void).returns(T.self_type) }
+    def each(&block); end
+
+    sig { returns(T::Boolean) }
+    def empty?; end
+
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def eql?(other); end
+
+    # The overloads mirror Hash#fetch, and accept a default or a block but not both.
+    sig { params(member: T.all(Key, Enummify::Enum)).returns(Value) }
+    sig do
+      type_parameters(:D)
+        .params(member: T.all(Key, Enummify::Enum), default: T.type_parameter(:D))
+        .returns(T.any(Value, T.type_parameter(:D)))
+    end
+    sig do
+      type_parameters(:D)
+        .params(
+          member: T.all(Key, Enummify::Enum),
+          block: T.proc.params(member: T.all(Key, Enummify::Enum)).returns(T.type_parameter(:D))
+        )
+        .returns(T.any(Value, T.type_parameter(:D)))
+    end
+    def fetch(member, default = T.unsafe(nil), &block); end
+
+    sig { returns(Integer) }
+    def hash; end
+
+    sig { returns(String) }
+    def inspect; end
+
+    sig { params(member: T.all(Key, Enummify::Enum)).returns(T::Boolean) }
+    def key?(member); end
+
+    sig { returns(EnumSet[T.all(Key, Enummify::Enum)]) }
+    def keys; end
+
+    sig { params(entries: T.any(EnumHash[Key, Value], T::Hash[Key, Value])).returns(EnumHash[Key, Value]) }
+    def merge(entries); end
+
+    sig { params(entries: T.any(EnumHash[Key, Value], T::Hash[Key, Value])).returns(T.self_type) }
+    def merge!(entries); end
+
+    sig { returns(Integer) }
+    def size; end
+
+    sig { returns(T::Hash[Key, Value]) }
+    def to_h; end
+
+    sig { returns(String) }
+    def to_s; end
+
+    sig { returns(T::Array[Value]) }
+    def values; end
+
+    alias each_pair each
+    alias has_key? key?
+    alias include? key?
+    alias length size
+    alias member? key?
+    alias store []=
+  end
+
+  # An immutable set of members of a single enum, stored as one Integer bitmask.
+  # new is public at runtime only for speed, and initialize is deliberately not declared here, so Sorbet rejects a
+  # call to new with arguments.
+  class EnumSet
+    extend T::Generic
+    extend T::Sig
+    include Enumerable
+
+    Elem = type_member
+
+    sig do
+      type_parameters(:M)
+        .params(enum_class: T.all(T::Class[T.type_parameter(:M)], T.class_of(Enummify::Enum)))
+        .returns(EnumSet[T.type_parameter(:M)])
+    end
+    def self.all(enum_class); end
+
+    sig do
+      type_parameters(:M)
+        .params(
+          enum_class: T.all(T::Class[T.type_parameter(:M)], T.class_of(Enummify::Enum)),
+          members: T::Enumerable[T.all(T.type_parameter(:M), Enummify::Enum)]
+        )
+        .returns(EnumSet[T.type_parameter(:M)])
+    end
+    def self.from(enum_class, members); end
+
+    sig do
+      type_parameters(:M)
+        .params(enum_class: T.all(T::Class[T.type_parameter(:M)], T.class_of(Enummify::Enum)))
+        .returns(EnumSet[T.type_parameter(:M)])
+    end
+    def self.none(enum_class); end
+
+    sig do
+      type_parameters(:M)
+        .params(
+          enum_class: T.all(T::Class[T.type_parameter(:M)], T.class_of(Enummify::Enum)),
+          members: T.all(T.type_parameter(:M), Enummify::Enum)
+        )
+        .returns(EnumSet[T.type_parameter(:M)])
+    end
+    def self.of(enum_class, *members); end
+
+    sig { params(other: EnumSet[Elem]).returns(EnumSet[Elem]) }
+    def &(other); end
+
+    sig { params(other: EnumSet[Elem]).returns(EnumSet[Elem]) }
+    def +(other); end
+
+    sig { params(other: EnumSet[Elem]).returns(EnumSet[Elem]) }
+    def -(other); end
+
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def ==(other); end
+
+    sig { params(member: T.untyped).returns(T::Boolean) }
+    def ===(member); end
+
+    sig { params(other: EnumSet[Elem]).returns(EnumSet[Elem]) }
+    def ^(other); end
+
+    sig { params(other: EnumSet[Elem]).returns(EnumSet[Elem]) }
+    def |(other); end
+
+    sig { returns(EnumSet[Elem]) }
+    def ~; end
+
+    sig { params(member: T.all(Elem, Enummify::Enum)).returns(EnumSet[Elem]) }
+    def add(member); end
+
+    sig { params(member: T.all(Elem, Enummify::Enum)).returns(EnumSet[Elem]) }
+    def delete(member); end
+
+    sig { params(other: EnumSet[Elem]).returns(EnumSet[Elem]) }
+    def difference(other); end
+
+    sig { params(other: EnumSet[Elem]).returns(T::Boolean) }
+    def disjoint?(other); end
+
+    sig { params(block: T.proc.params(member: Elem).void).returns(T.self_type) }
+    def each(&block); end
+
+    sig { returns(T::Boolean) }
+    def empty?; end
+
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def eql?(other); end
+
+    sig { returns(Integer) }
+    def hash; end
+
+    sig { params(member: Elem).returns(T::Boolean) }
+    def include?(member); end
+
+    sig { returns(String) }
+    def inspect; end
+
+    sig { params(other: EnumSet[Elem]).returns(T::Boolean) }
+    def intersect?(other); end
+
+    sig { params(other: EnumSet[Elem]).returns(EnumSet[Elem]) }
+    def intersection(other); end
+
+    sig { returns(Integer) }
+    def size; end
+
+    sig { params(other: EnumSet[Elem]).returns(T::Boolean) }
+    def subset?(other); end
+
+    sig { params(other: EnumSet[Elem]).returns(T::Boolean) }
+    def superset?(other); end
+
+    sig { returns(T::Array[Elem]) }
+    def to_a; end
+
+    sig { returns(String) }
+    def to_s; end
+
+    sig { params(other: EnumSet[Elem]).returns(EnumSet[Elem]) }
+    def union(other); end
+
+    alias complement ~
+    alias length size
+    alias member? include?
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: enummify
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Justin D. Harris
@@ -58,6 +58,8 @@ extra_rdoc_files: []
 files:
 - lib/enummify.rb
 - lib/enummify/enum.rb
+- lib/enummify/enum_hash.rb
+- lib/enummify/enum_set.rb
 - lib/enummify/version.rb
 - rbi/enummify.rbi
 homepage: https://github.com/juharris/enummify
@@ -80,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Typed Ruby enums using RBS.
 test_files: []