Debian Codegraph @

html/holding.html

raw
1 <head>
2 <!-- $Id: holding.html 313 2009-06-11 05:44:13Z thomasoa $ -->
3 <title>Holding Procedures</title>
4
5 </head>
6 <body bgcolor="#DDEEFF">
7 <h1>Holding Procedures in Deal 3.1 and iDeal</h1>
8
9 <h2>Introduction</h2>
10 One of the main new bridge evaluation features in Deal 3.1 and iDeal
11 is the ability to define fast procedures for evaluating a single holding.
12 <p>
13 In Deal 2.0, we were able to define
14 <a href="advanced.html#vector">Vector functions,</a> which assigned
15 integer values to each card. This covered a lot of standard evaluation
16 techniques, but not the more complicated forms. Evaluators like
17 "quick tricks" and "losers," while still computed suit by suit and totaled,
18 cannot be defined by assigning values to cards alone.
19 <p>
20 The solution is to allow the creation of general procedures for evaluating
21 a holding, while still taking advantage of fast lookup tables. Thus,
22 the introduction of the <em>holdingProc</em> command.
23
24 <h2>The <code>holdingProc</code> Command</h2>
25
26 holdingProc looks like a normal Tcl definition of a procedure. For example,
27 we might write:
28 <blockquote>
29 <pre>
30 holdingProc HCP {A K Q J} {
31 expr {$A*4+$K*3+$Q*2+$J}
32 }
33 </pre>
34 </blockquote>
35 to define a function called <code>HCP</code>. This function behaves exactly
36 the same as the builtin <code>hcp</code> routine - the user can ask for
37 the total points in a hand or for a specific suit in the hand:
38 <blockquote>
39 <pre>
40 set n [HCP north]
41 set hs [HCP north spades]
42 </pre>
43 </blockquote>
44 When evaluated, the parameter A is set to one if the holding has the ace,
45 and zero otherwise.
46 <p>
47 That's a simple example, but let's say we want to do some smart reevaluation.
48 For example, we might want to add a point for each card in a suit beyond
49 the fourth. We also might want to evaluate a stiff king as two points, rather
50 than three, a stiff queen as zero, and a doubleton queen as one.
51 <p>
52 We can do this by adding a "length" parameter to the parameters list:
53 <blockquote>
54 <pre>
55 holdingProc SmartHCP {A K Q J length} {
56
57 if {$length>=4} {
58 # Normal evaluation, +1 for each card longer than the fourth
59 return [expr {$A*4+$K*3+$Q*2+$J+($len-4)}]
60 }
61
62 if {$length==3} {
63 # Normal evaluation for 3-card suits
64 return [expr {$A*4+$K*3+$Q*2+$J}]
65 }
66
67 if {$length==2} {
68 # Jacks in doubletons are worth zero, queens one
69 return [expr {$A*4+$K*3+$Q}]
70 }
71
72 if {$length==1} {
73 # Queens and jacks in singletons are worth zero, kings two
74 return [expr {$A*4+$K*2}]
75 }
76
77 return 0
78 }
79 </pre>
80 </blockquote>
81
82 Even though this code is slow, it is only evaluated at most 160 times, after
83 which values are reused, yielding remarkably fast evaluations. One deal,
84 you might get a holding of <code>KQ75</code> which this routine evaluates
85 as if it were evaluating <code>KQxx</code>. The next hand, it sees the
86 holding <code>KQ82</code> and, seeing this also as <code>KQxx</code>, remembers
87 the previous value.
88 <h3>Types of Holding Procedures</h3>
89
90 By default, the holding procedure assumes that the values returned are integers,
91 so that when it tries to add up the values of all four suits, it applies
92 an integer sum.
93 <p>
94 If you want the return value interpreted as a double, you can specify it
95 in the declaration. For example, we can define a quick tricks procedure:
96 <blockquote>
97 <pre>
98 holdingProc -double QuickTricks {A K Q J T length} {
99 if {$A&&$K} { return 2 }
100 if {$A} { return 1 }
101 if {$K && ($Q || ($J && $T))} {
102 return 1
103 }
104 if {$K && $length>1} {
105 return 0.5
106 }
107 return 0
108 }
109 </pre>
110 </blockquote>
111 <p>
112 You can define the type to be any of the following:
113 <dl>
114 <dt><code>-integer</code>
115 <dd>The default, adds integer values when evaluated across multiple suits.
116 <dt><code>-double</code>
117 <dd>Adds resulting values as doubles when evaluated across multiple suits.
118 <dt><code>-boolean</code>
119 <dd>When evaluated on a hand, lists the suits, by name, which evaluate as true.
120 For example, if you defined 'biddableSuit' it would return the list
121 "<code>spades hearts</code>" for the hand <code>KT954 AJ32 94 92</code>.
122 <dt><code>-string</code>
123 <dd>Returns a list of values when evaluated on multiple suits.
124 </dl>
125 <h3>Arguments Allowed</h3>
126 The arguments are interpreted based on the first character of their name,
127 or, in the case of spots, via the idiom 'x<num>.' For example, we could
128 have defined SmartHCP as:
129 <blockquote>
130 <pre>
131 holdingProc SmartHCP {ace King QuizShow j len} {
132 ...
133 }
134 </pre>
135 </blockquote>
136 They can occur in any order.
137 <p>
138 For spot cards, you can use arguments named "x2", "x3", "x4", .., and "x9."
139 The ten can be passed as "x10" or "T."
140 <p>
141 One last possible parameter is anything beginning with an "s" or "S", which means
142 that the holding is passed as a string. This is useful when you already have
143 a hash table somewhere for stored data. For example, the 'ddeval' code which
144 comes with <em>iDeal</em> and Deal 3.1 uses a table of raw data created in
145 advance.
146 <hr>
147 <table><tr><td><a href="http://bridge.thomasoandrews.com/" class="image">
148 <img style="border:0;width:40px;height:56px" alt="Silhouette" src="graphics/StampSm.gif"></a><td>
149 Thomas Andrews
150 (<a href="mailto:deal&#64;thomasoandrews.com">deal&#64;thomasoandrews.com</a>)
151 Copyright 1996-2010. Deal is covered by the
152 <a href="http://www.gnu.org/copyleft/gpl.html">GNU General Public License.</a>
153 <p>
154 <a href="graphics/falling.jpg"><em>Plane Dealing</em></a> graphic
155 above created using
156 <a href="http://www.povray.org/">POV-Ray.</a>
157 </tr></table>
158 </div>