101 lines
5.8 KiB
Markdown
101 lines
5.8 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.Common/Classes/ISO/IsoCode.cs
|
||
generated_at: "2026-04-16T03:15:00.433406+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "f4af52456432964e"
|
||
---
|
||
|
||
# ISO
|
||
|
||
## Documentation: `IsoCode` Class
|
||
|
||
### 1. Purpose
|
||
The `IsoCode` class encapsulates a fixed-length 16-character ISO-compliant location code, where each position or substring has a defined semantic meaning (e.g., test object, position, main/fine locations, physical dimension, direction, filter class). It provides a structured, type-safe interface to parse, manipulate, and reconstruct such codes while enforcing padding with `'?'` for missing characters and `'0'` for out-of-bounds or invalid inputs. This class exists to standardize handling of ISO 14134–2–compliant or similar legacy location identifiers in the system, likely used in medical device or calibration contexts.
|
||
|
||
---
|
||
|
||
### 2. Public Interface
|
||
|
||
#### Constructor
|
||
- **`IsoCode(string isoCode)`**
|
||
Initializes a new instance by parsing a 16-character (or shorter/longer) input string. Truncates to 16 chars if longer; pads with `'?'` if shorter. Assigns each character directly to `_isoCodeFull[i]`.
|
||
|
||
#### Properties
|
||
- **`string TestObject`**
|
||
Gets/sets the first character (`_isoCodeFull[0]`). Setter replaces `null`/empty input with `'?'`.
|
||
|
||
- **`string Position`**
|
||
Gets/sets the second character (`_isoCodeFull[1]`). Setter replaces `null`/empty input with `'?'`.
|
||
|
||
- **`string MainLocation`**
|
||
Gets/sets characters at indices 2–5 (4 chars). Setter pads with `'?'` if < 4 chars, truncates to 4 if > 4.
|
||
|
||
- **`string FineLocation1`**
|
||
Gets/sets characters at indices 6–7 (2 chars). Setter pads with `'?'` if < 2 chars.
|
||
|
||
- **`string FineLocation2`**
|
||
Gets/sets characters at indices 8–9 (2 chars). Setter pads with `'?'` if < 2 chars.
|
||
|
||
- **`string FineLocation3`**
|
||
Gets/sets characters at indices 10–11 (2 chars). Setter pads with `'?'` if < 2 chars.
|
||
|
||
- **`string PhysicalDimension`**
|
||
Gets/sets characters at indices 12–13 (2 chars). Setter pads with `'?'` if < 2 chars, truncates to 2 if > 2.
|
||
|
||
- **`string Direction`**
|
||
Gets/sets the 15th character (`_isoCodeFull[14]`). Setter replaces `null`/empty input with `'?'`.
|
||
|
||
- **`string FilterClass`**
|
||
Gets/sets the 16th character (`_isoCodeFull[15]`). Setter replaces `null`/empty input with `'?'`.
|
||
|
||
- **`string StringRepresentation`**
|
||
Gets/sets the full 16-character code as a string.
|
||
- *Getter*: concatenates all `_isoCodeFull` characters.
|
||
- *Setter*: assigns `value[i]` to `_isoCodeFull[i]` for `i < 16`; sets remaining positions to `'0'` if `value.Length < 16`.
|
||
⚠️ **Note**: Unlike other setters, this one pads *short* inputs with `'0'`, not `'?'`.
|
||
|
||
---
|
||
|
||
### 3. Invariants
|
||
- `_isoCodeFull` is always exactly 16 characters long.
|
||
- All public properties (`TestObject`, `Position`, etc.) map to fixed, non-overlapping substrings of `_isoCodeFull`:
|
||
- `TestObject`: index 0
|
||
- `Position`: index 1
|
||
- `MainLocation`: indices 2–5
|
||
- `FineLocation1`: indices 6–7
|
||
- `FineLocation2`: indices 8–9
|
||
- `FineLocation3`: indices 10–11
|
||
- `PhysicalDimension`: indices 12–13
|
||
- `Direction`: index 14
|
||
- `FilterClass`: index 15
|
||
- When setting any property via its public setter:
|
||
- Short inputs are padded with `'?'` (except `StringRepresentation`, which uses `'0'`).
|
||
- Long inputs are truncated to the property’s fixed length.
|
||
- Invalid or missing characters (e.g., `null`, empty string) are normalized to `'?'` for most properties, but `'0'` may appear in `StringRepresentation` setter or internal `_mainLocation`/`_fineLocation*` setters if arrays are undersized (see *Gotchas*).
|
||
|
||
---
|
||
|
||
### 4. Dependencies
|
||
- **Internal**: Uses `System.Text.StringBuilder` (for `StringRepresentation` getter).
|
||
- **External**:
|
||
- `DTS.Common.ISO` namespace (no external NuGet or framework dependencies beyond `System`).
|
||
- **Depended on**: Not visible in source; likely consumed by higher-level location/positioning or calibration modules (e.g., device state management, test sequencing).
|
||
|
||
---
|
||
|
||
### 5. Gotchas
|
||
- **Inconsistent padding in `StringRepresentation` setter**: Unlike all other property setters, `StringRepresentation` pads short inputs with `'0'`, not `'?'`. This breaks the expected `'?'`-padding convention and may cause silent data corruption if used carelessly.
|
||
- **Undersized array handling in private setters**:
|
||
- `_mainLocation`, `_fineLocation1`, `_fineLocation2`, `_fineLocation3`, `_physicalDimension` setters use `value.Length <= i` or `value.Length < i` to decide whether to write `'0'` or `value[i]`. This is inconsistent:
|
||
- For `_mainLocation`, `value.Length <= i` (e.g., 3-char input → writes `'0'` for index 3).
|
||
- For `_fineLocation1`, `value.Length < i` (e.g., 1-char input → writes `'0'` for index 1).
|
||
→ Both produce `'0'` for missing chars, but the condition is off-by-one in `_fineLocation1`.
|
||
- **No validation of semantic meaning**: The class accepts any characters (including non-alphanumeric) and does not enforce ISO-specific character sets (e.g., digits, uppercase letters only).
|
||
- **`TestObject`, `Position`, etc. are misnamed**: `TestObject` is a property name but semantically appears to be a *test identifier* or *test type* (not an object). Likely legacy naming.
|
||
- **No immutability or thread safety**: The class is mutable and not thread-safe.
|
||
- **`StringRepresentation` setter mutates underlying array directly**: Does not validate or normalize input beyond length truncation/padding, potentially violating invariants if used after property setters (e.g., setting `StringRepresentation = "ABC"` yields `"ABC0000000000000"` instead of `"ABC???????????????"`).
|
||
- **No `Equals`/`GetHashCode`/`IEquatable` implementation**: Value equality is not defined, risking reference equality bugs.
|
||
|
||
None identified beyond the above. |