# BitWriter

<a id="bitwriter"></a>

# BitWriter

```cpp
#include <icy/buffer.h>

class BitWriter
```

[Defined in src/base/include/icy/buffer.h:450](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L450)

> **Subclassed by:** [`DynamicBitWriter`](https://auscaster.com/icey/docs/api-reference/icy-DynamicBitWriter.md#dynamicbitwriter)

Class for reading/writing binary streams.

Note that when using the constructor with the Buffer reference as an argument, the writer will dynamically expand the given buffer when writing passed the buffer capacity. All other cases will throw a std::out_of_range error when writing past the buffer capacity.

## Friends

| Name | Description |
|------|-------------|
| [`operator<<`](#operator-6) `inline` |  |

---

<a id="operator-6"></a>

### operator<<

`inline`

```cpp
friend inline std::ostream & operator<<(std::ostream & stream, const BitWriter & wr)
```

[Defined in src/base/include/icy/buffer.h:574](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L574)

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`BitWriter`](#bitwriter-1)  | Constructs a [`BitWriter`](#bitwriter) over a raw byte array with a fixed capacity. |
|  | [`BitWriter`](#bitwriter-2)  | Constructs a [`BitWriter`](#bitwriter) backed by a `Buffer`. Writes are bounded by the buffer's capacity; use [`DynamicBitWriter`](https://auscaster.com/icey/docs/api-reference/icy-DynamicBitWriter.md#dynamicbitwriter) for auto-resize. |
|  | [`BitWriter`](#bitwriter-3)  | Constructs a [`BitWriter`](#bitwriter) over a [`MutableBuffer`](https://auscaster.com/icey/docs/api-reference/icy-MutableBuffer.md#mutablebuffer-6) with a fixed capacity. |
|  | [`~BitWriter`](#bitwriter-4) `virtual` |  |
| `void` | [`put`](#put) `virtual` | Append bytes to the buffer. Throws a `std::out_of_range` exception if reading past the limit. |
| `void` | [`put`](#put-1)  | Appends the contents of a string. Throws `std::out_of_range` if capacity is exceeded. |
| `void` | [`putU8`](#putu8)  | Appends an unsigned 8-bit integer. Throws `std::out_of_range` if capacity is exceeded. |
| `void` | [`putU16`](#putu16)  | Appends an unsigned 16-bit integer with byte-order conversion. Throws `std::out_of_range` if capacity is exceeded. |
| `void` | [`putU24`](#putu24)  | Appends the low 24 bits of a 32-bit integer with byte-order conversion. Throws `std::out_of_range` if capacity is exceeded. |
| `void` | [`putU32`](#putu32)  | Appends an unsigned 32-bit integer with byte-order conversion. Throws `std::out_of_range` if capacity is exceeded. |
| `void` | [`putU64`](#putu64)  | Appends an unsigned 64-bit integer with byte-order conversion. Throws `std::out_of_range` if capacity is exceeded. |
| `bool` | [`update`](#update) `virtual` | Update a byte range. Throws a `std::out_of_range` exception if reading past the limit. |
| `bool` | [`update`](#update-1)  | Overwrites a previously written string at the given absolute position. |
| `bool` | [`updateU8`](#updateu8)  | Overwrites a `uint8_t` at the given absolute position. |
| `bool` | [`updateU16`](#updateu16)  | Overwrites a `uint16_t` at the given absolute position, with byte-order conversion. |
| `bool` | [`updateU24`](#updateu24)  | Overwrites 3 bytes (low 24 bits of `val`) at the given absolute position, with byte-order conversion. |
| `bool` | [`updateU32`](#updateu32)  | Overwrites a `uint32_t` at the given absolute position, with byte-order conversion. |
| `bool` | [`updateU64`](#updateu64)  | Overwrites a `uint64_t` at the given absolute position, with byte-order conversion. |
| `void` | [`seek`](#seek-1)  | Set position pointer to absolute position. Throws a `std::out_of_range` exception if the value exceeds the limit. |
| `void` | [`skip`](#skip-1)  | Set position pointer to relative position. Throws a `std::out_of_range` exception if the value exceeds the limit. |
| `size_t` | [`limit`](#limit-1) `const` | Returns the write limit. |
| `size_t` | [`position`](#position-1) `const` `inline` | Returns the current write position. |
| `size_t` | [`available`](#available-1) `const` | Returns the number of elements between the current write position and the limit. |
| `char *` | [`begin`](#begin-1) `inline` | Returns a pointer to the start of the write buffer. |
| `char *` | [`current`](#current-1) `inline` | Returns a pointer to the current write position. |
| `const char *` | [`begin`](#begin-2) `const` `inline` | Returns a const pointer to the start of the write buffer. |
| `const char *` | [`current`](#current-2) `const` `inline` | Returns a const pointer to the current write position. |
| [`ByteOrder`](https://auscaster.com/icey/docs/api-reference/base.md#byteorder) | [`order`](#order-1) `const` `inline` | Returns the byte order used for multi-byte integer writes. |
| `std::string` | [`toString`](#tostring-1)  | Returns all bytes written so far as a `std::string`. |

---

<a id="bitwriter-1"></a>

### BitWriter

```cpp
BitWriter(char * bytes, size_t size, ByteOrder order = ByteOrder::Network)
```

[Defined in src/base/include/icy/buffer.h:457](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L457)

Constructs a [`BitWriter`](#bitwriter) over a raw byte array with a fixed capacity.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `bytes` | `char *` | Pointer to the writable buffer. Must remain valid for the writer's lifetime. |
| `size` | `size_t` | Capacity of the buffer in bytes. |
| `order` | [`ByteOrder`](https://auscaster.com/icey/docs/api-reference/base.md#byteorder) | Byte order used for multi-byte integer writes. |

---

<a id="bitwriter-2"></a>

### BitWriter

```cpp
BitWriter(Buffer & buf, ByteOrder order = ByteOrder::Network)
```

[Defined in src/base/include/icy/buffer.h:463](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L463)

Constructs a [`BitWriter`](#bitwriter) backed by a `Buffer`. Writes are bounded by the buffer's capacity; use [`DynamicBitWriter`](https://auscaster.com/icey/docs/api-reference/icy-DynamicBitWriter.md#dynamicbitwriter) for auto-resize.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `buf` | [`Buffer`](https://auscaster.com/icey/docs/api-reference/base.md#buffer) & | Source buffer. Must remain valid for the writer's lifetime. |
| `order` | [`ByteOrder`](https://auscaster.com/icey/docs/api-reference/base.md#byteorder) | Byte order used for multi-byte integer writes. |

---

<a id="bitwriter-3"></a>

### BitWriter

```cpp
BitWriter(MutableBuffer & pod, ByteOrder order = ByteOrder::Network)
```

[Defined in src/base/include/icy/buffer.h:468](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L468)

Constructs a [`BitWriter`](#bitwriter) over a [`MutableBuffer`](https://auscaster.com/icey/docs/api-reference/icy-MutableBuffer.md#mutablebuffer-6) with a fixed capacity.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pod` | [`MutableBuffer`](https://auscaster.com/icey/docs/api-reference/icy-MutableBuffer.md#mutablebuffer-6) & | Source mutable buffer. Must remain valid for the writer's lifetime. |
| `order` | [`ByteOrder`](https://auscaster.com/icey/docs/api-reference/base.md#byteorder) | Byte order used for multi-byte integer writes. |

---

<a id="bitwriter-4"></a>

### ~BitWriter

`virtual`

```cpp
virtual ~BitWriter()
```

[Defined in src/base/include/icy/buffer.h:469](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L469)

---

<a id="put"></a>

### put

`virtual`

```cpp
virtual void put(const char * val, size_t len)
```

[Defined in src/base/include/icy/buffer.h:473](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L473)

Append bytes to the buffer. Throws a `std::out_of_range` exception if reading past the limit.

#### Reimplemented by

- [`DynamicBitWriter::put`](https://auscaster.com/icey/docs/api-reference/icy-DynamicBitWriter.md#put-2)

---

<a id="put-1"></a>

### put

```cpp
void put(const std::string & val)
```

[Defined in src/base/include/icy/buffer.h:476](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L476)

Appends the contents of a string. Throws `std::out_of_range` if capacity is exceeded.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `const std::string &` | String whose bytes are appended. |

---

<a id="putu8"></a>

### putU8

```cpp
void putU8(uint8_t val)
```

[Defined in src/base/include/icy/buffer.h:480](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L480)

Appends an unsigned 8-bit integer. Throws `std::out_of_range` if capacity is exceeded.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint8_t` | Value to write. |

---

<a id="putu16"></a>

### putU16

```cpp
void putU16(uint16_t val)
```

[Defined in src/base/include/icy/buffer.h:484](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L484)

Appends an unsigned 16-bit integer with byte-order conversion. Throws `std::out_of_range` if capacity is exceeded.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint16_t` | Value to write. |

---

<a id="putu24"></a>

### putU24

```cpp
void putU24(uint32_t val)
```

[Defined in src/base/include/icy/buffer.h:488](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L488)

Appends the low 24 bits of a 32-bit integer with byte-order conversion. Throws `std::out_of_range` if capacity is exceeded.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint32_t` | Value to write (only the lower 3 bytes are written). |

---

<a id="putu32"></a>

### putU32

```cpp
void putU32(uint32_t val)
```

[Defined in src/base/include/icy/buffer.h:492](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L492)

Appends an unsigned 32-bit integer with byte-order conversion. Throws `std::out_of_range` if capacity is exceeded.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint32_t` | Value to write. |

---

<a id="putu64"></a>

### putU64

```cpp
void putU64(uint64_t val)
```

[Defined in src/base/include/icy/buffer.h:496](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L496)

Appends an unsigned 64-bit integer with byte-order conversion. Throws `std::out_of_range` if capacity is exceeded.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint64_t` | Value to write. |

---

<a id="update"></a>

### update

`virtual`

```cpp
virtual bool update(const char * val, size_t len, size_t pos)
```

[Defined in src/base/include/icy/buffer.h:500](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L500)

Update a byte range. Throws a `std::out_of_range` exception if reading past the limit.

#### Reimplemented by

- [`DynamicBitWriter::update`](https://auscaster.com/icey/docs/api-reference/icy-DynamicBitWriter.md#update-2)

---

<a id="update-1"></a>

### update

```cpp
bool update(const std::string & val, size_t pos)
```

[Defined in src/base/include/icy/buffer.h:505](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L505)

Overwrites a previously written string at the given absolute position. 
#### Returns
True on success, false if the range exceeds available space.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `const std::string &` | String to write. |
| `pos` | `size_t` | Absolute byte offset to overwrite at. |

---

<a id="updateu8"></a>

### updateU8

```cpp
bool updateU8(uint8_t val, size_t pos)
```

[Defined in src/base/include/icy/buffer.h:511](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L511)

Overwrites a `uint8_t` at the given absolute position. 
#### Returns
True on success, false if the range exceeds available space.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint8_t` | Value to write. |
| `pos` | `size_t` | Absolute byte offset to overwrite at. |

---

<a id="updateu16"></a>

### updateU16

```cpp
bool updateU16(uint16_t val, size_t pos)
```

[Defined in src/base/include/icy/buffer.h:517](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L517)

Overwrites a `uint16_t` at the given absolute position, with byte-order conversion. 
#### Returns
True on success, false if the range exceeds available space.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint16_t` | Value to write. |
| `pos` | `size_t` | Absolute byte offset to overwrite at. |

---

<a id="updateu24"></a>

### updateU24

```cpp
bool updateU24(uint32_t val, size_t pos)
```

[Defined in src/base/include/icy/buffer.h:523](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L523)

Overwrites 3 bytes (low 24 bits of `val`) at the given absolute position, with byte-order conversion. 
#### Returns
True on success, false if the range exceeds available space.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint32_t` | Value to write. |
| `pos` | `size_t` | Absolute byte offset to overwrite at. |

---

<a id="updateu32"></a>

### updateU32

```cpp
bool updateU32(uint32_t val, size_t pos)
```

[Defined in src/base/include/icy/buffer.h:529](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L529)

Overwrites a `uint32_t` at the given absolute position, with byte-order conversion. 
#### Returns
True on success, false if the range exceeds available space.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint32_t` | Value to write. |
| `pos` | `size_t` | Absolute byte offset to overwrite at. |

---

<a id="updateu64"></a>

### updateU64

```cpp
bool updateU64(uint64_t val, size_t pos)
```

[Defined in src/base/include/icy/buffer.h:535](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L535)

Overwrites a `uint64_t` at the given absolute position, with byte-order conversion. 
#### Returns
True on success, false if the range exceeds available space.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint64_t` | Value to write. |
| `pos` | `size_t` | Absolute byte offset to overwrite at. |

---

<a id="seek-1"></a>

### seek

```cpp
void seek(size_t val)
```

[Defined in src/base/include/icy/buffer.h:539](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L539)

Set position pointer to absolute position. Throws a `std::out_of_range` exception if the value exceeds the limit.

---

<a id="skip-1"></a>

### skip

```cpp
void skip(size_t size)
```

[Defined in src/base/include/icy/buffer.h:543](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L543)

Set position pointer to relative position. Throws a `std::out_of_range` exception if the value exceeds the limit.

---

<a id="limit-1"></a>

### limit

`const`

```cpp
size_t limit() const
```

[Defined in src/base/include/icy/buffer.h:546](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L546)

Returns the write limit.

---

<a id="position-1"></a>

### position

`const` `inline`

```cpp
inline size_t position() const
```

[Defined in src/base/include/icy/buffer.h:549](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L549)

Returns the current write position.

---

<a id="available-1"></a>

### available

`const`

```cpp
size_t available() const
```

[Defined in src/base/include/icy/buffer.h:553](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L553)

Returns the number of elements between the current write position and the limit.

---

<a id="begin-1"></a>

### begin

`inline`

```cpp
inline char * begin()
```

[Defined in src/base/include/icy/buffer.h:556](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L556)

Returns a pointer to the start of the write buffer.

---

<a id="current-1"></a>

### current

`inline`

```cpp
inline char * current()
```

[Defined in src/base/include/icy/buffer.h:559](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L559)

Returns a pointer to the current write position.

---

<a id="begin-2"></a>

### begin

`const` `inline`

```cpp
inline const char * begin() const
```

[Defined in src/base/include/icy/buffer.h:562](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L562)

Returns a const pointer to the start of the write buffer.

---

<a id="current-2"></a>

### current

`const` `inline`

```cpp
inline const char * current() const
```

[Defined in src/base/include/icy/buffer.h:565](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L565)

Returns a const pointer to the current write position.

---

<a id="order-1"></a>

### order

`const` `inline`

```cpp
inline ByteOrder order() const
```

[Defined in src/base/include/icy/buffer.h:568](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L568)

Returns the byte order used for multi-byte integer writes.

---

<a id="tostring-1"></a>

### toString

```cpp
std::string toString()
```

[Defined in src/base/include/icy/buffer.h:572](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L572)

Returns all bytes written so far as a `std::string`. 
#### Returns
String containing bytes from the start of the buffer up to the current position.

## Protected Attributes

| Return | Name | Description |
|--------|------|-------------|
| `size_t` | [`_position`](#_position-1)  |  |
| `size_t` | [`_limit`](#_limit-1)  |  |
| [`ByteOrder`](https://auscaster.com/icey/docs/api-reference/base.md#byteorder) | [`_order`](#_order-1)  |  |
| `char *` | [`_bytes`](#_bytes-1)  |  |

---

<a id="_position-1"></a>

### _position

```cpp
size_t _position
```

[Defined in src/base/include/icy/buffer.h:582](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L582)

---

<a id="_limit-1"></a>

### _limit

```cpp
size_t _limit
```

[Defined in src/base/include/icy/buffer.h:583](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L583)

---

<a id="_order-1"></a>

### _order

```cpp
ByteOrder _order
```

Type: [`ByteOrder`](https://auscaster.com/icey/docs/api-reference/base.md#byteorder)

[Defined in src/base/include/icy/buffer.h:584](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L584)

---

<a id="_bytes-1"></a>

### _bytes

```cpp
char * _bytes
```

[Defined in src/base/include/icy/buffer.h:585](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L585)

## Protected Methods

| Return | Name | Description |
|--------|------|-------------|
| `void` | [`init`](#init-1) `virtual` |  |

---

<a id="init-1"></a>

### init

`virtual`

```cpp
virtual void init(char * bytes, size_t size, ByteOrder order)
```

[Defined in src/base/include/icy/buffer.h:580](https://github.com/auscaster/icey/blob/main/src/base/include/icy/buffer.h#L580)