philiprehberger-enum 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 870e3019e2981514154a2d9e9ea3c21398fbd009fe99e9511ecebcfc5162e6ef
-  data.tar.gz: fd6725e19f0dc48131ec4ee3143cf97c5db29b63bf30dbea8ed0edbc26fa1d15
+  metadata.gz: 2b55ad3be49fe204aa1e0588dca8f25995f0589f49c3c0aa6c77e670e03fa7b0
+  data.tar.gz: dd879b2ed6f61c12c3805b6b6a86cc4aac4391e383251a3188a60925989685ab
 SHA512:
-  metadata.gz: 4ac450c34e480d9036875c23c0e91f691d8b08695c7fab01f326ca5d5af53663d125786ffc05503bd37c4b98122cdb1d25e1c4305cf2d3507323df3692cd2b47
-  data.tar.gz: c63863fc33b8c4d25fd09c038ad25c9e782649077bae2bb4d9fca096453ab68d84f621c807f46af57fbba8225115a0c60e3a8fde7ccbcb6946ec9831c6d34ca9
+  metadata.gz: c29b4d8bb1a41e1a045363596d673febbaf7c6c984d99754ca1caafbbc7535ffdf92cbd3693464af201924f1d1cd2961b135f7c3fd97c4d66f5f34875f93e389
+  data.tar.gz: 50e33959a328aa0781d2a863df411e76b580ce6788a7b5bbf667078c74dfcb539eaa1b82c92612b2e34e7086dcb32e33de589a43edcc0b6107520c7c72e38e21

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-16
+
+### Added
+- `Enum.slice(*names)` returns an array of members matching the given symbol names, silently skipping unknown names
+- `Enum.sample(n = nil)` returns a random member when called without argument, or an array of n random members when called with an integer
+
+## [0.3.0] - 2026-04-09
+
+### Added
+- `Enum.fetch(name)` strict lookup that raises `Error` if the name is not a member (case-insensitive fallback)
+- `Enum.fetch_by_value(val)` strict value lookup that raises `Error` if no member has the given value
+- `Enum.names` returns a frozen array of all member name symbols in declaration order
+- `Enum.values` returns a frozen array of all member values in declaration order
+- `Enum.first` / `Enum.last` return the first and last declared members
+
 ## [0.2.0] - 2026-04-03
 
 ### Added

data/README.md

@@ -84,6 +84,45 @@ Status.size              # => 3
 Status.count             # => 3
 ```
 
+### Strict Lookup
+
+`fetch` and `fetch_by_value` raise an error instead of returning `nil`:
+
+```ruby
+Status.fetch(:draft)          # => Status::DRAFT
+Status.fetch(:unknown)        # raises Philiprehberger::Enum::Error
+HttpCode.fetch_by_value(200)  # => HttpCode::OK
+HttpCode.fetch_by_value(999)  # raises Philiprehberger::Enum::Error
+```
+
+### Names, Values, First & Last
+
+```ruby
+HttpCode.names   # => [:ok, :not_found, :server_error]
+HttpCode.values  # => [200, 404, 500]
+Status.first     # => Status::DRAFT
+Status.last      # => Status::ARCHIVED
+```
+
+### Slice
+
+`slice` returns members matching the given names, silently skipping any that are unknown:
+
+```ruby
+Status.slice(:draft, :archived)          # => [Status::DRAFT, Status::ARCHIVED]
+Status.slice(:draft, :nonexistent)       # => [Status::DRAFT]
+Status.slice(:archived, :draft)          # => [Status::ARCHIVED, Status::DRAFT]
+```
+
+### Sample
+
+`sample` returns a random member. Pass an integer to get an array:
+
+```ruby
+Status.sample       # => Status::DRAFT  (random)
+Status.sample(2)    # => [Status::PUBLISHED, Status::ARCHIVED]  (random)
+```
+
 ### Case-Insensitive Lookup
 
 `from_name` tries an exact match first, then falls back to case-insensitive:
@@ -133,9 +172,16 @@ Status::DRAFT.to_json  # => '{"name":"draft","ordinal":0,"value":null}'
 | `.to_h` | Return `{ name_symbol => value }` hash |
 | `.members_by_value` | Return `{ value => member }` reverse lookup hash |
 | `.size` / `.count` | Return the number of defined members |
+| `.names` | Return a frozen array of member name symbols |
+| `.values` | Return a frozen array of member values |
+| `.first` / `.last` | Return the first or last declared member |
+| `.fetch(name)` | Strict lookup by name; raises `Error` if not found |
+| `.fetch_by_value(val)` | Strict lookup by value; raises `Error` if not found |
 | `.from_name(name)` | Look up by name (case-insensitive fallback) |
 | `.from_string(string)` | Look up a member by string name |
 | `.from_value(val)` | Look up a member by custom value |
+| `.slice(*names)` | Return members matching the given symbol names, skipping unknowns |
+| `.sample(n = nil)` | Return a random member, or array of n random members |
 | `.valid?(name)` | Check if a name is a valid member |
 | `#name` | Return the member name as a symbol |
 | `#ordinal` | Return the ordinal position |

data/lib/philiprehberger/enum/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   class Enum
-    VERSION = '0.2.0'
+    VERSION = '0.4.0'
   end
 end

data/lib/philiprehberger/enum.rb

@@ -168,6 +168,56 @@ module Philiprehberger
         member_registry.values.find { |m| m.value == val }
       end
 
+      # Look up a member by name, raising if not found
+      #
+      # @param name [Symbol, String] the member name
+      # @return [Enum] the member
+      # @raise [Error] if the name is not a valid member
+      def fetch(name)
+        from_name(name) || raise(Error, "no member #{name.inspect} on #{self}")
+      end
+
+      # Look up a member by value, raising if not found
+      #
+      # @param val [Object] the value to search for
+      # @return [Enum] the member
+      # @raise [Error] if the value is not found
+      def fetch_by_value(val)
+        from_value(val) || raise(Error, "no member with value #{val.inspect} on #{self}")
+      end
+
+      # Return all member names in declaration order
+      #
+      # @return [Array<Symbol>] frozen array of member names
+      def names
+        freeze_members!
+        member_registry.keys.freeze
+      end
+
+      # Return all member values in declaration order
+      #
+      # @return [Array<Object>] frozen array of member values
+      def values
+        freeze_members!
+        member_registry.values.map(&:value).freeze
+      end
+
+      # Return the first declared member
+      #
+      # @return [Enum, nil] the first member, or nil if empty
+      def first
+        freeze_members!
+        member_registry.values.first
+      end
+
+      # Return the last declared member
+      #
+      # @return [Enum, nil] the last member, or nil if empty
+      def last
+        freeze_members!
+        member_registry.values.last
+      end
+
       # Check if a name is a valid member
       #
       # @param name [Symbol, String] the member name
@@ -177,6 +227,24 @@ module Philiprehberger
         member_registry.key?(name.to_sym)
       end
 
+      # Return members matching the given symbol names, silently skipping unknown names
+      #
+      # @param names [Array<Symbol>] the member names to look up
+      # @return [Array<Enum>] array of matching members in the given order
+      def slice(*names)
+        freeze_members!
+        names.filter_map { |n| member_registry[n.to_sym] }
+      end
+
+      # Return a random member or array of random members
+      #
+      # @param n [Integer, nil] number of members to return; nil returns a single member
+      # @return [Enum, Array<Enum>] single member if n is nil, array of n members otherwise
+      def sample(n = nil)
+        freeze_members!
+        n.nil? ? member_registry.values.sample : member_registry.values.sample(n)
+      end
+
       private
 
       def inherited(subclass)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-enum
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-04 00:00:00.000000000 Z
+date: 2026-04-17 00:00:00.000000000 Z
 dependencies: []
 description: Define type-safe enums in Ruby with automatic ordinals, custom values,
   lookup methods, and Ruby 3.x pattern matching support. A cleaner alternative to