DP44/enriched-qwen3-coder-next/Common/DTS.CommonCore/Classes/ISO.md

---
source_files:
  - Common/DTS.CommonCore/Classes/ISO/IsoCode.cs
generated_at: "2026-04-16T02:39:28.985647+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "e833a8924b8a2f43"
---

# ISO

## Documentation: `IsoCode` Class

### 1. Purpose  
The `IsoCode` class encapsulates a fixed-length 16-character ISO-standard location code, representing hierarchical spatial and physical metadata (e.g., for document or object tracking). It provides structured access to semantically meaningful substrings—such as test object, position, main/fine locations, physical dimension, direction, and filter class—while enforcing a strict 16-character internal representation. The class ensures consistent formatting (e.g., padding with `'?'` or truncating) and serves as a domain-specific abstraction over raw string manipulation for ISO-compliant codes.

### 2. Public Interface  

- **`public IsoCode(string isoCode)`**  
  Constructor. Initializes the 16-character internal buffer `_isoCodeFull`. If `isoCode` is `null`, treats it as `""`. Truncates to 16 characters if longer; pads with `'?'` if shorter. Assigns each character directly to `_isoCodeFull[i]`.

- **`public string StringRepresentation { get; set; }`**  
  Gets/sets the full 16-character ISO code as a string.  
  - **Getter**: Returns `_isoCodeFull` concatenated into a string.  
  - **Setter**: Assigns characters from `value` to `_isoCodeFull`. If `value` is shorter than 16 chars, pads remaining positions with `'0'`. Does *not* use `'?'` padding in setter.

- **`public string TestObject { get; set; }`**  
  Gets/sets the first character (`_isoCodeFull[0]`).  
  - **Setter**: If `value` is `null` or empty, sets to `'?'`; otherwise uses `value[0]`.

- **`public string Position { get; set; }`**  
  Gets/sets the second character (`_isoCodeFull[1]`).  
  - **Setter**: Same behavior as `TestObject`.

- **`public string MainLocation { get; set; }`**  
  Gets/sets characters at indices 2–5 (4 chars).  
  - **Setter**: Truncates to 4 chars if longer; pads right with `'?'` if shorter.

- **`public string FineLocation1 { get; set; }`**  
  Gets/sets characters at indices 6–7 (2 chars).  
  - **Setter**: Pads right with `'?'` if shorter than 2; truncates if longer (implicitly via `ToCharArray(0, 2)`).

- **`public string FineLocation2 { get; set; }`**  
  Gets/sets characters at indices 8–9 (2 chars).  
  - **Setter**: Same padding/truncation behavior as `FineLocation1`.

- **`public string FineLocation3 { get; set; }`**  
  Gets/sets characters at indices 10–11 (2 chars).  
  - **Setter**: Same padding/truncation behavior as `FineLocation1`.

- **`public string PhysicalDimension { get; set; }`**  
  Gets/sets characters at indices 12–13 (2 chars).  
  - **Setter**: Truncates to 2 chars if longer; pads right with `'?'` if shorter.

- **`public string Direction { get; set; }`**  
  Gets/sets character at index 14 (1 char).  
  - **Setter**: If `value` is `null` or empty, sets to `'?'`; otherwise uses `value[0]`.

- **`public string FilterClass { get; set; }`**  
  Gets/sets character at index 15 (1 char).  
  - **Setter**: Same behavior as `Direction`.

### 3. Invariants  
- `_isoCodeFull` is *always* exactly 16 characters long.  
- For all public properties (`TestObject`, `Position`, `FineLocation*`, `PhysicalDimension`, `Direction`, `FilterClass`), the setter ensures the underlying character(s) are set to `'?'` when input is `null`/empty (except `StringRepresentation`, which uses `'0'` in setter).  
- `MainLocation` and `PhysicalDimension` truncate to 4 and 2 chars respectively if input exceeds length; all fine location fields truncate to 2 chars.  
- The constructor *always* produces a 16-character buffer (via truncation or `'?'` padding).  
- `StringRepresentation` setter does *not* use `'?'` padding—uses `'0'` for missing characters.

### 4. Dependencies  
- **Internal**: Uses `System.Text.StringBuilder` (for `StringRepresentation` getter).  
- **External**: No external dependencies beyond `System` (no third-party or framework-specific APIs beyond core types).  
- **Consumers**: Presumably used by other modules in `DTS.Common` namespace (e.g., parsing/serialization logic, UI binding, or ISO code validation services), though not explicit in this file.

### 5. Gotchas  
- **Inconsistent padding in setters**:  
  - Public property setters (`TestObject`, `Position`, etc.) use `'?'` for missing/empty input.  
  - `StringRepresentation` setter uses `'0'` for missing characters. This discrepancy may cause unexpected behavior if `StringRepresentation` is set directly after using property setters (or vice versa).  
- **Off-by-one error in `_fineLocation*` setters**:  
  In `_fineLocation1`, `_fineLocation2`, and `_fineLocation3` private setters, the condition `value.Length < i` should be `value.Length <= i` to correctly handle `i == value.Length - 1`. As written, `value[i]` will throw `ArgumentOutOfRangeException` when `value.Length == i`.  
  Example: For `value = "A"` (length 1), when `i = 1`, `value.Length (1) < i (1)` is false, so it attempts `value[1]` → invalid.  
- **Redundant `string.IsNullOrEmpty` checks**:  
  Properties like `TestObject` and `Position` check `string.IsNullOrEmpty(value)` before accessing `value[0]`, but `value[0]` would throw `IndexOutOfRangeException` for empty strings anyway—so the check is defensive but not strictly necessary.  
- **No validation of character content**:  
  The class accepts any character (including non-alphanumeric) without validation. ISO compliance (e.g., allowed character set) is not enforced.  
- **`_mainLocation` setter has inconsistent padding**:  
  Uses `'0'` if `value.Length <= i`, but public `MainLocation` setter pads with `'?'`. This mismatch is hidden by the public setter, but could cause confusion if private setter is used directly (unlikely, but possible in reflection scenarios).  
- **No immutability guarantees**:  
  Though `_isoCodeFull` is `readonly`, its *contents* are mutable via public setters. The class is not thread-safe.  

None identified beyond the above.