# BitWriter

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

# BitWriter

```cpp
#include <buffer.h>

class BitWriter
```

Defined in src/base/include/icy/buffer.h:450

> **Subclassed by:** [`DynamicBitWriter`](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-DynamicBitWriter.md#dynamicbitwriter)

Class for reading/writing binary streams.

Note that when using the constructor with the [Buffer](https://sourcey.com/examples/docs-showcase/reference/cpp/base.md#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-1) `inline` |  |

---

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

### operator<<

`inline`

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

Defined in src/base/include/icy/buffer.h:574

## 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](base.html#buffer)`. Writes are bounded by the buffer's capacity; use `[DynamicBitWriter](icy-DynamicBitWriter.html#dynamicbitwriter)` for auto-resize. |
|  | [`BitWriter`](#bitwriter-3)  | Constructs a `[BitWriter](#bitwriter)` over a `[MutableBuffer](icy-MutableBuffer.html#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` `nodiscard` | Returns the write limit. |
| `size_t` | [`position`](#position-1) `const` `inline` `nodiscard` | Returns the current write position. |
| `size_t` | [`available`](#available-1) `const` `nodiscard` | Returns the number of elements between the current write position and the limit. |
| `char *` | [`begin`](#begin-1) `inline` `nodiscard` | Returns a pointer to the start of the write buffer. |
| `char *` | [`current`](#current-1) `inline` `nodiscard` | Returns a pointer to the current write position. |
| `const char *` | [`begin`](#begin-2) `const` `inline` `nodiscard` | Returns a const pointer to the start of the write buffer. |
| `const char *` | [`current`](#current-2) `const` `inline` `nodiscard` | Returns a const pointer to the current write position. |
| `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

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

Constructs a `[BitWriter](#bitwriter)` backed by a `[Buffer](base.html#buffer)`. Writes are bounded by the buffer's capacity; use `[DynamicBitWriter](icy-DynamicBitWriter.html#dynamicbitwriter)` for auto-resize.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `buf` | [`Buffer`](https://sourcey.com/examples/docs-showcase/reference/cpp/base.md#buffer) & | Source buffer. Must remain valid for the writer's lifetime. |
| `order` | `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

Constructs a `[BitWriter](#bitwriter)` over a `[MutableBuffer](icy-MutableBuffer.html#mutablebuffer-6)` with a fixed capacity.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pod` | [`MutableBuffer`](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-MutableBuffer.md#mutablebuffer-6) & | Source mutable buffer. Must remain valid for the writer's lifetime. |
| `order` | `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

---

<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

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

#### Reimplemented by

- [`DynamicBitWriter::put`](https://sourcey.com/examples/docs-showcase/reference/cpp/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

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

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

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

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

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

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

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

#### Reimplemented by

- [`DynamicBitWriter::update`](https://sourcey.com/examples/docs-showcase/reference/cpp/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

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

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

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

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

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

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

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

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` `nodiscard`

```cpp
[[nodiscard]] size_t limit() const
```

Defined in src/base/include/icy/buffer.h:546

Returns the write limit.

---

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

### position

`const` `inline` `nodiscard`

```cpp
[[nodiscard]] inline size_t position() const
```

Defined in src/base/include/icy/buffer.h:549

Returns the current write position.

---

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

### available

`const` `nodiscard`

```cpp
[[nodiscard]] size_t available() const
```

Defined in src/base/include/icy/buffer.h:553

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

---

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

### begin

`inline` `nodiscard`

```cpp
[[nodiscard]] inline char * begin()
```

Defined in src/base/include/icy/buffer.h:556

Returns a pointer to the start of the write buffer.

---

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

### current

`inline` `nodiscard`

```cpp
[[nodiscard]] inline char * current()
```

Defined in src/base/include/icy/buffer.h:559

Returns a pointer to the current write position.

---

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

### begin

`const` `inline` `nodiscard`

```cpp
[[nodiscard]] inline const char * begin() const
```

Defined in src/base/include/icy/buffer.h:562

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

---

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

### current

`const` `inline` `nodiscard`

```cpp
[[nodiscard]] inline const char * current() const
```

Defined in src/base/include/icy/buffer.h:565

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

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

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` | [`_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

---

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

### _limit

```cpp
size_t _limit
```

Defined in src/base/include/icy/buffer.h:583

---

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

### _order

```cpp
ByteOrder _order
```

Defined in src/base/include/icy/buffer.h:584

---

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

### _bytes

```cpp
char * _bytes
```

Defined in src/base/include/icy/buffer.h:585

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