tiny.preserves.SignedInteger

1/// A signed integer of any size, stored in the smallest of three representations that holds it.2/// Every integer in a value is one of these, so every reader, writer and comparison of integers3/// uses it. A value built by `fromCanonicalBytes` or `clone` owns its heap bytes, and `deinit`4/// frees them. Equality and order assume the smallest representation, so a value written directly5/// through `repr` has to keep it.6pub const SignedInteger = struct {7    /// The number in one of its three representations. A value set here directly has to use the8    /// smallest representation that holds the number, because nothing checks it.9    repr: Repr,1011    /// The number stored as 128 signed bits, 128 unsigned bits or heap bytes, tagged by which. Code12    /// that switches on how an integer is stored reads this.13    pub const Repr = union(Tier) {14        /// The number when it fits in 128 signed bits.15        i128: i128,16        /// The number when it is above the largest 128-bit signed integer and fits in 128 unsigned17        /// bits.18        u128: u128,19        /// The number's shortest big-endian two's-complement bytes, for a number outside both20        /// 128-bit ranges. These bytes are at least 17 long.21        big: []const u8,22    };2324    /// Returns zero, stored in 128 signed bits. Code that needs a zero integer calls it.25    pub fn zero() SignedInteger {26        return .{ .repr = .{ .i128 = 0 } };27    }2829    /// Returns `v`, stored in 128 signed bits. Readers and constructors call it for any integer30    /// that fits in 128 signed bits.31    pub fn fromI128(v: i128) SignedInteger {32        return .{ .repr = .{ .i128 = v } };33    }3435    /// Returns `v`, stored in 128 signed bits when it fits there and in 128 unsigned bits36    /// otherwise. Readers call it for a non-negative integer read as 128 unsigned bits.37    pub fn fromU128(v: u128) SignedInteger {38        const limit: u128 = @intCast(std.math.maxInt(i128));39        if (v <= limit) {40            return .{ .repr = .{ .i128 = @intCast(v) } };41        }42        return .{ .repr = .{ .u128 = v } };43    }4445    /// Reads a number from its shortest big-endian two's-complement bytes. The binary and text46    /// readers call it for integers too large for fixed-width parsing. Empty bytes are zero, up to47    /// 16 bytes give a 128-bit signed number, and 17 bytes of a number that fits 128 unsigned bits48    /// give a 128-bit unsigned number. Numbers with more bytes keep a copy of the bytes from49    /// `allocator`, which `deinit` frees. The call returns `error.NonCanonicalInteger` for any50    /// spelling longer than the shortest.51    pub fn fromCanonicalBytes(allocator: Allocator, bytes: []const u8) !SignedInteger {52        if (!isCanonicalBytes(bytes)) return DecodeError.NonCanonicalInteger;53        if (bytes.len == 0) return zero();54        if (bytes.len <= 16) return fromI128(decodeI128Bytes(bytes));55        if (bytes.len == 17 and bytes[0] == 0x00 and (bytes[1] & 0x80) != 0) {56            return .{ .repr = .{ .u128 = decode16BytesAsU128(bytes[1..]) } };57        }58        return .{ .repr = .{ .big = try allocator.dupe(u8, bytes) } };59    }6061    /// Frees the heap bytes of a number too large for 128 bits, and does nothing for any other62    /// number. `Value.deinit` and `freeValueDeep` call it for every integer they free. The value is63    /// undefined afterward.64    pub fn deinit(self: *SignedInteger, allocator: Allocator) void {65        switch (self.repr) {66            .big => |b| if (b.len != 0) allocator.free(b),67            else => {},68        }69        self.* = undefined;70    }7172    /// Returns a copy that owns its storage, copying the heap bytes of a large number with73    /// `allocator`. `cloneValueDeep` calls it for every integer it copies. A number that fits in74    /// 128 bits is copied without allocating.75    pub fn clone(self: SignedInteger, allocator: Allocator) !SignedInteger {76        return switch (self.repr) {77            .i128 => |v| fromI128(v),78            .u128 => |v| .{ .repr = .{ .u128 = v } },79            .big => |b| .{ .repr = .{ .big = try allocator.dupe(u8, b) } },80        };81    }8283    /// Returns a new allocation from `allocator` holding the number's shortest big-endian84    /// two's-complement bytes, which the caller frees. The binary writer calls it for the bytes of85    /// each integer it writes. Zero gives an empty slice.86    pub fn toCanonicalBytes(self: SignedInteger, allocator: Allocator) ![]u8 {87        return switch (self.repr) {88            .i128 => |v| try encodeI128(allocator, v),89            .u128 => |v| try encodeU128(allocator, v),90            .big => |b| try allocator.dupe(u8, b),91        };92    }9394    /// Returns the number when it is stored in 128 signed bits, and `error.OutOfRange` otherwise.95    /// Code that needs the number as a Zig `i128` calls it, as the package's tests do.96    pub fn toI128(self: SignedInteger) RangeError!i128 {97        return switch (self.repr) {98            .i128 => |v| v,99            .u128, .big => RangeError.OutOfRange,100        };101    }102103    /// Returns the number when it is zero or positive and fits in 128 unsigned bits, and104    /// `error.OutOfRange` otherwise. Code that needs a 128-bit unsigned integer calls it.105    pub fn toU128(self: SignedInteger) RangeError!u128 {106        return switch (self.repr) {107            .i128 => |v| if (v < 0) RangeError.OutOfRange else @intCast(v),108            .u128 => |v| v,109            .big => RangeError.OutOfRange,110        };111    }112113    /// Returns the number when it fits in 64 signed bits, and `error.OutOfRange` otherwise. Code114    /// that reads a field it expects to fit in 64 bits calls it for an `i64`.115    pub fn toI64(self: SignedInteger) RangeError!i64 {116        const v = try self.toI128();117        if (v < std.math.minInt(i64) or v > std.math.maxInt(i64)) return RangeError.OutOfRange;118        return @intCast(v);119    }120121    /// Returns the number clamped to the 64-bit signed range: the largest `i64` for any number122    /// above it and the smallest for any number below. The JSON writer calls it to print an integer123    /// too large for 128 bits. The call never fails.124    pub fn toI64Lossy(self: SignedInteger) i64 {125        return switch (self.repr) {126            .i128 => |v| blk: {127                if (v > std.math.maxInt(i64)) break :blk std.math.maxInt(i64);128                if (v < std.math.minInt(i64)) break :blk std.math.minInt(i64);129                break :blk @intCast(v);130            },131            .u128 => std.math.maxInt(i64),132            .big => |b| if (b.len > 0 and (b[0] & 0x80) != 0) std.math.minInt(i64) else std.math.maxInt(i64),133        };134    }135136    /// Returns the number when it is zero or positive and fits in 64 unsigned bits, and137    /// `error.OutOfRange` otherwise. Code that reads a count or a size calls it for a `u64`.138    pub fn toU64(self: SignedInteger) RangeError!u64 {139        const v = try self.toU128();140        if (v > std.math.maxInt(u64)) return RangeError.OutOfRange;141        return @intCast(v);142    }143144    /// Returns whether the number is zero. Code that tests for zero calls it. Only a zero stored in145    /// 128 signed bits counts, so a zero written directly into another representation reads as146    /// nonzero.147    pub fn isZero(self: SignedInteger) bool {148        return switch (self.repr) {149            .i128 => |v| v == 0,150            .u128, .big => false,151        };152    }153154    /// Returns whether the number is below zero. Code that needs the sign calls it.155    pub fn isNegative(self: SignedInteger) bool {156        return switch (self.repr) {157            .i128 => |v| v < 0,158            .u128 => false,159            .big => |b| b.len > 0 and (b[0] & 0x80) != 0,160        };161    }162163    /// Returns whether two integers are equal. `Value.eql` calls it for two integers. Integers in164    /// different representations are never equal, so the call is exact only when both use the165    /// smallest representation that holds their number.166    pub fn eql(a: SignedInteger, b: SignedInteger) bool {167        return switch (a.repr) {168            .i128 => |av| switch (b.repr) {169                .i128 => |bv| av == bv,170                else => false,171            },172            .u128 => |av| switch (b.repr) {173                .u128 => |bv| av == bv,174                else => false,175            },176            .big => |av| switch (b.repr) {177                .big => |bv| std.mem.eql(u8, av, bv),178                else => false,179            },180        };181    }182183    /// Returns the numeric order of two integers. `Value.compare` calls it for two integers. Large184    /// numbers compare by sign, then by byte length, then byte by byte. The order across185    /// representations is exact only when both integers use the smallest representation that holds186    /// their number.187    pub fn order(a: SignedInteger, b: SignedInteger) std.math.Order {188        return switch (a.repr) {189            .i128 => |av| switch (b.repr) {190                .i128 => |bv| std.math.order(av, bv),191                .u128 => .lt,192                .big => |bv| if (bigIsNegative(bv)) .gt else .lt,193            },194            .u128 => |av| switch (b.repr) {195                .i128 => .gt,196                .u128 => |bv| std.math.order(av, bv),197                .big => |bv| if (bigIsNegative(bv)) .gt else .lt,198            },199            .big => |av| switch (b.repr) {200                .i128, .u128 => if (bigIsNegative(av)) .lt else .gt,201                .big => |bv| compareBig(av, bv),202            },203        };204    }205206    /// Returns whether `bytes` are the shortest big-endian two's-complement spelling of their207    /// number. The binary reader calls it before reading an integer, so a longer spelling is208    /// rejected. Empty bytes spell zero. A lone `0x00` byte, a leading `0x00` before a byte whose209    /// top bit is clear, and a leading `0xff` before a byte whose top bit is set are all longer210    /// than needed.211    pub fn isCanonicalBytes(bytes: []const u8) bool {212        if (bytes.len == 0) return true;213        if (bytes.len == 1) return bytes[0] != 0x00;214        const first = bytes[0];215        const second = bytes[1];216        if (first == 0x00 and (second & 0x80) == 0) return false;217        if (first == 0xff and (second & 0x80) != 0) return false;218        return true;219    }220};

1pub const SignedInteger = integer_mod.SignedInteger;