binary.zig

//! A small, allocation-aware binary reader and writer.
//!
//! The legacy convenience methods use little-endian encoding. Use `writeInt`
//! and `readInt` when the byte order should be explicit.

const std = @import("std");

pub const BinaryStream = struct {
    const Self = @This();

    pub const Error = error{
        EndOfStream,
        InvalidPosition,
        Invalid7BitEncodedInt,
        StringTooLong,
    };

    allocator: std.mem.Allocator,
    buffer: std.ArrayList(u8) = .empty,
    offset: usize = 0,

    pub fn init(allocator: std.mem.Allocator) Self {
        return .{ .allocator = allocator };
    }

    pub fn initCapacity(allocator: std.mem.Allocator, capacity: usize) !Self {
        return .{
            .allocator = allocator,
            .buffer = try .initCapacity(allocator, capacity),
        };
    }

    /// Creates a stream containing a copy of `bytes`, positioned at byte zero.
    pub fn initFromSlice(allocator: std.mem.Allocator, data: []const u8) !Self {
        var self = init(allocator);
        errdefer self.deinit();
        try self.write(data);
        return self;
    }

    pub fn deinit(self: *Self) void {
        self.buffer.deinit(self.allocator);
        self.* = undefined;
    }

    /// Returns all bytes currently stored in the stream.
    pub fn bytes(self: *const Self) []const u8 {
        return self.buffer.items;
    }

    pub fn position(self: *const Self) usize {
        return self.offset;
    }

    pub fn remaining(self: *const Self) usize {
        return self.buffer.items.len - self.offset;
    }

    pub fn setPosition(self: *Self, new_position: usize) Error!void {
        if (new_position > self.buffer.items.len) return error.InvalidPosition;
        self.offset = new_position;
    }

    pub fn resetReader(self: *Self) void {
        self.offset = 0;
    }

    /// Removes all data while retaining allocated capacity for reuse.
    pub fn clearRetainingCapacity(self: *Self) void {
        self.buffer.clearRetainingCapacity();
        self.offset = 0;
    }

    pub fn write(self: *Self, value: []const u8) std.mem.Allocator.Error!void {
        try self.buffer.appendSlice(self.allocator, value);
    }

    pub fn writeByte(self: *Self, value: u8) std.mem.Allocator.Error!void {
        try self.buffer.append(self.allocator, value);
    }

    pub fn writeInt(
        self: *Self,
        comptime T: type,
        value: T,
        endian: std.builtin.Endian,
    ) std.mem.Allocator.Error!void {
        comptime assertByteAlignedInteger(T);
        var encoded: [@sizeOf(T)]u8 = undefined;
        std.mem.writeInt(T, &encoded, value, endian);
        try self.write(&encoded);
    }

    pub fn writeU16(self: *Self, value: u16) !void {
        try self.writeInt(u16, value, .little);
    }

    pub fn writeInt16(self: *Self, value: i16) !void {
        try self.writeInt(i16, value, .little);
    }

    pub fn writeInt32(self: *Self, value: i32) !void {
        try self.writeInt(i32, value, .little);
    }

    pub fn writeU64(self: *Self, value: u64) !void {
        try self.writeInt(u64, value, .little);
    }

    pub fn write7BitEncodedInt(self: *Self, value: usize) !void {
        var remaining_value = value;
        while (remaining_value >= 0x80) : (remaining_value >>= 7) {
            try self.writeByte(@as(u8, @truncate(remaining_value)) | 0x80);
        }
        try self.writeByte(@truncate(remaining_value));
    }

    /// Writes a 7-bit length-prefixed byte string.
    pub fn writeString(self: *Self, value: []const u8) !void {
        try self.write7BitEncodedInt(value.len);
        try self.write(value);
    }

    /// Writes a one-byte length-prefixed byte string.
    pub fn writeString8(self: *Self, value: []const u8) !void {
        if (value.len > std.math.maxInt(u8)) return error.StringTooLong;
        try self.writeByte(@intCast(value.len));
        try self.write(value);
    }

    // Backwards-compatible names from the first release.
    pub const writeStrL = writeString;
    pub const writeStrL8 = writeString8;

    /// Returns a borrowed view which remains valid until the stream reallocates.
    pub fn read(self: *Self, size: usize) Error![]const u8 {
        if (size > self.remaining()) return error.EndOfStream;
        const start = self.offset;
        self.offset += size;
        return self.buffer.items[start..self.offset];
    }

    pub fn skip(self: *Self, size: usize) Error!void {
        _ = try self.read(size);
    }

    pub fn readByte(self: *Self) Error!u8 {
        return (try self.read(1))[0];
    }

    pub fn readInt(
        self: *Self,
        comptime T: type,
        endian: std.builtin.Endian,
    ) Error!T {
        comptime assertByteAlignedInteger(T);
        const encoded = try self.read(@sizeOf(T));
        const encoded_array: *const [@sizeOf(T)]u8 = @ptrCast(encoded.ptr);
        return std.mem.readInt(T, encoded_array, endian);
    }

    pub fn readU16(self: *Self) !u16 {
        return self.readInt(u16, .little);
    }

    pub fn readInt16(self: *Self) !i16 {
        return self.readInt(i16, .little);
    }

    pub fn readInt32(self: *Self) !i32 {
        return self.readInt(i32, .little);
    }

    pub fn readU64(self: *Self) !u64 {
        return self.readInt(u64, .little);
    }

    // Backwards-compatible names from the first release.
    pub const read16 = readInt16;
    pub const readUInt64 = readU64;

    pub fn read7BitEncodedInt(self: *Self) Error!usize {
        const initial_offset = self.offset;
        errdefer self.offset = initial_offset;

        const bit_count = @bitSizeOf(usize);
        const max_encoded_bytes = (bit_count + 6) / 7;
        var result: u128 = 0;
        var byte_index: usize = 0;

        while (byte_index < max_encoded_bytes) : (byte_index += 1) {
            const byte = try self.readByte();
            const shift = byte_index * 7;
            const typed_shift: std.math.Log2Int(u128) = @intCast(shift);
            const payload: u128 = byte & 0x7f;

            result |= payload << typed_shift;
            if (byte & 0x80 == 0) {
                if (result > std.math.maxInt(usize)) return error.Invalid7BitEncodedInt;
                return @intCast(result);
            }
        }

        return error.Invalid7BitEncodedInt;
    }

    pub fn readString(self: *Self) Error![]const u8 {
        const initial_offset = self.offset;
        errdefer self.offset = initial_offset;
        const length = try self.read7BitEncodedInt();
        return self.read(length);
    }

    pub fn readString8(self: *Self) Error![]const u8 {
        const initial_offset = self.offset;
        errdefer self.offset = initial_offset;
        const length = try self.readByte();
        return self.read(length);
    }

    // Backwards-compatible names from the first release.
    pub const readStringL = readString;
    pub const readStringL8 = readString8;

    fn assertByteAlignedInteger(comptime T: type) void {
        const type_info = @typeInfo(T);
        if (type_info != .int or type_info.int.bits % 8 != 0) {
            @compileError("binary stream integer type must have a byte-aligned bit width");
        }
    }
};

/// Deprecated compatibility alias. Prefer `BinaryStream`.
pub const binaryStream = BinaryStream;

test "legacy names remain callable" {
    var stream = binaryStream.init(std.testing.allocator);
    defer stream.deinit();

    try stream.writeStrL("legacy");
    try stream.writeStrL8("api");
    try stream.writeInt16(-12);
    try stream.writeU64(34);
    try std.testing.expectEqualStrings("legacy", try stream.readStringL());
    try std.testing.expectEqualStrings("api", try stream.readStringL8());
    try std.testing.expectEqual(@as(i16, -12), try stream.read16());
    try std.testing.expectEqual(@as(u64, 34), try stream.readUInt64());
}

test "round trip legacy little-endian format" {
    var stream = BinaryStream.init(std.testing.allocator);
    defer stream.deinit();

    try stream.writeByte(1);
    try stream.writeString("Hello World");
    try stream.writeU16(500);
    try stream.writeInt32(-200);
    try stream.writeU64(505);
    try stream.writeInt16(-5000);
    try stream.writeString8("Hello World 2");

    try std.testing.expectEqual(@as(u8, 1), try stream.readByte());
    try std.testing.expectEqualStrings("Hello World", try stream.readString());
    try std.testing.expectEqual(@as(u16, 500), try stream.readU16());
    try std.testing.expectEqual(@as(i32, -200), try stream.readInt32());
    try std.testing.expectEqual(@as(u64, 505), try stream.readU64());
    try std.testing.expectEqual(@as(i16, -5000), try stream.readInt16());
    try std.testing.expectEqualStrings("Hello World 2", try stream.readString8());
    try std.testing.expectEqual(@as(usize, 0), stream.remaining());
}

test "integer byte order is explicit and portable" {
    var stream = BinaryStream.init(std.testing.allocator);
    defer stream.deinit();

    try stream.writeInt(u32, 0x12345678, .big);
    try stream.writeInt(u32, 0x12345678, .little);
    try std.testing.expectEqualSlices(u8, &.{
        0x12, 0x34, 0x56, 0x78,
        0x78, 0x56, 0x34, 0x12,
    }, stream.bytes());
    try std.testing.expectEqual(@as(u32, 0x12345678), try stream.readInt(u32, .big));
    try std.testing.expectEqual(@as(u32, 0x12345678), try stream.readInt(u32, .little));
}

test "all usize values round trip through 7-bit encoding" {
    const values = [_]usize{
        0,
        1,
        127,
        128,
        16_383,
        16_384,
        std.math.maxInt(usize),
    };

    var stream = BinaryStream.init(std.testing.allocator);
    defer stream.deinit();
    for (values) |value| try stream.write7BitEncodedInt(value);
    for (values) |value| try std.testing.expectEqual(value, try stream.read7BitEncodedInt());
}

test "failed reads are bounds checked and transactional" {
    var stream = try BinaryStream.initFromSlice(std.testing.allocator, &.{ 0x03, 'a' });
    defer stream.deinit();

    try std.testing.expectError(error.EndOfStream, stream.readString());
    try std.testing.expectEqual(@as(usize, 0), stream.position());
    try std.testing.expectError(error.EndOfStream, stream.read(3));
    try std.testing.expectEqual(@as(usize, 0), stream.position());
    try std.testing.expectError(error.InvalidPosition, stream.setPosition(3));
}

test "malformed 7-bit integers are rejected without consuming input" {
    const max_encoded_bytes = (@bitSizeOf(usize) + 6) / 7;
    const too_long = [_]u8{0x80} ** max_encoded_bytes;
    var stream = try BinaryStream.initFromSlice(std.testing.allocator, &too_long);
    defer stream.deinit();

    try std.testing.expectError(error.Invalid7BitEncodedInt, stream.read7BitEncodedInt());
    try std.testing.expectEqual(@as(usize, 0), stream.position());

    var overflow = [_]u8{0xff} ** max_encoded_bytes;
    const final_payload_bits = @bitSizeOf(usize) - ((max_encoded_bytes - 1) * 7);
    overflow[overflow.len - 1] = @as(u8, 1) << final_payload_bits;
    var overflow_stream = try BinaryStream.initFromSlice(std.testing.allocator, &overflow);
    defer overflow_stream.deinit();

    try std.testing.expectError(
        error.Invalid7BitEncodedInt,
        overflow_stream.read7BitEncodedInt(),
    );
    try std.testing.expectEqual(@as(usize, 0), overflow_stream.position());
}

test "8-bit strings reject lengths above 255" {
    var stream = BinaryStream.init(std.testing.allocator);
    defer stream.deinit();
    const long_string = [_]u8{'x'} ** 256;

    try std.testing.expectError(error.StringTooLong, stream.writeString8(&long_string));
    try std.testing.expectEqual(@as(usize, 0), stream.bytes().len);
}

test "clear and reset support stream reuse" {
    var stream = BinaryStream.init(std.testing.allocator);
    defer stream.deinit();

    try stream.write(&.{ 1, 2, 3 });
    try std.testing.expectEqual(@as(u8, 1), try stream.readByte());
    stream.resetReader();
    try std.testing.expectEqual(@as(u8, 1), try stream.readByte());
    stream.clearRetainingCapacity();
    try std.testing.expectEqual(@as(usize, 0), stream.bytes().len);
    try std.testing.expectEqual(@as(usize, 0), stream.position());
}