init

docs/ai/Common/DTS.Common.Utilities.md

@@ -0,0 +1,258 @@
+---
+source_files:
+  - Common/DTS.Common.Utilities/DTS.Utilities.cs
+  - Common/DTS.Common.Utilities/DegreesFromADC.cs
+  - Common/DTS.Common.Utilities/TaskbarHelper.cs
+  - Common/DTS.Common.Utilities/LevelTriggerLogging.cs
+  - Common/DTS.Common.Utilities/SignalToNoiseRatio.cs
+  - Common/DTS.Common.Utilities/StandardDev.cs
+  - Common/DTS.Common.Utilities/LargeArray.NameGeneratorLock.cs
+  - Common/DTS.Common.Utilities/XmlToObject.cs
+  - Common/DTS.Common.Utilities/FirmwareVersionToLong.cs
+  - Common/DTS.Common.Utilities/NaturalStringCompare.cs
+  - Common/DTS.Common.Utilities/KeywordAlert.cs
+  - Common/DTS.Common.Utilities/DataFlag.cs
+  - Common/DTS.Common.Utilities/Time.cs
+  - Common/DTS.Common.Utilities/PropertyComparer.cs
+  - Common/DTS.Common.Utilities/Math.DoubleListOperation.cs
+  - Common/DTS.Common.Utilities/UpdateNotifyingList.cs
+  - Common/DTS.Common.Utilities/DataWindowAverager.WindowDoesNotExistException.cs
+  - Common/DTS.Common.Utilities/Property.ConstructionException.cs
+  - Common/DTS.Common.Utilities/Property.InvalidValueException.cs
+  - Common/DTS.Common.Utilities/Property.NotInitializedException.cs
+  - Common/DTS.Common.Utilities/RangeRestrictedIntProperty.InvalidRangeException.cs
+  - Common/DTS.Common.Utilities/TextLogger.LogPathnameNotInitializedException.cs
+  - Common/DTS.Common.Utilities/RangeRestrictedDoubleProperty.InvalidRangeException.cs
+  - Common/DTS.Common.Utilities/LargeArray.MissingScratchFileException.cs
+  - Common/DTS.Common.Utilities/LargeArray.LargeOverflowException.cs
+  - Common/DTS.Common.Utilities/DescriptionAttributeCoder.cs
+  - Common/DTS.Common.Utilities/LargeArray.ScratchFileAlreadyExistsException.cs
+  - Common/DTS.Common.Utilities/CRC32.cs
+  - Common/DTS.Common.Utilities/AverageQueue.cs
+  - Common/DTS.Common.Utilities/ExceptionalForm.cs
+  - Common/DTS.Common.Utilities/SortableBindingList.cs
+  - Common/DTS.Common.Utilities/ExceptionalUserControl.cs
+  - Common/DTS.Common.Utilities/EnumDropDown.cs
+  - Common/DTS.Common.Utilities/XmlSerializationTagAttribute.cs
+  - Common/DTS.Common.Utilities/ExceptionalList.cs
+  - Common/DTS.Common.Utilities/Win32APIs.cs
+generated_at: "2026-04-17T15:26:26.405103+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "e717fe5c54d045c4"
+---
+
+# DTS.Common.Utilities Documentation
+
+## 1. Purpose
+
+This module is a general-purpose utility library providing common functionality for DTS applications. It offers mathematical operations (signal processing, statistics), Windows API interop, data structures with notification capabilities, XML serialization helpers, time conversions, memory-mapped file support, and a pattern for creating types with dedicated exception classes. The library serves as a foundational layer reused across multiple DTS projects.
+
+---
+
+## 2. Public Interface
+
+### Mathematical Utilities
+
+**`DTS.Common.Utilities.DegreesFromADC`** (static class)
+- `public static double GetDegrees(double Sxyz, double SG)` — Converts ADC values to degrees using the formula `(180/π) * Asin(Sxyz/SG)`.
+
+**`DTS.Utilities.StandardDev`** (static class)
+- `public static double StandardDeviation(IEnumerable<double> values)` — Calculates sample standard deviation using Bessel's correction (n-1 divisor). Returns 0 for empty collections.
+
+**`DTS.Utilities.SignalToNoiseRatio`** (static class)
+- `public static double CalculateSNR(IEnumerable<double> values, double fullScalePP = 65536.0)` — Calculates signal-to-noise ratio in dB given a dataset and full-scale peak-to-peak value. Uses `-20 * Log10(3 * stdDev / fullScalePP)`.
+
+**`DTS.Common.Utilities.Math.DoubleListOperation`** (abstract class)
+- `public DoubleListOperation(IList<double> domain)` — Base constructor accepting a domain of doubles.
+- Inherits from `Operation<IList<double>, IList<double>>`.
+
+**`DTS.Common.Utilities.AverageQueue`**
+- `public AverageQueue(int length)` — Constructs a fixed-length queue for running averages.
+- `public double Push(double newValue)` — Adds a value, returns current average.
+- `public double GetAverage()` — Returns current average.
+- `public void Reset()` — Clears the queue.
+- `public double GetMin()` — Returns minimum value in queue.
+- `public double GetMax()` — Returns maximum value in queue.
+
+**`DTS.Utilities.Crc32`**
+- `public Crc32()` — Constructs the CRC32 lookup table.
+- `public uint Get<T>(IEnumerable<T> byteStream)` — Calculates 32-bit reversed CRC checksum.
+
+### Time Utilities
+
+**`DTS.Common.Utilities.Time`** (static class)
+- `public static UInt32 DateTimeToUnixTimestamp(DateTime dateTime)` — Converts DateTime to Unix timestamp (seconds since 1970-01-01).
+- `public static UInt32 CurrentUtcUnixTimestamp()` — Returns current UTC time as Unix timestamp.
+- `public static UInt32 CurrentLocalUnixTimestamp()` — Returns current local time as Unix timestamp.
+- `public static DateTime ToDateTime(UInt32 seconds)` — Converts Unix timestamp to DateTime.
+- `public static UInt32 ToUnixTime(DateTime dateTime)` — Alias for `DateTimeToUnixTimestamp`.
+- `public static bool IsBeginningOfTime(DateTime dateTime)` — Returns true if DateTime equals Unix epoch.
+
+### String/Version Utilities
+
+**`DTS.Common.Utilities.NaturalStringComparer`** (implements `IComparer<string>`)
+- `public int Compare(string x, string y)` — Natural string comparison using Windows `StrCmpLogicalW`. Returns -1 if x is null, 1 if y is null.
+- `public static int StaticCompare(string x, string y)` — Static version of Compare.
+
+**`DTS.Common.Utilities.FirmwareVersionToLong`** (static class)
+- `public static long Query(string version)` — Converts up to 4 characters of a firmware version string to a long by bit-shifting each character (shifts of 48, 32, 16, 0 bits).
+
+### XML Utilities
+
+**`DTS.Common.Utilities.Xml.XmlToObject<T>`** (static class)
+- `public static T FromXml(string xml)` — Deserializes XML string to type T. Returns `default(T)` on failure.
+
+**`DTS.Common.Utilities.Xml.XmlSerializationTagAttribute`** (Attribute)
+- `public XmlSerializationTagAttribute(string value)` — Creates attribute with value and order 0.
+- `public XmlSerializationTagAttribute(string value, int order)` — Creates attribute with value and specified order.
+- `public string Value { get; }` — Tag value.
+- `public int Order { get; }` — Sort order.
+- `public int CompareTo(XmlSerializationTagAttribute that)` — Compares by Order.
+
+### Windows Interop
+
+**`DTS.Utilities.TaskbarHelper`** (static class)
+- `public static extern int SetCurrentProcessExplicitAppUserModelID([MarshalAs(UnmanagedType.LPWStr)] string AppID)` — P/Invoke to shell32.dll for setting Windows taskbar AppUserModelID.
+
+### Logging
+
+**`DTS.Common.Utilities.LTLogging.LevelTriggerLogging`**
+- `public static void LevelTriggerLog(string msg)` — Thread-safe append to `Logs\LevelTriggerSettings.txt`.
+
+### Data Structures
+
+**`DTS.Common.Utilities.SortableBindingList<T>`** (extends `BindingList<T>`)
+- `public SortableBindingList()` — Default constructor.
+- `public SortableBindingList(IEnumerable<T> enumeration)` — Constructs from enumeration.
+- Supports sorting via `ApplySortCore`, `RemoveSortCore`.
+- Supports searching via `FindCore(PropertyDescriptor property, object key)`.
+
+**`DTS.Common.Utilities.PropertyComparer<T>`** (implements `IComparer<T>`)
+- `public PropertyComparer(PropertyDescriptor property, ListSortDirection direction)` — Constructs comparer for specified property.
+- `public int Compare(T x, T y)` — Compares by property value.
+- `public void SetPropertyAndDirection(PropertyDescriptor descriptor, ListSortDirection direction)` — Updates property and sort direction.
+
+**`DTS.Common.Utilities.UpdateNotifyingList<T>`** (extends `Exceptional`)
+- `public List<T> Items { get; set; }` — Gets/sets items; setter fires `OnUpdate` event.
+- `public delegate void OnUpdateCallback(List<T> updatedContents)` — Callback delegate type.
+- `public event OnUpdateCallback OnUpdate` — Event fired when Items is set.
+
+**`DTS.Common.Utilities.ExceptionalList<T>`** (extends `List<T>`)
+- `public ExceptionalList()`, `public ExceptionalList(int capacity)`, `public ExceptionalList(IEnumerable<T> collection)` — Constructors.
+- Contains nested `Exception` class (extends `ApplicationException`).
+
+### UI Components
+
+**`DTS.Common.Utilities.EnumDropDown<T>`** (extends `ComboBox`) where `T : struct, IComparable`
+- `public EnumDropDown(Filter defaultFilter)` — Constructs with filter delegate.
+- `public Filter EnumFilter { set; }` — Sets filter and repopulates list.
+- `public void PopulateList()` — Populates combo with enum values.
+- `public EnumListEntry SelectedEntry { get; set; }` — Gets/sets selected entry.
+- `public T? SelectedEnum { get; set; }` — Gets/sets selected enum value.
+- Nested class `EnumListEntry` with `Value` property and `IComparable<EnumListEntry>` implementation.
+
+**`DTS.Common.Utilities.ExceptionalForm`** (extends `Form`)
+- Contains nested `Exception` class (extends `ApplicationException`).
+
+**`DTS.Common.Utilities.ExceptionalUserControl`** (extends `UserControl`)
+- Contains nested `Exception` class (extends `ApplicationException`).
+
+### Enums and Attributes
+
+**`DTS.Common.Utilities.DataFlag`** (enum)
+- Values: `None(0)`, `Normal(1)`, `Saturated(2)`, `ZeroCrossing(3)`, `BrokenWire(4)`, `Other(-1)`.
+- Each value has `[Description]` and `[Flag]` attributes.
+
+**`DTS.Common.Utilities.FlagAttribute`** (Attribute)
+- `public FlagAttribute(int flag)` — Constructor.
+- `public int Flag { get; }` — Flag value.
+
+**`DTS.Common.Utilities.DataFlagAttributeCoder`** (extends `AttributeCoder<DataFlag, FlagAttribute, int>`)
+- `public DataFlagAttributeCoder()` — Default constructor.
+
+**`DTS.Common.Utilities.DescriptionAttributeCoder<TTargetType>`** (extends `AttributeCoder<TTargetType, DescriptionAttribute, string>`)
+- `public DescriptionAttributeCoder()` — Default constructor.
+
+### Memory-Mapped File Support
+
+**`DTS.Common.Utilities.IO.MemoryMap.Win32MapApis`** (internal static class)
+- P/Invoke declarations for: `CreateFile`, `CreateFileMapping`, `FlushViewOfFile`, `MapViewOfFile`, `OpenFileMapping`, `UnmapViewOfFile`, `CloseHandle`, `GetLastError`.
+
+**`DTS.Common.Utilities.IO.MemoryMap.LargeArray<T>`** (partial class)
+- `protected class NameGeneratorLock` — Locking object for scratch file name generation.
+- Private nested exceptions: `MissingScratchFileException`, `LargeOverflowException`, `ScratchFileAlreadyExistsException`.
+
+### Monitoring
+
+**`DTS.Common.Utilities.KeywordAlert`** (sealed singleton)
+- `public static KeywordAlert Instance { get; }` — Singleton instance.
+- `public void ProcessMsg(string msg)` — Queues message for async keyword matching against `Keywords.txt`.
+
+### Exception Classes (Nested)
+
+- `Property<Type>.ConstructionException`
+- `Property<Type>.InvalidValueException`
+- `Property<Type>.NotInitializedException`
+- `RangeRestrictedIntProperty.InvalidRangeException`
+- `RangeRestrictedDoubleProperty.InvalidRangeException`
+- `DataWindowAverager.WindowDoesNotExistException`
+- `TextLogger.LogPathnameNotInitializedException` (private)
+
+---
+
+## 3. Invariants
+
+- **StandardDev.StandardDeviation**: Returns 0 for empty collections; uses n-1 divisor (sample standard deviation).
+- **AverageQueue**: Thread-safe via lock on `_queueLock`. Queue never exceeds `QueueLength` + 1 transiently during Push.
+- **LevelTriggerLogging**: Thread-safe via lock on `ltLock`. All writes append to the same file.
+- **KeywordAlert**: Singleton pattern; `Instance` is lazily initialized. `ProcessMsg` only queues work if `alerts` is non-null (i.e., `Keywords.txt` exists and was readable).
+- **NaturalStringComparer.Compare**: Null inputs are handled explicitly (null x returns -1, null y returns 1).
+- **XmlToObject<T>.FromXml**: Returns `default(T)` on any exception, never throws to caller.
+- **FirmwareVersionToLong.Query**: Processes at most 4 characters; longer strings are truncated.
+- **Time conversions**: No timezone corrections applied; `DateTimeToUnixTimestamp` and `ToUnixTime` treat input as unspecified kind.
+- **Crc32.Get<T>**: Requires `T` be convertible to byte via `Convert.ToByte`; throws `FormatException`, `InvalidCastException`, or `OverflowException` on conversion failure.
+
+---
+
+## 4. Dependencies
+
+### External Dependencies (from imports)
+- `System.Windows.Forms` — Required by `EnumDropDown<T>`, `ExceptionalForm`, `ExceptionalUserControl`.
+- `System.Runtime.InteropServices` — Required by `TaskbarHelper`, `NaturalStringComparer`, `Win32MapApis`, `LargeArray` partial classes.
+- `System.Xml.Serialization` — Required by `XmlToObject<T>`.
+- `System.ComponentModel` — Required by `PropertyComparer<T>`, `SortableBindingList<T>`, `DataFlag`, `DescriptionAttributeCoder`.
+
+### Internal Dependencies
+- `DTS.Common.Utilities.DotNetProgrammingConstructs` — Contains `Property<T>`, `Exceptional`, `RangeRestrictedIntProperty`, `RangeRestrictedDoubleProperty` (referenced but not provided in source).
+- `DTS.Common.Utilities` — Referenced by `LargeArray` partial classes.
+- `DTS.Common.Utilities.IO.MemoryMap` — Contains `LargeArray<T>` and `Win32MapApis`.
+
+### Inferred Downstream Dependencies
+- `LargeArray<T>` is a partial class; main implementation is in `LargeArray.cs` (not provided).
+- `DataWindowAverager` is a partial class; main implementation not provided.
+- `TextLogger` is a partial class; main implementation not provided.
+- `Operation<IList<double>, IList<double>>` base class not provided.
+- `AttributeCoder<TTarget, TAttribute, TValue>` base class not provided.
+
+---
+
+## 5. Gotchas
+
+1. **Namespace inconsistency**: Files exist in both `DTS.Utilities` and `DTS.Common.Utilities` namespaces. `DegreesFromADC`, `StandardDev`, `SignalToNoiseRatio`, `Crc32`, and `TaskbarHelper` are in `DTS.Utilities`; most others are in `DTS.Common.Utilities`.
+
+2. **StandardDev empty collection behavior**: Returns 0 without indicating the collection was empty. Callers cannot distinguish between empty input and actual zero standard deviation.
+
+3. **Time.CurrentLocalUnixTimestamp implementation oddity**: Uses `DateTime.UtcNow` but constructs the epoch with `DateTimeKind.Local`. This appears inconsistent—likely should use `DateTime.Now` or `DateTimeKind.Utc`.
+
+4. **FirmwareVersionToLong.Query character interpretation**: Shifts character values directly (not numeric parsing). Version "1.0" produces different results than "10" due to character-by-character processing.
+
+5. **KeywordAlert.DoWork result discarded**: The `foundKeys` variable is computed but never used—matches are found but no action is taken. This may be incomplete functionality.
+
+6. **NaturalStringComparer platform dependency**: Uses Windows-specific `StrCmpLogicalW` from shlwapi.dll. Requires Windows XP or greater; will not work on non-Windows platforms.
+
+7. **XmlToObject<T> silent failure**: Catches all exceptions and returns `default(T)`. Callers have no way to know if deserialization failed.
+
+8. **LargeArray<T> partial class**: Multiple exception classes reference `LargeArray.cs` which is not provided. Full behavior of `LargeArray<T>` cannot be determined from source alone.
+
+9. **Missing base classes**: `Operation<TIn, TOut>`, `AttributeCoder<T1, T2, T3>`, `Property<T>`, `Exceptional`, `RangeRestrictedIntProperty`, and `RangeRestrictedDoubleProperty` are referenced but their implementations are not provided in the source files.