Office of Digital Humanities

DigHT 310
Times and Dates in LiveCode

The Time and Date Functions

As you no doubt recall, the LiveCode functions the date and the time return the current date and time information as provided by the host operating system. You may also remember that you can get the date and time information in various formats, determined by the use of keywords like long and short. Let's revisit these functions and get a more in-depth look at them.

Here are the major variants of the date function. If you call these functions you'll get the results shown. Try them out in your own stack or in the message box.

The date function

This form	Produces this format
the date	2/14/17
the long date	Tuesday, February 14, 2017
the abbreviated date (or abbrev or abbr)	Tue, Mar 13, 2007
the short date	2/14/17 (same as the date)
the internet date	Tue, Tue, 14 Feb 2017 11:46:25 -0700
the english date	(forces the date to be displayed in U.S. format—the default)
the system date	(forces the date to be displayed in format specified by the host OS—country specific)

The time function

This form	Produces this format
the time	1:49 PM
the long time	1:49:31 PM
the abbreviated time	1:49 PM (same as the time)
the short time	1:49 PM (same as the time)
the english time	(forces the time to be displayed in U.S. format—the default)
the system time	(forces the time to be displayed in format specified by the host OS—country specific)

There are two functions—the monthNames and the weekdayNames—that return information useful when working with dates .

The monthNames function

This form	Produces	This form	Produces	This form	Produces
the monthNames	January February March April May June July August September October November December	the short monthNames	1 2 3 4 5 6 7 8 9 10 11 12	the abbreviated monthNames	Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec

The weekdayNames function

This form	Produces	This form	Produces	This form	Produces
the weekdayNames	Sunday Monday Tuesday Wednesday Thursday Friday Saturday	the short weekdayNames	1 2 3 4 5 6 7	the abbreviated weekdayNames	Sun Mon Tue Wed Thu Fri Sat

Checking for a valid date

If you need to verify whether a particular string is in a valid date format, you can use the is [not] a boolean operator. For example, if you are asking your users to enter a date, you may want to first check for a valid format:

if myDate is not a date then
  answer "Please type your date in this format: mm/dd/yyyy."
end if

Note that both a valid date string and a valid time string will cause is a date to evaluate to true, so if you want to make sure the string is a date, rather than a time, you will have to perform other checks besides this basic format check.

Date and Time Calculations

While getting date and time information from the OS is useful and important, it is even more useful to be able to do calculations based on dates and times. For example, what if you want to know which day of the week the 15th of April falls on? Or how many shopping days are left until Christmas? With a few useful tools you can easily do date and time arithmetic.

The first set of tools we have is time units keywords. LiveCode understands these time units:

seconds
ticks (one-sixtieth of a second)
milliseconds (one-thousandth of a second)

For each of these time units there is a corresponding function:

the seconds function: the total number of seconds since midnight, January 1, 1970, GMT*
the long seconds: seconds and fractions of seconds since midnight, January 1, 1970, GMT*
the ticks function: the total number of ticks since midnight, January 1, 1970, GMT*
the milliseconds: the total number of milliseconds since midnight, January 1, 1970, GMT*

* GMT = Greenwich Mean Time

To calculate minutes, days, weeks, etc., remember the simple formulas:

one minute = 60 seconds
one hour = 60*60 seconds
one day = 60*60*24 seconds
one week = 60*60*24*7 seconds
one year = 60*60*24*365 seconds

The convert command

The convert command is a powerful tool that lets you easily change any valid time or date format to any other valid format. You can specify a from format if desired, but if you don't LiveCode just analyzes the input to determine the format it's in.

Basic Syntax:

convert <date and/or time> to format [and format]
where <date and/or time> is a string in any valid date and/or time format
    e.g., the long date; the date && the time; a variable with a valid date or time in it
(The second format is optional. It simply means that instead of converting to a date only format or a time only format, you can convert to a date and a time.)

If you pass it a literal string, like this:

convert "March 14, 2017" to seconds

the converted time will go into the it variable.

If you pass it a date or time in a variable, the converted time/date will go into the variable you passed:

put the long date && the long time into tCurrentTime
-- makes the value of tCurrentTime something like: Tuesday, February 14, 2017 11:48:21 AM
convert tCurrentTime to abbr time and abbr date
-- tCurrentTime now holds something like this: 11:49 AM Tue, Feb 14, 2017

The convert command will convert to and from any of the date and time formats listed at the top of this page, plus two other formats:

seconds
dateItems

The dateItems format is a list of numbers, separated by commas (hence, dateitems.) There are seven items in the dateitems format:

year,month num,day of month,hour in 24-hour time,minute,second,numeric day of week.

So, for example, Wednesday, March 15, 2017 2:23:30 PM converted to dateitems would be:

2017,3,15,14,23,30,4

Why is this useful? There are a lot of reasons, but one major one is you can do "date arithmetic" with date items by adding or subtracting to or from the item, e.g.:

-- I want to find out what day of the week today's date falls on in 20 years
convert the long date to dateItems --> 2015,2,10,0,0,0,3
add 20 to item 1 of it --> 2035,2,10,0,0,0,3
convert it to dateItems --> 2035,2,10,0,0,0,7
put line (item 7 of it) of the weekdayNames --> Sunday

It even works if your arithmetic puts one or more of the items out of range, because the convert command will automatically adjust the date items to the appropriate values:

-- I want to find out the date 23 days from today:
convert the date to dateItems --> 2015,2,10,0,0,0,3
add 23 to item 3 of it --> 2015,2,33,0,0,0,3
convert it to long date --> Thursday, March 5, 2015

You can also use the seconds (or ticks or milliseconds) for time arithmetic.

-- How many days until Christmas?
convert "December 25," && the last word of the long date to seconds -->e.g., 1451026800
put it - the seconds into totalSeconds
put totalSeconds / (60*60*24) into totalDays
put "Only" && totalDays && "shopping days until Christmas!"