### A Lightweight Library for Efficient Card Representation

The `StandardCard` library provides a programmer-friendly way to represent a standard deck of 52 cards.

It prioritizes both fast access to card information and minimal storage footprint, making it ideal for various game development or card manipulation tasks.

### Card definition

A card is an integer is made up of four bytes. The high-order bytes are used to hold the rank bit pattern, whereas the low-order bytes hold the suit/rank/prime value of the card.

| xxxAKQJT | 98765432 | cdhsrrrr | sspppppp |
| :------: | :------: | :------: | :------: |
| xxxbbbbb | bbbbbbbb | cdhsrrrr | sspppppp |

Where

| Key  | Definition                                                           |
| :--: | -------------------------------------------------------------------- |
|  p   | Prime number of rank                                                 |
|  s   | Suit of card (clubs=00, diamonds=01, hearts=10, spades=11)           |
|  r   | Rank of card                                                         |
| cdhs | bit turned on depending on suit of card (spades=0001,...,clubs=1000) |
|  b   | bit turned on depending on rank of card                              |

As an example, the Five of Hearts (5h) would be represented as

| xxxAKQJT | 98765432 | cdhsrrrr | sspppppp |                       |
| :------: | :------: | :------: | :------: | :-------------------: |
| 00000000 | 00001000 | 00100011 | 01000111 | = 0x00082347 = 533319 |

More information about the card is presented in a table below

|        | 2   | 3   | 4   | 5   | 6   | 7   | 8   | 9   | 10  | J   | Q   | K   | A   |
| ------ | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Ranks  | 0   | 1   | 2   | 3   | 4   | 5   | 6   | 7   | 8   | 9   | 10  | 11  | 12  |
| Primes | 2   | 3   | 5   | 7   | 11  | 13  | 17  | 19  | 23  | 29  | 31  | 37  | 41  |

### The 52-card deck

Building on the previous card definition, let's look at the value table for a standard 52-card deck

|          | 2     | 3      | 4      | 5      | 6       | 7       | 8       | 9       | 10       | J        | Q        | K         | A         |
| -------- | ----- | ------ | ------ | ------ | ------- | ------- | ------- | ------- | -------- | -------- | -------- | --------- | --------- |
| Clubs    | 98306 | 164099 | 295429 | 557831 | 1082379 | 2131213 | 4228625 | 8423187 | 16812055 | 33589533 | 67144223 | 134253349 | 268471337 |
| Diamonds | 81986 | 147779 | 279109 | 541511 | 1066059 | 2114893 | 4212305 | 8406867 | 16795735 | 33573213 | 67127903 | 134237029 | 268455017 |
| Hearts   | 73858 | 139651 | 270981 | 533383 | 1057931 | 2106765 | 4204177 | 8398739 | 16787607 | 33565085 | 67119775 | 134228901 | 268446889 |
| Spades   | 69826 | 135619 | 266949 | 529351 | 1053899 | 2102733 | 4200145 | 8394707 | 16783575 | 33561053 | 67115743 | 134224869 | 268442857 |

### Benefits

- `Minimal Memory Usage`: data structures can represent all card information with a single identifier.

- `Faster Lookups`: Retrieving card information becomes a constant-time operation due to the use of bit-wise operator.