irsim.util.message
==================

.. py:module:: irsim.util.message

.. autoapi-nested-parse::

   Helpers for applying :mod:`irsim.msg` messages to simulation objects.

   These functions resolve which local objects an incoming message addresses.
   They only read the objects they are given, so a caller can validate a whole
   batch of updates before applying any of them.



Functions
---------

.. autoapisummary::

   irsim.util.message.resolve_message_targets


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

.. py:function:: resolve_message_targets(objects: collections.abc.Iterable[Any], msg: irsim.msg.WorldState | irsim.msg.ObjectState | Any, object_name: str | None = None, object_id: int | None = None, *, default_target: collections.abc.Callable[[], Any]) -> list[tuple[Any, Any]]

   Pair each incoming odometry with the distinct local object it addresses.

   A ``WorldState`` addresses every object it contains, an ``ObjectState``
   uses its embedded name and id, and a standalone odometry message goes to
   ``default_target`` unless a name or id selects another object.

   :param objects: Local objects the message can address.
   :type objects: Iterable
   :param msg: A :class:`~irsim.msg.WorldState`, an
               :class:`~irsim.msg.ObjectState`, or an odometry-shaped message.
   :param object_name: Explicit target name for a standalone odometry or
                       object message.
   :type object_name: str
   :param object_id: Explicit target id for the same messages. Names take
                     precedence when both are given.
   :type object_id: int
   :param default_target: Called only when a standalone odometry
                          selects no object; returns the object that receives it.
   :type default_target: Callable

   :returns: ``(object, odometry)`` pairs, one per addressed object.
   :rtype: list

   :raises ValueError: If a target cannot be found, a name or id is combined with
       a ``WorldState``, or one object is addressed more than once.