15 KiB
source_files, generated_at, model, schema_version, sha256
| source_files | generated_at | model | schema_version | sha256 | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
2026-04-17T15:26:26.405103+00:00 | zai-org/GLM-5-FP8 | 1 | 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 forDateTimeToUnixTimestamp.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 WindowsStrCmpLogicalW. 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. Returnsdefault(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 toLogs\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 firesOnUpdateevent.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
Exceptionclass (extendsApplicationException).
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
EnumListEntrywithValueproperty andIComparable<EnumListEntry>implementation.
DTS.Common.Utilities.ExceptionalForm (extends Form)
- Contains nested
Exceptionclass (extendsApplicationException).
DTS.Common.Utilities.ExceptionalUserControl (extends UserControl)
- Contains nested
Exceptionclass (extendsApplicationException).
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 againstKeywords.txt.
Exception Classes (Nested)
Property<Type>.ConstructionExceptionProperty<Type>.InvalidValueExceptionProperty<Type>.NotInitializedExceptionRangeRestrictedIntProperty.InvalidRangeExceptionRangeRestrictedDoubleProperty.InvalidRangeExceptionDataWindowAverager.WindowDoesNotExistExceptionTextLogger.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 exceedsQueueLength+ 1 transiently during Push. - LevelTriggerLogging: Thread-safe via lock on
ltLock. All writes append to the same file. - KeywordAlert: Singleton pattern;
Instanceis lazily initialized.ProcessMsgonly queues work ifalertsis non-null (i.e.,Keywords.txtexists 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;
DateTimeToUnixTimestampandToUnixTimetreat input as unspecified kind. - Crc32.Get: Requires
Tbe convertible to byte viaConvert.ToByte; throwsFormatException,InvalidCastException, orOverflowExceptionon conversion failure.
4. Dependencies
External Dependencies (from imports)
System.Windows.Forms— Required byEnumDropDown<T>,ExceptionalForm,ExceptionalUserControl.System.Runtime.InteropServices— Required byTaskbarHelper,NaturalStringComparer,Win32MapApis,LargeArraypartial classes.System.Xml.Serialization— Required byXmlToObject<T>.System.ComponentModel— Required byPropertyComparer<T>,SortableBindingList<T>,DataFlag,DescriptionAttributeCoder.
Internal Dependencies
DTS.Common.Utilities.DotNetProgrammingConstructs— ContainsProperty<T>,Exceptional,RangeRestrictedIntProperty,RangeRestrictedDoubleProperty(referenced but not provided in source).DTS.Common.Utilities— Referenced byLargeArraypartial classes.DTS.Common.Utilities.IO.MemoryMap— ContainsLargeArray<T>andWin32MapApis.
Inferred Downstream Dependencies
LargeArray<T>is a partial class; main implementation is inLargeArray.cs(not provided).DataWindowAverageris a partial class; main implementation not provided.TextLoggeris 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
-
Namespace inconsistency: Files exist in both
DTS.UtilitiesandDTS.Common.Utilitiesnamespaces.DegreesFromADC,StandardDev,SignalToNoiseRatio,Crc32, andTaskbarHelperare inDTS.Utilities; most others are inDTS.Common.Utilities. -
StandardDev empty collection behavior: Returns 0 without indicating the collection was empty. Callers cannot distinguish between empty input and actual zero standard deviation.
-
Time.CurrentLocalUnixTimestamp implementation oddity: Uses
DateTime.UtcNowbut constructs the epoch withDateTimeKind.Local. This appears inconsistent—likely should useDateTime.NoworDateTimeKind.Utc. -
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.
-
KeywordAlert.DoWork result discarded: The
foundKeysvariable is computed but never used—matches are found but no action is taken. This may be incomplete functionality. -
NaturalStringComparer platform dependency: Uses Windows-specific
StrCmpLogicalWfrom shlwapi.dll. Requires Windows XP or greater; will not work on non-Windows platforms. -
XmlToObject silent failure: Catches all exceptions and returns
default(T). Callers have no way to know if deserialization failed. -
LargeArray partial class: Multiple exception classes reference
LargeArray.cswhich is not provided. Full behavior ofLargeArray<T>cannot be determined from source alone. -
Missing base classes:
Operation<TIn, TOut>,AttributeCoder<T1, T2, T3>,Property<T>,Exceptional,RangeRestrictedIntProperty, andRangeRestrictedDoublePropertyare referenced but their implementations are not provided in the source files.