v0.2.0

🚨 Breaking Changes

Method Naming Changes

The following methods have been renamed for improved clarity and consistency:

BitReader:

• UXXR(bits, n int) uintXX → ReadXXR(bits, n int) uintXX

BitWriter:

• UXX(leftPadd, bits int, data uintXX) → WriteXX(leftPadd, bits int, data uintXX)
• Bool(data bool) → WriteBool(data bool)

Migration Guide:

// Before
reader.U8R(8, 0)
reader.U16R(12, 0)
writer.Bool(true)

// After
reader.Read8R(8, 0)
reader.Read16R(12, 0)
writer.WriteBool(true)

The R suffix indicates "Right-aligned" block-based reading, distinguishing these methods from the new cursor-based operations.

✨ New Features

Cursor-based Bit Manipulation

Added flexible cursor-based reading and writing operations, enabling sequential and random access bit manipulation patterns.

BitReader - New Methods:

• ReadBit() (bool, error) - Sequential reading with automatic cursor advancement
• ReadBitAt(pos int) (bool, error) - Random access reading without cursor movement
• Pos() int - Get current read position
• Seek(pos int) error - Set read position
• Data() []T - Access source data slice
• AnyData() any - Access source data as any type

BitWriter - New Methods:

• WriteBit(bit bool) error - Sequential writing with automatic cursor advancement
• WriteBitAt(pos int, bit bool) error - Random access writing with overwrite support
• Pos() int - Get current write position
• Seek(pos int) error - Set write position

Use Cases:

• Bit shuffling and permutation operations
• Selective bit modification without data recreation
• Stream-based bit processing
• Pattern matching and bit scanning

Example:

// Sequential reading
reader := bitstream.NewBitReader(data, 0, 0)
for {
    bit, err := reader.ReadBit()
    if err == io.EOF {
        break
    }
    // Process bit...
}

// Random access writing
writer := bitstream.NewBitWriter[uint8](0, 0)
writer.WriteBitAt(5, true)  // Write to specific position
writer.WriteBitAt(10, false) // Overwrite capability

For detailed examples and documentation, see PR #1.

🐛 Bug Fixes & Improvements

Error Handling

• Introduced ErrNegativePosition for semantically correct error handling
• io.EOF now strictly indicates end-of-data condition
• All position-accepting methods validate negative inputs

Input Validation

• Added negative position validation to prevent panics
• Comprehensive bounds checking for all cursor operations

Thread-Safety

• BitWriter.Bits() now protected by mutex for thread-safe access
• Clearly documented thread-safety guarantees:
  • BitReader: Not thread-safe (use separate instances for concurrent access)
  • BitWriter: Thread-safe (all operations protected by mutex)

📚 Documentation

• Comprehensive README updates with cursor-based operation examples
• Detailed API reference with categorized methods
• Thread-safety model clearly documented
• Error handling patterns and best practices added

🧪 Testing

• Comprehensive test coverage for all new methods
• Edge case testing including padding scenarios
• Negative position validation tests
• Thread-safety and consistency tests

---

For complete details on all changes, see Pull Request #1.