sltcodec 2.3.0__tar.gz → 2.4.1__tar.gz

{sltcodec-2.3.0 → sltcodec-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sltcodec
-Version: 2.3.0
+Version: 2.4.1
 Summary: Decode and encode bytearrays according to struct layout definitions using sltcore.
 Project-URL: Homepage, https://github.com/fangface-hub/StructLayoutToolkitCodec
 Project-URL: Documentation, https://readthedocs.org
@@ -69,6 +69,11 @@ decoded layout. `decode_field` stores the actual decoded size in the returned
 from the nested `StructInstance.size`; for repeated fields, the next element's
 offset advances by the actual size of the previous element.
 
+`FieldDef.repeat` also accepts the special string value `"end"`. When
+`repeat="end"`, decoding repeats until the input bytearray ends. Decoding
+stops when the next element offset is out of range or when the next element
+size would exceed the remaining input.
+
 ## Field Types
 
 The public `PRIMITIVE_TYPES` set contains:
@@ -180,7 +185,7 @@ internal implementation details and are omitted from the public method tables.
 | `size` | `InfoSize \| str` | Static size or expression. |
 | `type` | `str \| StructDef` | Primitive, named, or nested field type. |
 | `scale` | `float` | Numeric scale applied to the field. |
-| `repeat` | `int \| str \| None` | Number of repeated field values, or an expression that evaluates to the count. |
+| `repeat` | `int \| str \| None` | Number of repeated field values, an expression that evaluates to the count, or `"end"` to decode repeatedly until input end. |
 | `description` | `str \| None` | Optional field description. |
 | `range_expression` | `str \| None` | Optional value-range expression. |
 | `enum_def_name` | `str \| None` | Name of the associated enum definition. |
@@ -220,6 +225,8 @@ internal implementation details and are omitted from the public method tables.
 
 | Method | Description |
 | --- | --- |
+| `get_field(struct_def_name)` | Return the first field whose `type` references the given structure name. |
+| `get_fields(struct_def_name)` | Return all fields whose `type` references the given structure name. |
 | `to_dict()` | Convert the definition to a JSON-compatible dictionary. |
 | `to_json()` | Convert the definition to a JSON string. |
 | `from_dict(data)` | Create a `StructDef` from a dictionary or legacy field list. |
@@ -238,6 +245,8 @@ internal implementation details and are omitted from the public method tables.
 | --- | --- |
 | `append_field_instance(field_instance)` | Append one field instance. |
 | `extend_field_instances(field_instances)` | Append multiple field instances. |
+| `get_field(field_def_name)` | Return the first field instance whose `field_def.name` matches. |
+| `get_fields(field_def_name)` | Return all field instances whose `field_def.name` matches. |
 | `__iter__()` | Iterate over field instances. |
 | `__len__()` | Return the number of field instances. |
 | `__getitem__(index)` | Get a field instance by index. |

{sltcodec-2.3.0 → sltcodec-2.4.1}/README.md

@@ -80,6 +80,20 @@ stores the actual size in `FieldInstance.field_def.size`. For nested structures,
 the nested `StructInstance.size` is used; repeated fields advance each next
 offset by the preceding element's actual size.
 
+`FieldDef.repeat` also supports the special string value `"end"`.
+When `repeat="end"`, decoding repeats until the input bytearray ends.
+The decoder stops when the next element offset is out of range or when the
+next element size would exceed the remaining input.
+
+`StructDef` and `StructInstance` provide indexed accessors:
+
+- `get_field(name)`: return the first matching item, or `None`.
+- `get_fields(name)`: return all matching items as a list.
+
+For `StructDef`, these accessors resolve by referenced structure name in
+`FieldDef.type` (non-primitive types only). For `StructInstance`, they resolve
+by `FieldInstance.field_def.name`.
+
 ## Versioning And Release
 
 Version bump scripts are provided for patch, minor, and major releases:

{sltcodec-2.3.0 → sltcodec-2.4.1}/README_pypi.md

@@ -52,6 +52,11 @@ decoded layout. `decode_field` stores the actual decoded size in the returned
 from the nested `StructInstance.size`; for repeated fields, the next element's
 offset advances by the actual size of the previous element.
 
+`FieldDef.repeat` also accepts the special string value `"end"`. When
+`repeat="end"`, decoding repeats until the input bytearray ends. Decoding
+stops when the next element offset is out of range or when the next element
+size would exceed the remaining input.
+
 ## Field Types
 
 The public `PRIMITIVE_TYPES` set contains:
@@ -163,7 +168,7 @@ internal implementation details and are omitted from the public method tables.
 | `size` | `InfoSize \| str` | Static size or expression. |
 | `type` | `str \| StructDef` | Primitive, named, or nested field type. |
 | `scale` | `float` | Numeric scale applied to the field. |
-| `repeat` | `int \| str \| None` | Number of repeated field values, or an expression that evaluates to the count. |
+| `repeat` | `int \| str \| None` | Number of repeated field values, an expression that evaluates to the count, or `"end"` to decode repeatedly until input end. |
 | `description` | `str \| None` | Optional field description. |
 | `range_expression` | `str \| None` | Optional value-range expression. |
 | `enum_def_name` | `str \| None` | Name of the associated enum definition. |
@@ -203,6 +208,8 @@ internal implementation details and are omitted from the public method tables.
 
 | Method | Description |
 | --- | --- |
+| `get_field(struct_def_name)` | Return the first field whose `type` references the given structure name. |
+| `get_fields(struct_def_name)` | Return all fields whose `type` references the given structure name. |
 | `to_dict()` | Convert the definition to a JSON-compatible dictionary. |
 | `to_json()` | Convert the definition to a JSON string. |
 | `from_dict(data)` | Create a `StructDef` from a dictionary or legacy field list. |
@@ -221,6 +228,8 @@ internal implementation details and are omitted from the public method tables.
 | --- | --- |
 | `append_field_instance(field_instance)` | Append one field instance. |
 | `extend_field_instances(field_instances)` | Append multiple field instances. |
+| `get_field(field_def_name)` | Return the first field instance whose `field_def.name` matches. |
+| `get_fields(field_def_name)` | Return all field instances whose `field_def.name` matches. |
 | `__iter__()` | Iterate over field instances. |
 | `__len__()` | Return the number of field instances. |
 | `__getitem__(index)` | Get a field instance by index. |

{sltcodec-2.3.0 → sltcodec-2.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sltcodec"
-version = "2.3.0"
+version = "2.4.1"
 description = "Decode and encode bytearrays according to struct layout definitions using sltcore."
 readme = "README_pypi.md"
 requires-python = ">=3.12"

{sltcodec-2.3.0 → sltcodec-2.4.1}/src/sltcodec/codec.py

@@ -134,8 +134,20 @@ def load_enum_def_dict(path: str | Path) -> dict[str, EnumDef]:
 def _resolve_info_size(value: InfoSize | str, env: dict[str, Any]) -> InfoSize:
     """Resolve an InfoSize value that can be static or expression-based."""
     if isinstance(value, str):
-        stleval = SltEval(env)
-        resolved_byte = stleval.eval(value)
+        eval_env = dict(env)
+
+        def replace_info_size(match: re.Match[str]) -> str:
+            name = f"_info_size_{len(eval_env)}"
+            eval_env[name] = InfoSize(int(match.group(1)), int(match.group(2)))
+            return name
+
+        expression = re.sub(
+            r"\bInfoSize\s*\(\s*(-?\d+)\s*,\s*(-?\d+)\s*\)",
+            replace_info_size,
+            value,
+        )
+        stleval = SltEval(eval_env)
+        resolved_byte = stleval.eval(expression)
         if isinstance(resolved_byte, InfoSize):
             return resolved_byte
         return InfoSize(resolved_byte, 0)
@@ -152,6 +164,8 @@ def _resolve_byte_swap(field_def: FieldDef, env: dict[str, Any]) -> bool:
 def _resolve_repeat(value: int | str | None, env: dict[str, Any]) -> int | None:
     """Resolve a static or expression-based repeat count."""
     if isinstance(value, str):
+        if value == "end":
+            return None
         return int(SltEval(env).eval(value))
     return value
 
@@ -162,6 +176,13 @@ def _is_padding_field_def(field_def: FieldDef) -> bool:
             and field_def.type in ["bytes", "bytearray"])
 
 
+def _struct_def_has_dynamic_extent(struct_def: StructDef) -> bool:
+    """Check whether a nested structure can consume data beyond its fields."""
+    return any(field_def.repeat == "end" or isinstance(field_def.offset, str)
+               or isinstance(field_def.size, str)
+               for field_def in struct_def.fields)
+
+
 def _validate_padding_alignment_bits(padding_alignment_bits: int) -> None:
     """Validate padding alignment as a positive power-of-two bit size."""
     if (isinstance(padding_alignment_bits, bool)
@@ -335,6 +356,7 @@ def encode(
 
     for field_value in struct_instance.field_instances:
         field_def = field_value.field_def
+        repeat_until_end = field_def.repeat == "end"
         repeat = _resolve_repeat(field_def.repeat, env)
         if _is_padding_field_def(field_def):
             has_padding = True
@@ -342,9 +364,12 @@ def encode(
         if _is_padding_field_def(field_def):
             padding_size = _resolve_info_size(field_def.size, env)
             value = bytearray(padding_size.bytes)
+        if repeat_until_end:
+            repeat_values = list(value)
+            repeat = len(repeat_values)
         if repeat is not None and repeat > 1:
             current_offset = _resolve_info_size(field_def.offset, env)
-            values = list(value)
+            values = repeat_values if repeat_until_end else list(value)
 
             for i in range(repeat):
                 field_def_repeat = _repeated_field_def(field_def, i,
@@ -409,7 +434,10 @@ def decode_field(
         nested_layout = _layout_for_struct_def(resolved_type,
                                                type_dict,
                                                name=field_def.name)
-        nested_value = decode(nested_layout, bytearray(info.to_bytes),
+        nested_data = bytearray(info.to_bytes)
+        if _struct_def_has_dynamic_extent(resolved_type) and offset.bit == 0:
+            nested_data = bytearray(data[offset.byte:])
+        nested_value = decode(nested_layout, nested_data,
                               padding_alignment_bits)
         actual_size = nested_value.size
     else:
@@ -508,6 +536,27 @@ def decode(
     result = StructInstance(struct_def=struct_def_obj)
     current_position = InfoSize(0, 0)
     padding_index = 0
+    stop_due_to_out_of_range = False
+    data_bits = len(data) * 8
+    field_defs = _as_field_defs(struct_def_obj)
+
+    def is_out_of_range(offset: InfoSize, size: InfoSize) -> bool:
+        """Check whether the field range exceeds available input bits."""
+        if size.bits <= 0:
+            return False
+        if offset.bits < 0:
+            return True
+        if offset.bits >= data_bits:
+            return True
+        return offset.bits + size.bits > data_bits
+
+    def append_none_tail(start_index: int, first_field_def: FieldDef) -> None:
+        """Append current and remaining fields with None values."""
+        result.field_instances.append(
+            FieldInstance(field_def=first_field_def, value=None))
+        for tail_field_def in field_defs[start_index + 1:]:
+            result.field_instances.append(
+                FieldInstance(field_def=tail_field_def, value=None))
 
     def append_padding_until(target_offset: InfoSize) -> None:
         nonlocal current_position, padding_index
@@ -537,11 +586,18 @@ def decode(
 
         current_position = target_offset
 
-    for field_def in _as_field_defs(struct_def_obj):
-        repeat = _resolve_repeat(field_def.repeat, env)
+    for field_index, field_def in enumerate(field_defs):
+        repeat_until_end = field_def.repeat == "end"
+        repeat = (None if repeat_until_end else _resolve_repeat(
+            field_def.repeat, env))
         # Handle non-repeated fields
-        if repeat is None or repeat <= 1:
+        if not repeat_until_end and (repeat is None or repeat <= 1):
             resolved_offset = _resolve_info_size(field_def.offset, env)
+            resolved_size = _resolve_info_size(field_def.size, env)
+            if is_out_of_range(resolved_offset, resolved_size):
+                append_none_tail(field_index, field_def)
+                stop_due_to_out_of_range = True
+                break
             append_padding_until(resolved_offset)
             field_instance = decode_field(field_def, data, env, type_dict,
                                           padding_alignment_bits)
@@ -553,10 +609,79 @@ def decode(
             continue
         # Handle repeated fields
         current_offset = _resolve_info_size(field_def.offset, env)
-        append_padding_until(current_offset)
+        if repeat_until_end:
+            stop_decoding = False
+            i = 0
+            while True:
+                if current_offset.bits >= data_bits:
+                    if i == 0:
+                        append_none_tail(
+                            field_index,
+                            _repeated_field_def(field_def, i, current_offset,
+                                                field_def.size),
+                        )
+                        stop_decoding = True
+                    break
+
+                append_padding_until(current_offset)
+
+                field_def_repeat = _repeated_field_def(field_def, i,
+                                                       current_offset,
+                                                       field_def.size)
+                resolved_size = _resolve_info_size(field_def_repeat.size, env)
+                if resolved_size.bits <= 0:
+                    break
+                if is_out_of_range(current_offset, resolved_size):
+                    if i == 0:
+                        append_none_tail(field_index, field_def_repeat)
+                        stop_decoding = True
+                    break
+
+                field_instance = decode_field(field_def_repeat, data, env,
+                                              type_dict, padding_alignment_bits)
+                if field_instance is not None:
+                    env[field_instance.field_def.name] = field_instance.value
+                    result.append_field_instance(field_instance)
+                    actual_size = field_instance.field_def.size
+                else:
+                    actual_size = resolved_size
+
+                if isinstance(current_offset, InfoSize) and isinstance(
+                        actual_size, InfoSize):
+                    current_offset += actual_size
+                    current_position = current_offset
+                i += 1
+            if stop_decoding:
+                stop_due_to_out_of_range = True
+                break
+            continue
+
         for i in range(repeat):
             field_def_repeat = _repeated_field_def(field_def, i, current_offset,
                                                    field_def.size)
+            resolved_size = _resolve_info_size(field_def_repeat.size, env)
+            if is_out_of_range(current_offset, resolved_size):
+                result.field_instances.append(
+                    FieldInstance(field_def=field_def_repeat, value=None))
+                next_offset = current_offset
+                for remaining_index in range(i + 1, repeat):
+                    if isinstance(next_offset, InfoSize):
+                        next_offset += resolved_size
+                    remaining_field_def = _repeated_field_def(
+                        field_def,
+                        remaining_index,
+                        next_offset,
+                        field_def.size,
+                    )
+                    result.field_instances.append(
+                        FieldInstance(field_def=remaining_field_def,
+                                      value=None))
+                for tail_field_def in field_defs[field_index + 1:]:
+                    result.field_instances.append(
+                        FieldInstance(field_def=tail_field_def, value=None))
+                stop_due_to_out_of_range = True
+                break
+            append_padding_until(current_offset)
             field_instance = decode_field(field_def_repeat, data, env,
                                           type_dict, padding_alignment_bits)
             if field_instance is not None:
@@ -569,6 +694,15 @@ def decode(
                     actual_size, InfoSize):
                 current_offset += actual_size
                 current_position = current_offset
+        else:
+            continue
+        break
+
+    if stop_due_to_out_of_range:
+        result._sort_field_instances()
+        result._update_size()
+        result._rebuild_field_def_name_index()
+        return result
 
     actual_size = InfoSize(0, 0)
     for field_instance in result.field_instances:

{sltcodec-2.3.0 → sltcodec-2.4.1}/src/sltcodec/types.py

@@ -10,6 +10,16 @@ from typing import Any, Dict, Iterator, Optional
 from sltcalc import SltEval
 from sltcore import Info, InfoSize
 
+_PRIMITIVE_FIELD_TYPES = {
+    "bool",
+    "signed int",
+    "int",
+    "unsigned int",
+    "float",
+    "bytearray",
+    "bytes",
+}
+
 
 @total_ordering
 @dataclass(frozen=True)
@@ -367,6 +377,16 @@ class StructDef:
         default_factory=list,
         metadata={"desc": "The fields of the structure"},
     )
+    _fields_by_struct_def_name: dict[str, list[FieldDef]] = field(
+        default_factory=dict,
+        init=False,
+        repr=False,
+        compare=False,
+    )
+
+    def __post_init__(self) -> None:
+        """Build field index grouped by referenced struct definition name."""
+        self._rebuild_struct_def_name_index()
 
     def __lt__(self, other: object) -> bool:
         """Compare structure definitions using a stable serialized sort key."""
@@ -383,6 +403,42 @@ class StructDef:
                        sort_keys=True),
         )
 
+    def get_fields(self, struct_def_name: str) -> list[FieldDef]:
+        """Return fields that reference the given struct definition name."""
+        self._rebuild_struct_def_name_index()
+        return list(self._fields_by_struct_def_name.get(struct_def_name, []))
+
+    def get_field(self, struct_def_name: str) -> FieldDef | None:
+        """Return the first field that references the given name."""
+        self._rebuild_struct_def_name_index()
+        fields = self._fields_by_struct_def_name.get(struct_def_name)
+        if not fields:
+            return None
+        return fields[0]
+
+    @staticmethod
+    def _field_struct_def_name(field_def: FieldDef) -> str | None:
+        """Resolve struct definition name referenced by a field type."""
+        field_type = field_def.type
+        if isinstance(field_type, StructDef):
+            return field_type.name or None
+        if (isinstance(field_type, str) and field_type
+                and field_type not in _PRIMITIVE_FIELD_TYPES):
+            return field_type
+        return None
+
+    def _rebuild_struct_def_name_index(self) -> None:
+        """Rebuild struct_def_name index from current fields."""
+        fields_by_name: dict[str, list[FieldDef]] = {}
+        for field_def in self.fields:
+            struct_def_name = self._field_struct_def_name(field_def)
+            if struct_def_name is None:
+                continue
+            if struct_def_name not in fields_by_name:
+                fields_by_name[struct_def_name] = []
+            fields_by_name[struct_def_name].append(field_def)
+        object.__setattr__(self, "_fields_by_struct_def_name", fields_by_name)
+
     def to_dict(self) -> dict[str, Any]:
         """Convert this structure definition to JSON-serializable data."""
         return {
@@ -432,6 +488,11 @@ class StructInstance:
         default_factory=InfoSize,
         metadata={"desc": "The total size of the structure instance"},
     )
+    _field_instances_by_field_def_name: dict[str, list[FieldInstance]] = field(
+        default_factory=dict,
+        init=False,
+        repr=False,
+    )
 
     def __post_init__(self) -> None:
         """Normalize stored field instances to sorted order."""
@@ -469,6 +530,19 @@ class StructInstance:
         """Return one field instance by index."""
         return self.field_instances[index]
 
+    def get_fields(self, field_def_name: str) -> list[FieldInstance]:
+        """Return field instances that match the given field definition name."""
+        return list(
+            self._field_instances_by_field_def_name.get(field_def_name, []))
+
+    def get_field(self, field_def_name: str) -> FieldInstance | None:
+        """Return the first field instance that matches the given name."""
+        field_instances = self._field_instances_by_field_def_name.get(
+            field_def_name)
+        if not field_instances:
+            return None
+        return field_instances[0]
+
     def __lt__(self, other: object) -> bool:
         """Compare structure instances using a stable serialized sort key."""
         if not isinstance(other, StructInstance):
@@ -490,6 +564,16 @@ class StructInstance:
         """Keep field instances sorted by FieldDef order."""
         self.field_instances.sort()
 
+    def _rebuild_field_def_name_index(self) -> None:
+        """Rebuild field_def.name index from current field instances."""
+        field_instances_by_name: dict[str, list[FieldInstance]] = {}
+        for field_instance in self.field_instances:
+            field_def_name = field_instance.field_def.name
+            if field_def_name not in field_instances_by_name:
+                field_instances_by_name[field_def_name] = []
+            field_instances_by_name[field_def_name].append(field_instance)
+        self._field_instances_by_field_def_name = field_instances_by_name
+
     def _rebuild_padding_field_instances(self) -> None:
         """Rebuild padding field instances for gaps between stored values."""
         non_padding_instances = [
@@ -507,6 +591,7 @@ class StructInstance:
             self.field_instances = non_padding_instances
             self._sort_field_instances()
             self._update_size()
+            self._rebuild_field_def_name_index()
             return
 
         rebuilt_instances: list[FieldInstance] = []
@@ -555,6 +640,7 @@ class StructInstance:
         self.field_instances = rebuilt_instances
         self._sort_field_instances()
         self._update_size()
+        self._rebuild_field_def_name_index()
 
     def _update_size(self) -> None:
         """Update the instance size from the current field layout."""

{sltcodec-2.3.0 → sltcodec-2.4.1}/tests/test_codec.py

@@ -198,6 +198,122 @@ def test_expression_repeat_uses_previous_field_value():
             for instance in decoded.field_instances] == [2, 5, 6, 7]
 
 
+def test_repeat_end_decodes_until_bytearray_end():
+    """Test repeat='end' decodes values until the input bytearray ends."""
+    field_def = FieldDef(name="value",
+                         offset=InfoSize(0, 0),
+                         size=InfoSize(1, 0),
+                         type="unsigned int",
+                         repeat="end")
+
+    decoded = decode(layout_for([field_def]), bytearray(b"\x01\x02\x03"))
+
+    assert [instance.field_def.name
+            for instance in decoded.field_instances] == [
+                "value[0]",
+                "value[1]",
+                "value[2]",
+            ]
+    assert [instance.value for instance in decoded.field_instances] == [1, 2, 3]
+
+
+def test_repeat_end_stops_when_offset_is_out_of_range():
+    """Test repeat='end' stops when next element offset is out of range."""
+    field_def = FieldDef(name="value",
+                         offset=InfoSize(4, 0),
+                         size=InfoSize(1, 0),
+                         type="unsigned int",
+                         repeat="end")
+
+    decoded = decode(layout_for([field_def]), bytearray(b"\x01\x02\x03"))
+
+    assert [instance.field_def.name
+            for instance in decoded.field_instances] == ["value[0]"]
+    assert [instance.value for instance in decoded.field_instances] == [None]
+
+
+def test_info_size_expression_resolves_constructor():
+    """Test that serialized InfoSize constructors work in expressions."""
+    resolved = _resolve_info_size("InfoSize(1, 0) * count", {"count": 3})
+
+    assert resolved == InfoSize(3, 0)
+
+
+def test_repeat_end_uses_dynamic_nested_struct_size():
+    """Test repeat='end' advances by a variable-size nested structure."""
+    length_field = FieldDef(name="length",
+                            offset=InfoSize(0, 0),
+                            size=InfoSize(1, 0),
+                            type="unsigned int")
+    payload_field = FieldDef(name="payload",
+                             offset=InfoSize(1, 0),
+                             size="InfoSize(1, 0) * length",
+                             type="bytearray")
+    record_field = FieldDef(
+        name="record",
+        offset=InfoSize(0, 0),
+        size=InfoSize(1, 0),
+        type=StructDef(fields=[length_field, payload_field]),
+        repeat="end")
+
+    decoded = decode(layout_for([record_field]), bytearray(b"\x02ab\x01c"))
+
+    assert [instance.field_def.name for instance in decoded.field_instances
+            ] == ["record[0]", "record[1]"]
+    assert [instance.value.size for instance in decoded.field_instances
+            ] == [InfoSize(3, 0), InfoSize(2, 0)]
+
+
+def test_decode_out_of_range_sets_current_and_tail_values_to_none():
+    """Test out-of-range decode fills current/tail field values with None."""
+    fields = [
+        FieldDef(name="head",
+                 offset=InfoSize(0, 0),
+                 size=InfoSize(1, 0),
+                 type="unsigned int"),
+        FieldDef(name="far",
+                 offset=InfoSize(10, 0),
+                 size=InfoSize(1, 0),
+                 type="unsigned int"),
+        FieldDef(name="tail",
+                 offset=InfoSize(11, 0),
+                 size=InfoSize(1, 0),
+                 type="unsigned int"),
+    ]
+
+    decoded = decode(layout_for(fields), bytearray(b"\x11"))
+
+    assert [instance.field_def.name
+            for instance in decoded.field_instances] == ["head", "far", "tail"]
+    assert [instance.value
+            for instance in decoded.field_instances] == [17, None, None]
+
+
+def test_decode_out_of_range_skips_following_field_expression_evaluation():
+    """Test out-of-range decode skips evaluating following expressions."""
+    fields = [
+        FieldDef(name="head",
+                 offset=InfoSize(0, 0),
+                 size=InfoSize(1, 0),
+                 type="unsigned int"),
+        FieldDef(name="far",
+                 offset=InfoSize(10, 0),
+                 size=InfoSize(1, 0),
+                 type="unsigned int"),
+        FieldDef(name="tail",
+                 offset="1 / 0",
+                 size=InfoSize(1, 0),
+                 type="unsigned int"),
+    ]
+
+    decoded = decode(layout_for(fields), bytearray(b"\x11"))
+
+    assert [instance.field_def.name
+            for instance in decoded.field_instances] == ["head", "far", "tail"]
+    assert [instance.value
+            for instance in decoded.field_instances] == [17, None, None]
+
+
 def test_encode_recurses_for_nested_field_types():
     """Test that encoding a field with a nested field type works correctly."""
     child_field_defs = [

{sltcodec-2.3.0 → sltcodec-2.4.1}/tests/test_types.py

@@ -288,6 +288,42 @@ def test_struct_def_to_json_from_json_round_trip():
     assert restored == struct_def
 
 
+def test_struct_def_struct_def_name_accessors_use_fields_index():
+    """Test StructDef field accessors grouped by struct_def_name."""
+    nested_struct = StructDef(name="Nested", fields=[])
+    primitive_field = FieldDef(name="value",
+                               offset=InfoSize(0, 0),
+                               size=InfoSize(1, 0),
+                               type="unsigned int")
+    nested_field = FieldDef(name="nested",
+                            offset=InfoSize(1, 0),
+                            size=InfoSize(1, 0),
+                            type=nested_struct)
+    named_nested_a = FieldDef(name="payload_a",
+                              offset=InfoSize(2, 0),
+                              size=InfoSize(1, 0),
+                              type="Payload")
+    named_nested_b = FieldDef(name="payload_b",
+                              offset=InfoSize(3, 0),
+                              size=InfoSize(1, 0),
+                              type="Payload")
+    struct_def = StructDef(fields=[
+        primitive_field,
+        nested_field,
+        named_nested_a,
+        named_nested_b,
+    ])
+
+    assert struct_def.get_field("Nested") == nested_field
+    assert struct_def.get_fields("Payload") == [
+        named_nested_a,
+        named_nested_b,
+    ]
+    assert struct_def.get_field("missing") is None
+    assert struct_def.get_fields("missing") == []
+    assert struct_def.get_fields("unsigned int") == []
+
+
 def test_struct_instance_field_instance_interface():
     """Test StructInstance interface for field_instances operations."""
     field_def_0 = FieldDef(name="b",
@@ -359,6 +395,50 @@ def test_struct_instance_rebuilds_padding_when_field_instances_change():
     assert struct_instance.field_instances[1].value == b"\x00"
 
 
+def test_struct_instance_field_def_name_accessors_use_index():
+    """Test accessors return field instances indexed by field_def.name."""
+    field_def_a = FieldDef(name="a",
+                           offset=InfoSize(0, 0),
+                           size=InfoSize(1, 0),
+                           type="unsigned int")
+    field_def_b = FieldDef(name="b",
+                           offset=InfoSize(1, 0),
+                           size=InfoSize(1, 0),
+                           type="unsigned int")
+    struct_instance = StructInstance(
+        struct_def=StructDef(fields=[field_def_a, field_def_b]),
+        field_instances=[
+            FieldInstance(field_def_b, 2),
+            FieldInstance(field_def_a, 1),
+        ],
+    )
+
+    assert struct_instance.get_field("a") == (FieldInstance(field_def_a, 1))
+    assert struct_instance.get_fields("b") == [FieldInstance(field_def_b, 2)]
+    assert struct_instance.get_field("missing") is None
+    assert struct_instance.get_fields("missing") == []
+
+
+def test_struct_instance_field_def_name_index_updates_after_append_and_extend():
+    """Test name index is refreshed after append/extend operations."""
+    field_def_a = FieldDef(name="a",
+                           offset=InfoSize(0, 0),
+                           size=InfoSize(1, 0),
+                           type="unsigned int")
+    field_def_b = FieldDef(name="b",
+                           offset=InfoSize(1, 0),
+                           size=InfoSize(1, 0),
+                           type="unsigned int")
+    struct_instance = StructInstance(struct_def=StructDef(
+        fields=[field_def_a, field_def_b]))
+
+    struct_instance.append_field_instance(FieldInstance(field_def_a, 1))
+    struct_instance.extend_field_instances([FieldInstance(field_def_b, 2)])
+
+    assert struct_instance.get_field("a") == (FieldInstance(field_def_a, 1))
+    assert struct_instance.get_fields("b") == [FieldInstance(field_def_b, 2)]
+
+
 def test_field_instance_sort_uses_field_def_order():
     """Test that FieldInstance sorting delegates to FieldDef ordering."""
     later = FieldInstance(

{sltcodec-2.3.0 → sltcodec-2.4.1}/uv.lock

@@ -74,7 +74,7 @@ wheels = [
 
 [[package]]
 name = "sltcodec"
-version = "2.2.0"
+version = "2.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "sltcalc" },