.. _stdlib_strudel_time:

=============================================================
Cycle-space time primitives: TimeSpan, Hap, and cycle helpers
=============================================================

.. das:module:: strudel_time

Module strudel_time



++++++++++
Structures
++++++++++

.. _struct-strudel_time-TimeSpan:

.. das:attribute:: TimeSpan

:Fields: * **start** : double - Inclusive start position in cycles.

         * **stop** : double - Exclusive end position in cycles.



.. _struct-strudel_time-Hap:

.. das:attribute:: Hap

:Fields: * **whole** :  :ref:`TimeSpan <struct-strudel_time-TimeSpan>` - Ideal full span of the event (full note duration).

         * **part** :  :ref:`TimeSpan <struct-strudel_time-TimeSpan>` - Portion of `whole` visible in the current query window.

         * **has_whole** : bool = true - False for continuous events that have no discrete onset (e.g. signals).

         * **value** :  :ref:`Event <struct-strudel_event-Event>` - The event payload (what to play and how).




++++++++++
Cycle math
++++++++++

  *  :ref:`cyclePos (t: double) : double <function-strudel_time_cyclePos_double>`
  *  :ref:`sameCycle (t: double) : double <function-strudel_time_sameCycle_double>`
  *  :ref:`splitSpans (span: TimeSpan) : array\<TimeSpan\> <function-strudel_time_splitSpans_TimeSpan>`

.. _function-strudel_time_cyclePos_double:

.. das:function:: cyclePos(t: double) : double

Fractional position within the current cycle (0.0–1.0).


:Arguments: * **t** : double

.. _function-strudel_time_sameCycle_double:

.. das:function:: sameCycle(t: double) : double

Cycle number containing time position `t` (integer part as double).


:Arguments: * **t** : double

.. _function-strudel_time_splitSpans_TimeSpan:

.. das:function:: splitSpans(span: TimeSpan) : array<TimeSpan>

Split a time span at integer cycle boundaries. Example: `splitSpans(TimeSpan(0.75, 2.25))`
returns `[(0.75,1.0), (1.0,2.0), (2.0,2.25)]`.


:Arguments: * **span** :  :ref:`TimeSpan <struct-strudel_time-TimeSpan>`