风格与最佳实践

//! Resource-safe error handling patterns with defer and errdefer.

const std = @import("std");

/// Custom error set for data loading operations.
/// Keeping error sets small and explicit helps callers route failures precisely.
pub const LoaderError = error{InvalidNumber};

/// Loads floating-point samples from a UTF-8 text file.
/// Each non-empty line is parsed as an f64.
/// Caller owns the returned slice and must free it with the same allocator.
pub fn loadSamples(dir: std.fs.Dir, allocator: std.mem.Allocator, path: []const u8) ![]f64 {
    // Open the file; propagate any I/O errors to caller
    var file = try dir.openFile(path, .{});
    // Guarantee file handle is released when function exits, regardless of path taken
    defer file.close();

    // Start with an empty list; we'll grow it as we parse lines
    var list = std.ArrayListUnmanaged(f64){};
    // If any error occurs after this point, free the list's backing memory
    errdefer list.deinit(allocator);

    // Read entire file into memory; cap at 64KB for safety
    const contents = try file.readToEndAlloc(allocator, 1 << 16);
    // Free the temporary buffer once we've parsed it
    defer allocator.free(contents);

    // Split contents by newline; iterator yields one line at a time
    var lines = std.mem.splitScalar(u8, contents, '\n');
    while (lines.next()) |line| {
        // Strip leading/trailing whitespace and carriage returns
        const trimmed = std.mem.trim(u8, line, " \t\r");
        // Skip empty lines entirely
        if (trimmed.len == 0) continue;

        // Attempt to parse the line as a float; surface a domain-specific error on failure
        const value = std.fmt.parseFloat(f64, trimmed) catch return LoaderError.InvalidNumber;
        // Append successfully parsed value to the list
        try list.append(allocator, value);
    }

    // Transfer ownership of the backing array to the caller
    return list.toOwnedSlice(allocator);
}

test "loadSamples returns parsed floats" {
    // Create a temporary directory that will be cleaned up automatically
    var tmp_fs = std.testing.tmpDir(.{});
    defer tmp_fs.cleanup();

    // Write sample data to a test file
    const file_path = try tmp_fs.dir.createFile("samples.txt", .{});
    defer file_path.close();
    try file_path.writeAll("1.0\n2.5\n3.75\n");

    // Load and parse the samples; defer ensures cleanup even if assertions fail
    const samples = try loadSamples(tmp_fs.dir, std.testing.allocator, "samples.txt");
    defer std.testing.allocator.free(samples);

    // Verify we parsed exactly three values
    try std.testing.expectEqual(@as(usize, 3), samples.len);
    // Check each value is within acceptable floating-point tolerance
    try std.testing.expectApproxEqAbs(1.0, samples[0], 0.001);
    try std.testing.expectApproxEqAbs(2.5, samples[1], 0.001);
    try std.testing.expectApproxEqAbs(3.75, samples[2], 0.001);
}

test "loadSamples surfaces invalid numbers" {
    // Set up another temporary directory for error-path testing
    var tmp_fs = std.testing.tmpDir(.{});
    defer tmp_fs.cleanup();

    // Write non-numeric content to trigger parsing failure
    const file_path = try tmp_fs.dir.createFile("bad.txt", .{});
    defer file_path.close();
    try file_path.writeAll("not-a-number\n");

    // Confirm that loadSamples returns the expected domain error
    try std.testing.expectError(LoaderError.InvalidNumber, loadSamples(tmp_fs.dir, std.testing.allocator, "bad.txt"));
}

//! Maintainability checklist example with an internal invariant helper.
//!
//! This module demonstrates defensive programming practices by implementing
//! a ring buffer data structure that validates its internal state invariants
//! before and after mutating operations.

const std = @import("std");

/// A fixed-capacity circular buffer that stores i32 values.
/// The buffer wraps around when full, and uses modular arithmetic
/// to implement FIFO (First-In-First-Out) semantics.
pub const RingBuffer = struct {
    storage: []i32,
    head: usize = 0,      // Index of the first element
    count: usize = 0,     // Number of elements currently stored

    /// Errors that can occur during ring buffer operations.
    pub const Error = error{Overflow};

    /// Creates a new RingBuffer backed by the provided storage slice.
    /// The caller retains ownership of the storage memory.
    pub fn init(storage: []i32) RingBuffer {
        return .{ .storage = storage };
    }

    /// Validates internal state consistency.
    /// This is called before and after mutations to catch logic errors early.
    /// Checks that:
    /// - Empty storage implies zero head and count
    /// - Head index is within storage bounds
    /// - Count doesn't exceed storage capacity
    fn invariant(self: *const RingBuffer) void {
        if (self.storage.len == 0) {
            std.debug.assert(self.head == 0);
            std.debug.assert(self.count == 0);
            return;
        }

        std.debug.assert(self.head < self.storage.len);
        std.debug.assert(self.count <= self.storage.len);
    }

    /// Adds a value to the end of the buffer.
    /// Returns Error.Overflow if the buffer is at capacity or has no storage.
    /// Invariants are checked before and after the operation.
    pub fn push(self: *RingBuffer, value: i32) Error!void {
        self.invariant();
        if (self.storage.len == 0 or self.count == self.storage.len) return Error.Overflow;

        // Calculate the insertion position using circular indexing
        const index = (self.head + self.count) % self.storage.len;
        self.storage[index] = value;
        self.count += 1;
        self.invariant();
    }

    /// Removes and returns the oldest value from the buffer.
    /// Returns null if the buffer is empty.
    /// Advances the head pointer circularly and decrements the count.
    pub fn pop(self: *RingBuffer) ?i32 {
        self.invariant();
        if (self.count == 0) return null;

        const value = self.storage[self.head];
        // Move head forward circularly
        self.head = (self.head + 1) % self.storage.len;
        self.count -= 1;
        self.invariant();
        return value;
    }
};

// Verifies that the buffer correctly rejects pushes when at capacity.
test "ring buffer enforces capacity" {
    var storage = [_]i32{ 0, 0, 0 };
    var buffer = RingBuffer.init(&storage);

    try buffer.push(1);
    try buffer.push(2);
    try buffer.push(3);
    // Fourth push should fail because buffer capacity is 3
    try std.testing.expectError(RingBuffer.Error.Overflow, buffer.push(4));
}

// Verifies that values are retrieved in the same order they were inserted.
test "ring buffer preserves FIFO order" {
    var storage = [_]i32{ 0, 0, 0 };
    var buffer = RingBuffer.init(&storage);

    try buffer.push(10);
    try buffer.push(20);
    try buffer.push(30);

    // Values should come out in insertion order
    try std.testing.expectEqual(@as(?i32, 10), buffer.pop());
    try std.testing.expectEqual(@as(?i32, 20), buffer.pop());
    try std.testing.expectEqual(@as(?i32, 30), buffer.pop());
    // Buffer is now empty, should return null
    try std.testing.expectEqual(@as(?i32, null), buffer.pop());
}