# 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`:

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

### In your build.zig

```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

```zig
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

```zig
// 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:

```zig
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:

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

### Performance Metrics

Every search result includes detailed performance metrics:

```json
{
  "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