7A14 rpbridge.net Main


Binary File Formats


 by Richard Pavlicek

Working with huge amounts of bridge data is impractical in a text format, so I have designed various binary file formats to fit my needs. Some of these are documented here, so that others might adopt the methods or derive helpful ideas in designing their own formats.

ZBSZDSZBHZBDZDDZDRZRS

All my 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.

As apparent in the above listing, my binary formats begin with the letter Z. The format becomes the file extension, so it is easy to recognize as a binary file. For example, my latest simulation had the filename 8Z28, so its 100,000 deals and results are stored as 8z28.zrs. (Case is insignificant in a Windows environment but not for Unix and others. For uniformity I use lowercase throughout.)

7A14 rpbridge.net MainTop Binary File Formats

ZBS Format

ZBS (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 3 bits per card (39 total) 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 (digits 0-4). The rightmost digit shows which hand (1=W 2=N 3=E 4=S) holds the ace, or 0 if unused. The next digit locates the king, etc., thru the leftmost digit to locate the two.

Conveniently, 513 = 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 deal.

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, simply divide successively by five; the first remainder locates the ace; the next locates the king, etc.

ZBS 4 bytes per record
BitmapValueCoding
0Flag1 = next record same deal; 0 = end
1-31LocatorBase-5 digit code: 23456789TJQKA

If 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 but spades is assumed.

A null record (all cards unused and “end of deal”) would have no purpose to be included, so this fact can be used to terminate a list of records, thus allowing end detection.

7A14 rpbridge.net MainTop Binary File Formats

ZDS Format

ZDS (binary suit + data) is an expansion of ZBS, adding 2 extra bytes for data storage. I used this for my lead-analysis projects, where West is the opening leader with 2-5 cards in the suit. Data showed the number of tricks East-West win according to which card West leads. Since West could have up to five cards, I needed five results, so each is stored as a triad (3 bits) to fit into 2 bytes.

ZDS 6 bytes per record
BitmapValueCoding
0Flag1 = next record same deal; 0 = end
1-31LocatorBase-5 digit code: 23456789TJQKA
32-34Highest1-7 = tricks won minus 1; 0 = unused
35-372nd best1-7 = tricks won minus 1; 0 = unused
38-403rd best1-7 = tricks won minus 1; 0 = unused
41-434th best1-7 = tricks won minus 1; 0 = unused
44-465th best1-7 = tricks won minus 1; 0 = unused
47Unused0

If 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 but spades is assumed.

As with ZBS format, a record starting with 4 null bytes would have no purpose to be included and can be used to terminate a list of records, thus allowing end detection.

7A14 rpbridge.net MainTop Binary File Formats

ZBH Format

ZBH (binary hand + data) is a method of storing a single hand, and three nibbles of data. I used this for my opening-bid analyses and a few other projects. Each suit is coded by 13 bits, with a 1 bit meaning the card is held.

ZBH 8 bytes per record
BitmapValueCoding
0-12ClubsBit code: AKQJT98765432
13-25DiamondsBit code: AKQJT98765432
26-38HeartsBit code: AKQJT98765432
39-51SpadesBit code: AKQJT98765432
52-55Result 10-13 (15 = unknown)
56-59Result 20-13 (15 = unknown)
60-63Result 30-13 (15 = unknown)

Since a valid record could start with 4 null bytes (e.g., S A-K-Q-J-9-8-7 H 8-7-6-5-4-3 C -- D --) at least 5 null bytes are required to terminate a list of records and allow end detection.

7A14 rpbridge.net MainTop Binary File Formats

ZBD Format

ZBD (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.*

ZBD 13 bytes per record
BitmapValueCoding
0-1C A0 = West; 1 = North; 2 = East; 3 = South
2-3D A0 = West; 1 = North; 2 = East; 3 = South
4-5H A0 = West; 1 = North; 2 = East; 3 = South
6-7S A0 = West; 1 = North; 2 = East; 3 = South
8-95…Likewise for K Q J T 9 8 7 6 5 4 3
96-97C 20 = West; 1 = North; 2 = East; 3 = South
98-99D 20 = West; 1 = North; 2 = East; 3 = South
100-101H 20 = West; 1 = North; 2 = East; 3 = South
102-103S 20 = West; 1 = North; 2 = East; 3 = South

*In theory only 12 bytes (96 bits) per deal are required using my algorithm for Mapping Bridge Deals,
but this requires significant overhead to code and decode — not worth the effort to save 1 byte.

A record starting with 4 null bytes is impossible (it would mean the first 16 cards go to West) so this can be used to terminate any list of records, thus allowing end detection.

Note: ZBD replaces my obsolete ZBR format, which coded cards in suit order: S A S K S Q S J … C 5 C 4 C 3 C 2. Suit order was awkward to code and decode with suit boundaries mid-byte. The new way (ZBD) is much easier with one byte for each rank.

7A14 rpbridge.net MainTop Binary File Formats

ZDD Format

ZDD is a simple, compact way to store double-dummy results. I designed this for my database of 10,485,760 random solved deals, which took almost two years for my old computer to complete (this was 20 years ago). Each record is 20 nibbles (4-bit values) to show the tricks won by each hand in each strain.

ZDD 10 bytes per record
BitmapValueCoding
0-3NT by West0-13 (15 = unknown)
4-7NT by North0-13 (15 = unknown)
8-11NT by East0-13 (15 = unknown)
12-15NT by South0-13 (15 = unknown)
16-79Likewise in order for S H D C

A record starting with 4 null bytes 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.

7A14 rpbridge.net MainTop Binary File Formats

ZDR Format

ZDR combines ZBD (binary deal) and ZDD (20 double-dummy results) into a single record. The first 13 bytes (ZBD) define the deal, and the last 10 bytes (ZDD) contain the results. I use this as the final storage of all solved deals, thus keeping each deal together with its results.

ZDR 23 bytes per record
BitmapValueCoding
0-1C A0 = West; 1 = North; 2 = East; 3 = South
2-3D A0 = West; 1 = North; 2 = East; 3 = South
4-5H A0 = West; 1 = North; 2 = East; 3 = South
6-7S A0 = West; 1 = North; 2 = East; 3 = South
8-95…Likewise for K Q J T 9 8 7 6 5 4 3
96-97C 20 = West; 1 = North; 2 = East; 3 = South
98-99D 20 = West; 1 = North; 2 = East; 3 = South
100-101H 20 = West; 1 = North; 2 = East; 3 = South
102-103S 20 = West; 1 = North; 2 = East; 3 = South
104-107NT by West0-13 (15 = unknown)
108-111NT by North0-13 (15 = unknown)
112-115NT by East0-13 (15 = unknown)
116-119NT by South0-13 (15 = unknown)
120-183…Likewise in order for S H D C

As with ZBD format, a record starting with 4 null bytes is impossible (the first 16 cards cannot go to West) so this can be used to terminate any list of records, thus allowing end detection.

7A14 rpbridge.net MainTop Binary File Formats

ZRS Format

ZRS combines ZBD (binary deal) with six double-dummy results. I use this for simulations, because no more than six results are ever needed, and the record size (16 bytes) is ideal for computer processing.

ZRS 16 bytes per record
BitmapValueCoding
0-1C A0 = West; 1 = North; 2 = East; 3 = South
2-3D A0 = West; 1 = North; 2 = East; 3 = South
4-5H A0 = West; 1 = North; 2 = East; 3 = South
6-7S A0 = West; 1 = North; 2 = East; 3 = South
8-95…Likewise for K Q J T 9 8 7 6 5 4 3
96-97C 20 = West; 1 = North; 2 = East; 3 = South
98-99D 20 = West; 1 = North; 2 = East; 3 = South
100-101H 20 = West; 1 = North; 2 = East; 3 = South
102-103S 20 = West; 1 = North; 2 = East; 3 = South
104-107Result 10-13 (15 = unused)
108-111Result 20-13 (15 = unused)
112-115Result 30-13 (15 = unused)
116-119Result 40-13 (15 = unused)
120-123Result 50-13 (15 = unused)
124-127Result 60-13 (15 = unused)

As with ZBD format, a record starting with 4 null bytes is impossible (the first 16 cards cannot go to West) so this can be used to terminate any list of records, thus allowing end detection.

7A14 rpbridge.net MainTop Binary File Formats

© 2026 Richard Pavlicek