blob

Blobs are binary large objects — containers of bits (not bytes). They're used for encoding data, messages, images, network payloads, and more.

States

A blob exists in one of two states:

• antestone (mutable) — write operations allowed
• stone (immutable) — read operations allowed

var blob = use('blob')

var b = blob.make()       // antestone
blob.write_bit(b, 1)
blob.write_fit(b, 42, 8)
stone(b)                  // now stone, readable

Creation

blob.make()

Create an empty blob.

var b = blob.make()

blob.make(capacity)

Create with initial capacity (bits).

var b = blob.make(1024)  // 1024 bits capacity

blob.make(length, logical)

Create filled with zeros or ones.

blob.make(64, false)  // 64 zero bits
blob.make(64, true)   // 64 one bits

blob.make(blob, from, to)

Copy a range from another blob.

var slice = blob.make(original, 0, 32)  // first 32 bits

Writing (antestone only)

blob.write_bit(b, logical)

Append a single bit.

blob.write_bit(b, true)   // append 1
blob.write_bit(b, false)  // append 0

blob.write_fit(b, value, length)

Append a fixed-width integer.

blob.write_fit(b, 255, 8)   // 8-bit value
blob.write_fit(b, 1000, 16) // 16-bit value

blob.write_blob(b, other)

Append another blob's contents.

blob.write_blob(b, other_blob)

blob.write_dec64(b, number)

Append a 64-bit DEC64 number.

blob.write_dec64(b, 3.14159)

blob.write_text(b, text)

Append text (kim-encoded length + characters).

blob.write_text(b, "hello")

blob.write_pad(b, block_size)

Pad to block boundary (1 bit + zeros).

blob.write_pad(b, 8)  // pad to byte boundary

Reading (stone only)

blob.read_logical(b, from)

Read a single bit.

var bit = blob.read_logical(b, 0)  // first bit

blob.read_fit(b, from, length)

Read a fixed-width integer.

var value = blob.read_fit(b, 0, 8)  // read 8 bits from position 0

blob.read_blob(b, from, to)

Extract a range as new blob.

var slice = blob.read_blob(b, 8, 24)  // bits 8-23

blob.read_dec64(b, from)

Read a 64-bit DEC64 number.

var num = blob.read_dec64(b, 0)

blob.read_text(b, from)

Read kim-encoded text.

var str = blob.read_text(b, 0)

blob.pad?(b, from, block_size)

Check if padding is valid.

if (blob["pad?"](b, pos, 8)) {
  // valid byte-aligned padding
}

Length

length(b)  // returns bit count

Example

var blob = use('blob')

// Encode a simple message
var msg = blob.make()
blob.write_fit(msg, 1, 8)        // message type
blob.write_fit(msg, 42, 32)      // payload
blob.write_text(msg, "hello")    // text data
stone(msg)

// Decode
var type = blob.read_fit(msg, 0, 8)
var payload = blob.read_fit(msg, 8, 32)
var txt = blob.read_text(msg, 40)