---
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-16T14:11:35.779677+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "a50bc074e645dae7"
---

# Documentation: DTS.Common.Utilities

## 1. Purpose
This module serves as a core utility library for the DTS codebase, providing a collection of reusable components ranging from mathematical helpers (standard deviation, signal-to-noise ratio, CRC32) and data structures (sortable binding lists, thread-safe queues) to Windows Forms extensions and low-level file I/O wrappers. It centralizes common programming constructs, exception definitions, and conversion logic (time, firmware versions, XML) to promote code reuse across the system.

## 2. Public Interface

### Math & Signal Processing
*   **`DTS.Utilities.StandardDev`**
    *   `double StandardDeviation(IEnumerable<double> values)`: Calculates the sample standard deviation of a dataset. Returns 0 if the collection is empty.
*   **`DTS.Utilities.SignalToNoiseRatio`**
    *   `double CalculateSNR(IEnumerable<double> values, double fullScalePP = 65536.0)`: Calculates the Signal-to-Noise Ratio based on the standard deviation of the provided values.
*   **`DTS.Common.Utilities.DegreesFromADC`**
    *   `double GetDegrees(double Sxyz, double SG)`: Converts raw ADC values to degrees using the arcsine function.
*   **`DTS.Utilities.Crc32`**
    *   `uint Get<T>(IEnumerable<T> byteStream)`: Calculates a 32-bit CRC checksum for a generic byte stream.
*   **`DTS.Common.Utilities.AverageQueue`**
    *   `double Push(double newValue)`: Adds a value to the queue and returns the current average.
    *   `double GetAverage()`: Returns the current average.
    *   `void Reset()`: Clears the queue.
    *   `double GetMin()`, `double GetMax()`: Returns the minimum/maximum values in the queue.

### Time & Conversion
*   **`DTS.Common.Utilities.Time`**
    *   `UInt32 DateTimeToUnixTimestamp(DateTime dateTime)`: Converts a `DateTime` to a Unix timestamp (seconds since 1/1/1970).
    *   `UInt32 CurrentUtcUnixTimestamp()`, `UInt32 CurrentLocalUnixTimestamp()`: Returns the current UTC or local Unix timestamp.
    *   `DateTime ToDateTime(UInt32 seconds)`: Converts a Unix timestamp back to a `DateTime`.
    *   `bool IsBeginningOfTime(DateTime dateTime)`: Checks if the time is exactly 1/1/1970 00:00:00.
*   **`DTS.Common.Utilities.FirmwareVersionToLong`**
    *   `long Query(string version)`: Converts a firmware version string to a `long` by bit-shifting the first 4 characters.
*   **`DTS.Common.Utilities.Xml.XmlToObject`**
    *   `T FromXml(string xml)`: Deserializes an XML string into an object of type `T`. Returns `default(T)` on failure.

### Data Structures & Collections
*   **`DTS.Common.Utilities.SortableBindingList`**
    *   Inherits from `BindingList`. Provides sorting capabilities for data-bound controls.
*   **`DTS.Common.Utilities.UpdateNotifyingList`**
    *   A wrapper around `List` that fires an `OnUpdate` event when the `Items` property is set.
*