deck_of_cards_handler 0.1.91 → 0.1.92

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be5bc65959783676600d8d3f606d237e0db12525a5e564fc7f7078d0453a11a7
-  data.tar.gz: fab47433f5fc838c7ec452f72112f76d550acdc80eba02059fe2ba01384fb21b
+  metadata.gz: a76a16db0441bf9921dcf676cb1fbcf23f7bb674ee0628d146b9206955d138ff
+  data.tar.gz: eb6fe424f4cc1e08ac79494e08b9807c427901b78f86e202c351113d3ea7e1d6
 SHA512:
-  metadata.gz: 16a055066a557918d262cdf76ddcc81d31d72aeb41dbf458145f28d3d22181c1500a4bfee413adc9f38360debcbf17fc7a7952da4c038b8112737dc9c3b034b4
-  data.tar.gz: 16dbd4c77f7c553dd24f25e3a31202c37c4e2e1d23e82d49f84e23401e75e2a75dabe38cd2b71908b69ed75655209c7facbf9b6258dfabaf4112c9e6f4103b23
+  metadata.gz: 349564212186a705e3607c92ee86a49d62882f66625b04793e072114ce16b1d8914a5a312efbc993037375cf0a16ad564ed2c55f0c365b85911e79d9caabb03b
+  data.tar.gz: 702af9029ac27a8ff51a828efc11f364d8552c7cfa55ac77200239ba51d68fcc28e03b02e99354ec4ade7067508b592960ff9844c51e0b62cd68034425583337

data/CHANGELOG.md

@@ -7,3 +7,8 @@
 ## [0.1.6] - 2025-10-20
 
 - Added poker hand comparison
+
+## [0.1.9.2] - 2025-10-21
+
+- Added overhand shuffle
+- Added cull method

data/README.md

@@ -1,4 +1,4 @@
-[![Gem Version](https://badge.fury.io/rb/deck_of_cards_handler.svg)](https://badge.fury.io/rb/deck_of_cards_handler) [![Test suite](https://github.com/simonbernard2/deck_of_cards/actions/workflows/ruby.yml/badge.svg)](https://github.com/simonbernard2/deck_of_cards/actions/workflows/ruby.yml)
+[![Gem Version](https://badge.fury.io/rb/deck_of_cards_handler.svg?branch=master&kill_cache=1)](https://badge.fury.io/rb/deck_of_cards_handler) [![Test suite](https://github.com/simonbernard2/deck_of_cards/actions/workflows/ruby.yml/badge.svg)](https://github.com/simonbernard2/deck_of_cards/actions/workflows/ruby.yml)
 
 # Deck of cards handler
 
@@ -13,6 +13,70 @@ Run the following terminal command:
 gem install deck_of_cards_handler
 ```
 
+## Quickstart
+
+```ruby
+require "deck_of_cards_handler"
+
+# Cards
+c = Card.new(suit: "S", value: "A")
+c.red?        # => false
+c.black?      # => true
+c.spades?      # => true
+c.hearts?      # => false
+c.to_s        # => "A of S"
+c.rank        # => 14 (Ace high)
+
+Card.suits       # => ["C","D","H","S"]
+Card.values      # => ["A","2",...,"10","J","Q","K"]
+
+# Packets (decks or piles)
+deck = Packet.new                    # empty unless you pass cards
+one_card = Packet.new(cards: [c])
+full = Packet.build_from_text_file(file_path: "data/mnemonica.txt")
+five = Packet.build_from_string(string: "A:C, K:D, Q:H, J:S, 10:C")
+
+full.size                            # => 52
+full.shuffle                         # in-place shuffle
+full.reverse                         # in-place reverse
+top = full.top_deal                  # remove and return top card (Card)
+sec = full.second_deal               # remove and return second card (Card)
+bot = full.bottom_deal               # remove and return bottom card (Card)
+
+piles = full.deal_into_piles(number_of_piles: 4, number_of_cards: 5)
+# => [[Card,...],[...],[...],[...]]
+
+# Reassemble piles (all return Packet)
+full.reassemble_left_to_right_on_top(piles)
+
+# Packet ↔︎ Poker hand
+hand = five.to_poker_hand            # => a PokerHands::PokerHand subclass
+
+```
+
+## Shuffling
+
+```ruby
+# Perfect interleaving (Faro)
+top_half = deck.cut(number: 26)
+deck.faro(other_packet: top_half)
+
+# Imperfect riffle shuffle
+left_half = deck.cut(number: 26)
+deck.riffle_shuffle(other_packet: left_half)
+
+# Random shuffle
+deck.shuffle
+
+```
+
+## Convert Packets to Poker Hand
+
+```ruby
+five = Packet.build_from_string(string: "A:C, K:D, Q:H, J:S, 10:C")
+hand = five.to_poker_hand   # => PokerHands::Straight
+```
+
 ## Usage examples
 
 <details>
@@ -59,43 +123,7 @@ gem install deck_of_cards_handler
     #<Card:0x000000012ae2c9f0 @position=5, @suit="H", @value="4">,
     #<Card:0x000000012ae2c298 @position=6, @suit="D", @value="6">,
     #<Card:0x000000012ae2df08 @position=7, @suit="C", @value="A">,
-    #<Card:0x000000012ae2c978 @position=8, @suit="H", @value="5">,
-    #<Card:0x000000012ae2ce00 @position=9, @suit="C", @value="9">,
-    #<Card:0x000000012ae2d260 @position=10, @suit="C", @value="2">,
-    #<Card:0x000000012ae2c630 @position=11, @suit="H", @value="Q">,
-    #<Card:0x000000012ae2c400 @position=12, @suit="D", @value="3">,
-    #<Card:0x000000012ae2b960 @position=13, @suit="S", @value="Q">,
-    #<Card:0x000000012ae2c810 @position=14, @suit="H", @value="8">,
-    #<Card:0x000000012ae2cf68 @position=15, @suit="C", @value="6">,
-    #<Card:0x000000012ae2cfe0 @position=16, @suit="C", @value="5">,
-    #<Card:0x000000012ae2c798 @position=17, @suit="H", @value="9">,
-    #<Card:0x000000012ae2b8e8 @position=18, @suit="S", @value="K">,
-    #<Card:0x000000012ae2c478 @position=19, @suit="D", @value="2">,
-    #<Card:0x000000012ae2c6a8 @position=20, @suit="H", @value="J">,
-    #<Card:0x000000012ae2d0d0 @position=21, @suit="C", @value="3">,
-    #<Card:0x000000012ae2ce78 @position=22, @suit="C", @value="8">,
-    #<Card:0x000000012ae2c900 @position=23, @suit="H", @value="6">,
-    #<Card:0x000000012ae2ba50 @position=24, @suit="S", @value="10">,
-    #<Card:0x000000012ae2c310 @position=25, @suit="D", @value="5">,
-    #<Card:0x000000012ae2bf50 @position=26, @suit="D", @value="K">,
-    #<Card:0x000000012ae2be10 @position=27, @suit="S", @value="2">,
-    #<Card:0x000000012ae2ca68 @position=28, @suit="H", @value="3">,
-    #<Card:0x000000012ae2c1a8 @position=29, @suit="D", @value="8">,
-    #<Card:0x000000012ae2bca8 @position=30, @suit="S", @value="5">,
-    #<Card:0x000000012ae2cc20 @position=31, @suit="C", @value="K">,
-    #<Card:0x000000012ae2c040 @position=32, @suit="D", @value="J">,
-    #<Card:0x000000012ae2bb40 @position=33, @suit="S", @value="8">,
-    #<Card:0x000000012ae2cd88 @position=34, @suit="C", @value="10">,
-    #<Card:0x000000012ae2c5b8 @position=35, @suit="H", @value="K">,
-    #<Card:0x000000012ae2b9d8 @position=36, @suit="S", @value="J">,
-    #<Card:0x000000012ae2cef0 @position=37, @suit="C", @value="7">,
-    #<Card:0x000000012ae2c720 @position=38, @suit="H", @value="10">,
-    #<Card:0x000000012ae2c4f0 @position=39, @suit="D", @value="A">,
-    #<Card:0x000000012ae2d058 @position=40, @suit="C", @value="4">,
-    #<Card:0x000000012ae2c888 @position=41, @suit="H", @value="7">,
-    #<Card:0x000000012ae2c388 @position=42, @suit="D", @value="4">,
-    #<Card:0x000000012ae2be88 @position=43, @suit="S", @value="A">,
-    #<Card:0x000000012ae2bac8 @position=44, @suit="S", @value="9">,
+    #...
     #<Card:0x000000012ae2cd10 @position=45, @suit="C", @value="J">,
     #<Card:0x000000012ae2bfc8 @position=46, @suit="D", @value="Q">,
     #<Card:0x000000012ae2bbb8 @position=47, @suit="S", @value="7">,
@@ -125,10 +153,10 @@ gem install deck_of_cards_handler
 
   deck.shuffle
 
-  hands = deck.deal_into_piles(number_of_piles: 5, number_of_cards: 5)
+  piles = deck.deal_into_piles(number_of_piles: 5, number_of_cards: 5)
 
-  hands.map(&:to_s)
-  # => [["5 of D", "8 of C", "6 of S", "10 of D", "5 of C"], ["7 of C", "5 of S", "4 of C", "2 of D", "Q of D"], ["3 of S", "8 of D", "A of D", "2 of C", "7 of D"], ["Q of H", "4 of S", "3 of D", "J of S", "9 of S"], ["6 of C", "6 of H", "10 of C", "4 of D", "A of H"]]
+  hands = piles.map(&:to_poker_hand)
+  # => [#PokerHands::OnePair, [...],[...],[...],[...]]
 ```
 
 </details>

data/lib/deck_of_cards_handler/packet/packet.rb

@@ -10,6 +10,7 @@ class Packet
   require "deck_of_cards_handler/packet/cuts"
   include Deals
   include Cuts
+  include Shuffles
 
   sig { returns(T::Array[Card]) }
   attr_accessor :cards
@@ -93,6 +94,16 @@ class Packet
     self.cards = cards.reverse
   end
 
+  # Moves a card from position A to position B
+  # The first card position IS 1, NOT 0 as in a traditional array
+  sig { params(from: Integer, to: Integer).void }
+  def cull(from:, to:)
+    raise ArgumentError, "`from` must be in range with 1..#{size}" if from <= 0 || from > size
+    raise ArgumentError, "`to` must be in range with 1..#{size}" if to <= 0 || to > size
+
+    cards.insert(to - 1, T.must(cards.delete_at(from - 1)))
+  end
+
   sig { void }
   def set_cards_positions
     cards.each_with_index do |card, index|

data/lib/deck_of_cards_handler/packet/shuffles.rb

@@ -2,6 +2,24 @@
 # typed: strict
 
 module Shuffles
+  extend T::Helpers
+  extend T::Sig
+
+  requires_ancestor { Packet }
+
+  sig { void }
+  def overhand_shuffle
+    piles = []
+
+    until size.zero?
+      chunk_size = Kernel.rand(1..8)
+      chunk_size = size if chunk_size > size
+      piles << cut(number: chunk_size)
+    end
+
+    reassemble_right_to_left_on_top(piles)
+  end
+
   class << self
     extend T::Sig
 

data/lib/deck_of_cards_handler/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeckOfCardsHandler
-  VERSION = "0.1.91"
+  VERSION = "0.1.92"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deck_of_cards_handler
 version: !ruby/object:Gem::Version
-  version: 0.1.91
+  version: 0.1.92
 platform: ruby
 authors:
 - Simon Bernard