# BitReader

<a id="bitreader"></a>

# BitReader

```cpp
#include <buffer.h>

class BitReader
```

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

Class for reading binary streams.

## Friends

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

---

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

### operator<<

`inline`

```cpp
friend inline std::ostream & operator<<(std::ostream & stream, const BitReader & buf)
```

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

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`BitReader`](#bitreader-1)  | Constructs a `[BitReader](#bitreader)` over a raw byte array. |
|  | [`BitReader`](#bitreader-2)  | Constructs a `[BitReader](#bitreader)` over a `[Buffer](base.html#buffer)`. |
|  | [`BitReader`](#bitreader-3)  | Constructs a `[BitReader](#bitreader)` over a `[ConstBuffer](icy-ConstBuffer.html#constbuffer-6)`. |
|  | [`~BitReader`](#bitreader-4)  |  |
| `void` | [`get`](#get)  | Reads a value from the [BitReader](#bitreader). Returns false if there isn't enough data left for the specified type. Throws a std::out_of_range exception if reading past the limit. Reads `len` raw bytes into `val`. Throws `std::out_of_range` if insufficient data remains. |
| `void` | [`get`](#get-1)  | Reads `len` bytes and appends them to `val`. Throws `std::out_of_range` if insufficient data remains. |
| `void` | [`getU8`](#getu8)  | Reads an unsigned 8-bit integer. Throws `std::out_of_range` if insufficient data remains. |
| `void` | [`getU16`](#getu16)  | Reads an unsigned 16-bit integer, applying byte-order conversion. Throws `std::out_of_range` if insufficient data remains. |
| `void` | [`getU24`](#getu24)  | Reads an unsigned 24-bit integer into a 32-bit variable, applying byte-order conversion. Throws `std::out_of_range` if insufficient data remains. |
| `void` | [`getU32`](#getu32)  | Reads an unsigned 32-bit integer, applying byte-order conversion. Throws `std::out_of_range` if insufficient data remains. |
| `void` | [`getU64`](#getu64)  | Reads an unsigned 64-bit integer, applying byte-order conversion. Throws `std::out_of_range` if insufficient data remains. |
| `char` | [`peek`](#peek)  | Peeks at the current byte without advancing the position. |
| `uint8_t` | [`peekU8`](#peeku8)  | Peeks at the current byte as a `uint8_t` without advancing the position. |
| `uint16_t` | [`peekU16`](#peeku16)  | Peeks at the next two bytes as a `uint16_t` without advancing the position. |
| `uint32_t` | [`peekU24`](#peeku24)  | Peeks at the next three bytes as a `uint32_t` without advancing the position. |
| `uint32_t` | [`peekU32`](#peeku32)  | Peeks at the next four bytes as a `uint32_t` without advancing the position. |
| `uint64_t` | [`peekU64`](#peeku64)  | Peeks data from the [BitReader](#bitreader). -1 is returned if reading past boundary. |
| `size_t` | [`skipToChar`](#skiptochar)  | Advances the position until the given character is found, stopping before it. |
| `size_t` | [`skipWhitespace`](#skipwhitespace)  | Advances the position past any leading space characters. |
| `size_t` | [`skipToNextLine`](#skiptonextline)  | Advances the position past the end of the current line (past the newline). |
| `size_t` | [`skipNextWord`](#skipnextword)  | Advances the position past the next whitespace-delimited word. |
| `size_t` | [`readNextWord`](#readnextword)  | Reads the next whitespace-delimited word into `val`. |
| `size_t` | [`readNextNumber`](#readnextnumber)  | Reads the next whitespace-delimited decimal number into `val`. |
| `size_t` | [`readLine`](#readline)  | Reads bytes up to (but not including) the next newline into `val`. |
| `size_t` | [`readToNext`](#readtonext)  | Reads bytes up to (but not including) the next occurrence of `c` into `val`. |
| `void` | [`seek`](#seek)  | Set position pointer to absolute position. Throws a std::out_of_range exception if the value exceeds the limit. |
| `void` | [`skip`](#skip)  | Set position pointer to relative position. Throws a std::out_of_range exception if the value exceeds the limit. |
| `size_t` | [`limit`](#limit) `const` `nodiscard` | Returns the read limit. |
| `size_t` | [`position`](#position) `const` `inline` `nodiscard` | Returns the current read position. |
| `size_t` | [`available`](#available) `const` `nodiscard` | Returns the number of elements between the current position and the limit. |
| `const char *` | [`begin`](#begin) `const` `inline` `nodiscard` | Returns a pointer to the start of the buffer. |
| `const char *` | [`current`](#current) `const` `inline` `nodiscard` | Returns a pointer to the current read position. |
| `ByteOrder` | [`order`](#order) `const` `inline` | Returns the byte order used for multi-byte integer reads. |
| `std::string` | [`toString`](#tostring)  | Returns the remaining unread bytes as a `std::string`. |

---

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

### BitReader

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

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

Constructs a `[BitReader](#bitreader)` over a raw byte array.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `bytes` | `const char *` | Pointer to the start of the data. Must remain valid for the lifetime of the reader. |
| `size` | `size_t` | Number of bytes available for reading. |
| `order` | `ByteOrder` | Byte order used when reading multi-byte integer types. |

---

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

### BitReader

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

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

Constructs a `[BitReader](#bitreader)` over a `[Buffer](base.html#buffer)`.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `buf` | const [`Buffer`](https://sourcey.com/examples/docs-showcase/reference/cpp/base.md#buffer) & | Source buffer. Must remain valid for the lifetime of the reader. |
| `order` | `ByteOrder` | Byte order used when reading multi-byte integer types. |

---

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

### BitReader

```cpp
BitReader(const ConstBuffer & pod, ByteOrder order = ByteOrder::Network)
```

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

Constructs a `[BitReader](#bitreader)` over a `[ConstBuffer](icy-ConstBuffer.html#constbuffer-6)`.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pod` | const [`ConstBuffer`](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-ConstBuffer.md#constbuffer-6) & | Source const buffer. Must remain valid for the lifetime of the reader. |
| `order` | `ByteOrder` | Byte order used when reading multi-byte integer types. |

---

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

### ~BitReader

```cpp
~BitReader()
```

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

---

<a id="get"></a>

### get

```cpp
void get(char * val, size_t len)
```

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

Reads a value from the [BitReader](#bitreader). Returns false if there isn't enough data left for the specified type. Throws a std::out_of_range exception if reading past the limit. Reads `len` raw bytes into `val`. Throws `std::out_of_range` if insufficient data remains.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `char *` | Destination buffer; must have capacity of at least `len` bytes. |
| `len` | `size_t` | Number of bytes to read. |

---

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

### get

```cpp
void get(std::string & val, size_t len)
```

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

Reads `len` bytes and appends them to `val`. Throws `std::out_of_range` if insufficient data remains.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `std::string &` | String to append the read bytes to. |
| `len` | `size_t` | Number of bytes to read. |

---

<a id="getu8"></a>

### getU8

```cpp
void getU8(uint8_t & val)
```

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

Reads an unsigned 8-bit integer. Throws `std::out_of_range` if insufficient data remains.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint8_t &` | Output parameter receiving the read value. |

---

<a id="getu16"></a>

### getU16

```cpp
void getU16(uint16_t & val)
```

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

Reads an unsigned 16-bit integer, applying byte-order conversion. Throws `std::out_of_range` if insufficient data remains.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint16_t &` | Output parameter receiving the read value. |

---

<a id="getu24"></a>

### getU24

```cpp
void getU24(uint32_t & val)
```

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

Reads an unsigned 24-bit integer into a 32-bit variable, applying byte-order conversion. Throws `std::out_of_range` if insufficient data remains.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint32_t &` | Output parameter receiving the read value. |

---

<a id="getu32"></a>

### getU32

```cpp
void getU32(uint32_t & val)
```

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

Reads an unsigned 32-bit integer, applying byte-order conversion. Throws `std::out_of_range` if insufficient data remains.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint32_t &` | Output parameter receiving the read value. |

---

<a id="getu64"></a>

### getU64

```cpp
void getU64(uint64_t & val)
```

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

Reads an unsigned 64-bit integer, applying byte-order conversion. Throws `std::out_of_range` if insufficient data remains.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `uint64_t &` | Output parameter receiving the read value. |

---

<a id="peek"></a>

### peek

```cpp
char peek()
```

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

Peeks at the current byte without advancing the position. 
#### Returns
Current byte as `char`, or 0 if at the end of the buffer.

---

<a id="peeku8"></a>

### peekU8

```cpp
uint8_t peekU8()
```

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

Peeks at the current byte as a `uint8_t` without advancing the position. 
#### Returns
Current value, or 0 if at the end of the buffer.

---

<a id="peeku16"></a>

### peekU16

```cpp
uint16_t peekU16()
```

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

Peeks at the next two bytes as a `uint16_t` without advancing the position. 
#### Returns
Current value with byte-order conversion applied, or 0 on failure.

---

<a id="peeku24"></a>

### peekU24

```cpp
uint32_t peekU24()
```

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

Peeks at the next three bytes as a `uint32_t` without advancing the position. 
#### Returns
Current value with byte-order conversion applied, or 0 on failure.

---

<a id="peeku32"></a>

### peekU32

```cpp
uint32_t peekU32()
```

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

Peeks at the next four bytes as a `uint32_t` without advancing the position. 
#### Returns
Current value with byte-order conversion applied, or 0 on failure.

---

<a id="peeku64"></a>

### peekU64

```cpp
uint64_t peekU64()
```

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

Peeks data from the [BitReader](#bitreader). -1 is returned if reading past boundary.

---

<a id="skiptochar"></a>

### skipToChar

```cpp
size_t skipToChar(char c)
```

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

Advances the position until the given character is found, stopping before it. 
#### Returns
Number of bytes skipped.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `c` | `char` | Character to search for. |

---

<a id="skipwhitespace"></a>

### skipWhitespace

```cpp
size_t skipWhitespace()
```

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

Advances the position past any leading space characters. 
#### Returns
Number of bytes skipped.

---

<a id="skiptonextline"></a>

### skipToNextLine

```cpp
size_t skipToNextLine()
```

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

Advances the position past the end of the current line (past the newline). 
#### Returns
Number of bytes skipped including the newline character.

---

<a id="skipnextword"></a>

### skipNextWord

```cpp
size_t skipNextWord()
```

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

Advances the position past the next whitespace-delimited word. 
#### Returns
Number of bytes skipped.

---

<a id="readnextword"></a>

### readNextWord

```cpp
size_t readNextWord(std::string & val)
```

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

Reads the next whitespace-delimited word into `val`. 
#### Returns
Number of bytes consumed.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `std::string &` | String to receive the word. |

---

<a id="readnextnumber"></a>

### readNextNumber

```cpp
size_t readNextNumber(unsigned int & val)
```

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

Reads the next whitespace-delimited decimal number into `val`. 
#### Returns
Number of bytes consumed.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `unsigned int &` | Output parameter receiving the parsed unsigned integer. |

---

<a id="readline"></a>

### readLine

```cpp
size_t readLine(std::string & val)
```

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

Reads bytes up to (but not including) the next newline into `val`. 
#### Returns
Number of bytes consumed including the newline.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `std::string &` | String to receive the line content. |

---

<a id="readtonext"></a>

### readToNext

```cpp
size_t readToNext(std::string & val, char c)
```

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

Reads bytes up to (but not including) the next occurrence of `c` into `val`. 
#### Returns
Number of bytes consumed.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `val` | `std::string &` | String to receive the read bytes. |
| `c` | `char` | Delimiter character to stop at. |

---

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

### seek

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

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

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

---

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

### skip

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

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

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

---

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

### limit

`const` `nodiscard`

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

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

Returns the read limit.

---

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

### position

`const` `inline` `nodiscard`

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

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

Returns the current read position.

---

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

### available

`const` `nodiscard`

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

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

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

---

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

### begin

`const` `inline` `nodiscard`

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

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

Returns a pointer to the start of the buffer.

---

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

### current

`const` `inline` `nodiscard`

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

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

Returns a pointer to the current read position.

---

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

### order

`const` `inline`

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

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

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

---

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

### toString

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

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

Returns the remaining unread bytes as a `std::string`. 
#### Returns
String containing bytes from the current position to the end.

## Protected Attributes

| Return | Name | Description |
|--------|------|-------------|
| `size_t` | [`_position`](#_position)  |  |
| `size_t` | [`_limit`](#_limit)  |  |
| `ByteOrder` | [`_order`](#_order)  |  |
| `const char *` | [`_bytes`](#_bytes)  |  |

---

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

### _position

```cpp
size_t _position
```

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

---

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

### _limit

```cpp
size_t _limit
```

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

---

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

### _order

```cpp
ByteOrder _order
```

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

---

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

### _bytes

```cpp
const char * _bytes
```

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

## Protected Methods

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

---

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

### init

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

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