CardSimEngine/cardsim/deck.go

package cardsim

import (
	"errors"
	"fmt"
	"math"
	"math/rand"
)

var (
	WarningBackwardsRange = Warningf("low end of range was above high end of range, flipping it")
	WarningTopClamped     = Warningf("target above top of deck moved to top")
	WarningBottomClamped  = Warningf("target below bottom of deck moved to bottom")
	WarningTooFewCards    = Warningf("too few cards")

	ErrorNoCards = errors.New("totally out of cards")
)

const (
	BottomOfDeck = math.MaxInt
)

// The Deck stores cards yet-to-be-dealt.
type Deck[C StatsCollection] struct {
	cards []Card[C]
	rand  *rand.Rand
}

// Len returns the number of cards in the Deck.
func (d *Deck[C]) Len() int {
	return len(d.cards)
}

// Insert puts one or more cards at a specific location in the Deck. Cards
// at that location and all locations after are shifted deeper into the deck.
// Negative indexes are counted from the bottom of the deck. BottomOfDeck is
// a sentinel value for the bottommost position; -1 is one card above.
//
// Inserting at "one past the end", or using the BottomOfDeck sentinel,
// adds a card to the bottom of the deck  without error. Adding it deeper
// than that does the same but returns WarningBottomClamped. Negative indexes
// that exceed the number of cards in  the deck go to the top of the deck; if
// it's more negative than "one before the beginning", this returns
// WarningTopClamped. Like all warnings, these can be safely ignored and the
// program is in a well-defined state, but you may want to check for them
// if you expect some other behavior.
func (d *Deck[C]) Insert(idx int, card ...Card[C]) error {
	var errs ErrorCollector
	// Calculate actual target index.
	switch {
	case idx == BottomOfDeck:
		idx = d.Len()
	case idx > d.Len():
		errs.Add(fmt.Errorf("%w: position %d requested in %d cards", WarningBottomClamped, idx, d.Len()))
		idx = d.Len()
	case idx < -d.Len():
		errs.Add(fmt.Errorf("%w: position %d (backwards) requested in %d cards", WarningTopClamped, idx, d.Len()))
		idx = 0
	case idx < 0:
		idx += d.Len()
	}
	// remaining case: 0 <= idx <= d.Len(), which is a normal forward insert index.
	d.cards = InsertInto(d.cards, idx, card...)
	return errs.Emit()
}

// Draw pops the 0th card off the deck and returns it. If the deck has no cards, it returns nil.
func (d *Deck[C]) Draw() Card[C] {
	if d.Len() == 0 {
		return nil
	}
	ret := d.cards[0]
	// Discard the top card via reslicing. This means that cards and deck slots
	// hang around until an Append copies the deck structure somewhere else.
	// If this turns out to be a problem, implement a more efficient algorithm
	// or data structure.
	d.cards = d.cards[1:]
	return ret
}

// DrawN pops the top N cards off the deck and returns them. If the deck does
// not have that many cards, this returns as many cards as it has and
// WarningTooFewCards, unless the deck has no cards at all, in which case it
// returns nil, ErrorNoCards.
func (d *Deck[C]) DrawN(n int) ([]Card[C], error) {
	if d.Len() == 0 {
		return nil, ErrorNoCards
	}
	if d.Len() <= n {
		ret := d.cards
		d.cards = nil
		if len(ret) < n {
			return ret, WarningTooFewCards
		}
		return ret, nil
	}
	ret := d.cards[:n]
	d.cards = d.cards[n:]
	return ret, nil
}

// InsertRandom puts a card randomly in the deck, with equal probability for
// any of the Len()+1 possible locations.
func (d *Deck[C]) InsertRandom(card Card[C]) error {
	return d.InsertRandomRange(0.0, 1.0, card)
}

// InsertRandomTop puts a card randomly in the top part of the deck, within
// the fraction of the deck specified by frac, between 0.0 and 1.0 inclusive.
// If frac is not in this range, it returns ErrBadFrac and does not insert
// the card.
//
// InsertRandomTop chooses its insertion location uniformly randomly within
// the provided fractional range. If `frac * (d.Len()+1)` is not an integer,
// InsertRandomTop places the card slightly past the end of the specified range
// if its random location lands within the "fractional slot" at the end that
// didn't line up evenly.
//
// Example
// -------
//
// Consider a 1-card deck, `[A]`. This deck has two places a card (we'll call
// it `B`) can be inserted: before or after the existing card, yielding decks
// `[A, B]` and `[B, A]`. If `InsertRandomTop` is invoked on this deck, then:
//
//   - **If `frac <= 0.5`:** The only possible result is `[B, A]`. The range
//     covering 50% of the open slots does not include any portion of any slot
//     beyond the first. It may include less than the entire first slot, but
//     there are no other slots possible.
//   - **If `frac == 1.0`:** Both placements are equally likely. All slots are
//     completely covered.
//   - **If `frac == 0.75`:** It will choose `[B, A]` two-thirds of the time and
//     `[A, B]` one-third of the time. The first 0.5 of the range covers the
//     first slot (before `A`); the remaining 0.25 covers _half_ of the slot
//     after A. This slot is therefore half as likely to be chosen as any other
//     slot -- the only other slot, in this simplified example.
//
// For most practical purposes, this detail can be safely ignored.
func (d *Deck[C]) InsertRandomTop(frac float64, card Card[C]) error {
	return d.InsertRandomRange(0.0, frac, card)
}

// InsertRandomBottom puts a card randomly somewhere in the bottom part of
// the deck, within the fraction of the deck specified by frac. See
// InsertRandomTop for details on edge conditions of range calculation.
func (d *Deck[C]) InsertRandomBottom(frac float64, card Card[C]) error {
	return d.InsertRandomRange(frac, 1.0, card)
}

// InsertRandomRange puts a card randomly somewhere between the loFrac and
// hiFrac fraction of the deck. See InsertRandomTop for details on edge
// conditions of range calculation. 0.0 is the slot before the top of the
// deck and 1.0 is the slot after the end.
//
// Warnings it may return include WarningBackwardsRange, WarningTopClamped,
// and WarningBottomClamped, and any combination of these (multiple errors
// can be aggregated into one and errors.Is will recognize all of them).
func (d *Deck[C]) InsertRandomRange(loFrac, hiFrac float64, card Card[C]) error {
	var errs ErrorCollector

	// Check argument ordering and bounds.
	if loFrac > hiFrac {
		errs.Add(Warningf("%w: %f > %f", WarningBackwardsRange, loFrac, hiFrac))
		loFrac, hiFrac = hiFrac, loFrac
	}
	if loFrac < 0.0 {
		errs.Add(Warningf("%w: loFrac was %f", WarningTopClamped, loFrac))
		loFrac = 0.0
	}
	if loFrac > 1.0 {
		errs.Add(Warningf("%w: loFrac was %f", WarningBottomClamped, loFrac))
		loFrac = 1.0
	}
	if hiFrac < 0.0 {
		errs.Add(Warningf("%w: hiFrac was %f", WarningTopClamped, hiFrac))
		hiFrac = 0.0
	}
	if hiFrac > 1.0 {
		errs.Add(Warningf("%w: hiFrac was %f", WarningBottomClamped, hiFrac))
		hiFrac = 1.0
	}

	// Pick a random spot in this range and translate it to a card slot.
	scale := hiFrac - loFrac
	spotFrac := d.rand.Float64()*scale + loFrac
	slot := int(spotFrac * float64(d.Len()+1))
	if slot > d.Len() {
		// This can't happen. rand.Float64 cannot return 1.0, so len+1 itself
		// should not be reachable.
		slot = d.Len()
		errs.Add(Warningf("%w: InsertRandomRange(%f, %f, ...) chose slot end-plus-one: %d (limit %d). fraction %f",
			WarningRecoverableBug, loFrac, hiFrac, slot, d.Len(), spotFrac))
	}

	// okay, after all that, we have a slot!
	errs.Add(d.Insert(slot, card))
	return errs.Emit()
}

// Shuffle completely shuffles the deck. If the deck has one or fewer cards,
// this returns WarningTooFewCards since nothing can be shuffled.
func (d *Deck[C]) Shuffle() error {
	if len(d.cards) < 2 {
		return WarningTooFewCards
	}
	ShuffleAll(d.cards, d.rand)
	return nil
}

// ShufflePart shuffles the `n` cards of the deck starting at `loc`.
// If the provided range doesn't fit in the deck, this returns
// WarningTopClamped and/or WarningBottomClamped. If the eventual range
// of cards to be shuffled (after any off-the-end issues are corrected)
// is one or less, this returns WarningTooFewCards since nothing can
// be shuffled.
func (d *Deck[C]) ShufflePart(loc, n int) error {
	if n < 2 {
		// Nothing to do.
		return WarningTooFewCards
	}

	var errs ErrorCollector
	if loc < 0 {
		errs.Add(Warningf("%w: loc was %d", WarningTopClamped, loc))
		loc = 0
	}
	if loc+n > d.Len() {
		errs.Add(Warningf("%w: deck size %d does not have %d cards at and after location %d",
			WarningBottomClamped, len(d.cards), n, loc))
		n = d.Len() - loc
		// Now is there anything to do?
		if n < 2 {
			errs.Add(WarningTooFewCards)
			return errs.Emit()
		}
	}

	ShufflePart(d.cards, d.rand, loc, n)
	return nil
}

// ShuffleRange shuffles the cards between the specified fractions of
// the deck; the top of the deck is 0.0 and the bottom of the deck is
// 1.0. This rounds "outward" -- "partial" cards at each end are counted.
// This can return the same warnings ShufflePart can in the same circumstances
// and may also complain about a backwards range.
func (d *Deck[C]) ShuffleRange(loFrac, hiFrac float64) error {
	var errs ErrorCollector
	if loFrac > hiFrac {
		errs.Add(Warningf("%w: %f > %f", WarningBackwardsRange, loFrac, hiFrac))
		loFrac, hiFrac = hiFrac, loFrac
	}
	low := int(math.Floor(loFrac * float64(d.Len())))
	high := int(math.Ceil(hiFrac * float64(d.Len())))
	n := 1 + high - low
	errs.Add(d.ShufflePart(low, n))
	return errs.Emit()
}

// ShuffleTop uses ShuffleRange to shuffle the top frac (between 0.0 and 1.0)
// of the deck. See ShuffleRange and ShufflePart for information on
// rounding and warnings.
func (d *Deck[C]) ShuffleTop(frac float64) error {
	return d.ShuffleRange(0.0, frac)
}

// ShuffleBottom uses ShuffleRange to shuffle the bottom frac (between 0.0 and
// 1.0) of the deck. See ShuffleRange and ShufflePart for information on
// rounding and warnings.
func (d *Deck[C]) ShuffleBottom(frac float64) error {
	return d.ShuffleRange(frac, 1.0)
}

// Strip removes all cards from the deck where shouldRemove returns true.
// shouldRemove is provided with each card in the deck and its index.
// It returns how many cards were stripped from the deck.
func (d *Deck[C]) Strip(shouldRemove func(idx int, c Card[C]) bool) int {
	origLen := d.Len()
	d.cards = Strip(d.cards, shouldRemove)
	return origLen - d.Len()
}