Chneau.OpenHours 1.0.2

openhours-cs

A high-performance, zero-allocation C# (.NET 10) parser and interval-math evaluator for OpenStreetMap opening_hours specifications.

⚡ Features & Performance

• $O(1)$ Hardware-Accelerated Bitmask Table: Evaluates IsOpen in ~2.0 nanoseconds (>500 Million ops/sec) via embedded [InlineArray(158)] Bitmask158 scalar bit tests (BTQ).
• Zero-Allocation Interval Math: Zero heap allocations on query paths (IsOpen, GetTimeToOpen, GetTimeToOpenForDuration, When, NextDur, NextDate).
• Span-Based Parsing: Zero string allocations when parsing UTF-8 bytes or raw ReadOnlySpan<char>.
• Lock-Free Interning: Automatic lock-free deduplication and caching of parsed expressions.
• Overnight Shifts: Full support for shifts spanning midnight (e.g. Mo 22:00-04:00, Su 22:00-04:00).
• Overrides & Exclusions: Handles off / closed rules overriding previous rules (e.g. Mo-Su 00:00-24:00; Tu 12:00-13:00 off).
• Duration Availability: Find wait times for contiguous tasks of duration $D$ (GetTimeToOpenForDuration / When).
• Reflection-free JSON Decode: High-speed, zero-allocation DecodeJson(ReadOnlySpan<byte>) deserializing in ~31 nanoseconds.
• Source-Generated JSON: Native System.Text.Json converter and OpenHoursJsonContext for seamless serialization.

🧠 Optimizations & Engineering Architecture

The C# (.NET 10) implementation applies several state-of-the-art runtime and JIT-level optimizations:

1. Dual State Representation & [InlineArray(158)]:

   • Disjoint Interval Array (TimeWindow[]): Flat sorted array of { int Start, int End } minute intervals.
   • Contiguous Bitmask Struct: Employs .NET C# 12 [InlineArray(158)] struct Bitmask158 (158 × ulong = 10,080 bits) embedded directly inside the object payload. This enables zero heap indirection and compiles to single BTQ / bit-test instructions for IsOpen (~2.0 ns).

2. Reflection-Free JSON Fast Path:

   • DecodeJson(ReadOnlySpan<byte>) performs direct UTF-8 byte scanning, escape validation, and resolves directly to interned instances via zero-allocation span lookups in ~31 ns.

3. Zero-Allocation Stack & Span Parsing:

   • Parses expressions directly using ReadOnlySpan<char> with stackalloc OpeningRule[8] and stackalloc TimeWindow[32] buffers.
   • Character classification uses fast ASCII bitwise arithmetic ((c0 << 8) | c1 pair matching for day tokens), completely avoiding string allocations during parsing.

4. Two-Tier Lock-Free Caching Hierarchy:

   • L1 [ThreadStatic] Fast Cache: Caches the last resolved string key and OpenHours instance per thread, skipping dictionary lookups for tight loops and consecutive parses.
   • L2 Concurrent Dictionary: Uses ConcurrentDictionary<string, OpenHours> with GetAlternateLookup<ReadOnlySpan<char>>() to query span inputs without allocating string keys.

5. $O(\log N)$ Interval Binary Search:

   • Fast binary search over the windows array for duration calculations (GetTimeToOpen, When, NextDur), unrolled for small window counts.

6. [MethodImpl(MethodImplOptions.AggressiveInlining)]:

   • Applied across all hot evaluation paths to eliminate function call overhead and enable downstream JIT optimizations.

🚀 Quick Start

Installation

dotnet add package Chneau.OpenHours

Usage Example

using Chneau.OpenHours;

// 1. Parse an OSM opening_hours string
var oh = OpenHours.Parse("Mo-Fr 08:00-12:00, 13:00-17:00; Sa 08:00-12:00");

var monday10am = new DateTime(2026, 5, 18, 10, 0, 0, DateTimeKind.Utc);

// 2. Fast point-in-time check (2.0 ns/op)
bool isOpen = oh.IsOpen(monday10am); // true

// 3. Current shift end
DateTime? shiftEnd = oh.GetCurrentShiftEnd(monday10am); // 2026-05-18 12:00:00 UTC

// 4. Time to next open
var tuesdayLunch = new DateTime(2026, 5, 19, 12, 30, 0, DateTimeKind.Utc);
TimeSpan? timeToOpen = oh.GetTimeToOpen(tuesdayLunch); // 00:30:00 (opens at 13:00)

// 5. Find when a 3-hour job can be serviced
TimeSpan? waitFor3h = oh.GetTimeToOpenForDuration(tuesdayLunch, TimeSpan.FromHours(3));
DateTime? whenCanStart = oh.When(tuesdayLunch, TimeSpan.FromHours(3)); // 2026-05-19 13:00:00 UTC

// 6. Next state transitions
var (isOpenNow, durationRemaining) = oh.NextDur(monday10am);
var (_, nextTransitionDate) = oh.NextDate(monday10am); // 2026-05-18 12:00:00 UTC

📊 Benchmark Suite (.NET 10 on AMD Ryzen 9)

🛠️ Development & Quality Commands

# Run all unit tests
dotnet test

# Run tests in continuous watch mode during development
dotnet watch test

# Run full release build
dotnet build -c Release

📄 License

MIT License. Copyright (c) 2026 chneau.