eX version 0.4b User's Manual                         File eXMan20.txt
(C) Copyright 1995, 1996 William E. Wilgus III.   All rights reserved.


Date & Time Functions

Many of these descriptions indicate a date argument by "DateArgument"
or a term that includes "DateArgument".  Unless otherwise specified, it
may be given either as a `DateString' in the format 

                         mm-dd-yyyy

where mm is the two digit month, dd is the two digit day, and yyyy is
the four digit year; or as individual numeric components:

                    Month#, Day#, Year#

The descriptions often indicate a time argument with either 
"TimeArgument", or a term that includes "TimeArgument".  Unless otherwise
specified, it may be given either as a TimeString in the format 

                              hh:mm:ss

where hh is the two digit hour, mm is the two digit minute(s), and
ss is the two digit second(s); or as individual numeric components:

                     Hour#, Minute#, Second#


An example will provide any necessary clarity for the assignable
date/time component functions---even though pointless: 

                         month := month(date)

It assigns the month of the system date to the month of the system date. 
You might want to take note that the form `month(date)' is not
assignable. 


Date Functions
 
cDate  (Not available in eX Lite.)
                          cDate JulianDate
     Returns the calendar date of the julian date argument, which may
     be given either as a numeric or an un-formatted ASCII numeric
     string.  See also jDate (julian date).

date
     There are three forms of the function.

                              date
     The sans-argument form returns the system date as a date string
     and is assignable.

                    date(Month#, Day#, Year#)
     The second form returns the date string formed by the numeric
     arguments (which are not checked for validity).  Optionally, the
     year may be given first, and the year component of the 
     returned string will be the first element in the string.  

          date(1, 21, 1975)     returns     01-21-1975
          date(1975, 1, 21)     returns     1975-01-21

                         date(DateString$)
     Although essentially redundant, date will accept a single
     string argument in the form mm-dd-yyyy, where any character may
     be substituted for each occurance of -, as exemplified by  
     mm/dd/yyyy.  The form returns a `standard' date string and is
     provided for conversion convenience.  See also `tDate'. 

DateDiff  (Not available in eX Lite.)
          DateDiff(MinuendDateArgument, SubtrahendDateArgument) 
     Date subtraction function.  Returns the difference in days
     between the two argument dates.

               DateDiff(date, date)     returns    0

DateSum  (Not available in eX Lite.)
               DateSum(DateArgument, AddendDateArgument)
     Date addition function.  Returns the date string that is the
     algebraic sum of the date argument and the addends.

          DateSum("01-01-1988", "01-00-01")   returns   02-01-1989 
day
                    day<<$>><<(DateString$)>>
     Returns the day within the argument as a numeric, 7 being
     `Sunday'.  If the argument is omitted, the day of the system date
     is returned, and this form is assignable.  If a string suffix
     $ is used, returns the day as a two digit numeric string.  See
     also tDay. 

DTG  (Not available in eX Lite.)
               DTG<<DateArgument, TimeArgument)>>
     Date Time Group function.  Returns a long integer representation
     of the argument date and time which is equivalent to
               (jDate(date) * 100000 + esecs(time))
     and is handy for comparisons.  The sans-argument form uses the
     system date and time. 

jDate  (Not available in eX Lite.)
                    jDate<<$>><<(DateArgument)>>
     Returns the `Julian Date' of the argument date, which is simply
     the year multiplied by 1,000 plus the `day of the year'.  It's
     valid for years subsequent to 1847.  The sans-argument form uses
     the system date.  If the string suffix $ is used, an ASCII
     numeric string is returned.  See also `jDay'.

jDay  (Not available in eX Lite.)
                    jDay<<$>><<(DateArgument)>>
     Returns the Julian Day (day of the year) of the argument date.  
     It's valid for years subsequent to 1847.  The sans-argument form
     uses the system date.  If the string suffix $ is used, an ASCII
     numeric string is returned.  See also jDate.

LeapYear  (Not available in eX Lite.)
                         LeapYear Year#
     Returns true (-1) if Year# is a leap year, otherwise false (0)
     and is accurate for the years since 1847.  See also year. 

mDays
                    mDays MonthArgument
     Returns the number of days in the month specified by
     MonthArgument,  which may be given as a number or a string that
     is the name of the month, e.g. April'.  It cannot adjust February
     for leap years.  

MDY
                    MDY(YearMonthDayArgument)
     Returns the date string of the Year/Month/Day date argument, i.e.
     an argument in either of the forms yyyy-mm-dd or Year#, Month#,
     Day#.  See also YMD in this section, which shows that
     MDY(YMD(DateArgument)) isn't very productive!

month
                    month<<$>><<(DateString)>>
     Returns the month within the date string argument.  The sans
     argument form uses the system date and is assignable.  The
     un-parenthesized argument form is not allowed.  If a string
     suffix $ is used, returns the month as a two digit ASCII numeric
     string.  See also tMonth

tDate  (Not available in eX Lite.)
                         tDate<<(DateArgument)>>
     Returns the argument date in `text' form.  The sans-argument form
     uses the system date, and the un-parenthesized argument form is
     not allowed.
          tDate("01-31-1950")    returns    January 31, 1950

tDay  (Not available in eX Lite.)
                         tDay<<(DateArgument)>>
     Returns the name of the day of the week for DateArgument. 
     The sans-argument form uses the system date and the
     un-parenthesized argument form is not allowed.  It is valid for
     dates beginning 1/1/1900.

tDTG  (Not available in eX Lite.)
                    tDTG<<(DateArgument, TimeArgument)>>
     Returns the text Date Time Group for the argument date and time. 
     The sans-argument form uses the system date and time. 
          tDTG("1996-05-22", "16:05:30") returns
                             4:05 p.m. Wednesday, May 22, 1996 

tMonth
                    tMonth<<(DateArgument)>>
     Returns the name of the month in DateArgument.  The sans-argument
     form uses the system date and the un-parenthesized argument form
     is not allowed.  It is valid for dates beginning 1/1/1900.

WeekDay  (Not available in eX Lite.)
                    WeekDay<<$>><<(DateArgument)>>
     Returns the number of the day of the week for DateArgument,
     7 being Sunday.  If the string suffix $ is used, the number is
     returned as an ASCII numeric string.  The sans-argument form uses
     the system date and the un-parenthesized argument form is not
     allowed.  It is valid for dates beginning 1/1/1900.

year
                    year<<$>><<(DateString)>>
     Returns the year in DateString as a numeric.  If the string
     suffix $ is used, an ASCII numeric string is returned.  The
     sans-argument form uses the system date and may be assigned.
     The un-parenthesized argument form is not allowed.

YMD  (Not available in eX Lite.)
                         YMD<<(DateString)>>
     Returns a string containing the argument date in the format
     yyyy-mm-dd.  The sans-argument form uses the system date as its
     argument and the un-parenthesized form is not allowed.  See also
     MDY in this section. 

 

Time Functions
 
AmPm
                         AmPm<<(TimeArgument)>>
     Returns a string containing the 12-hour clock hours and minutes,
     suffixed with a.m. or p.m., of TimeArgument.  The sans-argument
     form uses the system time and the un-parenthesized form is not
     allowed.  

esecs
                         esecs<<(TimeArgument)>>
     Returns the elapsed seconds of time.  The sans-argument form
     returns the number of seconds since midnight on the system clock
     and will likely include a fractional part.  The time provided by
     the parenthesized argument form is converted into total seconds
     and will not include a fractional part.  The un-parenthesized
     argument form is not allowed.  See also eTime.

eTime  (Not available in eX Lite.)
                         eTime<<(seconds#)>>
     Returns the elapsed time of the argument seconds as a
     TimeString.  The sans-argument uses the elapsed seconds since
     midnight of the system clock.  The un-parenthesized form is not
     allowed.  See also esecs. 

hour
                    hour<<$>><<(TimeArgument)>>
     Returns the hour of the time argument as a numeric value.  If the
     string suffix $ is used, returns the hour as a two digit numeric
     string.  The sans-argument form uses system time and is
     assignable.  The un-parenthesized argument form is not allowed.

minute
                    minute<<$>><<(TimeArgument)>>
     Returns the minute of the time argument as a numeric value.  If
     the string suffix $ is used, returns the minute as a two digit
     numeric string.  The sans-argument form uses system time and is
     assignable.  The un-parenthesized argument form is not allowed.

second
                    second<<$>><<(TimeArgument)>>
     Returns the second[s] of the time argument as a numeric value.  
     If the string suffix $ is used, returns the second as a two digit
     numeric string.  The sans-argument form uses system time and is
     assignable.  The un-parenthesized argument form is not allowed.

time
                         time<<(TimeArgument)>>
     Returns TimeArgument as a TimeString.  The sans-argument form
     uses the system time and this form is assignable.  The
     un-parenthesized argument form is not allowed.

TimeDiff  (Not available in eX Lite.)
               TimeDiff(TimeArgument, TimeArgument)
     Returns the difference between the two argument times in seconds.

               TimeDiff(time, time)    returns    0

TimeSum  (Not available in eX Lite.)
               TimeSum(TimeArgument, AddendTimeArgument)
     Returns the algebraic sum of TimeArgument and the addend  
     argument(s) as a TimeString
     Note that if the addend arguments are given as a time string, the

     hour, minute, and second addends must be in the range 00--99.  
     Addends given as numeric components are not restricted in value,
     of course.  Note that the function does not limit the returned
     hour component to 24.
          TimeSum(0, 0, 60, 0, 0, 86339)    returns    23:59:59 

