Project

const std = @import("std");
const builder_mod = @import("string_builder.zig");
const StringBuilder = builder_mod.StringBuilder;

pub fn main() !void {
    // Initialize a general-purpose allocator with leak detection
    // This allocator tracks all allocations and reports leaks on deinit
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer {
        if (gpa.deinit() == .leak) std.log.err("leaked allocations detected", .{});
    }
    const allocator = gpa.allocator();

    // Create a StringBuilder with 64 bytes of initial capacity
    // Pre-allocating reduces reallocation overhead for known content size
    var builder = try StringBuilder.initCapacity(allocator, 64);
    defer builder.deinit();

    // Build report header using basic string concatenation
    try builder.append("Report\n======\n");
    try builder.append("source: dynamic builder\n\n");

    // Define structured data for report generation
    // Each item represents a category with its count
    const items = [_]struct {
        name: []const u8,
        count: usize,
    }{
        .{ .name = "widgets", .count = 7 },
        .{ .name = "gadgets", .count = 13 },
        .{ .name = "doodads", .count = 2 },
    };

    // Obtain a writer interface for formatted output
    // This allows using std.fmt.format-style print operations
    var writer = builder.writer();
    for (items, 0..) |item, index| {
        // Format each item as a numbered list entry with name and count
        try writer.print("* {d}. {s}: {d}\n", .{ index + 1, item.name, item.count });
    }

    // Capture allocation statistics before adding summary
    // Snapshot preserves metrics for analysis without affecting builder state
    const snapshot = builder.snapshot();
    try writer.print("\nsummary: appended {d} entries\n", .{items.len});

    // Transfer ownership of the constructed string to caller
    // After this call, builder is reset and cannot be reused without re-initialization
    const result = try builder.toOwnedSlice();
    defer allocator.free(result);

    // Display the generated report alongside allocation statistics
    std.debug.print("{s}\n---\n{any}\n", .{ result, snapshot });
}

const std = @import("std");
const builder_mod = @import("string_builder.zig");
const StringBuilder = builder_mod.StringBuilder;
const Stats = builder_mod.Stats;

/// Container for a generated report and its allocation statistics
const Report = struct {
    text: []u8,
    stats: Stats,
};

/// Builds a text report with random sample data
/// Demonstrates StringBuilder usage with various allocator strategies
fn buildReport(allocator: std.mem.Allocator, label: []const u8, sample_count: usize) !Report {
    // Initialize StringBuilder with the provided allocator
    var builder = StringBuilder.init(allocator);
    defer builder.deinit();

    // Write report header
    try builder.append("label: ");
    try builder.append(label);
    try builder.append("\n");

    // Initialize PRNG with a seed that varies based on sample_count
    // Ensures reproducible but different sequences for different report sizes
    var prng = std.Random.DefaultPrng.init(0x5eed1234 ^ @as(u64, sample_count));
    var random = prng.random();

    // Generate random sample data and accumulate totals
    var total: usize = 0;
    var writer = builder.writer();
    for (0..sample_count) |i| {
        // Each sample represents a random KiB allocation between 8-64
        const chunk = random.intRangeAtMost(u32, 8, 64);
        total += chunk;
        try writer.print("{d}: +{d} KiB\n", .{ i, chunk });
    }

    // Write summary line with aggregated statistics
    try writer.print("total: {d} KiB across {d} samples\n", .{ total, sample_count });

    // Capture allocation statistics before transferring ownership
    const stats = builder.snapshot();
    
    // Transfer ownership of the built string to the caller
    const text = try builder.toOwnedSlice();
    return .{ .text = text, .stats = stats };
}

pub fn main() !void {
    // Arena allocator will reclaim all allocations at once when deinit() is called
    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
    defer arena.deinit();

    // Small report: 256-byte stack buffer should be sufficient
    // stackFallback tries stack first, falls back to arena if needed
    var fallback_small = std.heap.stackFallback(256, arena.allocator());
    const small_allocator = fallback_small.get();
    const small = try buildReport(small_allocator, "stack-only", 6);
    defer small_allocator.free(small.text);

    // Large report: 256-byte stack buffer will overflow, forcing arena allocation
    // Demonstrates fallback behavior when stack space is insufficient
    var fallback_large = std.heap.stackFallback(256, arena.allocator());
    const large_allocator = fallback_large.get();
    const large = try buildReport(large_allocator, "needs-arena", 48);
    defer large_allocator.free(large.text);

    // Display both reports with their allocation statistics
    // Stats will reveal which allocator strategy was used (stack vs heap)
    std.debug.print("small buffer ->\n{s}stats: {any}\n\n", .{ small.text, small.stats });
    std.debug.print("large buffer ->\n{s}stats: {any}\n", .{ large.text, large.stats });
}

const std = @import("std");
const builder_mod = @import("string_builder.zig");
const StringBuilder = builder_mod.StringBuilder;
const Stats = builder_mod.Stats;

/// Container for built string and its allocation statistics
const Result = struct {
    text: []u8,
    stats: Stats,
};

/// Calculates the total byte length of all string segments
/// Used to pre-compute capacity requirements for efficient allocation
fn totalLength(parts: []const []const u8) usize {
    var sum: usize = 0;
    for (parts) |segment| sum += segment.len;
    return sum;
}

/// Builds a formatted string without pre-allocating capacity
/// Demonstrates the cost of incremental growth through multiple reallocations
/// Separators are spaces, with newlines every 8th segment
fn buildNaive(allocator: std.mem.Allocator, parts: []const []const u8) !Result {
    // Initialize with default capacity (0 bytes)
    // Builder will grow dynamically as content is appended
    var builder = StringBuilder.init(allocator);
    defer builder.deinit();

    for (parts, 0..) |segment, index| {
        // Each append may trigger reallocation if capacity is insufficient
        try builder.append(segment);
        if (index + 1 < parts.len) {
            // Insert newline every 8 segments, space otherwise
            const sep = if ((index + 1) % 8 == 0) "\n" else " ";
            try builder.append(sep);
        }
    }

    // Capture allocation statistics showing multiple growth operations
    const stats = builder.snapshot();
    const text = try builder.toOwnedSlice();
    return .{ .text = text, .stats = stats };
}

/// Builds a formatted string with pre-calculated capacity
/// Demonstrates performance optimization by eliminating reallocations
/// Produces identical output to buildNaive but with fewer allocations
fn buildPlanned(allocator: std.mem.Allocator, parts: []const []const u8) !Result {
    var builder = StringBuilder.init(allocator);
    defer builder.deinit();

    // Calculate exact space needed: all segments plus separator count
    // Separators: n-1 for n parts (no separator after last segment)
    const separators = if (parts.len == 0) 0 else parts.len - 1;
    // Pre-allocate all required capacity in a single allocation
    try builder.ensureUnusedCapacity(totalLength(parts) + separators);

    for (parts, 0..) |segment, index| {
        // Append operations never reallocate due to pre-allocation
        try builder.append(segment);
        if (index + 1 < parts.len) {
            // Insert newline every 8 segments, space otherwise
            const sep = if ((index + 1) % 8 == 0) "\n" else " ";
            try builder.append(sep);
        }
    }

    // Capture statistics showing single allocation with no growth
    const stats = builder.snapshot();
    const text = try builder.toOwnedSlice();
    return .{ .text = text, .stats = stats };
}

pub fn main() !void {
    // Initialize leak-detecting allocator to verify proper cleanup
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer {
        if (gpa.deinit() == .leak) std.log.err("leaked allocations detected", .{});
    }
    const allocator = gpa.allocator();

    // Sample data: 32 Greek letters and astronomy terms
    // Large enough to demonstrate multiple reallocations in naive approach
    const segments = [_][]const u8{
        "alpha",
        "beta",
        "gamma",
        "delta",
        "epsilon",
        "zeta",
        "eta",
        "theta",
        "iota",
        "kappa",
        "lambda",
        "mu",
        "nu",
        "xi",
        "omicron",
        "pi",
        "rho",
        "sigma",
        "tau",
        "upsilon",
        "phi",
        "chi",
        "psi",
        "omega",
        "aurora",
        "borealis",
        "cosmos",
        "nebula",
        "quasar",
        "pulsar",
        "singularity",
        "zenith",
    };

    // Build string without capacity planning
    // Stats will show multiple allocations and growth operations
    const naive = try buildNaive(allocator, &segments);
    defer allocator.free(naive.text);

    // Build string with exact capacity pre-allocation
    // Stats will show single allocation with no growth
    const planned = try buildPlanned(allocator, &segments);
    defer allocator.free(planned.text);

    // Compare allocation statistics side-by-side
    // Demonstrates the efficiency gain from capacity planning
    std.debug.print(
        "naive -> {any}\n{s}\n\nplanned -> {any}\n{s}\n",
        .{ naive.stats, naive.text, planned.stats, planned.text },
    );
}