migration-from-cpp.md

Migration From C++ PokerStove

pokerstove-go is a native Go package, not a cgo binding and not a port of the C++ class hierarchy. The goal for Go integrators is to keep PokerStove behavior where it matters while using Go values, errors, and package-level APIs.

Concept Map

C++ PokerStove concept	Go concept	Migration note
Card	Card	Construct with NewCard(rank, suit) or parse text with ParseCard.
CardSet	CardSet	A compact bit set. Use ParseCardSet, Insert, Remove, Contains, Disjoint, Size, Cards, and String.
CardSet::str()	CardSet.String()	Produces canonical PokerStove card text in deck order, such as AcQhKh.
PokerHandEvaluator::alloc(...)	NewEvaluator(game)	Parses C++-style game identifiers and aliases into a concrete Go *Evaluator. Unknown games return an error.
Evaluator metadata	Evaluator.Metadata() or Game.Metadata()	Reports hand size, board size, evaluation size, display name, and suit usage.
PokerHandEvaluator::evaluateHand(...)	Evaluator.Evaluate(hand, board)	Returns HandEvaluation, with high evaluation fields and an optional low evaluation.
Hold'em-only high evaluation	EvaluateHoldem(hand, board)	Convenience API for callers that only need Hold'em high-hand categories.
C++ evaluation ordering	Evaluator.Compare(left, right, board)	Returns positive, zero, or negative. Better hands compare greater, including lowball-style games.
PokerEvaluation high fields	Evaluation	Exposes hand category, major rank, minor rank, and kickers for high-hand results.
Optional low result	HandEvaluation.Low and HandEvaluation.HighLow()	Low == nil means there is no qualifying low, even in games whose metadata has two evaluation slots.
CardDistribution	HandDistribution from ParseHandDistribution	Parses raw weighted card sets such as AcAs=0.25,KhQh=0.75; . is accepted as the entire distribution string for a random completion placeholder.
ShowdownEnumerator	EvaluateShowdown(ShowdownRequest)	Enumerates selected distributions, completes partial hands and boards, applies weights, and returns per-player shares.
Win/tie shares	ShowdownResult.Players[i].WinShares and .TieShares	Equity is normalized from win plus tie shares when total shares are nonzero.

Common Migration Patterns

Create an evaluator once per game identifier and reuse it:

evaluator, err := pokerstove.NewEvaluator("o8")
if err != nil {
    return err
}
metadata := evaluator.Metadata()

Parse card text at your application boundary. A parsed CardSet is cheap to pass around and can be reused for direct evaluation, comparison, and showdown requests:

hand, err := pokerstove.ParseCardSet("AcKd")
if err != nil {
    return err
}
board, err := pokerstove.ParseCardSet("2c3d4h5s9c")
if err != nil {
    return err
}

evaluation, err := evaluator.Evaluate(hand, board)
if err != nil {
    return err
}
_ = evaluation.High

Use EvaluateShowdown when you need PokerStove-style enumeration rather than a single direct evaluation:

result, err := pokerstove.EvaluateShowdown(pokerstove.ShowdownRequest{
    Game:  "h",
    Board: "2c3d4h5s9c",
    Hands: []string{"AcAs=0.25,KcKs=0.75", "QhQs=0.5,JhJs=0.5"},
})
if err != nil {
    return err
}
_ = result.Players[0].Equity

Differences To Plan For

Go APIs return ordinary error values instead of relying on C++ allocation or exception patterns. Do not parse error strings for control flow; use the error as a rejection reason for users and keep your own validation state where you need typed application decisions.

pokerstove-go intentionally exposes a smaller public value model than C++. For lowball and badugi games, ordering parity is available through Evaluator.Compare; the public evaluation structs do not expose every C++ internal bit layout.

Showdown enumeration keeps low-level PokerStove parity. Partial hands, . distributions, and partial boards are completed by enumerating live cards. Overlapping selected distribution options are skipped. If every possible selection overlaps, the call succeeds and returns zero win and tie shares. Applications that want to reject impossible or unhelpful user input should do that before calling the low-level enumerator.

Higher-level range syntax is not currently the same thing as raw CardDistribution parsing. ParseHandDistribution accepts comma-separated card sets with optional weights, and accepts . only as the entire distribution string, but it is not a full range language.