init

docs/ai/Common/DTS.Common/Exceptions.md

@@ -0,0 +1,45 @@
+---
+source_files:
+  - Common/DTS.Common/Exceptions/OutOfDataException.cs
+generated_at: "2026-04-17T16:39:37.776631+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "7cb87e56ccef92d8"
+---
+
+# Documentation: OutOfDataException
+
+## 1. Purpose
+
+`OutOfDataException` is a custom exception class designed to signal when a read operation attempts to access data beyond the available bounds of a data source. It captures the specific index position where the failure occurred, enabling callers to understand exactly where in a stream or buffer the data exhaustion happened. This exception is part of the `DTS.Common.Exceptions` namespace and serves as a domain-specific alternative to generic exceptions for data-underflow scenarios.
+
+## 2. Public Interface
+
+### Class: `OutOfDataException`
+**Inherits from:** `System.Exception`
+
+| Member | Signature | Description |
+|--------|-----------|-------------|
+| Property | `public long Index { get; private set; }` | Read-only property that stores the index position at which the data read failure occurred. Set only during construction. |
+| Constructor | `public OutOfDataException(string ex, long index)` | Initializes a new instance with the specified message `ex` and the `index` where the out-of-data condition was detected. Passes the message string to the base `Exception` class. |
+
+## 3. Invariants
+
+- The `Index` property is immutable after construction (private setter).
+- `Index` is always a `long` (64-bit signed integer), supporting large data sources.
+- The exception message (passed via `ex` parameter) is always forwarded to the base `Exception` class.
+- There is no parameterless constructor; all instances must be created with both a message and an index value.
+
+## 4. Dependencies
+
+**This module depends on:**
+- `System` namespace (specifically `System.Exception` as the base class)
+
+**What depends on this module:**
+- Cannot be determined from source alone. This exception is likely thrown by data parsing, deserialization, or stream-reading components within the DTS codebase.
+
+## 5. Gotchas
+
+- **Misleading parameter name:** The constructor parameter `ex` suggests an exception object, but it is actually a string message. Callers should pass a descriptive error message, not an exception instance.
+- **No standard exception constructors:** Unlike typical .NET exceptions, this class lacks common constructors such as a parameterless constructor, a message-only constructor, or a serialization constructor. This limits its use in certain scenarios (e.g., serialization, standard exception patterns).
+- **No inner exception support:** There is no constructor overload that accepts an inner exception, making it impossible to wrap underlying exceptions while preserving the causal chain.