The `bits`

module acts on blobs.

use bits

from | thru | length | |
---|---|---|---|

bytes | bits | ||

-36028797018963968 | 10 | 80 | |

-562949953421312 | -36028797018963967 | 9 | 72 |

-4398046511104 | -562949953421311 | 8 | 64 |

-34359738368 | -4398046511103 | 7 | 56 |

-268435456 | -34359738367 | 6 | 48 |

-2097152 | -268435455 | 5 | 40 |

-16384 | -2097151 | 4 | 32 |

-128 | -16383 | 3 | 24 |

-1 | -127 | 2 | 16 |

0 | 127 | 1 | 8 |

128 | 16383 | 2 | 16 |

16384 | 2097151 | 3 | 24 |

2097152 | 268435455 | 4 | 32 |

268435456 | 34359738367 | 5 | 40 |

34359738368 | 4398046511103 | 6 | 48 |

4398046511104 | 562949953421311 | 7 | 56 |

562949953421312 | 36028797018963967 | 8 | 64 |

A blob can be in one of two states, either *antestone* or *stone*. In the mutable antestone state, the `write`

functions may be used to append bits to the blob. In the immutable stone state, bits can be harvested from the blob. Bits can be written to blobs as fixed size bit fields, that is a sequence of bits with a specified length, or as a Kim.

Kim is an encoding of fit numbers. Kim is a very simple encoding that delivers 7 bits per byte. The bottom 7 bits of each byte contain data, which can be accumulated to produce fit numbers. The top bit of each byte is `1`

if the byte is not the last and least byte of a number. The top bit of each byte is `0`

if the byte is the last byte of a number. The last byte contains the 7 least significant bits. A first byte of `0x80`

indicates negation.

Retrieve a bit from the `blob`. If `blob` is not a stone blob, or if `from` is out of range, it returns `null`

.

Retrieve a Kim encoded fit number from a stone `blob`.

Retrieve a fit number from a bit field from a stone `blob`.

Return `true`

if the stone `blob's` length is a multiple of the `block_size`, and if the difference between `length`

and `from` is less than or equal to the `block_size`, and if the bit at `from` is one, and that any remaining bits are zero.

Retrieve a Kim encoded text from a stone `blob`.

The `write`

functions append bits to the end of an antestone blob.

Append `second_blob` to the end of `first_blob`.

Append a bit to the end of the `blob`.

Append a `fit` number as a kim value.

Append a bit field to the `blob`. If `fit` requires more bits than allowed by `length`, it fails.

Append a text.

Append a `1`

bit to the antestone `blob` followed by enough zero bits to round up the `blob`'s `length`

to a multiple of the `block_size`.

The `kim`

function gives the length in bits of the Kim encoding of a fit number `value`. If `value` is a logical, it gives `1`

. If value is a text, it gives the length in bits of the Kim encoding of a `text`, giving the sum of the kim encodings of the length and each character. Otherwise, it gives `null`

.