37 lines
2.9 KiB
Markdown
37 lines
2.9 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.CommonCore/Exceptions/OutOfDataException.cs
|
||
generated_at: "2026-04-16T02:13:54.656604+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "fdc72f1eddeb3763"
|
||
---
|
||
|
||
# Exceptions
|
||
|
||
### 1. Purpose
|
||
The `OutOfDataException` class provides a specialized exception type for scenarios where an operation attempting to read or consume data from a sequential data source (e.g., a stream, buffer, or parser) has exceeded the available data. It extends `System.Exception` to include contextual information—the `Index` at which the shortage occurred—enabling callers to pinpoint the location of the failure and implement recovery or error-reporting logic accordingly.
|
||
|
||
### 2. Public Interface
|
||
- **`OutOfDataException(string message, long index)`**
|
||
Constructor. Initializes a new instance of the `OutOfDataException` class with a specified error message and the zero-based index in the data source where the shortage occurred. The `index` parameter is stored in the `Index` property and is immutable after construction.
|
||
|
||
- **`long Index { get; }`**
|
||
Read-only property exposing the zero-based index (e.g., byte offset, element position, or token index) in the underlying data source where the exception was thrown. This value is set at construction and cannot be modified.
|
||
|
||
### 3. Invariants
|
||
- `Index` is non-negative and represents a position *beyond* the last valid data element (i.e., `Index >= DataLength`).
|
||
- `Index` is set exactly once during construction and remains constant for the lifetime of the exception instance.
|
||
- The exception message (`Message` inherited from `Exception`) must clearly describe the nature of the data shortage (e.g., “Unexpected end of input at index 42”).
|
||
|
||
### 4. Dependencies
|
||
- **Depends on**: `System.Exception` (via `System` namespace).
|
||
- **Used by**: Likely consumed by data-parsing, deserialization, or streaming components within the `DTS.Common` namespace (e.g., `DTS.Common.Core`, `DTS.Common.IO`)—though no direct usages are visible in this file, the exception’s design implies integration with data-reading logic.
|
||
- **No external dependencies** beyond the base .NET runtime.
|
||
|
||
### 5. Gotchas
|
||
- The `Index` property uses a zero-based convention, but callers must verify whether the underlying data source uses byte offsets, character positions, or element indices (e.g., in a token stream) to avoid misinterpretation.
|
||
- The exception does *not* include the total data length; callers must track capacity separately if needed for context.
|
||
- The `Index` is `long`, suggesting support for large data sources (e.g., >2GB), but callers should ensure consistency with the data source’s indexing scheme (e.g., `int`-based APIs may require casting).
|
||
- No additional context (e.g., source name, buffer snapshot) is stored—only the index and message—limiting diagnostic depth without external correlation.
|
||
- None identified from source alone. |