HOWTO: Convert UHDAS Dates
==========================

Definitions:
~~~~~~~~~~~~~~~~~~

- ISO-8601 Calendar dates [wikipedia: ISO_8601#Calendar_dates]

  ``YYYY-MM-DD``

- UHDAS: $UNIXD or $PYRTM

  ``YYYY-DDD (DDD: 01 Jan = 000)``

  The day-of-year is zero based.

- Ordinal Date (or Day of year) [wikipedia: ordinal date; ISO_8601#Ordinal_date]

  ``YYYY-DDD (DDD: 01 Jan = 001)``

- Julian Day [wikipedia: Julian_day]

  ``Days since 4713-01-01 BC (noon UTC JD 1 = 0.0)``

- Unix (or POSIX) Time [wikipedia: Unix_time]

  Seconds since 1970-01-01 00:00:00 UTC
  Note: 1970-01-01 was day 0 (zero).

Conversions:
~~~~~~~~~~~~~~~~~~


UHDAS to Calendar date:
^^^^^^^^^^^^^^^^^^^^^^^^^^^

UHDAS utility: ``/usr/local/currents/bin/to_date``

**usage:**

``to_date [YY]YY DDD[.ddd]``

where:

- ``[YY]YY``		(year) is either 2 or 4 digits
- ``DDD``		(day) is the zero based day of year (01 Jan = 0)
- ``[.ddd]``		(fractional day)

Example::

  to_date 2018 322.33
  2018/11/19  07:55:12.00


Calendar to UHDAS date:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


UHDAS utility: ``/usr/local/currents/bin/to_day``

**usage:**

``to_day [YY]YY [YY]YY MM DD hh mm ss``

where:

- ``[YY]YY``		(year) is either 2 or 4 digits (beginning of cruise)
- ``[YY]YY``		(year) is either 2 or 4 digits (end of cruise)
- ``MM``		(month)
- ``DD``		(day) is the zero based day of year (01 Jan = 0)
- ``hh``		(hour of day, UTC)
- ``mm``		(minutes)
- ``ss``		(seconds)

.. NOTE::

   Two year-values are required to account for cruises that wrap a year-end.

   Example:

   to_day 2017 2018 01 19 06 00	# cruise starts 2017, ends 2018
   383.25000000

   to_day 2018 2018 11 19 08 00	# cruise is all within 2018
   322.33333333


**Linux utility**: ``/bin/date``

**usage:**

``date [OPTION] ... [+FORMAT]``

where::

 OPTIONS
 -d, --date=DATESTR
              display time described by STRING, not 'now'
 FORMAT
 %j	day of year (001..366)
 DATESTR

 “N day ago”	where N is an integer number of days
 “-N day”	where N is an integer number of days

 various date formats, such as YYYY-MM-DD
 combinations of the above

 Examples:
 date -d "-1 day 2018-11-19" +"%j"
 322

 date -d "1 day ago  2018-11-19" +"%j"
 322


.. NOTE:: since the Unix “%j” is day-of-year starting at 1 (one), we
          need to subtract a day to make the conversion zero-based.