card_dealer 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4f9b59efbde62a455eb8cc518b88e10819824ec42723a97947093ebda55ca88
-  data.tar.gz: 8be49f812cbde111460d824e308110dd2dcc5bda31248ab8d41fe8cbe6bf963f
+  metadata.gz: 10507b7c372be3c958141e1e06c399eaead316c8578bcbca4a988ece49e76af5
+  data.tar.gz: b0dfddf4d95907e61862efa01e0c8c8ae55a33a72d004c4557cf687e83dfaf96
 SHA512:
-  metadata.gz: 271397f599f5d7e05c5cb86795506e5c97afb853d77eb575fa1d8ab612bd8641c3f4d4eea63aed3e4493c9742f01be98d6f2778e8b19c6483552f9ae78d549c2
-  data.tar.gz: abbd762746b5b86b1ee16b983888072e396648fa7fd9632c02c9234d1f7be145c9a2b95ad949f2231a1fd289ed539482d6346bae24ef612db5912d3b0d10071d
+  metadata.gz: a0407ea05a850c8b2bac7be37c1b128589225d1122bd26ba4e01a4e510565d2b7ca89c187a27c362cd3d7fc564e6e7cc2a7b9d9bbdaf0c8462be512dcf79c72b
+  data.tar.gz: 1eb8477fd9c2f64e83133060a347a7b9a3e3f1f106d01612ec0e5ce72c21975974a9a0b1089c708e8403811063149ae93e22672e5f5eb762c78b86701e2f09e7

data/.rubocop.yml

@@ -23,5 +23,15 @@ Style/Documentation:
 Layout/LineLength:
   Max: 120
 
+Metrics/BlockLength:
+  AllowedMethods:
+    - 'namespace'
+
 RSpec/NestedGroups:
   Max: 4
+
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10

data/CHANGELOG.md

@@ -1,13 +1,45 @@
 ## [Unreleased]
 
+## [0.2.0] - 2023-04-01
+
+### BREAKING CHANGES
+
+- Deck building in extracted from the `Deck` class to the `BuildDeck` class:
+  - `Deck#new` now takes an array of cards instead of a hash of options
+  - `Deck#reset` removed
+
+### Added
+
+- `BinaryDeck` class to convert decks to binary format and back
+  (to save space when storing decks in a database, for example)
+- `BuildDeck` class to build decks
+- `Card` instances are now safe to use as hash keys
+- `Card#eql?`, `Card#hash` and `Card#==` methods to compare cards and safely use them as hash keys
+- `Card#<=>` method to make cards sortable
+- `Deck#size` method to get the number of cards in the deck
+- `Deck#deal` method to deal cards from the deck
+- `Deck#to_binary_s` helper method to convert the deck to a binary string
+- `Deck#from_binary` helper method to convert the binary string to a deck
+- `Deck#==` method to compare decks for equality
+- Lots of documentation
+- [Steep](https://github.com/soutaro/steep) gem to check types correctness
+
+### Changed
+
+- It's possible to initialize a card with a string now, e.g. `Card.new('9c')`
+
+### Fixed
+
+- All the type declarations are now correct
+
 ## [0.1.0] - 2023-03-26
 
 Initial release!
 
 ### Added
 
-- Card class
-- Deck class
+- `Card` class
+- `Deck` class
 - Ability to create a decks of various size, ranks and suits
 - Ability to shuffle a deck
 - Ability to reset a deck

data/Gemfile

@@ -7,10 +7,12 @@ gemspec
 
 gem "rake", "~> 13.0"
 
-gem "faker", "~> 3.1"
 gem "rspec", "~> 3.12"
-gem "simplecov", require: false, group: :test
+gem "simplecov", require: false
+gem "simplecov_json_formatter", require: false
 
 gem "rubocop", "~> 1.28"
 gem "rubocop-rake", "~> 0.6"
 gem "rubocop-rspec", "~> 2.19"
+
+gem "steep", require: false

data/Gemfile.lock

@@ -1,25 +1,41 @@
 PATH
   remote: .
   specs:
-    card_dealer (0.1.0)
+    card_dealer (0.2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    activesupport (7.0.4.3)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
     ast (2.4.2)
     concurrent-ruby (1.2.2)
+    csv (3.2.6)
     diff-lcs (1.5.0)
     docile (1.4.0)
-    faker (3.1.1)
-      i18n (>= 1.8.11, < 2)
+    ffi (1.15.5)
+    fileutils (1.7.0)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
     json (2.6.3)
+    language_server-protocol (3.17.0.3)
+    listen (3.8.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.5.3)
+    minitest (5.18.0)
     parallel (1.22.1)
     parser (3.2.1.1)
       ast (~> 2.4.1)
     rainbow (3.1.1)
     rake (13.0.6)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rbs (2.8.4)
     regexp_parser (2.7.0)
     rexml (3.2.5)
     rspec (3.12.0)
@@ -55,26 +71,49 @@ GEM
       rubocop (~> 1.33)
       rubocop-capybara (~> 2.17)
     ruby-progressbar (1.13.0)
+    securerandom (0.2.2)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
+    steep (1.3.2)
+      activesupport (>= 5.1)
+      csv (>= 3.0.9)
+      fileutils (>= 1.1.0)
+      json (>= 2.1.0)
+      language_server-protocol (>= 3.15, < 4.0)
+      listen (~> 3.0)
+      logger (>= 1.3.0)
+      parallel (>= 1.0.0)
+      parser (>= 3.1)
+      rainbow (>= 2.2.2, < 4.0)
+      rbs (~> 2.8.0)
+      securerandom (>= 0.1)
+      strscan (>= 1.0.0)
+      terminal-table (>= 2, < 4)
+    strscan (3.0.6)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
     unicode-display_width (2.4.2)
 
 PLATFORMS
   arm64-darwin-22
+  x86_64-linux
 
 DEPENDENCIES
   card_dealer!
-  faker (~> 3.1)
   rake (~> 13.0)
   rspec (~> 3.12)
   rubocop (~> 1.28)
   rubocop-rake (~> 0.6)
   rubocop-rspec (~> 2.19)
   simplecov
+  simplecov_json_formatter
+  steep
 
 BUNDLED WITH
    2.4.9

data/README.md

@@ -1,26 +1,133 @@
 # CardDealer
+[![Gem Version](https://badge.fury.io/rb/card_dealer.svg)](https://badge.fury.io/rb/card_dealer)
+[![Maintainability](https://api.codeclimate.com/v1/badges/a5266ef126fbbe754ff8/maintainability)](https://codeclimate.com/github/svyatov/card_dealer/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/a5266ef126fbbe754ff8/test_coverage)](https://codeclimate.com/github/svyatov/card_dealer/test_coverage)
+[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
 
-This gem allows you to generate a deck of cards, shuffle them, and deal them to players.
+CardDealer is your go-to gem for creating, shuffling, and dealing decks of cards
+with ease. Whether you're building a poker night app or a virtual bridge club,
+CardDealer has got you covered. Enjoy customizable deck options, smooth
+shuffling algorithms, and simple yet powerful deck manipulation tools that bring
+the classic card game experience to life.
 
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+    $ bundle add card_dealer
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+    $ gem install card_dealer
 
 ## Usage
 
-TBD
+### Creating a standard 52-card deck
+
+To create a standard 52-card deck, use the `CardDealer::BuildDeck.standard52` method:
+
+```ruby
+deck = CardDealer::BuildDeck.standard52
+puts deck.cards
+```
+
+### Creating a standard 36-card deck
+
+To create a standard 36-card deck, use the `CardDealer::BuildDeck.standard36` method:
+
+```ruby
+deck = CardDealer::BuildDeck.standard36
+puts deck.cards
+```
+
+### Creating a custom deck of cards
+
+To create a custom deck of cards, use the `CardDealer::BuildDeck.custom` method.
+You can specify the number of decks, cards per suit, ranks, and suits:
+
+```ruby
+deck = CardDealer::BuildDeck.custom(
+  decks: 2,
+  cards_per_suit: 5,
+  ranks: :highest,
+  suits: %w[c d]
+)
+puts deck.cards
+```
+
+### Shuffling and dealing cards
+
+The `CardDealer::Deck` class provides methods for shuffling and dealing cards:
+
+```ruby
+deck = CardDealer::BuildDeck.standard52
+deck.shuffle
+hand = deck.deal(5)
+puts hand
+```
+
+You can also burn cards before dealing:
+
+```ruby
+deck = CardDealer::BuildDeck.standard52
+deck.shuffle
+hand = deck.deal(3, burn: 1)
+puts hand
+```
+
+To burn cards without dealing, just pass `0` as the number of cards to deal:
+
+```ruby
+deck = CardDealer::BuildDeck.standard52
+deck.shuffle
+hand = deck.deal(0, burn: 1)
+puts hand
+```
+
+Burned cards are stored within the deck and can be accessed via `burned_cards` method:
+
+```ruby
+deck = CardDealer::BuildDeck.standard52
+deck.shuffle
+deck.deal(0, burn: 10)
+puts deck.burned_cards
+```
+
+### Encoding a deck of cards as a binary string
+
+To encode a deck of cards as a binary string, use the `CardDealer::BinaryDeck.encode` method.
+This is useful if you'd like to store a deck of cards in a database, cache, or a file:
+
+```ruby
+deck = CardDealer::BuildDeck.standard52
+encoded_deck = CardDealer::BinaryDeck.encode(deck)
+# - or -
+encoded_deck = deck.to_binary_s
+puts encoded_deck
+```
+
+### Decoding a binary string into a deck of cards
+
+To decode a binary string into a deck of cards, use the `CardDealer::BinaryDeck.decode` method:
+
+```ruby
+encoded_deck = "\x02\xCDP" # binary string
+decoded_deck = CardDealer::BinaryDeck.decode(encoded_deck)
+# - or -
+decoded_deck = CardDealer::Deck.from_binary(encoded_deck)
+puts decoded_deck.cards
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/Rakefile

@@ -9,4 +9,11 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+desc "Run Steep typeckecker"
+task :steep do
+  exit(1) unless system("bundle exec steep check")
+end
+
+Dir["tasks/**/*.rake"].each { |t| load t }
+
+task default: %i[steep rubocop spec]

data/Steepfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+target :lib do
+  signature "sig"
+  check "lib"
+  configure_code_diagnostics(Steep::Diagnostic::Ruby.lenient)
+end

data/lib/card_dealer/binary_deck.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module CardDealer
+  # The BinaryDeck class provides a way to efficiently store a deck of cards as binary data.
+  # It can encode a deck of cards into a binary string and decode it back into a deck.
+  # This class can handle encoding and decoding of decks with up to 4'294'967'295 cards.
+  #
+  # The binary format consists of an initial byte(s) representing the number of cards in the deck,
+  # followed by a series of 6-bit card representations packed into bytes.
+  #
+  # An encoded deck with 52 or fewer cards takes up no more than 40 bytes.
+  #
+  class BinaryDeck
+    class DeckTooLargeError < Error; end
+
+    SUIT_MAP = Card::SUIT_MAP.transform_values { |value| value * 13 }
+    RANK_MAP = Card::RANK_MAP
+
+    # A hash mapping cards to their corresponding numbers
+    CARD_NUMBER_MAP = SUIT_MAP.each_with_object({}) do |(suit, suit_number), hash|
+      RANK_MAP.each do |rank, rank_number|
+        hash[Card.new(rank, suit)] = suit_number + rank_number
+      end
+    end.freeze
+
+    # A hash mapping cards to their corresponding binary strings
+    CARD_BINARY_NUMBER_MAP = CARD_NUMBER_MAP.transform_values { |number| format "%06b", number }.freeze
+    # A hash mapping binary strings to their corresponding cards
+    REVERSE_CARD_BINARY_NUMBER_MAP = CARD_BINARY_NUMBER_MAP.invert
+
+    # The binary format string for encoding/decoding decks with size <= 255
+    BIN_TEMPLATE_8 = "CB*"
+    # The binary format string for encoding/decoding decks with size > 255 and <= 65535
+    BIN_TEMPLATE_16 = "SB*"
+    # The binary format string for encoding/decoding decks with size > 65535
+    BIN_TEMPLATE_32 = "LB*"
+
+    # The maximum deck size supported by the BIN_TEMPLATE_8 format
+    BIN_8_ENCODE_LIMIT = 255
+    # The maximum encoded deck bytesize supported by the BIN_TEMPLATE_8 format
+    BIN_8_DECODE_LIMIT = 193
+    # The maximum deck size supported by the BIN_TEMPLATE_16 format
+    BIN_16_ENCODE_LIMIT = 65_535
+    # The maximum encoded deck bytesize supported by the BIN_TEMPLATE_16 format
+    BIN_16_DECODE_LIMIT = 49_154
+    # The maximum deck size supported by the BIN_TEMPLATE_32 format
+    BIN_32_ENCODE_LIMIT = 4_294_967_295
+    # The maximum encoded deck bytesize supported by the BIN_TEMPLATE_32 format
+    BIN_32_DECODE_LIMIT = 3_221_225_472
+
+    class << self
+      # Encodes a deck of cards into a binary string using a suitable template.
+      #
+      # The method takes a Deck object, maps each card to its corresponding binary number,
+      # and concatenates the binary numbers to create a single binary string. Then, it chooses
+      # the appropriate binary encoding template based on the deck size and packs the deck size
+      # and binary numbers into a single encoded binary string.
+      #
+      # @param deck [Deck] The deck of cards to encode.
+      #
+      # @return [String] The encoded binary string representing the deck of cards.
+      #
+      # @example
+      #   deck = CardDealer::Deck.new([CardDealer::Card.new("As"), CardDealer::Card.new("Td")])
+      #   encoded_deck = CardDealer::BinaryDeck.encode(deck)
+      #   encoded_deck #=> "\x02\xCDP" (binary string)
+      #
+      def encode(deck)
+        template = encoding_template_for deck.size
+        binary_numbers = deck.cards.map { |card| CARD_BINARY_NUMBER_MAP.fetch(card) }.join
+        [deck.size, binary_numbers].pack(template)
+      end
+
+      # Decodes a binary string into a deck of cards using a suitable template.
+      #
+      # The method takes an encoded binary string, and based on its size, selects the
+      # appropriate decoding template. It unpacks the binary string into a deck size
+      # and binary numbers. Then, it scans the binary numbers, takes the required number
+      # of cards based on the deck size, and maps each binary number back to its
+      # corresponding card. Finally, it returns a new Deck object containing the decoded cards.
+      #
+      # @param encoded_deck [String] The encoded binary string to decode.
+      #
+      # @return [Deck] The decoded deck of cards.
+      #
+      # @example
+      #   encoded_deck = "\x02\xCDP" # (binary string)
+      #   decoded_deck = CardDealer::BinaryDeck.decode(encoded_deck)
+      #   decoded_deck.cards #=> [#<CardDealer::Card "As">, #<CardDealer::Card "Td">]
+      #
+      def decode(encoded_deck)
+        template = decoding_template_for encoded_deck.bytesize
+        deck_size, binary_numbers = encoded_deck.unpack(template)
+        cards = binary_numbers.scan(/.{6}/).take(deck_size).map do |binary_number|
+          REVERSE_CARD_BINARY_NUMBER_MAP.fetch(binary_number)
+        end
+
+        Deck.new cards
+      end
+
+      private
+
+      # Determines the appropriate encoding template based on the deck size.
+      #
+      # The method checks the deck size and returns the corresponding binary template
+      # for encoding the deck. If the deck size is too large to be supported, it raises
+      # a DeckTooLargeError.
+      #
+      # @param deck_size [Integer] The number of cards in the deck to be encoded.
+      #
+      # @return [String] The appropriate encoding template based on the deck size.
+      #
+      # @raise [DeckTooLargeError] If the deck size is too large to be supported.
+      #
+      # @example
+      #   encoding_template_for(52) #=> "CB*"
+      #   encoding_template_for(520) #=> "SB*"
+      #   encoding_template_for(5_000_000_000) #=> raises DeckTooLargeError
+      #
+      def encoding_template_for(deck_size)
+        return BIN_TEMPLATE_8  if deck_size <= BIN_8_ENCODE_LIMIT
+        return BIN_TEMPLATE_16 if deck_size <= BIN_16_ENCODE_LIMIT
+        return BIN_TEMPLATE_32 if deck_size <= BIN_32_ENCODE_LIMIT
+
+        raise DeckTooLargeError, "Deck size #{deck_size} is too large to encode!"
+      end
+
+      # Determines the appropriate decoding template based on the size of the encoded deck.
+      #
+      # The method checks the encoded deck size and returns the corresponding binary template
+      # for decoding the deck. If the encoded deck size is too large to be supported, it raises
+      # a DeckTooLargeError.
+      #
+      # @param bytesize [Integer] The size of the encoded deck to be decoded.
+      #
+      # @return [String] The appropriate decoding template based on the encoded deck size.
+      #
+      # @raise [DeckTooLargeError] If the encoded deck size is too large to be supported.
+      #
+      # @example
+      #   decoding_template_for(40) #=> "CB*"
+      #   decoding_template_for(392) #=> "SB*"
+      #   decoding_template_for(4_000_000_000) #=> raises DeckTooLargeError
+      #
+      def decoding_template_for(bytesize)
+        return BIN_TEMPLATE_8  if bytesize <= BIN_8_DECODE_LIMIT
+        return BIN_TEMPLATE_16 if bytesize <= BIN_16_DECODE_LIMIT
+        return BIN_TEMPLATE_32 if bytesize <= BIN_32_DECODE_LIMIT
+
+        raise DeckTooLargeError, "Encoded deck size #{bytesize} is too large to decode!"
+      end
+    end
+  end
+end

data/lib/card_dealer/build_deck.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module CardDealer
+  # The BuildDeck class is responsible for creating a deck of cards with various configurations.
+  #
+  # It allows specifying the number of decks, cards per suit, ranks, and suits. It also provides
+  # methods for creating standard 52-card and 36-card decks. The resulting deck can be used with
+  # the {Deck} class for shuffling and other operations.
+  #
+  class BuildDeck
+    class InvalidRanksError < Error; end
+    class InvalidSuitsError < Error; end
+
+    class << self
+      # Builds a new deck with the specified configuration.
+      #
+      # @param decks [Integer] The number of decks to use.
+      # @param cards_per_suit [Integer] The number of cards per suit to use.
+      # @param ranks [Array<String>, :highest, :lowest] The ranks to use.
+      #   - :highest will use the highest cards_per_suit ranks (A, K, Q, J, T, ...).
+      #   - :lowest will use the lowest cards_per_suit ranks (2, 3, 4, 5, 6, ...).
+      #   - Array will use the specified ranks (e.g., %w[2 4 6 8 T]).
+      # @param suits [Array<String>, :all] The suits to use.
+      #   - :all will use all suits (c, d, h, s).
+      #   - Array will use the specified suits (e.g., %w[d h]).
+      #
+      # @return [Deck] A new deck with the specified configuration of cards.
+      #
+      # @raise [InvalidRanksError] If ranks are invalid.
+      # @raise [InvalidSuitsError] If suits are invalid.
+      #
+      def custom(decks: 1, cards_per_suit: 13, ranks: :highest, suits: :all)
+        ranks = build_ranks ranks, cards_per_suit
+        suits = build_suits suits
+        build_deck decks, ranks, suits
+      end
+
+      # Builds a standard 52-card deck.
+      #
+      # @param decks [Integer] The number of decks to use.
+      #
+      # @return [Deck] A new deck with the standard 52-card configuration.
+      #
+      def standard52(decks: 1)
+        custom decks:
+      end
+
+      # Builds a standard 36-card deck.
+      #
+      # @param decks [Integer] The number of decks to use.
+      #
+      # @return [Deck] A new deck with the standard 36-card configuration.
+      #
+      def standard36(decks: 1)
+        custom decks:, cards_per_suit: 9
+      end
+
+      private
+
+      # Builds the ranks for the deck based on the provided configuration.
+      #
+      # @param ranks [:highest, :lowest, Array<String>] The ranks configuration.
+      # @param cards_per_suit [Integer] The number of cards per suit.
+      #
+      # @return [Array<String>] The resulting ranks for the deck.
+      #
+      # @raise [InvalidRanksError] If the ranks configuration is invalid.
+      #
+      def build_ranks(ranks, cards_per_suit)
+        case ranks
+        when :highest
+          Card::RANKS.last(cards_per_suit)
+        when :lowest
+          Card::RANKS.first(cards_per_suit)
+        when Array
+          ranks
+        else
+          raise InvalidRanksError, "Invalid ranks: #{ranks}"
+        end
+      end
+
+      # Builds the suits for the deck based on the provided configuration.
+      #
+      # @param suits [:all, Array<String>] The suits configuration.
+      #
+      # @return [Array<String>] The resulting suits for the deck.
+      #
+      # @raise [InvalidSuitsError] If the suits configuration is invalid.
+      #
+      def build_suits(suits)
+        case suits
+        when :all
+          Card::SUITS
+        when Array
+          suits
+        else
+          raise InvalidSuitsError, "Invalid suits: #{suits}"
+        end
+      end
+
+      # Builds the deck using the specified configuration of decks, ranks, and suits.
+      #
+      # @param decks [Integer] The number of decks to use.
+      # @param ranks [Array<String>] The ranks to use in the deck.
+      # @param suits [Array<String>] The suits to use in the deck.
+      #
+      # @return [Deck] A new deck object with the specified configuration.
+      #
+      def build_deck(decks, ranks, suits)
+        cards = []
+
+        decks.times do
+          suits.each do |suit|
+            ranks.each do |rank|
+              cards << Card.new(rank, suit)
+            end
+          end
+        end
+
+        Deck.new cards
+      end
+    end
+  end
+end

data/lib/card_dealer/card.rb

@@ -1,7 +1,26 @@
 # frozen_string_literal: true
 
 module CardDealer
+  # The Card class represents a standard playing card with a rank and suit.
+  #
+  # A card has a rank (2-9, T, J, Q, K, A) and a suit (c, d, h, s).
+  # The class provides methods to initialize a card, compare cards for equality,
+  # and generate string representations of card instances.
+  #
+  # Example:
+  #
+  #   card1 = CardDealer::Card.new("A", "s")
+  #   card2 = CardDealer::Card.new("K", "h")
+  #   card3 = CardDealer::Card.new("As")
+  #
+  #   card1 == card3 # => true
+  #   card1.to_s     # => "As"
+  #   card2.inspect  # => '#<CardDealer::Card "Kh">'
+  #
   class Card
+    class InvalidRankError < Error; end
+    class InvalidSuitError < Error; end
+
     CLUBS    = "c"
     DIAMONDS = "d"
     HEARTS   = "h"
@@ -10,39 +29,157 @@ module CardDealer
     # T = 10, J = Jack, Q = Queen, K = King, A = Ace
     RANKS = %w[2 3 4 5 6 7 8 9 T J Q K A].freeze
     SUITS = [CLUBS, DIAMONDS, HEARTS, SPADES].freeze
+    RANK_MAP = RANKS.zip((0..12).to_a).to_h.freeze
+    SUIT_MAP = SUITS.zip((0..3).to_a).to_h.freeze
 
-    # For faster lookup
-    RANKS_SET = RANKS.to_set.freeze
-    SUITS_SET = SUITS.to_set.freeze
+    # @return [String] The rank of the card
+    attr_reader :rank
+    # @return [String] The suit of the card
+    attr_reader :suit
 
-    attr_reader :rank, :suit
+    # Initializes a new card instance with the specified rank and suit.
+    #
+    # The method accepts either a combination of rank and suit as separate arguments
+    # or a single string containing both rank and suit (e.g., "9c").
+    #
+    # @param rank [String] The card's rank (2-9, T, J, Q, K, A) or the card's combined rank and suit (e.g., "9c")
+    # @param suit [String, nil] The card's suit (c, d, h, s). Omit if the rank parameter contains both rank and suit.
+    #
+    # @example Creating a card with separate rank and suit arguments
+    #   card = CardDealer::Card.new("9", "c")
+    #
+    # @example Creating a card with a combined rank and suit string
+    #   card = CardDealer::Card.new("9c")
+    #
+    def initialize(rank, suit = nil)
+      rank, suit = rank.chars if suit.nil?
+      @rank = rank.to_s
+      @suit = suit.to_s
+      validate_card!
+    end
 
-    # Initializes a new card.
+    # Returns the string representation of the card, combining its rank and suit (e.g., "As", "Td", "2c").
+    #
+    # @return [String] The card's combined rank and suit as a string.
+    #
+    # @example
+    #   card = CardDealer::Card.new("A", "s")
+    #   card.to_s #=> "As"
     #
-    # @param rank [String] the card's rank (2-9, T, J, Q, K, A)
-    # @param suit [String] the card's suit (c, d, h, s)
-    def initialize(rank, suit)
-      validate_arguments rank, suit
+    def to_s
+      @to_s ||= "#{rank}#{suit}"
+    end
 
-      @rank = rank
-      @suit = suit
+    # Determines if two card instances are identical based on their rank and suit.
+    #
+    # This method compares the rank and suit of the current card instance with those
+    # of another card instance. It returns true if both rank and suit are equal,
+    # and false otherwise.
+    #
+    # @param other [Card] The card instance to compare with.
+    #
+    # @return [Boolean] True if the rank and suit of both card instances are equal, false otherwise.
+    #
+    # @example
+    #   card1 = CardDealer::Card.new("A", "s")
+    #   card2 = CardDealer::Card.new("A", "s")
+    #   card1.eql?(card2) #=> true
+    #
+    def eql?(other)
+      return false unless other.is_a?(Card)
+
+      rank == other.rank && suit == other.suit
     end
 
-    # @return [String] the card's rank and suit
-    def to_s
-      "#{rank}#{suit}"
+    # Calculates a hash value for the card instance based on its string representation.
+    #
+    # This method computes a hash value for the card using the combined rank and suit string.
+    # This hash value is required when using card instances as hash keys.
+    #
+    # @return [Integer] The hash value of the card instance.
+    #
+    # @example
+    #   card = CardDealer::Card.new("A", "s")
+    #   card_hash = card.hash
+    #   cards_hash = { card => "Ace of Spades" }
+    #
+    def hash
+      to_s.hash
     end
 
-    # @return [String] the card's object string representation
+    # Compares two card instances for equality based on their rank and suit.
+    #
+    # This method utilizes the `eql?` method to compare the current card instance
+    # with another card instance. It returns true if both rank and suit are equal,
+    # and false otherwise.
+    #
+    # @param other [Card] The card instance to compare with.
+    #
+    # @return [Boolean] True if the rank and suit of both card instances are equal, false otherwise.
+    #
+    # @example
+    #   card1 = CardDealer::Card.new("A", "s")
+    #   card2 = CardDealer::Card.new("A", "s")
+    #   card1 == card2 #=> true
+    #
+    def ==(other)
+      eql?(other)
+    end
+
+    # Compares two card instances based on their rank and suit.
+    #
+    # @param other [Card] The card instance to compare with.
+    #
+    # @return [Integer, nil] Returns -1 if the current card is less than the
+    #  other card, 0 if both cards are equal, and 1 if the current card is
+    #  greater than the other card. Returns nil if the comparison is not possible
+    #  (e.g., other is not a Card object).
+    #
+    def <=>(other)
+      return unless other.is_a?(Card)
+      return 0 if self == other
+
+      rank_comparison = RANK_MAP[rank] <=> RANK_MAP[other.rank]
+      return rank_comparison unless rank_comparison.zero?
+
+      SUIT_MAP[suit] <=> SUIT_MAP[other.suit]
+    end
+
+    # Returns a string representation of the card instance's object state for debugging purposes.
+    #
+    # This method generates a human-readable string that includes the card's class and string representation.
+    # It is useful for inspecting the object state when debugging.
+    #
+    # @return [String] A string representation of the card instance's object state.
+    #
+    # @example
+    #   card = CardDealer::Card.new("A", "s")
+    #   card.inspect #=> '#<CardDealer::Card "As">'
+    #
     def inspect
-      %(#<CardDealer::Card "#{self}">)
+      %(#<#{self.class} "#{self}">)
     end
 
     private
 
-    def validate_arguments(rank, suit)
-      raise Error, "Invalid rank: #{rank}" unless RANKS_SET.include?(rank)
-      raise Error, "Invalid suit: #{suit}" unless SUITS_SET.include?(suit)
+    # Validates the rank and suit arguments provided when initializing a card instance.
+    #
+    # @raise [InvalidRankError] If the rank is invalid.
+    # @raise [InvalidSuitError] If the suit is invalid.
+    #
+    # @example
+    #   # Valid rank and suit
+    #   card = CardDealer::Card.new("A", "s")
+    #
+    #   # Invalid rank
+    #   card = CardDealer::Card.new("X", "s") #=> raises InvalidRankError, "Invalid rank: X"
+    #
+    #   # Invalid suit
+    #   card = CardDealer::Card.new("A", "x") #=> raises InvalidSuitError, "Invalid suit: x"
+    #
+    def validate_card!
+      raise InvalidRankError, "Invalid rank: #{rank}" unless RANK_MAP.key?(rank)
+      raise InvalidSuitError, "Invalid suit: #{suit}" unless SUIT_MAP.key?(suit)
     end
   end
 end

data/lib/card_dealer/deck.rb

@@ -1,89 +1,122 @@
 # frozen_string_literal: true
 
 module CardDealer
+  # The Deck class represents a collection of cards.
+  #
+  # It supports operations like shuffling, getting the size of the deck, and converting
+  # the deck to an array or string. The deck can be initialized with an array of {Card}
+  # objects, which can be created using the {BuildDeck} class.
+  #
   class Deck
-    attr_reader :cards, :seed
+    # @return [Array<Card>] The array of cards in the deck.
+    attr_reader :cards
+    # @return [Integer, nil] The seed used for shuffling the deck.
+    attr_reader :seed
+    # @return [Array<Card>] The array of cards that have been burned.
+    attr_reader :burned_cards
 
-    # Initializes a new deck.
-    #
-    # @param decks [Integer] the number of decks to use
-    # @param cards_per_suit [Integer] the number of cards per suit to use
-    # @param ranks [Array<String>, :highest, :lowest] the ranks to use
-    #   @option :highest will use the highest cards_per_suit ranks (A, K, Q, J, T, ...)
-    #   :lowest will use the lowest cards_per_suit ranks (2, 3, 4, 5, 6, ...)
-    #   array will use the specified ranks (e.g. %w[2 4 6 8 T])
-    # @param suits [Array<String>, :all] the suits to use
-    #   :all will use all suits (c, d, h, s)
-    #   array will use the specified suits (e.g. %w[d h])
-    # @raise [Error] if ranks or suits are invalid
-    def initialize(decks: 1, cards_per_suit: 13, ranks: :highest, suits: :all)
-      @decks = decks
-      @ranks = build_ranks ranks, cards_per_suit
-      @suits = build_suits suits
-      reset
+    # Initializes a new deck with the specified cards.
+    #
+    # @param cards [Array<Card>] The array of cards to use in the deck (see {BuildDeck}).
+    #
+    def initialize(cards)
+      @cards = cards
+      @burned_cards = []
     end
 
-    # Resets the deck to its original state.
+    # Shuffles the deck using the Fisher-Yates algorithm.
+    #
+    # @param seed [Integer] The seed to use for shuffling. If not provided, a new seed is generated.
+    #
+    # @return [Deck] The shuffled deck.
     #
-    # @return [Deck]
-    def reset
-      @cards = []
+    def shuffle(seed = Random.new_seed)
+      @seed ||= seed
+      @cards.shuffle! random: Random.new(@seed.to_i)
+      self
+    end
 
-      @decks.times do
-        @suits.each do |suit|
-          @ranks.each do |rank|
-            @cards << Card.new(rank, suit)
-          end
-        end
-      end
+    # Deals a specified number of cards from the top of the deck, optionally burning cards before the deal.
+    #
+    # The method removes the specified number of cards from the top of the deck and returns them.
+    # If the burn parameter is specified, it will remove (burn) the indicated number of cards
+    # from the top of the deck before dealing.
+    #
+    # @param num [Integer] The number of cards to deal (default: 1).
+    # @param burn [Integer] The number of cards to burn before dealing (default: 0).
+    #
+    # @return [Array<Card>] The dealt cards.
+    #
+    # @example
+    #   deck = CardDealer::Deck.new([CardDealer::Card.new("As"), CardDealer::Card.new("Td")])
+    #   dealt_cards = deck.deal(burn: 1)
+    #   dealt_cards #=> [#<CardDealer::Card "Td">]
+    #   deck.burned_cards #=> [CardDealer::Card.new("As")]
+    #
+    def deal(num = 1, burn: 0)
+      @burned_cards += cards.shift(burn) if burn.positive?
+      cards.shift(num)
+    end
 
-      self
+    # Returns the number of cards in the deck.
+    #
+    # @return [Integer] The number of cards in the deck.
+    #
+    def size
+      cards.size
     end
 
-    # Shuffles the deck using the Fisher-Yates algorithm.
+    # Compares two deck instances for equality based on their cards.
     #
-    # @param seed [Integer] the seed to use for shuffling
-    # @return [Deck]
-    def shuffle(seed = Random.new_seed)
-      @seed = seed
-      @cards.shuffle! random: Random.new(seed)
-      self
+    # Two decks are considered equal if they have the same cards in the same order.
+    #
+    # @param other [Deck] The other deck instance to compare with.
+    #
+    # @return [Boolean] True if the decks are equal, false otherwise.
+    #
+    # @example
+    #   deck1 = CardDealer::BuildDeck.standard52
+    #   deck2 = CardDealer::BuildDeck.standard52
+    #   deck1 == deck2 #=> true
+    #
+    def ==(other)
+      return false unless other.is_a?(Deck)
+
+      cards == other.cards
     end
 
-    # @return [Array<String>] the array of cards in the deck as strings
+    # Returns an array of cards as strings in the deck.
+    #
+    # @return [Array<String>] The array of cards in the deck as strings (see {Card#to_s})
+    #
     def to_a
       cards.map(&:to_s)
     end
 
-    # @return [String] the cards in the deck as a string
+    # Returns the cards in the deck as a single string.
+    #
+    # @return [String] The cards in the deck as a single string.
+    #
     def to_s
       to_a.to_s
     end
 
-    private
-
-    def build_suits(suits)
-      case suits
-      when :all
-        Card::SUITS
-      when Array
-        suits
-      else
-        raise Error, "Invalid suits: #{suits}"
-      end
+    # Encodes the deck as a binary string using the {BinaryDeck} class.
+    #
+    # @return [String] The binary representation of the deck.
+    #
+    def to_binary_s
+      BinaryDeck.encode(self)
     end
 
-    def build_ranks(ranks, cards_per_suit)
-      case ranks
-      when :highest
-        Card::RANKS.last(cards_per_suit)
-      when :lowest
-        Card::RANKS.first(cards_per_suit)
-      when Array
-        ranks
-      else
-        raise Error, "Invalid ranks: #{ranks}"
-      end
+    # Decodes a binary string into a Deck instance using the {BinaryDeck} class.
+    #
+    # @param encoded_deck [String] The binary string representation of a deck.
+    #
+    # @return [Deck] The decoded Deck object.
+    #
+    def self.from_binary(encoded_deck)
+      BinaryDeck.decode(encoded_deck)
     end
   end
 end

data/lib/card_dealer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CardDealer
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/card_dealer.rb

@@ -2,10 +2,12 @@
 
 require "set"
 
-require_relative "card_dealer/version"
-require_relative "card_dealer/card"
-require_relative "card_dealer/deck"
-
 module CardDealer
   class Error < StandardError; end
 end
+
+require_relative "card_dealer/version"
+require_relative "card_dealer/card"
+require_relative "card_dealer/deck"
+require_relative "card_dealer/build_deck"
+require_relative "card_dealer/binary_deck"

data/sig/card_dealer/binary_deck.rbs

@@ -0,0 +1,30 @@
+module CardDealer
+  class BinaryDeck
+    SUIT_MAP: Hash[String, Integer]
+    RANK_MAP: Hash[String, Integer]
+    CARD_NUMBER_MAP: Hash[Card, Integer]
+    CARD_BINARY_NUMBER_MAP: Hash[Card, String]
+    REVERSE_CARD_BINARY_NUMBER_MAP: Hash[String, Card]
+
+    BIN_TEMPLATE_8: String
+    BIN_TEMPLATE_16: String
+    BIN_TEMPLATE_32: String
+
+    BIN_8_ENCODE_LIMIT: Integer
+    BIN_8_DECODE_LIMIT: Integer
+    BIN_16_ENCODE_LIMIT: Integer
+    BIN_16_DECODE_LIMIT: Integer
+    BIN_32_ENCODE_LIMIT: Integer
+    BIN_32_DECODE_LIMIT: Integer
+
+    def self.encode: (Deck) -> String
+
+    def self.decode: (String) -> Deck
+
+    private
+
+    def self.encoding_template_for: (Integer) -> String
+
+    def self.decoding_template_for: (Integer) -> String
+  end
+end

data/sig/card_dealer/build_deck.rbs

@@ -0,0 +1,21 @@
+module CardDealer
+  class BuildDeck
+    def self.custom: (
+        ?decks: Integer,
+        ?cards_per_suit: Integer,
+        ?ranks: :highest | :lowest | Array[String],
+        ?suits: :all | Array[String]) -> Deck
+
+    def self.standard52: (?decks: Integer) -> Deck
+
+    def self.standard36: (?decks: Integer) -> Deck
+
+    private
+
+    def self.build_ranks: (:highest | :lowest | Array[String] ranks, Integer cards_per_rank) -> Array[String]
+
+    def self.build_suits: (:all | Array[String] suits) -> Array[String]
+
+    def self.build_deck: (Integer decks, Array[String] ranks, Array[String] suits) -> Deck
+  end
+end

data/sig/card_dealer/card.rbs

@@ -8,18 +8,20 @@ module CardDealer
     RANKS: Array[String]
     SUITS: Array[String]
 
-    RANKS_SET: Set[String]
-    SUITS_SET: Set[String]
+    RANK_MAP: Hash[String, Integer]
+    SUIT_MAP: Hash[String, Integer]
+
+    @to_s: String
 
     attr_reader rank: String
     attr_reader suit: String
 
-    def initialize: (rank: String, suit: String) -> void
+    def initialize: (String rank, ?String? suit) -> void
 
     def to_s: -> String
 
     private
 
-    def validate_arguments: (rank: String, suit: String) -> void
+    def validate_card!: -> void
   end
 end

data/sig/card_dealer/deck.rbs

@@ -1,30 +1,23 @@
 module CardDealer
   class Deck
     attr_reader cards: Array[Card]
-    attr_reader seed: Integer
+    attr_reader seed: Integer?
+    attr_reader burned_cards: Array[Card]?
 
-    @decks: Integer
-    @ranks: :highest | :lowest | Array[String]
-    @suits: :all | Array[String]
+    def self.from_binary: (String) -> Deck
 
-    def initialize: (
-        ?decks: Integer,
-        ?cards_per_suit: Integer,
-        ?ranks: :highest | :lowest | Array[String],
-        ?suits: :all | Array[String]) -> void
+    def initialize: (Array[Card] cards) -> void
 
-    def reset: -> self
+    def shuffle: (?Integer seed) -> self
 
-    def shuffle: (?seed: Integer) -> self
+    def deal: (?Integer num, ?burn: Integer) -> Array[Card]
+
+    def size: -> Integer
 
     def to_a: -> Array[String]
 
     def to_s: -> String
 
-    private
-
-    def build_suits: (suits: :all | Array[String]) -> Array[String]
-
-    def build_ranks: (ranks: :highest | :lowest | Array[String]) -> Array[String]
+    def to_binary_s: -> String
   end
 end

data/tasks/fixtures.rake

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+namespace :fixtures do
+  desc "Generates deck fixtures for specs"
+  task :generate do
+    require "json"
+    require_relative "../lib/card_dealer"
+
+    # Less then 255 cards
+    deck = CardDealer::BuildDeck.standard52.shuffle
+    deck_partial = CardDealer::Deck.new(deck.cards.take(11)).shuffle
+    deck_single_card = CardDealer::Deck.new([deck.cards.first])
+
+    File.write("spec/fixtures/deck_standard52.json", JSON.pretty_generate(seed: deck.seed, cards: deck.to_a))
+    File.write("spec/fixtures/deck_standard52.bin", CardDealer::BinaryDeck.encode(deck))
+    File.write("spec/fixtures/deck_partial.json", JSON.pretty_generate(cards: deck_partial.to_a))
+    File.write("spec/fixtures/deck_partial.bin", CardDealer::BinaryDeck.encode(deck_partial))
+    File.write("spec/fixtures/deck_single_card.json", JSON.pretty_generate(cards: deck_single_card.to_a))
+    File.write("spec/fixtures/deck_single_card.bin", CardDealer::BinaryDeck.encode(deck_single_card))
+
+    # Between 255 and 65535 cards
+    encodable_cards_limit_large = CardDealer::BinaryDeck::BIN_16_ENCODE_LIMIT
+    max_encodable_decks_large = (encodable_cards_limit_large / deck.size).floor
+    max_encodable_cards_large = (deck.cards * (max_encodable_decks_large + 1)).take(encodable_cards_limit_large)
+    deck_large = CardDealer::Deck.new(max_encodable_cards_large).shuffle
+
+    File.write("spec/fixtures/deck_large.json", JSON.pretty_generate(cards: deck_large.to_a))
+    File.write("spec/fixtures/deck_large.bin", CardDealer::BinaryDeck.encode(deck_large))
+
+    # More than 65535 cards
+    deck_large_plus_one = CardDealer::Deck.new(max_encodable_cards_large + [deck.cards.sample]).shuffle
+    deck_huge = CardDealer::Deck.new(max_encodable_cards_large * 2).shuffle
+
+    File.write("spec/fixtures/deck_large_plus_one.json", JSON.pretty_generate(cards: deck_large_plus_one.to_a))
+    File.write("spec/fixtures/deck_large_plus_one.bin", CardDealer::BinaryDeck.encode(deck_large_plus_one))
+    File.write("spec/fixtures/deck_huge.json", JSON.pretty_generate(cards: deck_huge.to_a))
+    File.write("spec/fixtures/deck_huge.bin", CardDealer::BinaryDeck.encode(deck_huge))
+  end
+end

metadata

@@ -1,17 +1,21 @@
 --- !ruby/object:Gem::Specification
 name: card_dealer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Leonid Svyatov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-03-26 00:00:00.000000000 Z
+date: 2023-04-01 00:00:00.000000000 Z
 dependencies: []
-description: Card dealer allows to generate a deck of cards, shuffle them, and deal
-  them to players.
+description: |
+  CardDealer is your go-to gem for creating, shuffling, and dealing decks of
+  cards with ease. Whether you're building a poker night app or a virtual
+  bridge club, CardDealer has got you covered. Enjoy customizable deck
+  options, smooth shuffling algorithms, and simple yet powerful deck
+  manipulation tools that bring the classic card game experience to life.
 email:
 - leonid@svyatov.com
 executables: []
@@ -26,13 +30,19 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- Steepfile
 - lib/card_dealer.rb
+- lib/card_dealer/binary_deck.rb
+- lib/card_dealer/build_deck.rb
 - lib/card_dealer/card.rb
 - lib/card_dealer/deck.rb
 - lib/card_dealer/version.rb
 - sig/card_dealer.rbs
+- sig/card_dealer/binary_deck.rbs
+- sig/card_dealer/build_deck.rbs
 - sig/card_dealer/card.rbs
 - sig/card_dealer/deck.rbs
+- tasks/fixtures.rake
 homepage: https://github.com/svyatov/card_dealer
 licenses:
 - MIT
@@ -59,5 +69,5 @@ requirements: []
 rubygems_version: 3.4.9
 signing_key:
 specification_version: 4
-summary: It deals with cards. It's a card dealer.
+summary: A delightful card dealing companion for your digital table.
 test_files: []