cards

cards

A tiny Go package that models a standard 52-card deck. It provides a fast, zero-allocation representation of cards and a simple, deterministic shuffle for reproducible results.

Features

• 52-card deck with suits and ranks encoded into a compact Card type
• Deterministic Shuffle(seed int64) for repeatable shuffles
• Sequential dealing with Next() and exhaustion check with IsExhausted()
• Human-readable String() representation (e.g. A♥, T♣, Q♦, K♠)

Installation

go get github.com/Heebron/cards

If you are already inside this repository as a module, no additional steps are required.

Quick start

package main

import (
    "fmt"
    "time"

    "github.com/Heebron/cards"
)

func main() {
    d := cards.NewDeck()

    // Shuffle with a deterministic seed (use time.Now().UnixNano() for non-deterministic)
    d.Shuffle(time.Now().UnixNano())

    for {
        c, exhausted := d.Next()
        fmt.Println(c) // e.g., A♥, 2♣, ...
        if exhausted {
            break
        }
    }
}

API overview

• Types
  • type Card uint8
  • type Deck struct
• Constructors
  • func NewDeck() Deck
• Methods
  • func (d *Deck) Shuffle(seed int64) — shuffle the deck using the provided seed
  • func (d *Deck) Next() (Card, bool) — deal the next card; second return value is true on last card
  • func (d *Deck) IsExhausted() bool — returns true after the last card has been returned
  • func (c Card) Suit() int — suit index (0..3) in the order Heart, Club, Diamond, Spade
  • func (c Card) Rank() int — rank index (0..12) in the order Ace..King
  • func (c Card) String() string — short string form like A♥, T♣, Q♦, K♠

Suits and ranks are exposed as integer constants:

• Suits: Heart, Club, Diamond, Spade
• Ranks: Ace, Two, Three, Four, Five, Six, Seven, Eight, Nine, Ten, Jack, Queen, King

Deterministic shuffles

The shuffle uses a local PRNG seeded with seed. Re-using the same seed will produce the same card order — useful for tests. Call Shuffle(time.Now().UnixNano()) for non-deterministic shuffles in production.

Testing

This repository includes unit tests. Run:

go test ./...

License

This project is licensed under the MIT License. See the LICENSE file for details.