read_bit

Builtin index · File I/O

result = read_bit(f)

Input: f · Output: result

What it is

Reads one bit from f (file handle, opened readable), MSB-first, advancing a sub-byte cursor that only moves to the next byte once all 8 bits of it are consumed.

Overloads

One call shape — this function is not overloaded.

Examples

From the documentation, and run by the build -- the output and the figure below are what the engine actually produced. Simplest first.

f = fopen("flags.bin", "wb")
write_bit(f, 1)
write_bit(f, 0)
write_bit(f, 1)
write_bit(f, 1)
close(f)                       # only 4 bits written -- flushed as one padded byte


g = fopen("flags.bin", "rb")
b0 = read_bit(g)
b1 = read_bit(g)
b2 = read_bit(g)
b3 = read_bit(g)
close(g)
print("{b0}{b1}{b2}{b3}")      # 1011

print(file_size("flags.bin"))  # 1 -- one byte on disk for 4 bits

1011
1

from file-io

How it works

read_bit(f) — one bit (0 or 1) from the current byte, MSB-first (the conventional default — bit 0 of a byte is its 0x80 bit), advancing a sub-byte cursor that only moves to the next byte once all 8 bits are consumed. An EE/embedded- flavored primitive most languages don't have, matching this project's explicitly targeted audience. Nothing at EOF. § real streaming reads (2026-08-31): the underlying byte is read off the stream ONCE (into pending_bit_byte) the first time a bit of it is requested (read_bit_pos == 0), then re-examined from that cached byte for the remaining 7 bits — a forward-only reader can't be re-indexed the way the old whole-file buffer could, so the byte has to be cached somewhere for its own 8-bit lifetime. read_pos intentionally still points AT this byte the whole time (matching the old behavior exactly), only advancing once bit 7 is consumed.

From the note above this builtin in the interpreter, where the reasoning was written down as it was built.