Gedcom.Vector 1.3.2

Gedcom.Vector

A lightening fast, .net 8, high-performance, zero-dependency, low-allocation C# library for parsing, building, mutating, and exporting GEDCOM 5.1.1 and 7.0 genealogy files. Probably the fastest and best gedcom library out there!

Gedcom.Vector is the fastest, most efficient Gedcom library for .net available today. Anywhere. Benchmark it against it's competitors and see for yourself!

🚀 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 (Automatic 5.5.1 & 7.0 Specification Detection) ---
using var inputStream = File.OpenRead("family.ged");
var importAdapter = new GedcomImportAdapter();
GedcomParseResult result = importAdapter.Parse(inputStream);

Console.WriteLine($"Specification Version: {result.SpecVersion}"); // Gedcom551 or Gedcom70
Console.WriteLine($"Parsed {result.Persons.Count} individuals and {result.Families.Count} families.");

// --- EXPORT (Specify Target Specification) ---
var exportWriter = new GedcomExportWriter();

// Export as GEDCOM 7.0 (Mandatory UTF-8, no CONC/CONT tags)
result.SpecVersion = GedcomSpecVersion.Gedcom70;
using var outputStream7 = File.Create("output_7_0.ged");
exportWriter.Write(result, outputStream7);

// Export as GEDCOM 5.5.1
result.SpecVersion = GedcomSpecVersion.Gedcom551;
using var outputStream5 = File.Create("output_5_5_1.ged");
exportWriter.Write(result, outputStream5);

3. GEDZIP Container Support (.gdz)

Gedcom.Vector provides full native support for GEDZIP (.gdz) packages (zipped containers storing a .ged manifest along with bundled media files):

using Gedcom.Vector.Gedzip;

// 1. Parse a GEDZIP (.gdz) package
using var gdzInput = File.OpenRead("family_tree.gdz");
GedcomParseResult gdzResult = GedzipAdapter.ParseGedzip(gdzInput, importAdapter);

// 2. Export to a GEDZIP (.gdz) package
using var gdzOutput = File.Create("exported_tree.gdz");
GedzipAdapter.CreateGedzip(gdzResult, exportWriter, gdzOutput);

4. $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.