Clarify how to represent fractional seconds in UUIDv7

[uuid6]

Clarify how to represent fractional seconds in UUIDv7

[oittaa]

Python code example

# Enough to represent nanoseconds from time.time_ns()
SUBSEC_BITS = 30
SUBSEC_DECIMAL_DIGITS = 9


def subsec_encode(
    value: int,
    subsec_bits: int = SUBSEC_BITS,
    subsec_decimal_digits: int = SUBSEC_DECIMAL_DIGITS,
) -> int:
    return value * 2 ** subsec_bits // 10 ** subsec_decimal_digits


def subsec_decode(
    value: int,
    subsec_bits: int = SUBSEC_BITS,
    subsec_decimal_digits: int = SUBSEC_DECIMAL_DIGITS,
) -> int:
    return -(-value * 10 ** subsec_decimal_digits // 2 ** subsec_bits)


def test_millisecond():
    print("Testing millisecond conversions.")
    for i in range(10 ** 3):
        if i % 10 ** 2 == 0:
            print(f"{i=} ...")
        assert i == subsec_decode(subsec_encode(i, 10, 3), 10, 3)


def test_microsecond():
    print("Testing microsecond conversions.")
    for i in range(10 ** 6):
        if i % 10 ** 5 == 0:
            print(f"{i=} ...")
        assert i == subsec_decode(subsec_encode(i, 20, 6), 20, 6)


def test_nanosecond():
    print("Testing nanosecond conversions.")
    for i in range(10 ** 9):
        if i % 10 ** 6 == 0:
            print(f"{i=} ...")
        assert i == subsec_decode(subsec_encode(i, 30, 9), 30, 9)


def main():
    import time

    timestamp = time.time_ns()
    unixts, ns = divmod(timestamp, 10 ** SUBSEC_DECIMAL_DIGITS)
    subsec = subsec_encode(ns)
    subsec_to_ns = subsec_decode(subsec)
    print(f"{timestamp=}")
    print(f"{unixts=}")
    print(f"{ns=}")
    print(f"{subsec=}")
    print(f"{subsec_to_ns=}")
    test_millisecond()
    test_microsecond()
    test_nanosecond()


if __name__ == "__main__":
    main()

Ouput is something like

timestamp=1641075060289465000
unixts=1641075060
ns=289465000
subsec=310810677
subsec_to_ns=289465000
Testing millisecond conversions.
i=0 ...

Those main() and test_... functions here are to show that it actually works and maybe you would just include subsec_encode() and subsec_decode() in the actual documentation. The encoding and decoding should work correctly even if you change SUBSEC_BITS to something like the above mentioned 12 for a millisecond precision.

[oittaa]

I think it might be a good idea to include code examples, at least in a few of the most common programming languages, how to encode and decode those timestamps. Basically every programming language I know expresses precision timestamps as integers. For example https://docs.python.org/3/library/time.html#time.time_ns

[fabiolimace]

Great code example @oittaa !