HashTableRx

A reactive hash table that mirrors the structure of an object into a dotted path key/value store you can observe and update.

• Targets: .NET Standard 2.0, .NET 8, .NET 9
• Dependencies: System.Reactive

HashTableRx lets you:

• Reflect an object (even from an unknown assembly) into a hierarchical hash table.
• Get and set values using dotted path keys like "Process.Temperature.PV.Value".
• Observe individual variables or all changes as IObservable streams.
• Toggle case sensitivity via UseUpperCase.

Installation

• NuGet: dotnet add package HashTableRx
• Or reference the HashTableRx project in your solution.

Key concepts

• Dotted variable paths: Nested members are addressed with dot separators, e.g. "A.B.C".
• Primitive-like members: primitives and string (including arrays of these) are treated as values.
• Complex members: non-primitive-like types become nested HashTableRx nodes.
• Case handling: When UseUpperCase is true, all keys are normalized to uppercase for reads/writes/observations.
• Value API: Reading works with Value<T>(path). Writing with Value(path, value) requires the variable to already exist; otherwise InvalidVariableException is thrown (to prevent silent writes).
• Indexer API: The string indexer always creates intermediate nodes as needed.

Quick start

using CP.Collections;
using System.Reactive.Linq;

// Create a reactive hash table (case sensitive keys)
var h = new HashTableRx(useUpperCase: false);

// Create a few variables using the string indexer
h["System.Online"] = true;        // bool
h["Process.Temperature.CV"] = 20f; // float

// Read variables
bool online = h.Value<bool>("System.Online") ?? false;
float temp = h.Value<float>("Process.Temperature.CV") ?? 0f;

// Observe changes to an individual variable
var sub1 = h.Observe<float>("Process.Temperature.CV")
            .Subscribe(v => Console.WriteLine($"Temp changed to {v}"));

// Update a value (variable must already exist for Value(..) write)
h.Value("Process.Temperature.CV", 25f);

// Or use the indexer to create and/or set directly (creates if missing)
h["Process.Temperature.SP"] = 30f;

// Observe all changes
var sub2 = h.ObserveAll
            .Subscribe(kv => Console.WriteLine($"{kv.key} => {kv.value}"));

// Cleanup
sub1.Dispose();
sub2.Dispose();

Case sensitivity and UseUpperCase

var h = new HashTableRx(useUpperCase: true);

// All keys are normalized to uppercase internally
h["Rig.Temp.PV"] = 10f;

Console.WriteLine(h.Value<float>("rig.temp.pv")); // 10
Console.WriteLine(h.Value<float>("RIG.TEMP.PV")); // 10

// Observations also normalize
using var sub = h.Observe<float>("rig.temp.pv").Subscribe(v => Console.WriteLine(v));
h.Value("RIG.TEMP.PV", 11f); // Emits 11

Reflecting an unknown assembly (structures)

You can reflect any object instance (e.g., created via reflection from an external assembly) into the hash table.

using System.Reflection;
using CP.Collections;

// Load an external assembly and create an instance
var asm = Assembly.LoadFrom(@"path\to\UnknownLibrary.dll");
var obj = asm.CreateInstance("Namespace.TypeName");

var h = new HashTableRx(useUpperCase: false);

// Populate the hash table from the object's public fields/properties
h.SetStructure(obj!);

// Now you can read values from reflected primitive-like fields/properties
var pv = h.Value<float>("Some.Structured.Path.PV");

// Update values in the hash table
h.Value("Some.Structured.Path.SP", 42.0f);

// Push current hash table values back to the original object
var updated = h.GetStructure();
// 'updated' is the same instance with primitive-like values written back

Notes:

• Primitive-like = primitive or string (including arrays of those). Complex members become nested nodes.
• When trimming/AOT, reflection is annotated and may require preserving members. See code attributes for details.

Indexer API vs Value API

• String indexer h["A.B.C"]:

  • Reading returns the current value (or null if missing).
  • Writing creates intermediate nodes as required and sets the value.

• Value API:

  • T? Value<T>(string path): typed read, returns default when missing.
  • bool Value<T>(string path, T value): typed write. Throws InvalidVariableException if the variable does not exist.

Example:

var h = new HashTableRx(false);

// Create then write
h["A.B.C"] = 1;
h.Value("A.B.C", 2); // ok

// Attempting to write unknown path throws
Assert.Throws<InvalidVariableException>(() => h.Value("X.Y.Z", 5));

Observing changes

• Observe<T>(path): emits typed values on change (distinct until changed).
• ObserveAll: emits (key, object?) for any change (also distinct until changed at the tuple level).

var h = new HashTableRx(false);

// Create initial variable then observe
h["A.B.C"] = 10;
using var sub = h.Observe<int>("A.B.C").Subscribe(v => Console.WriteLine($"A.B.C = {v}"));

h.Value("A.B.C", 10); // may not emit due to DistinctUntilChanged
h.Value("A.B.C", 11); // emits 11

using var subAll = h.ObserveAll.Subscribe(kv => Console.WriteLine($"{kv.key} => {kv.value}"));
h["X.Y"] = 3.14f; // emits ("X.Y", 3.14f)

Working with nested structures

var h = new HashTableRx(false);

// Writes automatically create intermediate nodes
h["Plant.Unit1.Pump.Speed"] = 1200;

// Reads follow the same structure
int? speed = h.Value<int>("Plant.Unit1.Pump.Speed");

// Switching a scalar to a branch via write
h["Plant.Unit1"] = 123;         // was scalar
h["Plant.Unit1.Pump.Speed"] = 900; // Node becomes a nested table to accommodate deeper path

Using the bool indexer for reflection

The bool indexer h[true] is a convenience to reflect the entire object graph to and from the hash table.

var h = new HashTableRx(false);

// Push an object's values into the table
h[true] = myObject;    // equivalent to h.SetStructure(myObject)

// Later, materialize current values back into the object
var updated = h[true]; // equivalent to h.GetStructure()

HashTable base members

HashTableRx derives from a reactive HashTable that is observable as a sequence of (key, value) updates.

• Add(object key, object? value): Adds a key/value (also notifies observers).
• Remove(object key): Removes a key (scheduled).
• Clear(): Clears all entries (scheduled).
• Get(object key): Returns IObservable<(string key, object value)> that reads the indexer on a scheduler.

var ht = new HashTable();

ht.Add("K", 123);
var (k, v) = ht.Get("K").Wait();  // ("K", 123)

ht.Remove("K");
ht.Clear();

Error handling

• InvalidVariableException: thrown by Value(path, value) when the variable does not exist.
• InvalidCastException: thrown by Value(path, value) when the existing variable type is incompatible with value.

try
{
    h.Value("A.B.C", "wrong-type");
}
catch (InvalidCastException ex)
{
    Console.WriteLine(ex.Message);
}

Performance notes

• Reflection for SetStructure/GetStructure is optimized using compiled expression trees and caching per Type.
• Primitive-like members read/write via fast delegates, avoiding slow PropertyInfo/FieldInfo.GetValue/SetValue loops.
• For heavy usage, prefer creating variables once (via indexer or SetStructure) and then use Value(path, value) for updates.

Tips

• If you need case-insensitive behavior, construct HashTableRx with useUpperCase: true.
• Prefer Value<T>(path) for typed reads. It returns default(T) when missing instead of throwing.
• To write to a brand new path, use the indexer (h["A.B.C"] = value) or SetStructure first. Value(path, value) enforces that the variable already exists.

License

MIT