==========
Time Tools
==========

.. default-domain:: bash

.. file:: time_tools.bsh


.. function:: get_time_seconds

Print the epoch time in seconds

:Output: **stdout** - The epoch time, in seconds with nanosecond precision (if available)

Uses the ``date`` command to print nanosecond-accurate epoch time, if your date command supports that feature.

Else, uses ``python3``, ``ruby``, or ``perl`` if available to get microsecond-accurate time. If all else fails, use the ``date`` command, even if it does not support more than second precision.

.. function:: get_time_nanoseconds

Print the epoch time in nanoseconds. Same as :func:`get_time_seconds`, but in nanoseconds and always an integer

.. function:: timeout

:Arguments: * ``$1`` - Timeout in integer seconds
            * ``$2``... - Command to execute
:Return Value: ``142`` - On time out
:Uses: perl

macOS function similar to linux timeout

.. rubric:: Bugs

Since this uses SIGALRM, bash will print out "Alarm clock: 14" to indicate SIGALRM (14) has been raised. This could cause unexpected text in stderr if you are parsing it.

.. seealso::

   https://www.cyberciti.biz/faq/shell-scripting-run-command-under-alarmclock/

.. function:: tic

Part of a tic/toc functionality to easily take time measurements.

.. rubric:: Example

.. code-block:: bash

  $ tic
  $ sleep 1.3
  $ toc_ms
  1302 ms

.. seealso::
 :func:`toc`, :func:`toc_ms`, :func:`toc_ns`

.. function:: toc

Prints the time passed since calling :func:`toc` in seconds (rounded).

Also stores the number of seconds passed in ``toc_time``

.. function:: toc_ms

Prints the time passed since calling :func:`toc` in milliseconds (rounded).

Also stores the number of milliseconds passed in ``toc_time``

.. note::

  Older ``date`` commands that don't support nanoseconds, will not be more accurate than a second.

.. function:: toc_ns

Prints the time passed since calling :func:`toc` in nanoseconds.

Also stores the number of nanoseconds passed in ``toc_time``

.. note::

  Older ``date`` commands that don't support nanoseconds, will not be more accurate than a second.

.. function:: get_timezone

Retrieves the Olson compliant timezone for the system. If this is not easily obtained, a POSIX compliant timezone will be returned instead.

.. rubric:: Example

.. code-block:: bash

  $ get_timezone
  America/New_York
  # Windows
  $ get_timezone
  EDT+04:00

.. function:: get_posix_timezone

Retrieves a POSIX compliant timezone for the system. This POSIX timezone will not encapsulate daylight saving times change rules, however if the computer is currently in daylight saving time, the offset will be applied.

If all the methods to determine the timezone file, it will return ``UTC`` with no ``+/-``

.. rubric:: Example

.. code-block:: bash

  $ get_posix_timezone
  UTC+00:00
  $ get_posix_timezone
  EDT+04:00
  $ get_posix_timezone
  UTC