/********************************************************/
/*                        datime.h                      */
/* Header file for sundry utility functions concerning  */
/*                     date and time.                   */
/********************************************************/

/*-------------------- datime_hourmin --------------------
 * Description: Converts time of day in hours into integer
 *              hours and minutes.
 *
 * Parameters:  REAL time    -- time of day in hours.
 *              int *hourptr -- integer to fill in with
 *                              number of hours.
 *              int *minptr  -- integer to fill in with
 *                              number of minutes.
 * Returns:     void.
 * Other info:  'time' must be in the range
 *              0 <= time < 24.0
 */

  void datime_hourmin(REAL time, int *hourptr, int *minptr);


/*--------------------- datime_julian --------------------
 * Description: Calculates the number of days (and fraction of a
 *              day) from noon GMT on 00/01/1900 to the specified
 *              date and time.
 *
 * Parameters:  observerstr *ptr -- pointer to the observerstr
 *                                  containing the required date
 *                                  & the time offset (time zone).
 *              int hour         -- the required time (hour part).
 *              int min          -- the required time (min part).
 *
 * Returns:     Calculated no. of days.
 * Other info:  The following fields in the specified observerstr
 *              must be valid: year, month, day, offset.
 */

double datime_julian(observerstr *ptr, int hour, int min);


/*-------------------- datime_siderial -------------------
 * Description: Calculates the local siderial time corresponding
 *              to the specified date and time.
 *
 * Parameters:  observerstr *ptr -- pointer to the observerstr con-
 *                                  taining input data.
 *              double jul   -- No. of days from noon GMT 0/1/1900
 *                              to required date and time.
 *              int hour     -- the required time (hour part).
 *              int min      -- the required time (min part).
 *
 * Returns:     Local siderial time, in radians.  Range is
 *              0 <= time < 2*PI.
 * Other info:  The following fields in the specified observerstr
 *              must be valid: offset, longit.
 */

REAL datime_siderial(observerstr *ptr, double jul, int hour, int min);


/*------------------- datime_time_today ------------------
 * Description: Calculates (one) civil time during the day at which
 *              the Local Siderial Time is equal to the value given.
 *
 * Parameters:  REAL sid_time    -- the required local siderial time,
 *                                  in radians.
 *              observerstr *ptr -- pointer to the observerstr con-
 *                                  taining details of the relationship
 *                                  between civil and local siderial time.
 *              int *hourptr     -- pointer to int to fill in with
 *                                  hour.
 *              int *minptr      -- pointer to int to fill in with
 *                                  minute.
 * Returns:     void.
 * Other info:  The sid field in the observerstr must correspond
 *              with the hour and min fields.
 */

void datime_time_today(REAL sid_time, observerstr *ptr,
                       int *hourptr, int *minptr);
