RFC: buffer.readbits/writebits

[vegorov-rbx]

Rendered: link

[ccuser44]

Bump, this would be extremely helpful.

[vegorov-rbx]

Yeah, it took a while in the pipeline with other priorities, but we still remember about this one and it's likely to be accepted.

[zeux]

Operations are always preformed in little-endian byte order and starting from least significant bits.

This has a typo (performed), but more importantly the spec doesn't specifically have an example for fractional bit offsets. My understanding is that the way this works is:

• Bytes are numbered from 0 to buffer size - 1
• Bits within bytes are numbered from 0 (least significant) to 7 (most significant)
• Bits inside the buffer are numbered from 0 to 8 * buffer size - 1
• Reads/writes across a byte boundary will write most significant bits of an earlier byte and least significant bits of a later byte, for example:

buffer.writebits(buf, 5, 17, value)

Will take 17 least-significant bits of value, split them in groups of 3, 8, 6 (in least significant order), and overwrite 3 most significant bits to byte 0 (keeping the 5 least significant bits as is), the entire byte 1, and overwrite 6 least significant bits of byte 2 (keeping the 2 most significant bits as is).

... There's probably a cleaner way to describe this but at least one example of boundary straddling would be helpful.

[vegorov-rbx]

That is correct, in a code form example:

  local buf0 = buffer.create(16)
  buffer.writebits(buf0, 5, 17, 0b11111111_11111111_11111111_11111111)

  assert(buffer.readu8(buf0, 0) == 0b11100000)
  assert(buffer.readu8(buf0, 1) == 0b11111111)
  assert(buffer.readu8(buf0, 2) == 0b00111111)
  
  local buf1 = buffer.create(16)
  buffer.fill(buf1, 0, 0xff)
  buffer.writebits(buf1, 5, 17, 0b00000000_00000000_00000000_00000000)

  assert(buffer.readu8(buf1, 0) == 0b00011111)
  assert(buffer.readu8(buf1, 1) == 0b00000000)
  assert(buffer.readu8(buf1, 2) == 0b11000000)