feat: add support for alignment in structs

MrIndeciso · MrIndeciso · commit dd6df6bb1f61 · 2026-03-31T19:42:34.000-05:00
diff --git a/SKILL.md b/SKILL.md
@@ -43,6 +43,7 @@ from libdestruct import (
     tagged_union,      # tagged union field descriptor
     offset,            # explicit field offset
     size_of,           # get size in bytes of any type/instance/field
+    alignment_of,      # get natural alignment of any type/instance
 )
 ```
 
@@ -245,6 +246,32 @@ class message_t(struct):
 
 The discriminator field must appear before the union. The union size is the max of all variant sizes. Struct variant fields are accessible directly: `msg.payload.x.value`. Use `.variant` to get the raw variant object. Unknown discriminator values raise `ValueError`.
 
+### Struct Alignment
+
+```python
+# Default: packed (no padding)
+class packed_t(struct):
+    a: c_char
+    b: c_int
+# size: 5
+
+# Aligned: natural C alignment with padding
+class aligned_t(struct):
+    _aligned_ = True
+    a: c_char
+    b: c_int
+# size: 8 (1 + 3 padding + 4)
+
+alignment_of(c_int)       # 4
+alignment_of(aligned_t)   # 4 (max member alignment)
+
+# Custom alignment width
+class wide_t(struct):
+    _aligned_ = 16
+    a: c_int
+# size: 16, alignment: 16
+```
+
 ### Explicit Field Offsets
 
 ```python
diff --git a/docs/advanced/alignment.md b/docs/advanced/alignment.md
@@ -0,0 +1,126 @@
+# Struct Alignment
+
+By default, libdestruct structs are **packed** — fields are placed sequentially with no padding, like C structs with `__attribute__((packed))`.
+
+You can opt into natural alignment (matching standard C struct layout) by setting `_aligned_ = True` on your struct:
+
+## Enabling Alignment
+
+```python
+from libdestruct import struct, c_char, c_int, c_long, size_of
+
+class packed_t(struct):
+    a: c_char
+    b: c_int
+
+size_of(packed_t)  # 5 (1 + 4, no padding)
+
+class aligned_t(struct):
+    _aligned_ = True
+    a: c_char
+    b: c_int
+
+size_of(aligned_t)  # 8 (1 + 3 padding + 4)
+```
+
+## Alignment Rules
+
+When `_aligned_ = True`:
+
+1. **Field alignment**: Each field is placed at an offset that is a multiple of its natural alignment (1 for `c_char`, 2 for `c_short`, 4 for `c_int`/`c_float`, 8 for `c_long`/`c_double`/`ptr`).
+2. **Tail padding**: The struct's total size is rounded up to a multiple of the struct's alignment (the maximum alignment of any member).
+
+```python
+class mixed_t(struct):
+    _aligned_ = True
+    a: c_char       # offset 0, size 1
+    b: c_short      # offset 2 (aligned to 2), size 2
+    c: c_char       # offset 4, size 1
+    d: c_int        # offset 8 (aligned to 4), size 4
+    e: c_char       # offset 12, size 1
+    f: c_long       # offset 16 (aligned to 8), size 8
+
+size_of(mixed_t)    # 24 (padded to 8-byte boundary)
+```
+
+## Reading Aligned Structs
+
+```python
+import struct as pystruct
+from libdestruct import inflater
+
+class header_t(struct):
+    _aligned_ = True
+    flags: c_char
+    size: c_int
+
+# flags at offset 0, 3 bytes padding, size at offset 4
+memory = pystruct.pack("<b", 0x01) + b"\x00" * 3 + pystruct.pack("<i", 1024)
+header = header_t.from_bytes(memory)
+
+print(header.flags.value)  # 1
+print(header.size.value)   # 1024
+```
+
+## Nested Aligned Structs
+
+Alignment is respected for nested structs too. A nested struct's alignment equals the maximum alignment of its own members:
+
+```python
+class inner_t(struct):
+    _aligned_ = True
+    a: c_char
+    b: c_int
+
+class outer_t(struct):
+    _aligned_ = True
+    x: c_char
+    inner: inner_t  # aligned to 4 (inner's max member alignment)
+
+size_of(inner_t)  # 8
+size_of(outer_t)  # 12 (1 + 3 padding + 8)
+```
+
+## Custom Alignment Width
+
+Set `_aligned_` to an integer to enforce a minimum alignment boundary. Fields still use natural alignment, but the struct's total size is padded to the specified boundary:
+
+```python
+class wide_t(struct):
+    _aligned_ = 16
+    a: c_int
+
+size_of(wide_t)       # 16 (4 bytes data, padded to 16-byte boundary)
+alignment_of(wide_t)  # 16
+```
+
+`_aligned_ = True` is equivalent to using the maximum natural member alignment (up to 8).
+
+## Interaction with Explicit Offsets
+
+When a field has an explicit `offset()`, alignment does **not** override the specified position. Alignment resumes for subsequent fields without explicit offsets:
+
+```python
+from libdestruct import offset
+
+class s_t(struct):
+    _aligned_ = True
+    a: c_char
+    b: c_int = offset(3)   # placed at offset 3, not rounded to 4
+    c: c_int               # aligned normally after b
+
+size_of(s_t)  # 7 (3 + 4)
+```
+
+## alignment_of()
+
+Use `alignment_of()` to query the alignment requirement of any type:
+
+```python
+from libdestruct import alignment_of, c_int, c_long
+
+alignment_of(c_int)      # 4
+alignment_of(c_long)     # 8
+alignment_of(aligned_t)  # max member alignment
+alignment_of(packed_t)   # 1 (packed structs have alignment 1)
+```
diff --git a/libdestruct/__init__.py b/libdestruct/__init__.py
@@ -20,11 +20,12 @@
 from libdestruct.common.ptr.ptr import ptr
 from libdestruct.common.struct import ptr_to, ptr_to_self, struct
 from libdestruct.common.union import tagged_union, union, union_of
-from libdestruct.common.utils import size_of
+from libdestruct.common.utils import alignment_of, size_of
 from libdestruct.libdestruct import inflate, inflater
 
 __all__ = [
     "Resolver",
+    "alignment_of",
     "array",
     "array_of",
     "bitfield_of",
diff --git a/libdestruct/common/struct/struct_impl.py b/libdestruct/common/struct/struct_impl.py
@@ -18,7 +18,7 @@
 from libdestruct.common.obj import obj
 from libdestruct.common.struct import struct
 from libdestruct.common.type_registry import TypeRegistry
-from libdestruct.common.utils import iterate_annotation_chain, size_of
+from libdestruct.common.utils import _align_offset, alignment_of, iterate_annotation_chain, size_of
 
 
 class struct_impl(struct):
@@ -79,8 +79,12 @@ def _inflate_struct_attributes(
     ) -> None:
         current_offset = 0
         bf_tracker = BitfieldTracker()
+        aligned = getattr(reference_type, "_aligned_", False)
 
         for name, annotation, reference in iterate_annotation_chain(reference_type, terminate_at=struct):
+            if name == "_aligned_":
+                continue
+
             resolved_type, bitfield_field, explicit_offset = self._resolve_field(
                 name, annotation, reference, inflater, reference_type,
             )
@@ -97,6 +101,8 @@ def _inflate_struct_attributes(
                 current_offset += offset_delta
             else:
                 current_offset += bf_tracker.flush()
+                if aligned and explicit_offset is None:
+                    current_offset = _align_offset(current_offset, alignment_of(resolved_type))
                 result = resolved_type(resolver.relative_from_own(current_offset, 0))
                 current_offset += size_of(result)
 
@@ -154,11 +160,17 @@ def _resolve_field(
     def compute_own_size(cls: type[struct_impl], reference_type: type) -> None:
         """Compute the size of the struct."""
         size = 0
+        max_alignment = 1
         bf_tracker = BitfieldTracker()
+        aligned = getattr(reference_type, "_aligned_", False)
 
         for name, annotation, reference in iterate_annotation_chain(reference_type, terminate_at=struct):
+            if name == "_aligned_":
+                continue
+
             bitfield_field = None
             attribute = None
+            has_explicit_offset = False
 
             if name in reference.__dict__:
                 attrs = getattr(reference, name)
@@ -174,6 +186,7 @@ def compute_own_size(cls: type[struct_impl], reference_type: type) -> None:
                     elif isinstance(attr, Field):
                         attribute = cls._inflater.inflater_for((attr, annotation), (None, cls))(None)
                     elif isinstance(attr, OffsetAttribute):
+                        has_explicit_offset = True
                         offset = attr.offset
                         if offset < size:
                             raise ValueError("Offset must be greater than the current size.")
@@ -190,10 +203,21 @@ def compute_own_size(cls: type[struct_impl], reference_type: type) -> None:
                 size += bf_tracker.compute_size(bitfield_field)
             else:
                 size += bf_tracker.flush()
+                if aligned and not has_explicit_offset:
+                    field_align = alignment_of(attribute)
+                    max_alignment = max(max_alignment, field_align)
+                    size = _align_offset(size, field_align)
                 size += size_of(attribute)
 
         size += bf_tracker.flush()
+
+        if aligned:
+            if isinstance(aligned, int) and aligned is not True:
+                max_alignment = max(max_alignment, aligned)
+            size = _align_offset(size, max_alignment)
+
         cls.size = size
+        cls.alignment = max_alignment if aligned else 1
 
     @property
     def address(self: struct_impl) -> int:
diff --git a/libdestruct/common/utils.py b/libdestruct/common/utils.py
@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import sys
 from types import MethodType
 from typing import TYPE_CHECKING, Any, ForwardRef
@@ -56,6 +57,58 @@ def size_of(item_or_inflater: obj | callable[[Resolver], obj]) -> int:
     raise ValueError(f"Cannot determine the size of {item_or_inflater}")
 
 
+def alignment_of(item: obj | type[obj]) -> int:
+    """Return the natural alignment of a type or instance.
+
+    For primitive types, alignment equals their size (1, 2, 4, or 8).
+    For struct types, alignment is computed as the max of member alignments.
+    For packed structs (the default), alignment is 1.
+    """
+    # For uninflated struct types, trigger inflation first so alignment is computed
+    if isinstance(item, type) and not hasattr(item, "size") and not hasattr(item, "_type_impl"):
+        with contextlib.suppress(ValueError, TypeError):
+            size_of(item)
+
+    # Struct types with computed alignment
+    if isinstance(item, type) and hasattr(item, "_type_impl"):
+        impl = item._type_impl
+        if hasattr(impl, "alignment"):
+            return impl.alignment
+
+    # Explicit alignment attribute (struct_impl instances, arrays, etc.)
+    if not isinstance(item, type) and hasattr(item, "alignment") and isinstance(item.alignment, int):
+        return item.alignment
+    if isinstance(item, type) and "alignment" in item.__dict__ and isinstance(item.__dict__["alignment"], int):
+        return item.__dict__["alignment"]
+
+    # Field descriptors
+    if isinstance(item, Field):
+        return _alignment_from_size(item.get_size())
+    if is_field_bound_method(item):
+        return _alignment_from_size(item.__self__.get_size())
+
+    # Derive from size for power-of-2 sized types
+    try:
+        s = size_of(item)
+        return _alignment_from_size(s)
+    except (ValueError, TypeError):
+        return 1
+
+
+def _alignment_from_size(s: int) -> int:
+    """Derive alignment from size: return size if it's a power of 2 and <= 8, else 1."""
+    max_alignment = 8
+    if s > 0 and (s & (s - 1)) == 0 and s <= max_alignment:
+        return s
+    return 1
+
+
+def _align_offset(offset: int, alignment: int) -> int:
+    """Round up offset to the next multiple of alignment."""
+    remainder = offset % alignment
+    return offset + (alignment - remainder) if remainder else offset
+
+
 def _resolve_annotation(annotation: Any, defining_class: type) -> Any:
     """Resolve a string annotation to its actual type.
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -67,4 +67,5 @@ nav:
     - Forward References: advanced/forward_refs.md
     - Hex Dump: advanced/hexdump.md
     - Unions: advanced/tagged_unions.md
+    - Struct Alignment: advanced/alignment.md
     - Field Offsets: advanced/offset.md
diff --git a/test/scripts/alignment_test.py b/test/scripts/alignment_test.py
