Category.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace JSONstat.Models;

/// <summary>
/// The <c>category</c> object of a dimension: ordered ids plus per-category
/// labels, hierarchies, coordinates and units. Source: <c>../wiki/dimensions.md</c>.
/// </summary>
public sealed class Category
{
    /// <summary>
    /// Category ordering. Accepts the array form (<c>["M","F"]</c>) or the
    /// object form (<c>{"M":0,"F":1}</c>) on read and always writes the object
    /// form. <c>null</c> for constant dimensions without an index.
    /// </summary>
    [JsonPropertyName("index")]
    [JsonConverter(typeof(CategoryIndexConverter))]
    public Dictionary<string, int>? Index { get; set; }

    /// <summary>Per-category labels (falls back to the id when absent).</summary>
    [JsonPropertyName("label")]
    public Dictionary<string, string>? Label { get; set; }

    /// <summary>Hierarchical relationships (parent id -> child ids).</summary>
    [JsonPropertyName("child")]
    public Dictionary<string, string[]>? Child { get; set; }

    /// <summary>Geographic coordinates [longitude, latitude].</summary>
    [JsonPropertyName("coordinates")]
    public Dictionary<string, double[]>? Coordinates { get; set; }

    /// <summary>Units of measure for metric-role categories.</summary>
    [JsonPropertyName("unit")]
    public Dictionary<string, Unit>? Unit { get; set; }

    /// <summary>Provider-specific extension properties.</summary>
    [JsonExtensionData]
    public IDictionary<string, JsonElement>? ExtensionData { get; set; }

    private string[] _orderedIds = System.Array.Empty<string>();
    private readonly Dictionary<string, int> _idToPos = new Dictionary<string, int>();
    private bool _built;

    /// <summary>Canonicalizes the category order. Called by the owning dimension.</summary>
    internal void Build(int size)
    {
        if (_built) return;

        if (Index != null && Index.Count > 0)
        {
            _orderedIds = Index.OrderBy(kv => kv.Value).Select(kv => kv.Key).ToArray();
        }
        else if (Label != null && Label.Count > 0)
        {
            _orderedIds = Label.Keys.ToArray();
        }
        else
        {
            int n = size > 0 ? size : 1;
            _orderedIds = Enumerable.Range(0, n).Select(_ => "").ToArray();
        }

        _idToPos.Clear();
        for (int i = 0; i < _orderedIds.Length; i++) _idToPos[_orderedIds[i]] = i;
        _built = true;
    }

    private void EnsureBuilt()
    {
        if (!_built) Build(0);
    }

    private string LabelOf(string id) =>
        Label != null && Label.TryGetValue(id, out var l) ? l : id;

    private double[]? CoordinatesOf(string id) =>
        Coordinates != null && Coordinates.TryGetValue(id, out var c) ? c : null;

    private Unit? UnitOf(string id) =>
        Unit != null && Unit.TryGetValue(id, out var u) ? u : null;

    /// <summary>The category ids in order.</summary>
    [JsonIgnore]
    public IReadOnlyList<string> Ids
    {
        get { EnsureBuilt(); return _orderedIds; }
    }

    /// <summary>The category labels in order.</summary>
    [JsonIgnore]
    public IReadOnlyList<string> Labels
    {
        get { EnsureBuilt(); return _orderedIds.Select(LabelOf).ToArray(); }
    }

    /// <summary>The categories as entries.</summary>
    [JsonIgnore]
    public IReadOnlyList<CategoryEntry> Entries
    {
        get
        {
            EnsureBuilt();
            return _orderedIds
                .Select((id, i) => new CategoryEntry(id, LabelOf(id), i, CoordinatesOf(id), UnitOf(id)))
                .ToArray();
        }
    }

    /// <summary>Gets the category at the given index, or <c>null</c>.</summary>
    public CategoryEntry? Entry(int index)
    {
        EnsureBuilt();
        if (index < 0 || index >= _orderedIds.Length) return null;
        var id = _orderedIds[index];
        return new CategoryEntry(id, LabelOf(id), index, CoordinatesOf(id), UnitOf(id));
    }

    /// <summary>Gets the category with the given id, or <c>null</c>.</summary>
    public CategoryEntry? Entry(string id)
    {
        EnsureBuilt();
        if (!_idToPos.TryGetValue(id, out var i)) return null;
        return new CategoryEntry(id, LabelOf(id), i, CoordinatesOf(id), UnitOf(id));
    }

    /// <summary>Position of a category id, or <c>null</c> when unknown.</summary>
    public int? PositionOf(string id)
    {
        EnsureBuilt();
        return _idToPos.TryGetValue(id, out var i) ? (int?)i : null;
    }
}

/// <summary>
/// Reads a category <c>index</c> in either array or object form into a
/// <see cref="Dictionary{TKey, TValue}"/> of id -> position, and writes the
/// canonical object form.
/// </summary>
internal sealed class CategoryIndexConverter : JsonConverter<Dictionary<string, int>>
{
    public override Dictionary<string, int> Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        var dict = new Dictionary<string, int>();
        if (reader.TokenType == JsonTokenType.StartArray)
        {
            int pos = 0;
            while (reader.Read() && reader.TokenType != JsonTokenType.EndArray)
            {
                dict[reader.GetString()!] = pos++;
            }
        }
        else if (reader.TokenType == JsonTokenType.StartObject)
        {
            while (reader.Read())
            {
                if (reader.TokenType == JsonTokenType.EndObject) break;
                string key = reader.GetString()!;
                if (!reader.Read()) throw new JsonException("Unexpected end of category index.");
                dict[key] = reader.GetInt32();
            }
        }
        else
        {
            throw new JsonException("category index must be an array or an object.");
        }
        return dict;
    }

    public override void Write(Utf8JsonWriter writer, Dictionary<string, int> value, JsonSerializerOptions options)
    {
        writer.WriteStartObject();
        foreach (var kv in value.OrderBy(p => p.Value))
        {
            writer.WritePropertyName(kv.Key);
            writer.WriteNumberValue(kv.Value);
        }
        writer.WriteEndObject();
    }
}