The `blob`

module acts on blobs.

use blob

A blob is a binary large object, a linear container of bits. Blobs can be used to encode sounds, images, public keys, network address, and encrypted payloads.

Blobs are created with bob.make. Bits are appended to a blob with the blob.write_ functions. Information can be retrieved from a blob with the blob.read_ functions. Blogs produce true with the blob? and data? intrinsic functions. The length intrinsic function determines the number of bits in a bob.

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.

The `make`

function makes mutable blobs.

Make a new empty blob.

Make a new empty blob with an initial capacity in bits.

Make a new blob of a given `length` whose content is random.
The `random` parameter is a random generator function that returns fit numbers, like `@.random_fit()`

.

Make a copy of all or part of a blob. The default of `from` is `0`

. The default of `to` is the `length(`

`blob`).

The `write`

functions append bits to the end of a blob. The `blob` must be mutable. If the `blob` is stone, then a disrupt occurs.

Append a bit to the end of the `blob`. The `logical` value can be `true`

, `false`

, `1`

, or `0`

.
Any other value will disrupt.

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

Append a 64 bit DEC64 encoded number to a stone `blob`.

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

Append a `fit` number or a single character as a kim value.

Append a `1`

bit to the `blob` followed by enough `0`

bits to round up the `blob`'s length to a multiple of the `block_size`.

Append a text. This will be encoded as a kim encoded length followed by a sequence of kim encoded UTF-32 characters.

The read functions retrieve bits from an immutable stone blob. The `from` argument specifies the bit location at which to read. The beginning of the blob is at `0`

.

Make a copy of all or part of a blob. The default of `from` is `0`

. The default of `to` is the `length(`

`blob`).

Retrieve a 64 bit DEC64 encoded number from a stone `blob`.

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

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

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 text from a stone `blob`.

Return `true`

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

and `from` is less than or equal to the `block_size`, and if the bit at `from` is `1`

, and that any remaining bits are `0`

. See `write_pad`

.

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 |

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.

The `kim_length`

function gives the length in bits of the kim encoding of a `value`. If the value is a fit number, it gives a result as shown in the table. 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`

.