feat: add PolylineFormatter, FormatterBuilder, PolylineOptions and FormatterRule

Agent-Logs-Url: https://github.com/petesramek/polyline-algorithm-csharp/sessions/16db7628-2cc2-4c51-982b-0264a04d7157

Co-authored-by: petesramek <2333452+petesramek@users.noreply.github.com>

Author: Copilot

src/PolylineAlgorithm/FormatterBuilder.cs

@@ -0,0 +1,119 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm;
+
+using PolylineAlgorithm.Internal;
+using System;
+using System.Collections.Generic;
+
+/// <summary>
+/// Provides a fluent builder for constructing a <see cref="PolylineFormatter{T}"/>.
+/// </summary>
+/// <typeparam name="T">The source object type from which column values are extracted.</typeparam>
+/// <remarks>
+/// <para>
+/// Use <see cref="Create"/> to obtain an instance, call <see cref="AddValue"/> once per column,
+/// optionally chain <see cref="SetBaseline"/> to specify an epoch for the most-recently added column,
+/// then call <see cref="Build"/> to produce the immutable <see cref="PolylineFormatter{T}"/>.
+/// </para>
+/// <para>
+/// The builder is the <em>only</em> way to create a <see cref="PolylineFormatter{T}"/> — its
+/// constructor is internal.
+/// </para>
+/// </remarks>
+public sealed class FormatterBuilder<T> {
+    private readonly List<FormatterRule<T>> _rules = [];
+    private readonly HashSet<string> _names = new(StringComparer.Ordinal);
+
+    private FormatterBuilder() { }
+
+    /// <summary>
+    /// Creates a new <see cref="FormatterBuilder{T}"/> instance.
+    /// </summary>
+    /// <returns>A fresh <see cref="FormatterBuilder{T}"/> with no rules.</returns>
+    public static FormatterBuilder<T> Create() => new();
+
+    /// <summary>
+    /// Adds a column with the specified value selector and precision.
+    /// </summary>
+    /// <param name="name">
+    /// A unique, non-null, non-empty name that identifies the column. Used for diagnostics only.
+    /// </param>
+    /// <param name="selector">
+    /// A delegate that extracts the column's raw <see cref="double"/> value from an item of type
+    /// <typeparamref name="T"/>.
+    /// </param>
+    /// <param name="precision">
+    /// The number of decimal places to preserve. Each extracted value is multiplied by
+    /// 10^<paramref name="precision"/> before encoding. Defaults to 5.
+    /// </param>
+    /// <returns>The current <see cref="FormatterBuilder{T}"/> instance for method chaining.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="name"/> or <paramref name="selector"/> is <see langword="null"/>.
+    /// </exception>
+    /// <exception cref="ArgumentException">
+    /// Thrown when <paramref name="name"/> is empty, or a rule with the same name already exists.
+    /// </exception>
+    public FormatterBuilder<T> AddValue(string name, Func<T, double> selector, uint precision = 5) {
+        if (name is null) {
+            throw new ArgumentNullException(nameof(name));
+        }
+
+        if (name.Length == 0) {
+            throw new ArgumentException("Name cannot be empty.", nameof(name));
+        }
+
+        if (selector is null) {
+            throw new ArgumentNullException(nameof(selector));
+        }
+
+        if (!_names.Add(name)) {
+            throw new ArgumentException($"A rule with the name '{name}' has already been added.", nameof(name));
+        }
+
+        _rules.Add(new FormatterRule<T>(name, (long)Pow10.GetFactor(precision), selector));
+
+        return this;
+    }
+
+    /// <summary>
+    /// Sets a baseline (epoch) on the most-recently added column.
+    /// During encoding the baseline is subtracted from the first item's scaled column value,
+    /// keeping the initial delta small when the absolute first value is large.
+    /// </summary>
+    /// <param name="baseline">The baseline value to apply to the first item's column value.</param>
+    /// <returns>The current <see cref="FormatterBuilder{T}"/> instance for method chaining.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when no rules have been added yet. Call <see cref="AddValue"/> before <see cref="SetBaseline"/>.
+    /// </exception>
+    public FormatterBuilder<T> SetBaseline(long baseline) {
+        if (_rules.Count == 0) {
+            throw new InvalidOperationException("Cannot set a baseline when no rules have been added. Call AddValue first.");
+        }
+
+        var last = _rules[^1];
+        _rules[^1] = new FormatterRule<T>(last.Name, last.Factor, last.Select, baseline);
+
+        return this;
+    }
+
+    /// <summary>
+    /// Bakes all added rules into a sealed, immutable <see cref="PolylineFormatter{T}"/>.
+    /// </summary>
+    /// <returns>
+    /// An immutable <see cref="PolylineFormatter{T}"/> whose rules can no longer be changed.
+    /// </returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when no rules have been added.
+    /// </exception>
+    public PolylineFormatter<T> Build() {
+        if (_rules.Count == 0) {
+            throw new InvalidOperationException("At least one rule must be added before calling Build.");
+        }
+
+        return new PolylineFormatter<T>(_rules.ToArray());
+    }
+}

src/PolylineAlgorithm/Internal/FormatterRule.cs

@@ -0,0 +1,53 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm.Internal;
+
+using System;
+
+/// <summary>
+/// Represents a single column rule baked into a <see cref="PolylineFormatter{T}"/>.
+/// Stores the pre-calculated factor and an optional baseline alongside the user-supplied value selector.
+/// </summary>
+/// <typeparam name="T">The source object type from which the column value is extracted.</typeparam>
+internal sealed class FormatterRule<T> {
+    /// <summary>
+    /// Initializes a new instance of <see cref="FormatterRule{T}"/>.
+    /// </summary>
+    /// <param name="name">The column name used for diagnostics.</param>
+    /// <param name="factor">The pre-calculated scaling factor (10^precision).</param>
+    /// <param name="select">The delegate that extracts the raw value from an item.</param>
+    /// <param name="baseline">The optional baseline value applied to the first item only.</param>
+    internal FormatterRule(string name, long factor, Func<T, double> select, long? baseline = null) {
+        Name = name;
+        Factor = factor;
+        Select = select;
+        Baseline = baseline;
+    }
+
+    /// <summary>
+    /// Gets the column name. Used for diagnostics and duplicate-name detection only.
+    /// </summary>
+    internal string Name { get; }
+
+    /// <summary>
+    /// Gets the pre-calculated scaling factor (10^precision).
+    /// Stored as <see cref="long"/> so that <c>(long)(value * Factor)</c> stays in 64-bit arithmetic
+    /// throughout the encoding hot loop without additional casting.
+    /// </summary>
+    internal long Factor { get; }
+
+    /// <summary>
+    /// Gets the optional baseline (epoch). When set, the encoder subtracts this value from the
+    /// first point's scaled column value to keep the initial delta small.
+    /// </summary>
+    internal long? Baseline { get; }
+
+    /// <summary>
+    /// Gets the delegate that extracts the column's raw <see cref="double"/> value from an item of type
+    /// <typeparamref name="T"/>. Stored as a concrete delegate so the JIT can inline the call site.
+    /// </summary>
+    internal Func<T, double> Select { get; }
+}

src/PolylineAlgorithm/PolylineFormatter.cs

@@ -0,0 +1,80 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm;
+
+using PolylineAlgorithm.Internal;
+using System;
+using System.Runtime.CompilerServices;
+
+/// <summary>
+/// Provides an immutable, sealed rule engine that describes how to extract and scale values from
+/// an object of type <typeparamref name="T"/> for polyline encoding.
+/// </summary>
+/// <typeparam name="T">The source object type from which column values are extracted.</typeparam>
+/// <remarks>
+/// <para>
+/// Instances of this class are constructed exclusively through <see cref="FormatterBuilder{T}"/>.
+/// </para>
+/// <para>
+/// The <see langword="sealed"/> modifier allows the JIT to devirtualise and inline calls to
+/// <see cref="GetValues"/>, eliminating vtable dispatch in the encoding hot loop.
+/// </para>
+/// </remarks>
+public sealed class PolylineFormatter<T> {
+    private readonly FormatterRule<T>[] _rules;
+
+    /// <summary>
+    /// Initializes a new instance of <see cref="PolylineFormatter{T}"/> with the baked rules.
+    /// This constructor is intentionally internal; use <see cref="FormatterBuilder{T}"/> to create instances.
+    /// </summary>
+    /// <param name="rules">The pre-calculated rules array produced by the builder.</param>
+    internal PolylineFormatter(FormatterRule<T>[] rules) {
+        _rules = rules;
+        Width = rules.Length;
+        HasBaselines = Array.Exists(rules, static r => r.Baseline.HasValue);
+    }
+
+    /// <summary>
+    /// Gets the number of columns (values per item).
+    /// This is the required length of the <see cref="Span{T}"/> passed to <see cref="GetValues"/>.
+    /// </summary>
+    public int Width { get; }
+
+    /// <summary>
+    /// Gets a value indicating whether any column has a baseline defined.
+    /// When <see langword="false"/> the encoder can skip the baseline-subtraction branch entirely,
+    /// keeping the common-case encoding path branch-free.
+    /// </summary>
+    public bool HasBaselines { get; }
+
+    /// <summary>
+    /// Extracts and scales all column values from <paramref name="item"/> into the <paramref name="values"/> span.
+    /// Called once per item in the encoding hot loop. This method performs no heap allocation;
+    /// the caller is responsible for providing and owning the output buffer.
+    /// </summary>
+    /// <param name="item">The source item from which column values are extracted.</param>
+    /// <param name="values">
+    /// Output buffer that receives the scaled values.
+    /// Its length must equal <see cref="Width"/>.
+    /// </param>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void GetValues(T item, Span<long> values) {
+        var rules = _rules; // local copy avoids repeated bounds check on the field
+        for (var i = 0; i < rules.Length; i++) {
+            ref var rule = ref rules[i];
+            values[i] = (long)(rule.Select(item) * rule.Factor);
+        }
+    }
+
+    /// <summary>
+    /// Returns the baseline for the column at <paramref name="index"/>, or <c>0</c> if none is configured.
+    /// The encoder subtracts this value from the first item's scaled column value during encoding.
+    /// </summary>
+    /// <param name="index">The zero-based column index. Must be in the range <c>[0, Width)</c>.</param>
+    /// <returns>The baseline value, or <c>0</c> when no baseline has been defined for the column.</returns>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public long GetBaseline(int index) => _rules[index].Baseline ?? 0L;
+}

src/PolylineAlgorithm/PolylineOptions.cs

@@ -0,0 +1,50 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm;
+
+using System;
+
+/// <summary>
+/// Provides configuration for a <see cref="PolylineFormatter{T}"/>-driven encoding operation.
+/// </summary>
+/// <typeparam name="T">The source object type from which column values are extracted.</typeparam>
+/// <remarks>
+/// Combines a <see cref="PolylineFormatter{T}"/> (which defines the column schema and scaling rules)
+/// with a <see cref="PolylineEncodingOptions"/> (which controls buffer sizes, precision, and logging).
+/// </remarks>
+public sealed class PolylineOptions<T> {
+    /// <summary>
+    /// Initializes a new instance of <see cref="PolylineOptions{T}"/>.
+    /// </summary>
+    /// <param name="formatter">
+    /// The sealed formatter that defines the column schema. Must not be <see langword="null"/>.
+    /// </param>
+    /// <param name="encoding">
+    /// The encoding options that control buffer sizes, precision, and logging.
+    /// Pass <see langword="null"/> to use default options.
+    /// </param>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="formatter"/> is <see langword="null"/>.
+    /// </exception>
+    public PolylineOptions(PolylineFormatter<T> formatter, PolylineEncodingOptions? encoding = null) {
+        if (formatter is null) {
+            throw new ArgumentNullException(nameof(formatter));
+        }
+
+        Formatter = formatter;
+        Encoding = encoding ?? new PolylineEncodingOptions();
+    }
+
+    /// <summary>
+    /// Gets the sealed formatter that defines the column schema and scaling rules.
+    /// </summary>
+    public PolylineFormatter<T> Formatter { get; }
+
+    /// <summary>
+    /// Gets the encoding options that control buffer sizes, precision, and logging.
+    /// </summary>
+    public PolylineEncodingOptions Encoding { get; }
+}

src/PolylineAlgorithm/PublicAPI.Unshipped.txt

@@ -1 +1,15 @@
 #nullable enable
+PolylineAlgorithm.FormatterBuilder<T>
+PolylineAlgorithm.FormatterBuilder<T>.AddValue(string! name, System.Func<T, double>! selector, uint precision = 5) -> PolylineAlgorithm.FormatterBuilder<T>!
+PolylineAlgorithm.FormatterBuilder<T>.Build() -> PolylineAlgorithm.PolylineFormatter<T>!
+PolylineAlgorithm.FormatterBuilder<T>.SetBaseline(long baseline) -> PolylineAlgorithm.FormatterBuilder<T>!
+PolylineAlgorithm.PolylineFormatter<T>
+PolylineAlgorithm.PolylineFormatter<T>.GetBaseline(int index) -> long
+PolylineAlgorithm.PolylineFormatter<T>.GetValues(T item, System.Span<long> values) -> void
+PolylineAlgorithm.PolylineFormatter<T>.HasBaselines.get -> bool
+PolylineAlgorithm.PolylineFormatter<T>.Width.get -> int
+PolylineAlgorithm.PolylineOptions<T>
+PolylineAlgorithm.PolylineOptions<T>.Encoding.get -> PolylineAlgorithm.PolylineEncodingOptions!
+PolylineAlgorithm.PolylineOptions<T>.Formatter.get -> PolylineAlgorithm.PolylineFormatter<T>!
+PolylineAlgorithm.PolylineOptions<T>.PolylineOptions(PolylineAlgorithm.PolylineFormatter<T>! formatter, PolylineAlgorithm.PolylineEncodingOptions? encoding = null) -> void
+static PolylineAlgorithm.FormatterBuilder<T>.Create() -> PolylineAlgorithm.FormatterBuilder<T>!