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 a card at a specific location in the Deck. The card previously
// at that location and all locations after are shifted one card later.
// 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.

	// Place new card on bottom and "bubble" into position.
	// Takes O(N) time. If this turns out to be a problem, implement a more
	// efficient data structure.
	d.cards = append(d.cards, card)
	for i := len(d.cards) - 1; i > idx; i-- {
		d.cards[i], d.cards[i-1] = d.cards[i-1], d.cards[i]
	}
	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 %d", WarningTopClamped, loFrac))
		loFrac = 0.0
	}
	if loFrac > 1.0 {
		errs.Add(Warningf("%w: loFrac was %d", WarningBottomClamped, loFrac))
		loFrac = 1.0
	}
	if hiFrac < 0.0 {
		errs.Add(Warningf("%w: hiFrac was %d", WarningTopClamped, hiFrac))
		hiFrac = 0.0
	}
	if hiFrac > 1.0 {
		errs.Add(Warningf("%w: hiFrac was %d", 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()
}