Innobate.CardDeck 0.0.11-alpha

CardDeck Library

Introduction

The CardDeck library provides a versatile framework for working with playing cards, offering features to create and manipulate decks of cards. It is designed to be flexible and adaptable for various card games and applications.

Card Class

ICard Interface

• An interface representing a playing card.
• Properties:
  • Suit: Represents the suit of the card.
  • CardValue: Represents the value of the card.
  • Rank: Used to rank the card in the deck.
• Methods:
  • GetShortCode(): Returns a short code representing the card.
  • GetCardTypeName(): Returns the name of the card type (e.g., "Standard US").

Card Class

• Simplest data structure to represent information about a general playing card.
• Inherits from ICard.
• Provides a constructor to set the suit and card value.
• Implements the GetShortCode method to get a short code representation of the card.

Card Type Jacketing Classes

CourtCard<TCard> Class

• Represents a court card, which is a card ranked higher than a pip card.
• Inherits from Card and implements ICard.
• Allows categorization of cards as court cards.
• Enables parameterization with a base card type (TCard).
• Inherits the GetShortCode method from Card and adds the IsCourtCard property.

AceCard<TCard> Class

• Represents an Ace card, which is ranked higher than a pip card and court card.
• Inherits from Card and implements ICard.
• Allows categorization of cards as Ace cards.
• Enables parameterization with a base card type (TCard).
• Inherits the GetShortCode method from Card and adds the IsAceCard property.

PipCard<TCard> Class

• Represents a pip card, which is ranked lower than a court card or an Ace card.
• Inherits from Card and implements ICard.
• Allows categorization of cards as pip cards.
• Enables parameterization with a base card type (TCard).
• Inherits the GetShortCode method from Card and adds the IsPipCard property.

Card Enumerations

CardSuit Enum

• Enumerates the possible suits of a card, including Joker, Spades, Hearts, Clubs, and Diamonds.

CardValue Enum

• Enumerates the possible face values of a card, including Joker, Ace, Two, Three, and so on.

DeckFactory Class

DeckFactory<TCard, TJokerCard> Class

Responsible for creating instances of card and joker card classes. Provides methods for creating cards, joker cards, initializing decks, and setting the number of packs in a deck. Properties:

• DeckType: Represents the type of the deck (e.g., "French" or "US Standard").

Methods:

• CardsInStandardSuit(): Returns the number of cards in a standard suit.
• StandardDeckSize(): Returns the size of a standard deck.
• SuitsInDeck(): Returns the number of suits in the deck.
• CreateCard(int suit, int value): Creates a card instance.
• CreateJokerCard(int suit, int value): Creates a joker card instance.
• CreateJokerCard(int suit, int value, JokerType type): Creates a joker card instance with a specific type.
• InitialiseCards(Deck<TCard, TJokerCard> deck, bool includeJokers = false, int jokerQuantity = 2, int packQuantity = 1): Initializes the cards in a deck, allowing for setting the number of packs.
• GetDeckType(): Returns the type of the deck.

IDeckFactory Interface

IDeckFactory<TCard, TJokerCard> Interface

• Provides a common interface for creating card decks.
• Defines methods for creating standard card decks and joker decks, initializing cards, and providing information about deck sizes.

Deck Class

Deck<TCard, TJokerCard> Class

• A generic class to represent a card deck.
• Supports shuffling, dealing, pulling cards, and cutting the deck.
• Allows custom deck factory implementation.
• Constructors:
  • Deck(bool includeJokers = false, int jokerQuantity = 2): Creates a deck instance.
  • Deck(IDeckFactory<TCard, TJokerCard> deckFactory, bool includeJokers = false, int jokerQuantity = 2): Creates a deck instance with a custom deck factory.

DeckShuffler Class

DeckShuffler Class

• A generic deck shuffler that can shuffle an array of objects.
• Implements the Fisher-Yates shuffle algorithm.

JokerCard Class

JokerCard Class

• Represents a special joker card in a deck.
• Inherits from Card and implements ICard.
• Properties:
  • Replacing: The card that the joker replaces.
  • Type: The type of the joker (e.g., Black, Red, White, FullColor).
• Provides a constructor for creating joker cards.
• Overrides the GetShortCode method to represent joker cards.
• Methods:
  • ReplaceCard(ICard replacing): Replaces the joker with another card.
  • IsBigJoker(): Returns whether the joker is a big joker.

JokerType Enumeration

• Enumerates the possible types of joker cards, including Black, Red, White, and FullColor.

---

This library is a comprehensive solution for working with playing cards in various applications, providing essential tools for card game development and simulations.

Class Relationships and Dependencies

DeckFactory<TCard, TJokerCard> Class

• Responsible for creating new instances of card objects.
• Provides two methods: CreateCard and CreateJokerCard, to create card and joker card instances.
• Uses generic type parameters TCard and TJokerCard for flexibility in creating different card types.

Deck<TCard, TJokerCard> Class

• A generic class representing a card deck.
• Can include joker cards based on the includeJokers parameter and the specified jokerQuantity.
• Uses the DeckFactory class to create card and joker card instances.
• Supports operations such as shuffling, dealing, pulling cards from specific indexes, getting the card count, and cutting the deck.
• Enforces constraints on card index ranges when pulling or cutting the deck.
• Maintains an array of card objects, with the size determined by the type of cards (TCard).
• Relies on the DeckShuffler class to shuffle the cards.
• Relies on the DeckFactory class to create card objects.

Dependencies

• DeckFactory<TCard, TJokerCard> uses the DeckFactory class to create card objects.
• Deck<TCard, TJokerCard> uses the DeckFactory class to create card and joker card instances and the DeckShuffler class to shuffle the cards.

Examples of Using the Classes

To use the DeckFactory class, specify the types of cards to create. For a standard deck with jokers:

Deck<Card, JokerCard> deck = new Deck<Card, JokerCard>(true, 2);

Creating Custom Cards

You can also create decks of custom cards. For example, to create a deck of custom cards:

class CustomCard : Card
{
    public CustomCard(CardSuit suit, CardValue value) : base(suit, value)
    {
    }
}

class CustomJokerCard : JokerCard
{
    public CustomJokerCard(CardSuit suit, CardValue value) : base(suit, value)
    {
    }
}

Deck<CustomCard, CustomJokerCard> customDeck = new Deck<CustomCard, CustomJokerCard>(true, 2);

Additional ways of instantiating the Deck Class

Method 1: Using Constructor Parameters

Deck<CustomCard, CustomJokerCard> deck = new Deck<CustomCard, CustomJokerCard>(includeJokers: true, jokerQuantity: 2);

• In this method, a Deck is created by specifying constructor parameters.
• The includeJokers parameter is set to true, indicating that joker cards should be included in the deck.
• The jokerQuantity parameter is set to 2, specifying that two joker cards should be added.

Method 2: Using Constructor with DeckFactory

Deck<CustomCard, CustomJokerCard> deckTwo = new Deck<CustomCard, CustomJokerCard>(new DeckFactory<CustomCard, CustomJokerCard>(), true, 4);

• In this method, a Deck is created using the constructor that accepts a custom deck factory and additional parameters.
• The new DeckFactory<CustomCard, CustomJokerCard>() creates a custom deck factory for this deck.
• The includeJokers parameter is set to true, indicating that joker cards should be included in the deck.
• The jokerQuantity parameter is set to 4, specifying that four joker cards should be added.

Method 3: Using a Predefined DeckFactory

IDeckFactory<CustomCard, CustomJokerCard> deckFactory1 = new DeckFactory<CustomCard, CustomJokerCard>();
Deck<CustomCard, CustomJokerCard> deck3 = new Deck<CustomCard, CustomJokerCard>(deckFactory1, true, 5);

• In this method, a custom deck factory (deckFactory1) is created using the DeckFactory class.
• The Deck is then instantiated using this predefined custom deck factory.
• The includeJokers parameter is set to true, indicating that joker cards should be included in the deck.
• The jokerQuantity parameter is set to 5, specifying that five joker cards should be added.

Deck Class - French and US Deck of Cards

The Deck class is a versatile card deck representation that allows for the creation of both French and US decks of cards. The primary distinction between these two types of decks is the presence of Joker cards. The US deck includes two Joker cards, while the French deck does not contain any Joker cards.

French Deck

The French deck consists of the following characteristics:

• Number of Cards: 52
• Joker Cards: None
• Court Cards: King, Queen, Jack
• Suit Order: Clubs, Diamonds, Hearts, Spades

US Deck

The US deck is an extension of the French deck and features the following attributes:

• Number of Cards: 54
• Joker Cards: 2 Jokers
• Court Cards: King, Queen, Jack, Joker
• Suit Order: Clubs, Diamonds, Hearts, Spades

Historical Perspective

The US deck is derived from the French deck and was altered in the early 19th century to introduce the Joker card. Originally, the Joker card was used as a wild card in specific card games, but it has now become a standard component of the US deck.

Game Preferences

The choice of deck often reflects the popularity of certain card games in various regions. French decks are favored in regions where games like bridge and whist are prevalent. In contrast, US decks are more common in regions where games like poker and blackjack are popular.

In summary, while the French deck and the US deck share many similarities, the key distinction lies in the inclusion of the Joker card in the US deck, making it suitable for a broader range of card games.

Examples

Here is an example of how to instantiate the Deck class as a French deck and as a US deck of cards:

// Create a new DeckFactory object
IDeckFactory<Card, JokerCard> deckFactory = new DeckFactory<Card, JokerCard>();

// Create a new French deck of cards
Deck<Card, JokerCard> frenchDeck = new Deck<Card, JokerCard>(deckFactory, includeJokers: false, jokerQuantity: 0);

// Create a new US deck of cards
Deck<Card, JokerCard> usDeck = new Deck<Card, JokerCard>(deckFactory, includeJokers: true, jokerQuantity: 2);

We can still use the frenchDeck and usDeck objects to shuffle the decks, deal cards from the decks, and check the number of cards remaining in the decks, as before.

Here is an example of how to shuffle the French deck and deal a card:

// Shuffle the French deck
await frenchDeck.Shuffle();

// Deal a card from the French deck
Card frenchCard = frenchDeck.DealCard();

Here is an example of how to shuffle the US deck and deal a card:

// Shuffle the US deck
await usDeck.Shuffle();

// Deal a card from the US deck
Card usCard = usDeck.DealCard();

These examples demonstrate the creation and utilization of both French and US decks using the Deck class, showcasing how you can customize decks for different card games.

Class Dependencies, Relationships, Properties, and Methods

In the CardDeck namespace, we have several classes and enums that interact to represent a card deck. These classes are responsible for creating and managing card decks for different card games.

CardDeck

Classes

Card

• Description: Represents a general playing card.
• Properties:
  • Suit: The suit of the card.
  • CardValue: The face value of the card.
  • Rank: The ranking of the card in the deck.

DeckFactory<TCard, TJokerCard>

• Description: Creates instances of Card and JokerCard classes.
• Methods:
  • CreateCard(int suit, int value): Creates a card of the specified type.
  • CreateJokerCard(int suit, int value): Creates a joker card of the specified type.
  • CreateJokerCard(int suit, int value, JokerType type): Creates a joker card with a specified type.
  • InitialiseCards(Deck<TCard, TJokerCard> deck, bool includeJokers = false, int jokerQuantity = 2): Initializes a deck with cards and jokers.

Deck<TCard, TJokerCard>

• Description: Represents a generic card deck that can be shuffled and cards dealt from.
• Properties:
  • StandardDeckSize: The size of a standard deck.
  • CardsInStandardSuit: The number of cards in a standard suit.
• Methods:
  • Shuffle(): Shuffles the deck.
  • DealCard(): Deals a card from the top of the deck.
  • PullCard(int cardIndex): Pulls a specific card from the deck.
  • CardCount(): Returns the number of cards in the deck.
  • CutDeck(int cutIndex): Cuts the deck at a specified index.

DeckShuffler

• Description: A generic deck shuffler that can shuffle an array of objects.
• Methods:
  • Shuffle<T>(T[] array): Shuffles an array of objects.

JokerCard

• Description: Represents a special card that can replace other cards in some games.
• Properties:
  • Replacing: The card being replaced.
  • Type: The type of the joker card (Black, Red, White, FullColor)

Enums

CardSuit

• Description: An enum used to represent the suit of a playing card.
• Values:
  • Joker
  • Spades
  • Hearts
  • Clubs
  • Diamonds

CardValue

• Description: An enum used to represent the face value of a playing card.
• Values:
  • Joker
  • Ace
  • Two
  • Three
  • Four
  • Five
  • Six
  • Seven
  • Eight
  • Nine
  • Ten
  • Jack
  • Queen
  • King

JokerType

• Description: An enum representing different types of joker cards.
• Values:
  • Black
  • Red
  • White
  • FullColor

Interfaces

ICard

• Description: An interface representing a playing card.
• Properties:
  • Suit: The suit of the card.
  • CardValue: The face value of the card.
  • Rank: The ranking of the card in the deck.

IDeckFactory<TCard, TJokerCard>

• Description: An interface for creating card decks of various standards using the DeckFactory<TCard, TJokerCard> class.

• Methods:

  • StandardDeckSize(): Returns the size of a standard deck.
  • CardsInStandardSuit(): Returns the number of cards in a standard suit.
  • SuitsInDeck(): Returns the number of suits in the deck.
  • CreateCard(int suit, int value): Creates a card of the specified type.
  • CreateJokerCard(int suit, int value): Creates a joker card of the specified type.
  • CreateJokerCard(int suit, int value, JokerType type): Creates a joker card with a specified type.
  • InitialiseCards(Deck<TCard, TJokerCard> deck, bool includeJokers = false, int jokerQuantity = 2): Initializes a deck with cards and jokers.

  Relationships

• Card and JokerCard classes implement the ICard interface.

• The DeckFactory<TCard, TJokerCard> class creates instances of cards and joker cards.

• The Deck<TCard, TJokerCard> class uses the DeckShuffler class to shuffle the deck.

• Various classes interact with Deck<TCard, TJokerCard> for card game functionality.

Dependencies

• The library depends on the .NET Framework.
• It utilizes standard C# classes, enums, and interfaces.

These classes and enums are used to represent and interact with card decks in various card games.

US Deck of Playing Cards

The US Deck of playing cards, also known as the Standard American deck, is one of the most widely recognized and used decks of cards in the world. It consists of 52 cards divided into four suits:

• Hearts
• Diamonds
• Clubs
• Spades

Each suit contains 13 cards: ace, 2-10, and the court cards (king, queen, and jack).

Court Card Ranking

The court cards in a US Deck are ranked as follows:

1. King
2. Queen
3. Jack

The other cards are ranked in numerical order, with the ace being the highest card.

Jokers: A standard US Deck includes two joker cards, which are often used in various card games and for entertainment purposes.

Usage: The US Deck is widely used in North America and other parts of the world for various card games, including poker, bridge, and blackjack. It is also used in magic tricks and other entertainment.

French Deck of Playing Cards

The French Deck of playing cards is a standard deck used in France and many other countries. It is similar to the US Deck but with some differences. The deck consists of 52 cards divided into four suits:

• Hearts
• Diamonds
• Clubs
• Spades

Each suit contains 13 cards: ace, 2-10, and the court cards (king, queen, and jack).

Court Card Ranking

The court cards in a French Deck are ranked as follows:

1. King
2. Queen
3. Jack

The other cards are ranked in numerical order, with the ace being the highest card.

Jokers: Unlike the US Deck, a standard French Deck does not include joker cards.

Usage: French cards are commonly used in France and many European countries for various card games, including bridge and belote. They are also used in some poker games and for fortune telling.

Differences from US Deck: While the French Deck shares many similarities with the US Deck, the key difference lies in the absence of joker cards in the French Deck.

Here's a table of the different names for French and US cards in English and French:

English	French
Ace	As
King	Roi
Queen	Dame
Jack	Valet
Hearts	Cœurs
Diamonds	Carreaux
Clubs	Trèfles
Spades	Piques

The US Deck and French Deck of playing cards serve as the foundation for a wide range of card games and entertainment across the world.

New Feature: Specify Number of Packs in a Deck

The DeckFactory class now includes a new method called InitialiseCards() that allows you to specify the number of packs in a deck. This is useful if you need to create a deck with more than one pack of cards.

Usage

To create a deck with two packs of cards, use the following code:

Deck<TCard, TJokerCard> deck = new Deck<TCard, TJokerCard>(false, 0, 2);

This will create a deck with 104 cards (2 packs of 52 cards).

To create a deck with two packs of cards and two jokers, use the following code:

Deck<TCard, TJokerCard> deck = new Deck<TCard, TJokerCard>(true, 2, 2);

This will create a deck with 108 cards (2 packs of 52 cards and 2 jokers).

Example

The following example shows how to create a deck with two packs of cards and two jokers, and then shuffle the deck:

Deck<TCard, TJokerCard> deck = new Deck<TCard, TJokerCard>(true, 2, 2);

Console.WriteLine("Deck size: {0}", deck.CardCount());

Task.Run(() => deck.Shuffle()).Wait();

Console.WriteLine("Deck size after shuffle: {0}", deck.CardCount());

ICard? card = deck.DealCard();
Console.WriteLine("Dealt card: {0} of {1}", card.CardValue.ToString(), card.Suit.ToString());

This will output the following:

Deck size: 108
Deck size after shuffle: 108
Dealt card: Two of Clubs

Enhanced Random Number Generation and Cryptographically Secure Shuffling

The latest update to the CardDeck library introduces significant enhancements in random number generation and card deck shuffling. These improvements aim to provide users with more control over random number generation and ensure cryptographically secure shuffling of card decks.

IRandomiser Interface for Flexible Random Number Generation

The IRandomiser interface has been introduced to provide a standardized approach to random number generation. This interface defines four methods for generating random numbers:

• Next(int exclusive): Generates a random integer within the exclusive range from 0 to the specified exclusive bound.

• Next(long exclusive): Generates a random long integer within the exclusive range from 0 to the specified exclusive bound.

• Next(int inclusive, int exclusive): Generates a random integer within the inclusive range from the specified inclusive bound to the specified exclusive bound.

• Next(long inclusive, long exclusive): Generates a random long integer within the inclusive range from the specified inclusive bound to the specified exclusive bound.

SystemRandomiser and CryptoRandomiser Implementations

The CardDeck library now includes two concrete implementations of the IRandomiser interface:

• SystemRandomiser: This class implements the IRandomiser methods using the System.Random class, which is a non-cryptographically secure random number generator.

• CryptoRandomiser: This class implements the IRandomiser methods using the System.Security.Cryptography.RandomNumberGenerator class, which provides cryptographically secure random number generation.

Cryptographically Secure Shuffling with DeckShuffler

The DeckShuffler class has been updated to utilize the CryptoRandomiser class for shuffling card decks. This ensures that the shuffling process is cryptographically secure, providing a higher level of randomness and protection against potential biases or predictability.

Benefits of the New Feature

The enhanced random number generation and cryptographically secure shuffling capabilities offer several benefits to users of the CardDeck library:

• More Control over Random Number Generation: The IRandomiser interface provides users with the flexibility to choose between cryptographically secure and non-cryptographically secure random number generation based on their specific requirements.

• Enhanced Security for Card Shuffling: The use of the CryptoRandomiser class in the DeckShuffler class ensures that card decks are shuffled in a cryptographically secure manner, preventing any predictable patterns or biases.

• Increased Reliability for Simulations and Games: The combination of enhanced random number generation and cryptographically secure shuffling provides a more reliable foundation for simulations, games, and other applications that depend on randomness.

attribute

<a href="https://www.flaticon.com/free-icons/card-deck" title="card deck icons">Card deck icons created by ArtBit - Flaticon</a>