Reference

std/binary/bits

std/binary/src/bits.trb

BitReader and BitWriter: numbers of any width up to 56 bits, packed into bytes in a BitOrder.

type BitOrder

type BitOrder with Show, Equals, Hash

Which bit of a byte comes first, and so which bit of a number read from several of them is its lowest.

case LeastSignificantFirst

case LeastSignificantFirst

The lowest bit of a byte first, and the first bit read is the lowest of the number: DEFLATE, GIF's LZW, most little-endian formats.

case MostSignificantFirst

case MostSignificantFirst

The highest bit of a byte first, and the first bit read is the highest of the number: JPEG, H.264, the samples of PNG and PBM, and most network headers.

type BitReader

type BitReader

The bits of bytes, read as numbers of 0 to 56 bits in a BitOrder - most significant first unless it was made with another. A read answers a ReadError instead of reading past the end, and moves nothing then.

var reader = BitReader([0b1011_0010], order: .MostSignificantFirst)
print reader.bits(3)
print reader.bit()

The reader loads a byte when a read needs one of its bits, and fewer than eight bits wait between two reads, so BitReader.position is a byte boundary a format can go on from after BitReader.alignToByte.

field input

input: Bytes

The bytes this reader reads.

field order

order: BitOrder = BitOrder.MostSignificantFirst

Which bit of a byte is read first.

fn position

fn position(): Int

How many bytes the reader has started: the byte the next bit comes from is the one before it while bits of that byte are left, and after BitReader.alignToByte it is the next byte to read.

fn remaining

fn remaining(): Int

How many bits are left to read.

fn bits

var fn bits(width: Int): Result<Int, ReadError>

The next width bits as a number, from 0 to 56 of them. In the least significant order the first bit read is the lowest of the number, in the most significant order the highest.

Panics

  • For a width below 0 or above 56: a mistake of the caller, not of the bytes.

Errors

fn bit

var fn bit(): Result<Bool, ReadError>

Whether the next bit is set.

Errors

fn alignToByte

var fn alignToByte()

Drops the bits left of the byte the last read came from, so the next read starts at a byte boundary.

fn seek

var fn seek(position: Int): Result<Void, ReadError>

Moves to the first bit of the byte at position, dropping the bits left of the current byte; the end itself is a position too. What a format that starts inside other bytes begins with: a DEFLATE stream after a gzip header.

Errors

fn bytes

var fn bytes(count: Int): Result<Bytes, ReadError>

The next count whole bytes, after the bits left of the current byte are dropped as BitReader.alignToByte drops them: the stored block of DEFLATE.

Errors

type BitWriter

type BitWriter

Numbers of 0 to 56 bits packed into bytes in a BitOrder, most significant first unless it was made with another.

var writer = BitWriter(order: .LeastSignificantFirst)
writer.bits 5, 3
writer.bit true
print writer.bytes()

A byte that is not full yet is kept back, and BitWriter.bytes answers it filled up with zero bits.

field order

order: BitOrder = BitOrder.MostSignificantFirst

Which bit of a byte is written first.

fn length

fn length(): Int

How many bits have been written.

fn bits

var fn bits(value: Int, width: Int)

The lowest width bits of value, from 0 to 56 of them: in the least significant order its lowest bit first, in the most significant order its highest bit first.

Panics

  • For a width below 0 or above 56.

fn bit

var fn bit(value: Bool)

One bit: 1 where value is true.

fn alignToByte

var fn alignToByte()

Fills the byte that is not full yet with zero bits, so the next write starts at a byte boundary.

fn bytes

fn bytes(): Bytes

Everything written so far, a byte that is not full yet filled up with zero bits. The writer is unchanged.