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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.CommonCore/Classes/ISO/IsoCode.cs	2026-04-16T02:39:28.985647+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.