DP44/enriched-qwen3-coder-next/Common/DTS.Common.Serialization/Test/Module/Channel.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.Serialization/Test/Module/Channel/IConvertable.cs Common/DTS.Common.Serialization/Test/Module/Channel/ChannelWithMeta.cs Common/DTS.Common.Serialization/Test/Module/Channel/DataArray.cs	2026-04-16T03:40:40.401644+00:00	Qwen/Qwen3-Coder-Next-FP8	1	6e59e4819411113f

Channel

Documentation: DTS.Serialization.Test.Module.Channel Submodule

---

1. Purpose

This module defines core serialization abstractions for channel data within the DTS test data serialization framework. It provides interfaces and classes to represent channel metadata, raw data arrays, and conversion mechanisms between domain-specific objects and a canonical Channel representation used for persistence or transmission. The module serves as the foundational layer for serializing and deserializing time-series channel data—including scaling, timing, and unit-conversion metadata—into and from XML.

---

2. Public Interface

IConvertable Interface

(Nested in DTS.Serialization.Test.Module.Channel)

• Channel ToDtsSerializationTestModuleChannel()
  Converts the implementing object into a canonical Channel instance.

• void FromDtsSerializationTestModuleChannel(Channel channel)
  Initializes the implementing object using data from a Channel instance.

Note

: This interface is intended to be implemented by domain objects that need to be serialized/deserialized as Channel instances. The interface name is intentionally misspelled (IConvertable instead of IConvertible) per source.

---

ChannelWithMeta Class

(Top-level in DTS.Serialization)

• Channel Channel { get; }
  The canonical channel object to be serialized.

• DataScaler Scaler { get; }
  Scaling metadata associated with the channel.

• double SampleRate { get; }
  Sample rate (in Hz) of the channel.

• double StartTime { get; }
  Start time (in seconds) of the channel’s data.

• ChannelWithMeta(Channel channel, DataScaler scaler, double samplerate, double starttime)
  Constructor initializing all properties.

• static double GetMinStartTime(double start, IList<ChannelWithMeta> channelsWithMeta)
  Computes the earliest common start time across all provided channels and the given start offset. Uses Math.Max(start, channelsWithMeta.Min(cwm => cwm.StartTime)).

  Comment in source: “Start is a generally a negative value, so to get the value for the start time of the minimum common data set, run Max()”.

• static double GetMinStopTime(double stop, IList<ChannelWithMeta> channelsWithMeta)
  Computes the latest common stop time across all channels. Uses:
  Math.Min(stop, min(cwm.StartTime + (cwm.Channel.PersistentChannelInfo.Length - 1) / cwm.SampleRate)),
  with intermediate casting to decimal to mitigate floating-point rounding errors.

---

DataArray<DataType> Class

(Nested in DTS.Serialization.Test.Module.Channel)

• DataType[] Values { get; set; }
  Underlying array of data values. Returns an empty array if uninitialized or null.

• double ScaleFactorMv { get; set; }
  ADC-to-millivolt scaling factor.

• double MvPerEu { get; set; }
  Sensitivity: millivolts per engineering unit.

• double ScaleFactorEU { get; set; }
  EU scaling factor (unused in current XML schema per tags).

• bool UseEUScaleFactors { get; set; }
  Flag indicating whether EU scale factors should be applied.

• short DataZeroLevel { get; set; }
  Zero-level offset for ADC data.

• double UnitConversion { get; set; }
  Unit conversion multiplier (default 1.0).

• double Multiplier { get; set; }
  General-purpose multiplier (default 1.0).

• double UserOffsetEU { get; set; }
  User-defined offset in engineering units (default 0.0).

• DataArray()
  Default constructor.

• DataArray(DataType[] values)
  Constructor initializing Values with the provided array.

• Implicit operator List<DataType> → DataArray<DataType>
  Converts a List<DataType> to DataArray<DataType>.

• Implicit operator DataArray<DataType> → List<DataType>
  Converts DataArray<DataType> to List<DataType>.

• void WriteXml(XmlWriter writer)
  Serializes the instance to XML with the following structure:

  <Data Length="N" Type="System.Double" ScaleFactorMv="..." SensitivityMvEu="...">
    <Datum Value="..." />
    ...
  </Data>
  

  Includes attributes for Length, Type, ScaleFactorMv, and SensitivityMvEu. Each datum is serialized as <Datum Value="..."/>.

• void ReadXml(XmlReader reader)
  Deserializes XML into the instance. Requires:

  • DataType to have a public static Parse(string) method.
  • DataType to be constructible via Activator.CreateInstance.
  • XML to contain Length, Type, ScaleFactorMv, and SensitivityMvEu attributes.

• XmlSchema GetSchema()
  Always returns null. Per comment: “This method is never invoked during XML object serialization.”

• bool Equals(object obj)
  Memberwise equality test: compares ScaleFactorMv, MvPerEu, Values.Length, and element-wise Values equality.

• int GetHashCode()
  Returns base hash code (no custom hashing implemented).

---

3. Invariants

• DataArray<DataType>

  • Values is never null when accessed (returns empty array if uninitialized).
  • XML serialization/deserialization requires DataType to implement Parse(string) and be instantiable via Activator.CreateInstance.
  • ScaleFactorMv and MvPerEu are always serialized/deserialized as XML attributes (not child elements).
  • DataZeroLevel, UseEUScaleFactors, UnitConversion, Multiplier, UserOffsetEU are not serialized in XML (no corresponding XML tags), though they are properties.

• ChannelWithMeta

  • GetMinStartTime and GetMinStopTime assume StartTime and SampleRate are non-negative and consistent across channels.
  • GetMinStopTime uses decimal arithmetic internally to avoid floating-point rounding artifacts.

• IConvertable

  • Implementers must ensure FromDtsSerializationTestModuleChannel fully initializes the object from the Channel argument.
  • ToDtsSerializationTestModuleChannel must produce a fully populated Channel instance.

---

4. Dependencies

Imports/Usings

• System, System.Collections.Generic, System.Linq → used in ChannelWithMeta.
• DTS.Common.DAS.Concepts → provides DataScaler type (used in ChannelWithMeta).
• System.Xml, System.Xml.Schema, System.Xml.Serialization → used in DataArray<DataType>.
• DTS.Common.Utilities, DTS.Common.Utilities.DotNetProgrammingConstructs → provides Exceptional base class and Property<T> wrapper (used in DataArray<DataType>).

Known Dependencies

• DTS.Serialization.Test.Module.Channel (itself) — ChannelWithMeta references Channel and PersistentChannelInfo.Length.
• DataScaler — assumed to be defined in DTS.Common.DAS.Concepts.
• Property<T> — internal wrapper used for observable/validated properties in DataArray<T>.

Dependents (Inferred)

• Serialization/deserialization pipelines (e.g., XML writers/readers) that consume DataArray<T>.
• Higher-level serialization modules that use IConvertable to bridge domain objects and Channel.
• ChannelWithMeta consumers (e.g., file writers) that need to align multiple channels in time.

---

5. Gotchas

• Typo in interface name: IConvertable (not IConvertible) — likely historical.
• DataArray<T> XML schema is incomplete: Only ScaleFactorMv and MvPerEu are serialized; other properties (ScaleFactorEU, DataZeroLevel, etc.) are ignored in XML.
• GetSchema() always returns null: This is intentional per comment, but may confuse developers expecting a schema for validation.
• Rounding mitigation in GetMinStopTime: Uses decimal cast to avoid floating-point artifacts (e.g., 4.999999999999995 vs 5.0), but this may be fragile if StartTime or SampleRate are very large/small.
• DataArray<T> requires Parse(string): If DataType lacks a static Parse(string) method, ReadXml throws an exception.
• Values property returns empty array if null: This avoids null-reference exceptions but may mask uninitialized state.
• Implicit conversions are one-way in practice: While both implicit operators exist, DataArray<T> is not a List<T>—conversions copy data, not reference.

None identified from source alone beyond the above.

---

Documentation generated from provided source files. No external assumptions or API speculation applied.