vhlibbitptr

VHBitPtr — Bitstream Pointer Class

VHBitPtr is a lightweight, header-only C++ class designed for efficient bit-level manipulation and bitstream processing. It provides granular read and write operations for variable-length bit fields (1 to 16 bits) directly into memory buffers, with native support for both forward and reverse bit ordering.

Library Metadata

Class Name: VHBitPtr
Source File: pack81bitptr.cpp / vhbitptr.hpp
Author: Viktor Glebov (V01G04A81)
Copyright: © 2025 Viktor Glebov
License: MIT
Language: C++17 or higher (relies on <cstdint>)

Key Features

Granular Bit Operations: Read and write 1, 2, 3, 4 (half-byte/nibble), 5, 6, 7, 8 (byte), and 16 (word) bits at a time.
Bidirectional Processing: Supports both forward (MSB-first) and reverse (LSB-first) bit ordering via a simple configuration flag (rev).
Peek Operations: Non-destructive read methods (TBit, T2bts, THalf, TByte) allow inspecting data without advancing the internal bit pointer.
Zero Overhead: Inline-friendly design with minimal state (pointer, bit count, reverse flag, and temporary storage). No dynamic memory allocation.
Alignment Utilities: Built-in methods to query current bit/byte counts and align the pointer to the next byte boundary seamlessly.

API Reference

Constructors & Initialization

Method	Description
`VHBitPtr()`	Default constructor (null pointer, 0 bits, forward mode).
`VHBitPtr(u8 *pa, u16 bits=0, bool rev=false)`	Initialize with memory pointer, starting bit offset, and reverse mode flag.
`void set(u8 *pa, u16 bits=0, bool rev=false)`	Re-initialize or update the pointer, bit count, and direction.

Write Operations (Put)

Method	Description
`void PBit0()` / `void PBit1()`	Write a single `0` or `1` bit.
`void PBit(u8 b)`	Write a single bit based on boolean/integer value.
`void P2Bts(u8 v)` … `void P7Bts(u8 v)`	Write 2 to 7 bits from the provided value (using bitmask iteration).
`void PHalf(u8 v)`	Write a 4-bit half-byte (nibble).
`void PByte(u8 v)`	Write a full 8-bit byte.
`void PWord(u16 w)`	Write a 16-bit word (two consecutive bytes).

Read Operations (Get)

Method	Description
`u8 GBit()`	Read a single bit.
`u8 G2bts()`	Read 2 bits.
`u8 GHalf()`	Read 4 bits (half-byte).
`u8 GByte()`	Read 8 bits (full byte).
`u16 GWord()`	Read 16 bits (word), respecting the `rev` endianness flag.

Peek Operations (Test)

Method	Description
`u8 TBit()` … `u8 TByte()`	Read 1 to 8 bits without advancing the internal bit counter (uses internal `psh`/`pop` state).

Utility & State

Method	Description
`u16 bitscnt()`	Get the total number of bits processed.
`u16 bytescnt()`	Get the total number of bytes consumed/produced (including partial bytes).
`u8 lastbyte()`	Returns `1` if there is a partial byte, `0` otherwise.
`void setr(bool r)`	Set the reverse direction flag (`true` for reverse, `false` for forward).
`void align()`	Advance the bit counter to the next byte boundary (multiple of 8).

Basic Usage Examples

Writing and Reading a Bitstream

#include <cstdint>
#include <iostream>
// #include "vhbitptr.hpp" // Assume the class is defined here

int main() {
    uint8_t buffer[4] = {0}; // 4-byte buffer initialized to zero

    // 1. Initialize for writing (forward mode)
    VHBitPtr writer(buffer, 0, false);

    // Write a 3-bit value (e.g., 5 = 101 in binary)
    writer.P3Bts(5);
    
    // Write a 4-bit half-byte (nibble)
    writer.PHalf(0x0C); // 12
    
    // Write a full byte
    writer.PByte(0xAB);

    // 2. Initialize for reading from the same buffer
    VHBitPtr reader(buffer, 0, false);

    // Read 2 bits (part of the 3-bit value)
    uint8_t val2 = reader.G2bts(); 
    
    // Read next 1 bit (completing the 3-bit value)
    uint8_t val1 = reader.GBit();   
    
    // Read the 4-bit half-byte
    uint8_t half = reader.GHalf();  
    
    // Read the full byte
    uint8_t byte = reader.GByte();  

    std::cout << "Bits read: " << (int)val2 << ", " << (int)val1 
              << " | Half: 0x" << std::hex << (int)half 
              << " | Byte: 0x" << (int)byte << std::endl;

    return 0;
}

Peek Operation (Non-destructive Read)

uint8_t buffer[1] = {0};
VHBitPtr ptr(buffer, 0, false);

ptr.PByte(0x5A); // Write 0101 1010
ptr.set(buffer, 0, false); // Reset to beginning

// Peek at the first 4 bits without advancing the pointer
uint8_t peeked = ptr.THalf(); 
// ptr.bitscnt() is still 0 here!

// Now actually read them, advancing the pointer
uint8_t actual = ptr.GHalf();

Implementation Details & Notes

Bit Ordering (`rev` flag)

Forward (rev = false): Bits are processed from MSB to LSB within each byte (standard network/big-endian bit order). The bit counter bcnt increments.
Reverse (rev = true): Bits are processed from LSB to MSB. The bit counter bcnt decrements, allowing backward parsing of bitstreams.

Read/Write Asymmetry

The class provides explicit write methods for 3, 5, 6, and 7 bits (P3Bts, P5Bts, P6Bts, P7Bts). However, to maintain a minimal embedded footprint, explicit read methods for these exact widths are omitted. Reading non-standard bit widths should be composed using multiple GBit(), G2bts(), and GHalf() calls.

Memory Layout

The class maintains only four lightweight state variables:

u8 *ptr: Pointer to the base of the memory buffer.
u16 bcnt: Total number of bits processed (acts as the bit-level offset).
bool rv: Reverse mode flag.
u16 tmp: Temporary storage for peek (psh/pop) operations.

Integration & Requirements

Requirements

C++17 or higher (relies on <cstdint> for fixed-width integer types uint8_t, uint16_t).
The caller is responsible for ensuring the provided buffer has sufficient capacity to prevent out-of-bounds memory access. The class does not perform automatic bounds checking to maximize execution speed.

Alignment

The align() method is highly useful when transitioning from bit-level operations to byte-level operations (e.g., before writing a standard PByte or PWord to ensure the stream is byte-aligned).