Pi Finder Library

A Zig library for searching numeric sequences in the decimal places of Pi.

Features

• Efficient searching of numeric sequences in Pi decimal places
• Automatic memory management with result.deinit()
• Custom JSON serialization using std.json.stringify
• JSON output as standard format
• Configurable context display with delimiters
• Performance metrics included in results
• Reusable module design
• Compatible with Zig 0.14.1

Installation

As a Dependency in a Zig Project

Add this library as a dependency in your build.zig.zon:

.dependencies = .{
    .@"pi-finder" = .{
        .path = "path/to/pi-finder-lib",
    },
},

In your build.zig

const pi_finder_dep = b.dependency("pi-finder", .{
    .target = target,
    .optimize = optimize,
});

exe.root_module.addImport("pi-finder", pi_finder_dep.module("pi-finder"));

Usage

Basic Usage

const std = @import("std");
const PiFinder = @import("pi-finder");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Initialize Pi Finder
    var pi_finder = try PiFinder.PiFinder.init(allocator, "pi-data.txt");
    defer pi_finder.deinit();

    // Configure context
    const context_config = PiFinder.ContextConfig{
        .size = 50,
        .position = 25,
        .delimiter = "-",
        .delimiter_interval = 2,
        .prefix = "[",
        .suffix = "]",
    };

    // Search for sequence
    const result = try pi_finder.searchSequence("123456", context_config, allocator);
    defer result.deinit(); // Automatically frees allocated memory
    
    // Output as JSON using std.json.stringify
    var json_string = std.ArrayList(u8).init(allocator);
    defer json_string.deinit();
    
    try std.json.stringify(result, .{}, json_string.writer());
    std.debug.print("{s}\n", .{json_string.items});
}

Plain Text Output Example

// After getting the search result
if (result.success) {
    std.debug.print("Success: {}\n", .{result.success});
    std.debug.print("Sequence: {s}\n", .{result.sequence});
    if (result.position) |pos| {
        std.debug.print("Position: {}\n", .{pos});
    }
    if (result.context) |context| {
        std.debug.print("Context: {s}\n", .{context});
    }
} else {
    std.debug.print("Search failed: {s}\n", .{result.error_message orelse "Unknown error"});
}

Key Features

Automatic Memory Management

The library uses RAII (Resource Acquisition Is Initialization) pattern:

const result = try pi_finder.searchSequence("123456", context_config, allocator);
defer result.deinit(); // Automatically frees allocated context memory

Custom JSON Serialization

SearchResult implements custom JSON serialization that excludes internal fields:

// The allocator field is automatically excluded from JSON output
try std.json.stringify(result, .{}, writer);

Performance Metrics

Every search result includes detailed performance metrics:

{
  "performance": {
    "file_load_time_ms": 327.988,
    "search_time_ms": 10.766,
    "file_size_mb": 953.674,
    "load_speed_mbs": 2948.052
  }
}

API

PiFinder

• init(allocator, file_path) - Initializes the Pi Finder
• deinit() - Frees allocated memory
• findSequenceInPi(sequence) - Searches for a sequence
• getContext(position, config, sequence, allocator) - Generates context
• searchSequence(sequence, config, allocator) - Comprehensive search with structured result

ContextConfig

Configuration for context display:

• size - Size of the context
• position - Position of the sequence within the context
• delimiter - Delimiter character (optional)
• delimiter_interval - Interval for delimiter insertion
• prefix - Prefix for the sequence
• suffix - Suffix for the sequence

SearchResult

Structured result containing:

• success - Search success status
• sequence - Searched sequence
• position - Position in Pi (if found)
• context - Context around the position
• error_message - Error message (if any)
• performance - Performance metrics
• context_config - Used context configuration

Methods:

• deinit() - Frees any dynamically allocated memory (like context)
• jsonStringify(writer) - Custom JSON serialization (automatically used by std.json.stringify)

Examples

See the examples/ directory for complete examples:

• birth-date-finder/ - Basic example for searching birth dates
• birth-date-finder/src/plain_text_example.zig - Example using plain text output format