src.dackar.RCA.signal_evidence._util
====================================

.. py:module:: src.dackar.RCA.signal_evidence._util

.. autoapi-nested-parse::

   Shared helpers for the signal-evidence package.

   Centralizes the small utilities that were previously duplicated between
   ``builder.py`` and ``historian_adapter.py`` (MR#49 review), so the
   UTC-normalization rule below lives in exactly one place.



Functions
---------

.. autoapisummary::

   src.dackar.RCA.signal_evidence._util.parse_dt
   src.dackar.RCA.signal_evidence._util.clamp01


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

.. py:function:: parse_dt(value)

   Parse an ISO-8601 timestamp, normalized to a UTC-aware ``datetime``.

   A naive input (no offset, e.g. ``"2024-01-01T00:00:00"``) is assumed to
   be UTC and stamped with ``timezone.utc``, while offset-aware inputs
   (``...+00:00`` / ``...Z``) are preserved. This guarantees every downstream
   comparison and subtraction operates on offset-aware datetimes, avoiding
   ``TypeError: can't compare offset-naive and offset-aware datetimes``.

   :param value: An ISO-8601 timestamp string, or ``None``/empty.

   :returns: A UTC-aware ``datetime``, or ``None`` when *value* is empty or cannot
             be parsed.


.. py:function:: clamp01(x)

   Clamp *x* to the closed unit interval ``[0.0, 1.0]``.