initial commits

master
Charles Iliya Krempeaux 2021-11-07 21:04:43 -08:00
parent 1dff92d981
commit b42905d454
1 changed files with 185 additions and 0 deletions

185
README.md
View File

@ -18,3 +18,188 @@ Here is an example of using `package iid`:
```go
var id iid.IID = iid.Generate()
```
## Representation
Internally, the IID is compactly stored in an `uint64`. The anatomy of this is as follows:
```
unix timestamp (39-bits)
▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼
0b0000000001100001100001110110100111011001110000111111000101100100
▲ ▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲
always zero (1-bit) chaos (20-bits)
```
The `iid.IID.UnixTime()` method will give you that 39-bit _unix timestamp_.
And the `iid.IID.Chaos()` method will give you that 24-bit _chaos_.
(The _chaos_ is just a randomness that helps make these IIDs unique, when multiple IIDs are being produced simultaneously.)
## Temporal Ordering of Representation
On thing to note that is, because this puts the _unix timestamp_ at the most-significant-bits, that the numerical-ordering of this `uint64` will almost always be the same as temporal-ordering.
This was done intentionally.
## Serialization
This is serialized using what this package calls **xim** notation.
An example of **xim** notation looks like this:
```
xi-556PVvNyq3m
```
The anatomy of the **xim** string is as follows:
```
a special base64 encoding
▼▼▼▼▼▼▼▼▼▼▼
xi-556PVvNyq3m
▲▲ ▲
prefix suffix
```
So every **xim** string starts with the characters `xi`, and ends with the character `m`.
And then what is in the middle of those is a special base64 encoding of the `uint64` mentioned before.
What is special about the base64 encoding is that it doesn't use the usual ordering of the symbols.
This special base64 encoding uses:
```
┌───────┬────────┬──────┐
│ Index │ Binary │ Char │
├───────┼────────┼──────┤
│ 0 │ 000000 │ - │
├───────┼────────┼──────┤
│ 1 │ 000001 │ 0 │
├───────┼────────┼──────┤
│ 2 │ 000010 │ 1 │
├───────┼────────┼──────┤
│ 3 │ 000011 │ 2 │
├───────┼────────┼──────┤
│ 4 │ 000100 │ 3 │
├───────┼────────┼──────┤
│ 5 │ 000101 │ 4 │
├───────┼────────┼──────┤
│ 6 │ 000110 │ 5 │
├───────┼────────┼──────┤
│ 7 │ 000111 │ 6 │
├───────┼────────┼──────┤
│ 8 │ 001000 │ 7 │
├───────┼────────┼──────┤
│ 9 │ 001001 │ 8 │
├───────┼────────┼──────┤
│ 10 │ 001010 │ 9 │
├───────┼────────┼──────┤
│ 11 │ 001011 │ A │
├───────┼────────┼──────┤
│ 12 │ 001100 │ B │
├───────┼────────┼──────┤
│ 13 │ 001101 │ C │
├───────┼────────┼──────┤
│ 14 │ 001110 │ D │
├───────┼────────┼──────┤
│ 15 │ 001111 │ E │
├───────┼────────┼──────┤
│ 16 │ 010000 │ F │
├───────┼────────┼──────┤
│ 17 │ 010001 │ G │
├───────┼────────┼──────┤
│ 18 │ 010010 │ H │
├───────┼────────┼──────┤
│ 19 │ 010011 │ I │
├───────┼────────┼──────┤
│ 20 │ 010100 │ J │
├───────┼────────┼──────┤
│ 21 │ 010101 │ K │
├───────┼────────┼──────┤
│ 22 │ 010110 │ L │
├───────┼────────┼──────┤
│ 23 │ 010111 │ M │
├───────┼────────┼──────┤
│ 24 │ 011000 │ N │
├───────┼────────┼──────┤
│ 25 │ 011001 │ O │
├───────┼────────┼──────┤
│ 26 │ 011010 │ P │
├───────┼────────┼──────┤
│ 27 │ 011011 │ Q │
├───────┼────────┼──────┤
│ 28 │ 011100 │ R │
├───────┼────────┼──────┤
│ 29 │ 011101 │ S │
├───────┼────────┼──────┤
│ 30 │ 011110 │ T │
├───────┼────────┼──────┤
│ 31 │ 011111 │ U │
├───────┼────────┼──────┤
│ 32 │ 100000 │ V │
├───────┼────────┼──────┤
│ 33 │ 100001 │ W │
├───────┼────────┼──────┤
│ 34 │ 100010 │ X │
├───────┼────────┼──────┤
│ 35 │ 100011 │ Y │
├───────┼────────┼──────┤
│ 36 │ 100100 │ Z │
├───────┼────────┼──────┤
│ 37 │ 100101 │ _ │
├───────┼────────┼──────┤
│ 38 │ 100110 │ a │
├───────┼────────┼──────┤
│ 39 │ 100111 │ b │
├───────┼────────┼──────┤
│ 40 │ 101000 │ c │
├───────┼────────┼──────┤
│ 41 │ 101001 │ d │
├───────┼────────┼──────┤
│ 42 │ 101010 │ e │
├───────┼────────┼──────┤
│ 43 │ 101011 │ f │
├───────┼────────┼──────┤
│ 44 │ 101100 │ g │
├───────┼────────┼──────┤
│ 45 │ 101101 │ h │
├───────┼────────┼──────┤
│ 46 │ 101110 │ i │
├───────┼────────┼──────┤
│ 47 │ 101111 │ j │
├───────┼────────┼──────┤
│ 48 │ 110000 │ k │
├───────┼────────┼──────┤
│ 49 │ 110001 │ l │
├───────┼────────┼──────┤
│ 50 │ 110010 │ m │
├───────┼────────┼──────┤
│ 51 │ 110011 │ n │
├───────┼────────┼──────┤
│ 52 │ 110100 │ o │
├───────┼────────┼──────┤
│ 53 │ 110101 │ p │
├───────┼────────┼──────┤
│ 54 │ 110110 │ q │
├───────┼────────┼──────┤
│ 55 │ 110111 │ r │
├───────┼────────┼──────┤
│ 56 │ 111000 │ s │
├───────┼────────┼──────┤
│ 57 │ 111001 │ t │
├───────┼────────┼──────┤
│ 58 │ 111010 │ u │
├───────┼────────┼──────┤
│ 59 │ 111011 │ v │
├───────┼────────┼──────┤
│ 60 │ 111100 │ w │
├───────┼────────┼──────┤
│ 61 │ 111101 │ x │
├───────┼────────┼──────┤
│ 62 │ 111110 │ y │
├───────┼────────┼──────┤
│ 63 │ 111111 │ z │
└───────┴────────┴──────┘
```
The advantage of this is that lexical-ordering (in Unicode & ASCII) is also symbol-ordering.
One design goal is that lexical ordering of the **xim** strings is (almost always) also temporal ordering of the **xim** strings.
Another design goal of it is that these **xim** strings should be able to be used as a file-name, or a directory-name.