--- 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 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 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 domain)` — Base constructor accepting a domain of doubles. - Inherits from `Operation, IList>`. **`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(IEnumerable 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`) - `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`** (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`** (extends `BindingList`) - `public SortableBindingList()` — Default constructor. - `public SortableBindingList(IEnumerable enumeration)` — Constructs from enumeration. - Supports sorting via `ApplySortCore`, `RemoveSortCore`. - Supports searching via `FindCore(PropertyDescriptor property, object key)`. **`DTS.Common.Utilities.PropertyComparer`** (implements `IComparer`) - `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`** (extends `Exceptional`) - `public List Items { get; set; }` — Gets/sets items; setter fires `OnUpdate` event. - `public delegate void OnUpdateCallback(List updatedContents)` — Callback delegate type. - `public event OnUpdateCallback OnUpdate` — Event fired when Items is set. **`DTS.Common.Utilities.ExceptionalList`** (extends `List`) - `public ExceptionalList()`, `public ExceptionalList(int capacity)`, `public ExceptionalList(IEnumerable collection)` — Constructors. - Contains nested `Exception` class (extends `ApplicationException`). ### UI Components **`DTS.Common.Utilities.EnumDropDown`** (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` 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`) - `public DataFlagAttributeCoder()` — Default constructor. **`DTS.Common.Utilities.DescriptionAttributeCoder`** (extends `AttributeCoder`) - `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`** (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.ConstructionException` - `Property.InvalidValueException` - `Property.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.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**: 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`, `ExceptionalForm`, `ExceptionalUserControl`. - `System.Runtime.InteropServices` — Required by `TaskbarHelper`, `NaturalStringComparer`, `Win32MapApis`, `LargeArray` partial classes. - `System.Xml.Serialization` — Required by `XmlToObject`. - `System.ComponentModel` — Required by `PropertyComparer`, `SortableBindingList`, `DataFlag`, `DescriptionAttributeCoder`. ### Internal Dependencies - `DTS.Common.Utilities.DotNetProgrammingConstructs` — Contains `Property`, `Exceptional`, `RangeRestrictedIntProperty`, `RangeRestrictedDoubleProperty` (referenced but not provided in source). - `DTS.Common.Utilities` — Referenced by `LargeArray` partial classes. - `DTS.Common.Utilities.IO.MemoryMap` — Contains `LargeArray` and `Win32MapApis`. ### Inferred Downstream Dependencies - `LargeArray` 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>` base class not provided. - `AttributeCoder` 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 silent failure**: Catches all exceptions and returns `default(T)`. Callers have no way to know if deserialization failed. 8. **LargeArray partial class**: Multiple exception classes reference `LargeArray.cs` which is not provided. Full behavior of `LargeArray` cannot be determined from source alone. 9. **Missing base classes**: `Operation`, `AttributeCoder`, `Property`, `Exceptional`, `RangeRestrictedIntProperty`, and `RangeRestrictedDoubleProperty` are referenced but their implementations are not provided in the source files.