Gedcom.Vector 1.3.0

Gedcom.Vector

A lightening fast, high-performance, zero-dependency, low-allocation C# library for parsing, building, mutating, and exporting GEDCOM genealogy files.

🚀 Key Capabilities

📦 Getting Started

1. Installation

dotnet add package Gedcom.Vector

2. High-Performance Stream Import & Export

Import GEDCOM files directly into memory-optimized record structures (GedcomParseResult), or serialize records directly to streams:

using Gedcom.Vector;

// --- IMPORT ---
using var inputStream = File.OpenRead("family.ged");
var importAdapter = new GedcomImportAdapter();
GedcomParseResult result = importAdapter.Parse(inputStream);

Console.WriteLine($"Parsed {result.Persons.Count} individuals and {result.Families.Count} families.");

// --- EXPORT ---
var exportWriter = new GedcomExportWriter();

// Export directly to file stream (Interpolation-free UTF-8 byte serialization)
using var outputStream = File.Create("output.ged");
exportWriter.Write(result, outputStream);

3. $O(1)$ Relationship Navigation & Tree Mutation (GedcomTreeContext)

Navigating raw GEDCOM collections usually requires writing slow $O(N)$ LINQ queries. Wrapping the result in GedcomTreeContext indexes the tree upon instantiation, enabling $O(1)$ constant-time relationship lookups and $O(1)$ incremental updates:

// Wrap result in an indexed context
GedcomTreeContext tree = result.ToContext();

// 1. O(1) Traversal Queries (53 ns execution time)
PersonRecord? father = tree.GetPerson("@I1@");
foreach (var child in tree.ChildrenOf(father))
{
    Console.WriteLine($"Child: {child.FirstName} {child.LastName}");
}

foreach (var spouse in tree.SpousesOf(father))
{
    Console.WriteLine($"Spouse: {spouse.FirstName} {spouse.LastName}");
}

// 2. O(1) Incremental Tree Mutations (Backing collections automatically kept in sync)
tree.AddPerson(new PersonRecord("@I4@", "Alice", "Doe", PersonSex.Female, null, null, null, null));
tree.DeletePerson("@I1@"); // Father is deleted and unlinked from spouses, children, and media in O(1) time

4. Programmatic Tree Construction (GedcomBuilder)

Construct syntactically valid GEDCOM trees programmatically without manually creating collections or managing cross-references:

using Gedcom.Vector.Builder;

GedcomParseResult result = new GedcomBuilder()
    .AddPerson("@I1@", "John", "Doe", PersonSex.Male)
        .WithBirth("1 JAN 1900", "New York, USA")
        .WithDeath("1 JAN 1980", "Boston, USA")
    .AddPerson("@I2@", "Jane", "Smith", PersonSex.Female)
        .WithBirth("1 JUN 1905")
    .AddFamily("@F1@", "@I1@", "@I2@")
        .WithMarriage("1 JUN 1925", "Chicago, USA")
        .WithChild("@I3@")
    .AddPerson("@I3@", "Bobby", "Doe", PersonSex.Male)
    .Build();

⚡ Performance & Benchmarks

BenchmarkDotNet metrics evaluated on a dataset of 4,000 individuals (INDI) and 2,000 families (FAM):

1. Core Streaming Import & Export (GedcomParseResult)

2. Relationship Query Interface Benchmark (LINQ vs Fluent GedcomTreeContext)

To execute benchmarks locally:

dotnet run -c Release --project tests/Gedcom.Vector.Benchmarks -- --filter *

🛠️ Technical Reference

Character Encoding Detection

GedcomEncodingDetector automatically selects the target decoder:

Configuration Options

📂 Project Structure & Documentation

gedcom-vector/
├── src/
│   └── Gedcom.Vector/
│       ├── Builder/           # GedcomBuilder, PersonBuilder, FamilyBuilder, MediaBuilder
│       ├── Parsing/           # StreamingGedcomParser, GedcomStringPool, AnselDecoder
│       ├── GedcomImportAdapter.cs
│       ├── GedcomExportWriter.cs
│       ├── GedcomEncodingDetector.cs
│       ├── GedcomTreeContext.cs
│       └── ...
├── tests/
│   ├── Gedcom.Vector.Tests/   # Unit tests (90.4% Line Rate, 84.6% Branch Rate)
│   └── Gedcom.Vector.Benchmarks/
├── docs/
│   ├── architecture.md        # Technical Architecture Guide & Pipeline Diagrams
│   └── performance_roadmap.md # Performance Roadmap & Historical Benchmarks
├── LICENSE
└── README.md

For detailed architectural diagrams and deep-dive technical specs, see the Architecture Guide and Performance Roadmap.

📜 License & Support

Free for non-commercial use under the PolyForm Noncommercial License 1.0.0.

• Allowed: Personal projects, research, open-source software, non-profit organizations.
• Commercial Use: Requires a commercial license. Please open an issue to discuss commercial terms.