Illegal Behavior & Safety Modes

const std = @import("std");

/// Performs addition with overflow detection and saturation.
/// If overflow occurs, returns the maximum u8 value instead of wrapping.
/// Uses @setRuntimeSafety(false) in the non-overflow path for performance.
fn guardedUncheckedAdd(a: u8, b: u8) u8 {
    // Check if addition would overflow using builtin overflow detection
    const sum = @addWithOverflow(a, b);
    const overflow = sum[1] == 1;
    // Saturate to max value on overflow
    if (overflow) return std.math.maxInt(u8);

    // Safe path: disable runtime safety checks for this addition
    // since we've already verified no overflow will occur
    return blk: {
        @setRuntimeSafety(false);
        break :blk a + b;
    };
}

/// Performs addition without runtime safety checks.
/// This allows the operation to wrap on overflow (undefined behavior in safe mode).
/// Demonstrates completely disabling safety for a function scope.
fn wrappingAddUnsafe(a: u8, b: u8) u8 {
    // Disable all runtime safety checks for this entire function
    @setRuntimeSafety(false);
    return a + b;
}

// Verifies that guardedUncheckedAdd correctly handles both normal addition
// and overflow saturation scenarios.
test "guarded unchecked addition saturates on overflow" {
    // Normal case: 120 + 80 = 200 (no overflow)
    try std.testing.expectEqual(@as(u8, 200), guardedUncheckedAdd(120, 80));
    // Overflow case: 240 + 30 = 270 > 255, should saturate to 255
    try std.testing.expectEqual(std.math.maxInt(u8), guardedUncheckedAdd(240, 30));
}

// Demonstrates that wrappingAddUnsafe produces the same wrapped result
// as @addWithOverflow when overflow occurs.
test "wrapping addition mirrors overflow tuple" {
    // @addWithOverflow returns [wrapped_result, overflow_bit]
    const sum = @addWithOverflow(@as(u8, 250), @as(u8, 10));
    // Verify overflow occurred (250 + 10 = 260 > 255)
    try std.testing.expect(sum[1] == 1);
    // Verify wrapped result matches unchecked addition (260 % 256 = 4)
    try std.testing.expectEqual(sum[0], wrappingAddUnsafe(250, 10));
}

const std = @import("std");
const builtin = @import("builtin");

// Extract the compile-time type of the optimization mode enum
const ModeType = @TypeOf(builtin.mode);

/// Captures both the active optimization mode and its default safety behavior
const ModeInfo = struct {
    mode: ModeType,
    safety_default: bool,
};

/// Determines whether runtime safety checks are enabled by default for a given mode.
/// Debug and ReleaseSafe modes retain safety checks; ReleaseFast and ReleaseSmall disable them.
fn defaultSafety(mode: ModeType) bool {
    return switch (mode) {
        // These modes prioritize correctness with runtime checks
        .Debug, .ReleaseSafe => true,
        // These modes prioritize performance/size by removing checks
        .ReleaseFast, .ReleaseSmall => false,
    };
}

/// Performs checked addition that detects overflow without panicking.
/// Returns both the wrapped result and an overflow flag.
fn sampleAdd(a: u8, b: u8) struct { result: u8, overflowed: bool } {
    // @addWithOverflow returns a tuple: [wrapped_result, overflow_bit]
    const pair = @addWithOverflow(a, b);
    return .{ .result = pair[0], .overflowed = pair[1] == 1 };
}

/// Performs unchecked addition by explicitly disabling runtime safety.
/// In Debug/ReleaseSafe, this avoids the panic on overflow.
/// In ReleaseFast/ReleaseSmall, the safety was already off, so this is redundant but harmless.
fn uncheckedAddStable(a: u8, b: u8) u8 {
    return blk: {
        // Temporarily disable runtime safety for this block only
        @setRuntimeSafety(false);
        // Raw addition without overflow checks; wraps silently on overflow
        break :blk a + b;
    };
}

pub fn main() void {
    // Capture the current build mode and its implied safety setting
    const info = ModeInfo{
        .mode = builtin.mode,
        .safety_default = defaultSafety(builtin.mode),
    };

    // Report which optimization mode the binary was compiled with
    std.debug.print("optimize-mode: {s}\n", .{@tagName(info.mode)});
    // Show whether runtime safety is on by default in this mode
    std.debug.print("runtime-safety-default: {}\n", .{info.safety_default});

    // Demonstrate checked addition that reports overflow without crashing
    const checked = sampleAdd(200, 80);
    std.debug.print("checked-add result={d} overflowed={}\n", .{ checked.result, checked.overflowed });

    // Demonstrate unchecked addition that wraps silently (24 = (200+80) % 256)
    const unchecked = uncheckedAddStable(200, 80);
    std.debug.print("unchecked-add result={d}\n", .{unchecked});
}

// This file demonstrates different safety modes in Zig and how to handle
// conversions with varying levels of runtime checking.

const std = @import("std");

/// Converts an ASCII digit character to its numeric value without runtime safety checks.
/// This function uses an assert to document the precondition that the input must be
/// a valid ASCII digit ('0'-'9'). The @setRuntimeSafety(false) directive disables
/// runtime integer overflow checks for the subtraction and cast operations.
/// 
/// Precondition: byte must be in the range ['0', '9']
/// Returns: The numeric value (0-9) as a u4
pub fn asciiDigitToValueUnchecked(byte: u8) u4 {
    // Assert documents the contract: caller must provide a valid ASCII digit
    std.debug.assert(byte >= '0' and byte <= '9');
    
    // Block with runtime safety disabled for performance-critical paths
    return blk: {
        // Disable runtime overflow/underflow checks for this conversion
        @setRuntimeSafety(false);
        // Safe cast because precondition guarantees result fits in u4 (0-9)
        break :blk @intCast(byte - '0');
    };
}

/// Converts an ASCII digit character to its numeric value with error handling.
/// This function validates the input at runtime and returns an error if the
/// byte is not a valid ASCII digit, making it safe to use with untrusted input.
/// 
/// Returns: The numeric value (0-9) as a u4, or error.InvalidDigit if invalid
pub fn asciiDigitToValue(byte: u8) !u4 {
    // Validate input is within valid ASCII digit range
    if (byte < '0' or byte > '9') return error.InvalidDigit;
    // Safe cast: validation ensures result is in range 0-9
    return @intCast(byte - '0');
}

// Verifies that the unchecked conversion produces correct results for all valid inputs.
// Tests all ASCII digits to ensure the assert-backed function maintains correctness
// even when runtime safety is disabled internally.
test "assert-backed conversion stays safe across modes" {
    // Iterate over all valid ASCII digit characters at compile time
    inline for ("0123456789") |ch| {
        // Verify unchecked function produces same result as direct conversion
        try std.testing.expectEqual(@as(u4, @intCast(ch - '0')), asciiDigitToValueUnchecked(ch));
    }
}

// Verifies that the error-returning conversion properly rejects invalid input.
// Ensures that error handling path works correctly and provides meaningful diagnostics.
test "error path preserves diagnosability" {
    // Verify that non-digit characters return the expected error
    try std.testing.expectError(error.InvalidDigit, asciiDigitToValue('z'));
}