Date - Date Manipulation Library Routines
                =========================================
                       File: BLib.Date - Update: 1.03
                 Author: J.G.Harston - Date: 13-Mar-2007

  The Date library provides functions for converting dates between a 5-byte
centisecond count and real-world date and time values and for converting
between date numbers and english language date names. It replicates parts
of the functionality of the RISC OS SWIs Territory_ConvertOrdinalsToTime
and Territory_ConvertDateAndTime but can be used in an environment where
these calls are not available, when running BBC BASIC on any non-RISC OS
platform.

Routine Summary
===============
PROCDate_FromOrd()   - convert time and date to 5-byte centi-second count
PROCDate_ToOrd()     - convert 5-byte centi-second count to time and date
  FNDate_Since()     - return number of days since a past date
  FNDate_DayOfWeek() - return day of week for supplied date
  FNDate_FromDay()   - return day number of supplied day name
  FNDate_FromMonth() - return month number of supplied month name
  FNDate_ToDay()     - return full-length day name string
  FNDate_ToMonth()   - return full-length month name string
  FNDay()            - return 3-character day name string
  FNMon()            - return 3-character month name string

Requirements and Dependancies
=============================
  Date_FromDay() and Date_FromMonth() require the FNuc() function in the
String library.

  Date_Since() requires a global control block of at least 5 bytes in
length to be accessible with X% holding the address of this block. This can
easily be set up with DIM ctrl% 4 near the start of the program and
X%=ctrl% at the begining of the major program code and at the start of any
main program loop.

Convert time and date to 5-byte centi-second count
==================================================
DEFPROCDate_FromOrd(mem%,d%,m%,y%,hr%,mn%,sc%,cs%)

On entry: mem%->five bytes of memory
          day, month, year of the date
          hours, minutes, seconds, centiseconds of the time
On exit:  mem% to mem%+4 containes five-byte centisecond time since
          00:00:00 on 1-Jan-1900.

Convert 5-byte centi-second count to time and date
==================================================
DEFPROCDate_ToOrd(mem%)

On entry: mem%->five bytes of memory containing five-byte centisecond
          time since 00:00:00 on 1-Jan-1900.
On exit:  day%, month%, year% set to the date
          hour%, minute%, second%, centi% set to the time

Calculate number of days between two dates
==========================================
DEFFNDate_Since(td%,tm%,ty%,pd%,pm%,py%)

On entry: td%, tm% and ty% should be set to the future date, month and
          year and pd%, pm% and py% should be set to the past date,
          month and year.
On exit:  returns the number of days between the two dates.
Requires  X%->5-byte control block

Find day of week
================
DEFFNDate_DayOfWeek(day%,month%,year%)

On entry: day%, month%, year%
On exit:  return day of week for supplied date, 1=Sunday, 7=Saturday

Convert day and month to day and month number
=============================================
DEFFNDate_FromDay(day$)
DEFFNDate_FromMonth(month$)

FNDate_FromDay() returns the day number of the supplied string, with "Sun"=1
and "Sat"=7.

FNDate_FromMonth() returns the month number of the supplied string, with
"Jan"=1 and "Dec"=12.

Both functions return zero if the string is unrecognised. Case is ignored
and the supplied name can be the 3-character form or the full name.

Convert day and month to string
===============================
DEFFNDay(day%)
DEFFNMon(month%)
DEFFNDate_ToDay(day%)
DEFFNDate_ToMonth(month%)

FNDay() returns a 3-character day name string with 1="Sun" and 7="Sat".

FNMon() returns a 3-character month name string with 1="Jan" and 12="Dec".

FNDate_ToDay() returns the full-length day name string with 1="Sunday" and
7="Saturday".

FNDate_ToMonth() returns the full-length month name string with 1="January"
and 12="December".

Notes
=====
The library is based around the five-byte centisecond count since 1900, so
passing any dates outside the range 1900-2247 will give undefined results.

Version History
===============
1.00 12-Sep-1992 FromOrd(), DayOfWeek(), Day() and Mon() written as part of
                 HADFS Filer.
1.01 18-Feb-1994 ToOrd() and Since() added.
1.02 17-Sep-2005 ToOrd() debugged.
1.03 13-Mar-2007 [From|To][Day|Month]() functions added, inspired by Knud
                 van Eeden.