183 lines
3.0 KiB
Markdown
183 lines
3.0 KiB
Markdown
# 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
|
|
|
|
```javascript
|
|
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.
|
|
|
|
```javascript
|
|
var b = blob.make()
|
|
```
|
|
|
|
### blob.make(capacity)
|
|
|
|
Create with initial capacity (bits).
|
|
|
|
```javascript
|
|
var b = blob.make(1024) // 1024 bits capacity
|
|
```
|
|
|
|
### blob.make(length, logical)
|
|
|
|
Create filled with zeros or ones.
|
|
|
|
```javascript
|
|
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.
|
|
|
|
```javascript
|
|
var slice = blob.make(original, 0, 32) // first 32 bits
|
|
```
|
|
|
|
## Writing (antestone only)
|
|
|
|
### blob.write_bit(b, logical)
|
|
|
|
Append a single bit.
|
|
|
|
```javascript
|
|
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.
|
|
|
|
```javascript
|
|
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.
|
|
|
|
```javascript
|
|
blob.write_blob(b, other_blob)
|
|
```
|
|
|
|
### blob.write_dec64(b, number)
|
|
|
|
Append a 64-bit DEC64 number.
|
|
|
|
```javascript
|
|
blob.write_dec64(b, 3.14159)
|
|
```
|
|
|
|
### blob.write_text(b, text)
|
|
|
|
Append text (kim-encoded length + characters).
|
|
|
|
```javascript
|
|
blob.write_text(b, "hello")
|
|
```
|
|
|
|
### blob.write_pad(b, block_size)
|
|
|
|
Pad to block boundary (1 bit + zeros).
|
|
|
|
```javascript
|
|
blob.write_pad(b, 8) // pad to byte boundary
|
|
```
|
|
|
|
## Reading (stone only)
|
|
|
|
### blob.read_logical(b, from)
|
|
|
|
Read a single bit.
|
|
|
|
```javascript
|
|
var bit = blob.read_logical(b, 0) // first bit
|
|
```
|
|
|
|
### blob.read_fit(b, from, length)
|
|
|
|
Read a fixed-width integer.
|
|
|
|
```javascript
|
|
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.
|
|
|
|
```javascript
|
|
var slice = blob.read_blob(b, 8, 24) // bits 8-23
|
|
```
|
|
|
|
### blob.read_dec64(b, from)
|
|
|
|
Read a 64-bit DEC64 number.
|
|
|
|
```javascript
|
|
var num = blob.read_dec64(b, 0)
|
|
```
|
|
|
|
### blob.read_text(b, from)
|
|
|
|
Read kim-encoded text.
|
|
|
|
```javascript
|
|
var str = blob.read_text(b, 0)
|
|
```
|
|
|
|
### blob.pad?(b, from, block_size)
|
|
|
|
Check if padding is valid.
|
|
|
|
```javascript
|
|
if (blob["pad?"](b, pos, 8)) {
|
|
// valid byte-aligned padding
|
|
}
|
|
```
|
|
|
|
## Length
|
|
|
|
```javascript
|
|
length(b) // returns bit count
|
|
```
|
|
|
|
## Example
|
|
|
|
```javascript
|
|
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)
|
|
```
|