# 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)
```