DP44/enriched-partialglm/Common/DTS.Common.Utilities.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T11:32:34.054047+00:00	zai-org/GLM-5-FP8	1	a50bc074e645dae7

DTS.Common.Utilities Documentation

1. Purpose

DTS.Common.Utilities is a general-purpose utility library providing common functionality for DTS applications. It includes mathematical operations (standard deviation, SNR calculation, degree conversion), data structures (sortable binding lists, average queues, notifying lists), Windows Forms helpers (enum dropdowns, exceptional base classes), file/memory operations (CRC32, memory-mapped file support via Win32 APIs), XML serialization helpers, and various framework extensions (property comparers, attribute coders). The library serves as a foundational layer reused across multiple DTS projects.

---

2. Public Interface

Mathematical Utilities

DTS.Common.Utilities.DegreesFromADC

• public static double GetDegrees(double Sxyz, double SG) — Converts ADC values to degrees using arcsin formula: (180/π) * asin(Sxyz / SG).

DTS.Common.Utilities.SignalToNoiseRatio

• public static double CalculateSNR(IEnumerable<double> values, double fullScalePP = 65536.0) — Calculates signal-to-noise ratio given a dataset and full scale peak-to-peak value (defaults to 65536.0 for ADC data).

DTS.Common.Utilities.StandardDev

• public static double StandardDeviation(IEnumerable<double> values) — Calculates sample standard deviation using Bessel's correction (n-1 denominator). Returns 0 for empty collections.

DTS.Common.Utilities.Math.DoubleListOperation (abstract)

• public DoubleListOperation(IList<double> domain) — Abstract base class for mathematical operations on IList<double> data. Inherits from Operation<IList<double>, IList<double>>.

DTS.Common.Utilities.Crc32

• public Crc32() — Constructor that builds the CRC32 lookup table.
• public uint Get<T>(IEnumerable<T> byteStream) — Calculates 32-bit reversed CRC checksum. Throws FormatException, InvalidCastException, or OverflowException if conversion to byte fails.

DTS.Common.Utilities.AverageQueue

• public AverageQueue(int length) — Constructs a fixed-length queue for running average calculation.
• public double Push(double newValue) — Adds a value to the queue, returns current average. Thread-safe.
• public double GetAverage() — Returns current average. Thread-safe.
• public void Reset() — Clears the queue. Thread-safe.
• public double GetMin() — Returns minimum value in queue. Thread-safe.
• public double GetMax() — Returns maximum value in queue. Thread-safe.

Time Utilities

DTS.Common.Utilities.Time

• public static UInt32 DateTimeToUnixTimestamp(DateTime dateTime) — Converts DateTime to Unix timestamp (seconds since 1970-01-01). No timezone correction.
• public static UInt32 CurrentUtcUnixTimestamp() — Returns current UTC time as Unix timestamp.
• public static UInt32 CurrentLocalUnixTimestamp() — Returns current time as Unix timestamp (calculated from UtcNow but with Local kind in epoch).
• public static DateTime ToDateTime(UInt32 seconds) — Converts Unix timestamp back to DateTime.
• public static UInt32 ToUnixTime(DateTime dateTime) — Alias for DateTimeToUnixTimestamp.
• public static bool IsBeginningOfTime(DateTime dateTime) — Returns true if DateTime equals Unix epoch (1970-01-01).

String/Version Utilities

DTS.Common.Utilities.FirmwareVersionToLong

• public static long Query(string version) — Converts firmware version string to long by taking first 4 characters and bit-shifting each character into 16-bit positions (shifts: 48, 32, 16, 0).

DTS.Common.Utilities.NaturalStringComparer : IComparer<string>

• public int Compare(string x, string y) — Natural string comparison (like Windows Explorer). Returns -1 if x < y, 1 if x > y, 0 if equal. Null strings sort first.
• public static int StaticCompare(string x, string y) — Static version of Compare.

XML Utilities

DTS.Common.Utilities.Xml.XmlToObject<T>

• public static T FromXml(string xml) — Deserializes XML string to object of type T. Returns default(T) on any exception (including InvalidOperationException from deserialization).

DTS.Common.Utilities.Xml.XmlSerializationTagAttribute : Attribute, IComparable<XmlSerializationTagAttribute>

• public string Value { get; } — The tag string value.
• public int Order { get; } — Sort order for multiple tags.
• public XmlSerializationTagAttribute(string value) — Constructor with default order 0.
• public XmlSerializationTagAttribute(string value, int order) — Constructor with explicit order.
• public int CompareTo(XmlSerializationTagAttribute that) — Compares by Order property.

Windows/OS Integration

DTS.Utilities.TaskbarHelper

• public static extern int SetCurrentProcessExplicitAppUserModelID([MarshalAs(UnmanagedType.LPWStr)] string AppID) — P/Invoke to shell32.dll to set Windows taskbar AppUserModelID. Reference: FB 45077.

Logging

DTS.Common.Utilities.LTLogging.LevelTriggerLogging

• public static void LevelTriggerLog(string msg) — Thread-safe append to Logs\LevelTriggerSettings.txt.

Collections/Data Structures

DTS.Common.Utilities.SortableBindingList<T> : BindingList<T>

• public SortableBindingList() — Default constructor.
• public SortableBindingList(IEnumerable<T> enumeration) — Construct from enumeration.
• Protected sorting/searching overrides: SupportsSortingCore, IsSortedCore, SortPropertyCore, SortDirectionCore, SupportsSearchingCore, ApplySortCore, RemoveSortCore, FindCore.

DTS.Common.Utilities.PropertyComparer<T> : IComparer<T>

• public PropertyComparer(PropertyDescriptor property, ListSortDirection direction) — Constructs comparer for specified property and sort direction.
• public int Compare(T x, T y) — Compares two objects by the configured property.
• public void SetPropertyAndDirection(PropertyDescriptor descriptor, ListSortDirection direction) — Updates property and sort direction.

DTS.Common.Utilities.UpdateNotifyingList<T> : Exceptional

• public List<T> Items { get; set; } — Gets/sets the list contents; setter triggers 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> : List<T>

• public ExceptionalList(), ExceptionalList(int capacity), ExceptionalList(IEnumerable<T> collection) — Standard list constructors.
• Nested public class Exception : ApplicationException — List-specific exception type.

Windows Forms Components

DTS.Common.Utilities.EnumDropDown<T> : System.Windows.Forms.ComboBox where T : struct, IComparable

• public class EnumListEntry : IComparable<EnumListEntry> — Wrapper for enum values with DescriptionAttribute decoding.
  • public T Value { get; set; }
  • public override string ToString() — Returns decoded description.
• public delegate bool Filter(T enumEntry) — Filter delegate type.
• public Filter EnumFilter { set; } — Sets filter and repopulates list.
• public EnumDropDown(Filter defaultFilter) — Constructor with filter.
• public void PopulateList() — Clears and repopulates items based on filter.
• public EnumListEntry SelectedEntry { get; set; } — Currently selected entry.
• public T? SelectedEnum { get; set; } — Currently selected enum value.

DTS.Common.Utilities.ExceptionalForm : Form

• Nested public class Exception : ApplicationException — Form-specific exception type with standard constructors.

DTS.Common.Utilities.ExceptionalUserControl : UserControl

• Nested public class Exception : ApplicationException — UserControl-specific exception type with standard constructors.

Enums and Attributes

DTS.Common.Utilities.DataFlag (enum)

• None (0), Normal (1), Saturated (2), ZeroCrossing (3), BrokenWire (4), Other (-1)
• Each value has [Description("...")] and [Flag(int)] attributes.

DTS.Common.Utilities.FlagAttribute : Attribute

• public int Flag { get; } — The flag value.
• public FlagAttribute(int flag) — Constructor.

DTS.Common.Utilities.DataFlagAttributeCoder : AttributeCoder<DataFlag, FlagAttribute, int>

• public DataFlagAttributeCoder() — Constructor for encoding/decoding DataFlag values.

DTS.Common.Utilities.DescriptionAttributeCoder<TTargetType> : AttributeCoder<TTargetType, DescriptionAttribute, string>

• public DescriptionAttributeCoder() — Constructor for encoding/decoding DescriptionAttribute values. Uses case-insensitive comparison.

Keyword Processing

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. Uses PLINQ for parallel matching. Note: Matched keys are joined but result is not persisted or returned anywhere visible in source.

Memory-Mapped File Support

DTS.Common.Utilities.IO.MemoryMap.Win32MapApis (internal)

• P/Invoke declarations for kernel32.dll:
  • CreateFile, CreateFileMapping, FlushViewOfFile, MapViewOfFile, OpenFileMapping, UnmapViewOfFile, CloseHandle, GetLastError.

DTS.Common.Utilities.IO.MemoryMap.LargeArray<T> (partial)

• protected class NameGeneratorLock — Locking object for scratch file name generation.
• private class MissingScratchFileException : ApplicationException
• private class ScratchFileAlreadyExistsException : ApplicationException
• private class LargeOverflowException : ApplicationException

Exception Types (Various)

DTS.Common.Utilities.DataWindowAverager.WindowDoesNotExistException : ApplicationException

• Standard exception constructors for invalid window access.

DTS.Common.Utilities.DotNetProgrammingConstructs.Property<Type>.ConstructionException : Exception

• Exception for property construction failures.

DTS.Common.Utilities.DotNetProgrammingConstructs.Property<Type>.InvalidValueException : Exception

• Exception for invalid property values.

DTS.Common.Utilities.DotNetProgrammingConstructs.Property<Type>.NotInitializedException : Exception

• Exception for uninitialized property access.

DTS.Common.Utilities.DotNetProgrammingConstructs.RangeRestrictedIntProperty.InvalidRangeException : Exception

• Exception for integer range violations.

DTS.Common.Utilities.DotNetProgrammingConstructs.RangeRestrictedDoubleProperty.InvalidRangeException : Exception

• Exception for double range violations.

DTS.Common.Utilities.Logging.TextLogger.LogPathnameNotInitializedException : ApplicationException (private)

• Exception for uninitialized log pathname.

---

3. Invariants

• StandardDev.StandardDeviation: Returns 0 for empty collections; uses sample standard deviation (n-1 divisor).
• AverageQueue: Always maintains _queueSum as the sum of current queue contents; Queue.Count never exceeds QueueLength.
• XmlToObject.FromXml: Always returns default(T) on any failure (never throws to caller).
• NaturalStringComparer.Compare: Null values are always sorted first (null x returns -1, null y returns 1).
• FirmwareVersionToLong.Query: Only processes first 4 characters of version string; shorter strings use available characters.
• KeywordAlert: Singleton pattern; alerts list is only populated if Keywords.txt exists and is readable.
• Time conversions: All Unix timestamp methods use UInt32 (32-bit), limiting date range to 1970–2106.
• LargeArray exceptions: All nested exception classes are private to LargeArray<T>.

---

4. Dependencies

External Dependencies (Imports)

• System (core types, Math, DateTime, Exception)
• System.Collections.Generic (List<T>, IEnumerable<T>, IList<T>, Queue<T>, Dictionary<TKey,TValue>)
• System.ComponentModel (PropertyDescriptor, ListSortDirection, DescriptionAttribute, BindingList<T>)
• System.Linq (LINQ extensions, AsParallel())
• System.Runtime.InteropServices (P/Invoke, DllImport, MarshalAs)
• System.Runtime.Serialization (SerializationInfo, StreamingContext)
• System.Text (StringBuilder)
• System.Threading (ThreadPool, WaitCallback)
• System.Threading.Tasks (Task)
• System.Windows.Forms (Form, UserControl, ComboBox)
• System.Xml.Serialization (XmlSerializer)
• System.IO (TextReader, StringReader, File)

Internal Dependencies

• DTS.Common.Utilities.DotNetProgrammingConstructs — Referenced by Property<T>, RangeRestrictedIntProperty, RangeRestrictedDoubleProperty, Exceptional, Operation<TInput,TOutput>.
• DTS.Common.Utilities.IO.MemoryMap — Contains LargeArray<T> and Win32MapApis.
• DTS.Common.Utilities.LTLogging — Contains LevelTriggerLogging.
• DTS.Common.Utilities.Logging — Contains TextLogger.
• DTS.Common.Utilities.Xml — Contains XmlToObject<T>, XmlSerializationTagAttribute.
• DTS.Common.Utilities.Math — Contains DoubleListOperation.

Referenced but Not Provided

• DTS.Common.Utilities.Property<T> — Referenced by UpdateNotifyingList<T> and exception partial classes.
• DTS.Common.Utilities.RangeRestrictedIntProperty — Referenced by exception partial class.
• DTS.Common.Utilities.RangeRestrictedDoubleProperty — Referenced by exception partial class.
• DTS.Common.Utilities.Exceptional — Base class for UpdateNotifyingList<T>.
• DTS.Common.Utilities.Operation<TInput, TOutput> — Base class for DoubleListOperation.
• DTS.Common.Utilities.AttributeCoder<TTarget, TAttribute, TValue> — Base class for DescriptionAttributeCoder and DataFlagAttributeCoder.
• DTS.Common.Utilities.DataWindowAverager — Referenced by WindowDoesNotExistException partial class.
• DTS.Common.Utilities.LargeArray<T> — Main class referenced by partial exception files.
• DTS.Common.Utilities.TextLogger — Referenced by LogPathnameNotInitializedException partial class.
• DTS.Common.Utilities.Properties.Resources — Referenced by XmlSerializationTagAttribute for error message.

---

5. Gotchas

1. KeywordAlert.DoWork has no observable output: The DoWork method builds foundKeys string from matches but never writes, logs, or returns it. The matched keywords are effectively discarded.

2. Time.CurrentLocalUnixTimestamp naming is misleading: The method calculates DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0, 0, DateTimeKind.Local). Subtracting UTC now from a Local-kind epoch produces a counterintuitive result that doesn't represent true local Unix time.

3. StandardDev.StandardDeviation uses Count()-1 for empty check: The method calls values.Any() to check for emptiness, then later calls values.Count() - 1 as divisor. If the enumerable has exactly one element, this causes division by zero (resulting in Infinity or NaN).

4. XmlToObject.FromXml silently swallows all exceptions: Any exception during XML deserialization returns default(T) without any indication of failure. Callers cannot distinguish between "deserialization failed" and "deserialized to default value."

5. **FirmwareVersionToLong.Query uses character values