Main
Guide 7A14 by Richard Pavlicek
Working with large amounts of bridge data is impractical in a text format, so I have designed various binary file formats to fit my needs. These are explained here, so that others might benefit from the structures and accumulated data.
| ZBS | ZBD | ZDD | ZRD | ZRJ | BIN |
All binary formats follow the Intel “little endian” architecture, wherein multi-byte values are stored least significant byte first. Bits are numbered from zero (least significant) upward to the end of each record.
Provided in the documentation of each binary file is a checksum, which is simply an addition of all 32-bit words to produce a 64-bit sum (shown in hexadecimal). This can be used to verify the integrity of the file. In the event of a mismatch, the file is corrupt; try downloading again, and if it still doesn’t match, please contact me.
My Bridge File Converter will convert ZBS, ZBD and ZRD files to any other format, provided the output file does not exceed 2 GB and you have enough disk space to store it — or enough trees if the output is to a printer. For practical purposes, however, conversion of large binary files to readable formats should be limited to a small portion at a time.
ZBS FormatZBS (binary suit) is a way to store any suit layout, including unused cards, in the minimal space. I designed this circa 1988 for my now extinct Bridge Tutor program, because it allowed any bridge diagram (full deal, ending, paired hands, card combination, etc.) to be stored efficiently. (In those days of low memory and floppy disks, saving bytes was crucial.)
Each card can be in one of five places: West, North, East, South or unused. In a bit-mapping scheme this would require three bits per card (39 total bits) which is wasteful. Much better is a power-of-five algorithm, where the location of each card is shown by a 13-digit number in base five (each digit 0-4). The rightmost digit shows which hand (1-4) holds the ace, or 0 = unused; the next digit locates the king, etc., thru the leftmost digit to locate the two.* Conveniently, 5 to the 13th power = 1,220,703,125 (48C27395 hexadecimal) which stores in 31 bits, or 4 bytes with 1 bit left over. I use the extra bit as a flag to mean the next record belongs to the same deal, hence 32-bit records can stand alone to define a suit layout, or combine to form a diagram.
*Originally I used the reverse order (ace leftmost, two rightmost) but switched so that decoding extracts cards in ranking order (ace, king, queen) to facilitate and speed up some routines.
Encoding and decoding is straightforward. To encode, start with the two and its location (0-4); multiply by five and add the three location (0-4); multiply by five and add the four location (0-4), etc. To decode, just divide successively by five; the first remainder locates the ace; the next locates the king, etc. The record structure is shown below.
| Bit | Value | Coding |
|---|---|---|
| 0 | Flag | 0 = end of group; 1 = next record same group |
| 1-31 | Locator | 0 to 1220703124 |
When records are combined, suits must be given in ranking order: spades, hearts, diamonds, clubs. For stand-alone records (single-suit layouts) suit identity doesn’t matter (at least for my purposes) but spades is assumed.
A null record (all cards unused and “end of group”) would have no purpose to be included, so this fact can be used to terminate a list records, thus allowing end detection.
ZBD FormatZBD (binary deal) is a simple, compact way to store a complete deal. Each card must be in one of four places (West, North, East or South) so two bits of information are required for each card. Two × 52 = 104 bits, so each deal requires 13 bytes.* The bitmap of each record is shown below.
| Bit | Value | Coding |
|---|---|---|
| 0-1 |  A | 0 = West; 1 = North; 2 = East; 3 = South |
| 2-3 | K | 0 = West; 1 = North; 2 = East; 3 = South |
| 4-103 | Likewise in order for Q-2  A-2  A-2  A-2 | |
*In theory only 12 bytes are required per deal using my algorithm for Mapping Bridge Deals, but this requires significant overhead to code and decode each deal — hardly worth the effort to save a single byte. Simplicity rules.
A record starting with 32 null bits is impossible (it would mean the first 16 cards go to West) so this fact can be used to terminate any list of records, thus allowing end detection.
ZDD FormatZDD is a simple, compact way to store double-dummy results for each hand in each strain. I designed this for my database of 10,485,760 Random Solved Deals, a project that took almost two years of computer time to complete. The random deals themselves are not stored but generated on-the-fly (mother-of-all algorithm). Given a fixed seed, the same sequence of deals is reproduced.
Each record is 10 bytes (80 bits). Each of the 20 results (5 strains × 4 hands) is stored as a nibble, or 4-bit value. The bitmap of each record is shown below.
| Bit | Value | Coding |
|---|---|---|
| 0-3 | NT by West | 0-13 (or 15 = unknown) |
| 4-7 | NT by North | 0-13 (or 15 = unknown) |
| 8-11 | NT by East | 0-13 (or 15 = unknown) |
| 12-15 | NT by South | 0-13 (or 15 = unknown) |
| 16-79 | Likewise in order for | |
A record starting with 32 null bits is impossible (it would mean each hand makes zero tricks in notrump or spades) so this fact can be used to terminate a list of records, thus allowing end detection.
ZRD FormatZRD is a stand-alone version of ZDD, in that each random deal is stored with its double-dummy results. This simplifies the reproduction of each deal at the expense of using 2.3 times the storage space.
Each record is 23 bytes (184 bits). The first 13 bytes (104 bits) follow the ZBD structure, and the last 10 bytes (80 bits) follow the ZDD structure. The bitmap of each record is shown below.
| Bit | Value | Coding |
|---|---|---|
| 0-1 | A | 0 = West; 1 = North; 2 = East; 3 = South |
| 2-3 | K | 0 = West; 1 = North; 2 = East; 3 = South |
| 4-103 | Likewise in order for Q-2 A-2 A-2 A-2
| |
| 104-107 | NT by West | 0-13 (or 15 = unknown) |
| 108-111 | NT by North | 0-13 (or 15 = unknown) |
| 112-115 | NT by East | 0-13 (or 15 = unknown) |
| 116-119 | NT by South | 0-13 (or 15 = unknown) |
| 120-183 | Likewise in order for | |
A record starting with 32 null bits is impossible (it would mean the first 16 cards go to West) so this fact can be used to terminate any list of records, thus allowing end detection.
ZRJ FormatZRJ is a way of storing essential information about a bridge deal — card diagram, board number, dealer, vulnerability, contract, declarer, result, auction and play — in a fixed format. Each record is 80 bytes in the following structure:
| Offset | Value | Coding |
|---|---|---|
| 0 | A A A A | bitmap SSHHDDCC (00=W 01=N 10=E 11=S) |
| 1-12 | ? ? ? ? | likewise for kings thru twos |
| 13 | Board# minus 1 | 0-255 (also determines dealer and vul) |
| 14 | Contract | bitmap RXLLLSSS |
| 15 | Declarer, result | bitmap 00DDRRRR (2 high bits unused) |
| 16 | Calls | bitmap ?!LLLSSS null terminated (PPP assumed) |
| ?? | Plays | bitmap ?!SSRRRR terminated by null or record end |
Calls and plays combined are allowed 64 bytes, including a null byte between, so in rare cases the play string must be truncated. The two high bits of each call or play indicate punctuation (! = good, ? = poor) and both set indicates an alert (*) or special meaning. Of course, no explanations fit in this structure.
A record starting with 4 null bytes (32 bits) is impossible (it would mean the first 16 cards go to West) and can be used to terminate a list of records to allow end detection.
BIN FormatBIN is not a specific format (like ZBS ZBD ZDD ZRD ZRJ) but simply an indication that the file’s contents are binary coded and unreadable. Accompanying each BIN file is a TXT file explaining the contents and structure used. Current BIN files include the following:
| File | Explanation |
|---|---|
| GHP.BIN | Generic hand patterns |
| SHP.BIN | Specific hand patterns |
| GSP.BIN | Generic side patterns |
| SSP.BIN | Specific side patterns |
| GSX.BIN | Generic sideprints |
| SSX.BIN | Specific sideprints |
| GDX.BIN | Generic dealprints |
| ESH.BIN | Every Suit Holding |
| GHC.BIN | Generic high cards |
| SHC.BIN | Specific high cards |
| SCO.BIN | Bridge Result Scores |
© 2016 Richard Pavlicek
