NAME
Games::Cards::Poker - Perl Poker functions
VERSION
This documentation refers to version 1.0.44KFNKP of Games::Cards::Poker, which was released on Tue Apr 20 15:23:20:25 2004.
SYNOPSIS
use Games::Cards::Poker;
# Deal 4 players hands && score them...
my $players = 4; # number of players to get hands dealt
my $hand_size = 5; # number of cards to deal to each player
my @hands = ();# player hand data
my @deck = Shuffle(Deck());
for(my $pndx = 0; $pndx < $players; $pndx++) { # players
for(my $cndx = 0; $cndx < $hand_size; $cndx++) { # cards
push(@{$hands[$pndx]}, pop(@deck));
}
printf("Player%d score:%4d hand:@{$hands[$pndx]}\n",
$pndx, ScoreHand(@{$hands[$pndx]}));
}DESCRIPTION
Poker provides a few simple functions for creating decks of cards && manipulating them for simple Poker games or simulations.
2DO
- - mk up sim XML data file format (w/ RELAX NG?)
- - mk Games::Cards compatability object interface
- - better error checking
- - What else does Poker need?
USAGE
Deck()
Returns a new array of scalars with the abbreviated Poker names of cards (eg. 'As' eq 'Ace of Spades', 'Td' eq 'Ten of Diamonds', '2c' eq 'Two of Clubs', etc.).
Shuffle(@cards)
Shuffles the passed in @cards array in one quick pass. Shuffle() returns a shuffled copy of the @cards array.
Shuffle() can also take an arrayref parameter instead of an explicit @cards array in which case, the passed in arrayref will be shuffled in place && the return value need not be reassigned.
SortCards(@cards)
Sorts the passed in @cards array. SortCards() returns a sorted copy of the @cards array.
SortCards() can also take an arrayref parameter instead of an explicit @cards array in which case, the passed in arrayref will be sorted in place && the return value need not be reassigned.
ShortHand(@hand)
Returns a scalar string containing the abbreviated Poker description of @hand (eg. 'AKQJTs' eq 'Royal Flush', 'QQ993' eq 'Two Pair', etc.).
ShortHand() calls SortCards() on it's parameter before doing to abbreviation to make sure that the return value is consistent.
SlowScoreHand(@hand)
Returns an integer score (where lower is better) for the passed in Poker @hand. This means 0 (zero) is returned for a Royal Flush && the worst possible score is 7461 awarded to 7, 5, 4, 3, 2 unsuited.
If you want higher scores to mean higher hands, just subtract the return value from 7461.
All suits are considered to have equal value in this scoring function. It should be easy to use ScoreHand() as a first pass where ties can be resolved by another suit-comparison function if you want such behavior.
HandScore($scor)
This function is the opposite of ScoreHand(). It takes an integer score paramter && returns the corresponding ShortHand string.
HandScore() uses a fully enumerated table to just index the associated ShortHand so it should be quite fast. The table was generated using SlowScoreHand().
ScoreHand(@hand)
This is a new version of SlowScoreHand() which does the opposite of HandScore() by indexing a ShortHand() key string into a hash of corresponding score values. This faster version should be used for any normal hand scoring needs. If you still want to use the slower version, you can call the UseSlow() function to make ScoreHand() actually call SlowScoreHand() instead of just indexing the answer score in a hash.
UseSlow([$new_slow_flag])
UseSlow() is a function provided in case you'd prefer to actually employ the SlowScoreHand() function whenever you call ScoreHand().
UseSlow() takes an optional $new_slow_flag value. If you don't provide $new_slow_flag, UseSlow() will toggle the slow state.
UseSlow() always returns the current state of whether SlowScoreHand() is being used whenever ScoreHand() is called.
BestHoldEmIndices(@hole, @board)
BestHoldEmIndices() takes 5, 6, or 7 cards && returns an array of the indices of the 5 cards (hand) which yield the best score.
BestHoldEmHand(@best, @hole, @board)
BestHoldEmHand() takes the return value of BestHoldEmIndices() as the first parameter (which is an array of the best indices) && then the same other parameters (@hole && @board) to give you a copy of just the best cards. The return value of this function can be passed to ScoreHand() to get the score of the best hand in HoldEm.
BestHoldEmHand() can optionally take just the @hole && @board like BestHoldEmIndices() && it will automagically call BestHoldEmIndices() first to obtain @best. It will then return copies of those indexed cards from the @hole && @board.
WHY?
Games::Poker::* wouldn't compile correctly for me so I thought it shouldn't take too long to write my own. =) It was a fun problem... much trickier than I first imagined but I think I have solved the problem elegantly once && for all.
NOTES
Suits are: s,h,d,c (Spade,Heart,Diamond,Club) like bridge (alphabetical). Although they are sorted && appear in this order, suits are ignored for scoring by default (but can be optionally reordered && scored later)
B64 notes: Cards map perfectly into A..Z,a..z so += 10 for only letter rep
B64 Cards: 0.As 4.Ks 8.Qs C.Js G.Ts K.9s O.8s S.7s W.6s a.5s e.4s i.3s m.2s
1.Ah 5.Kh 9.Qh D.Jh H.Th L.9h P.8h T.7h X.6h b.5h f.4h j.3h n.2h
2.Ad 6.Kd A.Qd E.Jd I.Td M.9d Q.8d U.7d Y.6d c.5d g.4d k.3d o.2d
3.Ac 7.Kc B.Qc F.Jc J.Tc N.9c R.8c V.7c Z.6c d.5c h.4c l.3c p.2c
Values: 0 1 2 3 4 5 6 7 8 9 A B C
B64 Cards: 0.As 1.Ah 2.Ad 3.Ac Values: 0
4.Ks 5.Kh 6.Kd 7.Kc 1
8.Qs 9.Qh A.Qd B.Qc 2
C.Js D.Jh E.Jd F.Jc 3
G.Ts H.Th I.Td J.Tc 4
K.9s L.9h M.9d N.9c 5
O.8s P.8h Q.8d R.8c 6
S.7s T.7h U.7d V.7c 7
W.6s X.6h Y.6d Z.6c 8
a.5s b.5h c.5d d.5c 9
e.4s f.4h g.4d h.4c A
i.3s j.3h k.3d l.3c B
m.2s n.2h o.2d p.2c C
q.Jok0 r.Jok1 -1Error checking is minimal.
I hope you find Games::Cards::Poker useful. Please feel free to e-mail me any suggestions or coding tips or notes of appreciation ("app-ree-see-ay-shun"). Thank you. TTFN.
CHANGES
Revision history for Perl extension Games::Cards::Poker:
- - 1.0.44KFNKP Tue Apr 20 15:23:20:25 2004
-
* wrote UseSlow() so that benchmrk.pl would still work without Best() && in case anyone would rather have ScoreHand() call SlowScoreHand() every time instead.
* since my old Best() was actually slower than BestHoldEmIndices() =O I removed Best().
* since old Scor() was so much faster than old ScoreHand(), I renamed them to ScoreHand() && SlowScoreHand() respectively since computational version is unnecessary now.
* wrote benchmrk.pl to test BestHoldEmIndices() + ScoreHand() against Best() + Scor(). Best()+Scor() only took 60% as long to run.
* added SortCards() call on ShortHand() param just in case
- - 1.0.44ILBKV Sun Apr 18 21:11:20:31 2004
-
* wrote Scor() with gen'd enumerated hash of ShortHand => Score
* wrote HandScore() to just lookup index of a ShortHand from a score
* squashed 4 scoring bugs in one pair section
* used Algorithm::ChooseSubsets for new BestHoldEmIndices (on Jan's recommendation)
* renamed enumerated BestHoldEmIndices() as Best()
* gave ScoreHand() optional arrayref param like others
* gave ScoreHand() optional ShortHand() string param
* updated 2do && tidied up documentation a bit
- - 1.0.44H2DUS Sat Apr 17 02:13:30:28 2004
-
* added BestHoldEmIndices() && BestHoldEmHand() for Tim && Jan
* commented unnecessary Games::Cards inheritance since I haven't written any compatability / object interface yet
- - 1.0.44F2Q8F Thu Apr 15 02:26:08:15 2004
-
* original version
INSTALL
Please run:
`perl -MCPAN -e "install Games::Cards::Poker"`or uncompress the package and run the standard:
`perl Makefile.PL; make; make test; make install`LICENSE
Most source code should be Free! Code I have lawful authority over is and shall be! Copyright: (c) 2004, Pip Stuart. All rights reserved. Copyleft : I license this software under the GNU General Public License (version 2). Please consult the Free Software Foundation (http://www.fsf.org) for important information about your freedom.
AUTHOR
Pip Stuart <Pip@CPAN.Org>