Package com.github.jmp.poker

Record Class Hand

java.lang.Object
java.lang.Record
com.github.jmp.poker.Hand
Record Components:
cards - the 5 cards that comprise this hand
public record Hand(Card[] cards) extends Record
Represents an immutable 5-card poker hand with evaluation capabilities.

This record provides functionality to create, validate, and evaluate poker hands according to standard poker rules. Each hand must contain exactly 5 unique cards from a standard 52-card deck.

The hand evaluation is based on Kevin Suffecool's 5-card hand evaluator with Paul Senzee's pre-computed hash tables, providing fast and accurate poker hand rankings from 1 (best possible hand) to 7462 (worst possible hand).

See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Hand(Card... cards)
    Constructs a new Hand with exactly 5 unique cards.

  • Method Summary

    Modifier and Type
    Method
    Description
    Card[]
    cards()
    Returns the value of the cards record component.
    final boolean
    equals(Object o)
    Indicates whether some other object is "equal to" this one.
    int
    evaluate()
    Evaluates this poker hand and returns its ranking value.
    static Hand
    fromString(String string)
    Creates a new 5-card hand from its string representation.
    final int
    hashCode()
    Returns a hash code value for this object.
    String
    toString()
    Returns the string representation of this hand.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Hand

      public Hand(Card... cards)
      Constructs a new Hand with exactly 5 unique cards.

      Validates that exactly 5 cards are provided and that no duplicate cards exist in the hand. Duplicate detection is based on the internal card values to ensure proper poker hand validation.

      Parameters:
      cards - the cards to include in this hand (must be exactly 5 unique cards)
      Throws:
      IllegalArgumentException - if cards is null, does not contain exactly 5 cards, or contains duplicate cards

  • Method Details

    • evaluate

      public int evaluate()
      Evaluates this poker hand and returns its ranking value.

      Uses Kevin Suffecool's 5-card hand evaluator algorithm with Paul Senzee's pre-computed hash tables for fast and accurate evaluation. The algorithm handles all poker hand types including straight flushes, four of a kind, full houses, flushes, straights, three of a kind, two pair, one pair, and high card hands.

      The evaluation process:

      1. Checks for flush conditions using bitwise operations
      2. Evaluates straights and high card hands using lookup tables
      3. Handles remaining hands (pairs, trips, etc.) using prime number products and hashing
      Returns:
      the ranking value of this hand as an integer between 1 and 7462, where 1 represents the best possible hand (royal flush) and 7462 represents the worst possible hand (7-5-4-3-2 offsuit)
      Throws:
      IllegalArgumentException - if the hand contains duplicate cards

    • fromString

      public static Hand fromString(String string)
      Creates a new 5-card hand from its string representation.

      Parses a space-separated string of card representations into a Hand object. Each card in the string must follow the two-character format defined by Card.fromString(String).

      Parameters:
      string - the space-separated string representation of 5 cards
      Returns:
      a new Hand instance corresponding to the parsed cards
      Throws:
      IllegalArgumentException - if the string does not contain exactly 5 valid cards or if any individual card string is invalid
      See Also:

    • toString

      public String toString()
      Returns the string representation of this hand.

      Creates a space-separated string of the individual card representations, in the order they were provided to the constructor.

      Example outputs:

      • "As Kd Qh Jc Ts"
      • "2c 7s 9h Jd Ac"
      Specified by:
      toString in class Record
      Returns:
      a space-separated string representation of all cards in this hand

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • cards

      public Card[] cards()
      Returns the value of the cards record component.
      Returns:
      the value of the cards record component