pyfebiopt.xplt.binary_reader
============================

.. py:module:: pyfebiopt.xplt.binary_reader

.. autoapi-nested-parse::

   Utility for reading FEBio PLT tags via a memory-mapped file.



Classes
-------

.. autoapisummary::

   pyfebiopt.xplt.binary_reader.BinaryReader


Module Contents
---------------

.. py:class:: BinaryReader(filename: str)

   TLV reader optimized for FEBio .xplt.

   Design
   ------
   - Memory-mapped file, zero-copy slices.
   - Iterative tag scan (no recursion).
   - Integer cursor `pos` replaces file seeks.
   - Backward compatible API: `read`, `search_block`, `check_block`, `seek_block`.

   Notes:
   ------
   Tag records are stored as little-endian:
       [u32 tag][u32 size][size bytes of payload]

   Memory-map the xplt file for fast tag scanning.


   .. py:attribute:: __slots__
      :value: ('_buf', '_f', '_mm', '_tag2int', 'filesize', 'pos')



   .. py:attribute:: filesize


   .. py:attribute:: pos
      :value: 0



   .. py:method:: __repr__() -> str


   .. py:attribute:: __str__


   .. py:method:: tell() -> int

      Return the current cursor position.



   .. py:method:: seek(offset: int, whence: int = os.SEEK_SET) -> None

      Move the cursor according to the requested offset.



   .. py:method:: skip(n: int) -> None

      Advance the cursor by the requested number of bytes.



   .. py:method:: read(n: int = 4) -> bytes

      Return `n` bytes and advance.



   .. py:method:: read_u32() -> int

      Read little-endian unsigned 32-bit.

      :returns: Parsed value.
      :rtype: int



   .. py:method:: peek_u32() -> int

      Peek next u32 without advancing.

      :returns: Next 32-bit value without moving the cursor.
      :rtype: int



   .. py:method:: read_f32() -> float

      Read a little-endian float32 from the buffer.

      :returns: Parsed value.
      :rtype: float



   .. py:method:: search_block(BLOCK_TAG: str, _max_depth: int = 5, _cur_depth: int = 0, _print_tag: int = 0, print_tag: int | None = None) -> int

      Scan forward for the next tag. Return payload size or -1.

      Leaves cursor at the *payload start* of the found block.
      Restores position if not found.

      :returns: Payload size in bytes, or -1 when not found.
      :rtype: int



   .. py:method:: check_block(BLOCK_TAG: str, filesize: int = -1) -> int

      Return 1 if next header's tag equals BLOCK_TAG. Cursor unchanged.



   .. py:method:: seek_block(BLOCK_TAG: str) -> int

      Consume the next header if it matches. Return payload size.

      Cursor is left at the payload start.

      :returns: Payload size in bytes.
      :rtype: int



   .. py:method:: close() -> None

      Release resources held by the reader.



   .. py:method:: __del__() -> None

      Attempt a clean shutdown when the reader is garbage collected.