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 the time units keywords. Revolution 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 GMT*, January 1, 1970
the long seconds: seconds and fractions of seconds since GMT*, January 1, 1970
the ticks function: the total number of ticks since GMT*, January 1, 1970
the milliseconds: the total number of milliseconds since GMT*, January 1, 1970

* 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 Revolution 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, 2007" 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: Tuesday, March 13, 2007 6:36:47 PM
convert tCurrentTime to abbr time and abbr date
-- tCurrentTime now holds something like this: 6:37 PM Tue, Mar 13, 2007

The convert command will convert to and from any of the date and time formats listed above, 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 14, 2007 2:23:30 PM converted to dateitems would be:

2007,3,14,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 --> 2007,3,14,0,0,0,3
add 20 to item 1 of it --> 2027,3,14,0,0,0,3
convert it to dateItems --> 2027,3,14,0,0,0,1
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 --> 2007,3,14,0,0,0,3
add 23 to item 3 of it --> 2007,3,37,0,0,0,3
convert it to date --> 4/6/07

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., 1197705600
put it - the seconds into totalSeconds
put totalSeconds / (60*60*24) into totalDays
put "Only" && totalDays && "shopping days until Christmas!"

Executing Time-delayed or Repeating Events

Often you may want to something to happen after a certain amount of time has elapsed, or you may want something to happen every few minutes or seconds. To do that you use a command that should already be familiar to you: the send command. This command has an optional in time clause that will cause the message you send to be executed when that time period has elapsed.

Syntax: send <message> to <object> in <time>
Where <message> is the name of any handler, and
<object> is a valid object reference (only needed if the object you are sending the message to is not in the current message hierarchy, or if you want to bypass intervening objects in the hierarchy,) and
<time> is any valid time period in seconds, ticks or milliseconds.

Examples:

Play a system alert to signal the end of a timed test:

send "beep" to this card in 30 seconds

To automatically advance to the next card after a specified time period:

send "go to next card" in 180 ticks

As useful as it is to execute a single action at some future time, the real power of send in time comes when you want to continuously check or update some aspect of your stack.

Examples:

Create a simple digital clock or timer on your card:

In button "startTimer":

on mouseUp
  updateTime
end mouseUp

In the card script:

on updateTime
  put the long time into field "timer"
  send updateTime to me in 500 milliseconds
end updateTime

With calls like this problems can arise. Let's say you wanted to move on to another card where the timer was no longer required. When you go to the next card, there would most likely still be a message in the queue waiting to be sent, but since you are now on a card that doesn't have field "timer" on it, the updateTime handler would cause an error. So you need to cancel the pending message before you leave the card. For this there is the cancel command:

Syntax: cancel <queued message ID>
The < queued message ID> is a number that is automatically generated when you use the send in <time> command. You can capture it by using the result function, storing the ID in a global variable or custom property, then canceling it when you leave the card:

In the card script:

global messageID
on updateTime
  put the long time into field "timer"
  send updateTime to me in 500 milliseconds
  put the result into messageID
end updateTim

on closeCard
  cancel messageID
end closeCard

What if you have several messages in the queue and you want to cancel some or all of them when you leave the card. One way is to save each message ID in its own global variable, but that can rapidly become unwieldy. Another approach would be to save all queued message IDs in a single variable, on separate lines, then loop through the variable when you leave the card:

In the card script:

global messageIDs
on updateTime
  put the long time into field "timer"
  send updateTime to me in 500 milliseconds
  if messageIDs is empty then
    put the result into messageIDs
  else
    put cr & the result after messageIDs
  end if
end updateTime

on startCounting
  put the seconds - startSeconds into fld "counter"
  send startCounting to me in 30 ticks
  if messageIDs is empty then
    put the result into messageIDs
  else
    put cr & the result after messageID
  end if
end startCounting

on closeCard
  repeat for each line thisMsgID in messageIDs
    cancel thisMsgID
  end repeat
end closeCard

There is also a function, the pendingMessages, that will return a list of all queued messages. Each line contains four items of information, the first item being the message ID. So if you wanted to kill all queued messages you could do this:

on closeCard -- brute-force method
  repeat until the pendingMessages is empty
    cancel item 1 of line 1 of the pendingMessages
  end repeat
end closeCard

Your Turn: