Class Cards

java.lang.Object
com.github.yellowstonegames.core.Cards
All Implemented Interfaces:
ISerializersNeeded
@Beta public class Cards extends Object implements ISerializersNeeded
A simple class to simulate a deck of cards that can be shuffled or drawn from (without replacement). If the deck is empty and the user tries to draw a card, the deck is shuffled entirely and then a card is drawn. You can draw a card simulated by an int index with drawInt(), or get a String name for a card drawn with drawName().
An array of String names must be provided (currently) for each card's name, such as "Ace of Spades" or "The Chariot" (for a game like poker, and for tarot, respectively). You can get a name from an int retrieved earlier with nameForInt(int), or just retrieve the name directly with drawName().

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Cards.DeckType
    Predefined common types of card decks, stored by the names of cards (permitting duplicates).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    com.github.tommyettinger.ds.IntDeque
    deck
     
    String[]
    names
     
    com.github.tommyettinger.random.EnhancedRandom
    random
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Cards(Cards other)
    Copy constructor; makes a copy of each field (no direct references).
    Cards(Cards.DeckType type)
    Creates a new Cards using the specified Cards.DeckType and an unseeded Xoshiro256MX3Random generator, which is guaranteed to be able to produce all possible shuffles of an up-to-57-card deck.
    Cards(Cards.DeckType type, com.github.tommyettinger.random.EnhancedRandom random)
    Creates a new Cards using the specified Cards.DeckType and the given EnhancedRandom generator.
    Cards(String[] names, com.github.tommyettinger.random.EnhancedRandom random)
    Creates a new Cards using the given array of names (which will be used directly, permitting the name of a card to potentially be changed later if the array is modified) and an EnhancedRandom generator.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    drawInt()
    If the deck has any remaining cards, this removes the last card from the deck and returns its index.
    String
    drawName()
    If the deck has any remaining cards, this removes the last card from the deck and returns its name.
    final boolean
    equals(Object o)
     
    List<Class<?>>
    getSerializersNeeded()
    Gets a List of Class instances that must each be registered with a serialization library before this object can be successfully serialized or deserialized.
    int
    hashCode()
     
    String
    nameForInt(int index)
     
    int
    remainingCards()
    Gets how many cards are left in the deck, before drawing a card would need to shuffle.
    void
    shuffleDeck(boolean full)
    If full is true, shuffles the entire deck back in to restart it from its original size in a new order.
    String
    toString()
     

    Methods inherited from class Object

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

  • Field Details

    • deck

      public com.github.tommyettinger.ds.IntDeque deck

    • random

      public com.github.tommyettinger.random.EnhancedRandom random

    • names

      public String[] names

  • Constructor Details

    • Cards

      public Cards(String[] names, com.github.tommyettinger.random.EnhancedRandom random)
      Creates a new Cards using the given array of names (which will be used directly, permitting the name of a card to potentially be changed later if the array is modified) and an EnhancedRandom generator.
      If the EnhancedRandom.getMinimumPeriod() of the generator is at least equal to the MathTools.factorial(double) of names.length, then the generator will (in theory) be able to produce all possible shuffles of that deck. A generator such as OrbitalRandom with a period of 2 to the 71 or greater can produce all shuffles for the 22 tarot major arcana. Larger decks might need as much as a period of 2 to the 256 for a typical playing card deck (with or without jokers). CCG-type decks with 60 or more cards likely can't have all shuffles produced by a single generator currently, though the amount of possible shuffles for even the 22 tarot major arcana cards is astronomically large already.
      Parameters:
      names - a String array of names for cards, which do not need to be unique; used directly (not copied)
      random - an EnhancedRandom generator that will be used directly (not copied)

    • Cards

      public Cards(Cards.DeckType type, com.github.tommyettinger.random.EnhancedRandom random)
      Creates a new Cards using the specified Cards.DeckType and the given EnhancedRandom generator.
      If the EnhancedRandom.getMinimumPeriod() of the generator is at least equal to the MathTools.factorial(double) of Cards.DeckType.size(), then the generator will (in theory) be able to produce all possible shuffles of that deck type. A generator such as OrbitalRandom with a period of 2 to the 71 or greater can produce all shuffles for Cards.DeckType.TAROT_MAJOR_ARCANA. Larger decks might need as much as a period of 2 to the 256 for a typical playing card deck (with or without jokers). CCG-type decks with 60 or more cards likely can't have all shuffles produced by a single generator currently, though the amount of possible shuffles for even the 22 tarot major arcana cards is astronomically large already.
      Parameters:
      type - a predefined Cards.DeckType enum constant

    • Cards

      public Cards(Cards.DeckType type)
      Creates a new Cards using the specified Cards.DeckType and an unseeded Xoshiro256MX3Random generator, which is guaranteed to be able to produce all possible shuffles of an up-to-57-card deck.
      Parameters:
      type - a predefined Cards.DeckType enum constant

    • Cards

      public Cards(Cards other)
      Copy constructor; makes a copy of each field (no direct references).
      Parameters:
      other - another Cards instance to copy exactly, including the remaining deck and its order

  • Method Details

    • shuffleDeck

      public void shuffleDeck(boolean full)
      If full is true, shuffles the entire deck back in to restart it from its original size in a new order. Otherwise, this only shuffles the remaining cards in the deck into a new order.
      Parameters:
      full - if true, the deck will start again at its original size; if false, only the remaining cards will be shuffled

    • drawInt

      public int drawInt()
      If the deck has any remaining cards, this removes the last card from the deck and returns its index. Otherwise, this shuffles the entire deck back up to its original size, and then removes the last card and returns its index.
      Returns:
      an index of a card in the deck

    • drawName

      public String drawName()
      If the deck has any remaining cards, this removes the last card from the deck and returns its name. Otherwise, this shuffles the entire deck back up to its original size, and then removes the last card and returns its name.
      Returns:
      a String name of a card in the deck

    • nameForInt

      public String nameForInt(int index)
      Parameters:
      index - typically returned by drawInt()
      Returns:
      the name associated with index, or null if the index is invalid.

    • remainingCards

      public int remainingCards()
      Gets how many cards are left in the deck, before drawing a card would need to shuffle.
      Returns:
      how many cards are left in the deck

    • equals

      public final boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getSerializersNeeded

      public List<Class<?>> getSerializersNeeded()
      Description copied from interface: ISerializersNeeded
      Gets a List of Class instances that must each be registered with a serialization library before this object can be successfully serialized or deserialized. This is GwtIncompatible; none of the serialization libraries this is meant for have any support for GWT.
      Specified by:
      getSerializersNeeded in interface ISerializersNeeded
      Returns:
      a List of Class instances that must each be registered with a serialization library