Misty Programming Language:Blob Functions

The blob subprogram acts on blobs.

use blob()

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

Blobs are created with blob.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 blob.

A blob can be in one of two states, either writeable or stone. In the mutable writeable 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.

Make function

The make function makes mutable blobs.

blob.make()

Make a new empty blob.

blob.make(capacity)

Make a new empty blob with an initial capacity in bits. When turned to stone, the excess bits are discarded. If the initial capacity is too small, the write functions will extended it. A good initial guess can improve performance.

blob.make(length value)

Make a new blob containing all zeros (0 or false) or all ones (1 or true). Any other value will halt.

blob.make(length random)

Make a new blob of a given length whose content is random. The random argument is a random generator function that returns ints, like random.random_int().

blob.make(blob from to)

Make a copy of all or part of a blob. The default of from is 0. The default of to is the length(blob).

Write functions

The write functions append bits to the end of a blob. The blob must be mutable. If the blob is stone, then the actor halts.

blob.write_bit(blob logical)

Append a bit to the end of the blob. The logical value can be true, false, 1, or 0. Any other value halts.

blob.write_blob(blob second_blob)

Append second_blob to the end of blob.

blob.write_dec64(blob number)

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

blob.write_int(blob int length)

Append a bit field to the blob. If the int requires more bits than allowed by length, it halts.

blob.write_kim(blob int)

Append an int as a kim value.

blob.write_pad(blob block_size)

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.

blob.write_text(blob text)

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

Read functions

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.

blob.read_blob(blob from to)

Make a copy of all or part of a blob. The default of from is 0. The default of to is the length(blob).

blob.read_dec64(blob from)

Retrieve a 64 bit DEC64 encoded number from a stone blob. If the number is invalid, it returns null.

blob.read_int(blob from length)

Retrieve length bits and return them as an int.

blob.read_kim(blob from)

Retrieve a kim encoded int from a stone blob.

blob.read_logical(blob from)

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

blob.read_text(blob from)

Retrieve a kim encoded text from a stone blob.

blob.pad?(blob from block_size)

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.

Kim

Kim is a variable byte encoding of ints. 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. 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.

Kim encoding of small integers can be space saving.

blob.kim_length(value)

The kim_length function gives the length in bits of the kim encoding of a value. If the value is an int, 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.