Introduction to newLISP/Working with dates and times

= Working with dates and times =

Date and time functions
To work with dates and times, use the following functions:


 * date convert a seconds count to a date/time, or return date/time for now


 * date-value return the time in seconds since 1970-1-1 for a date and time, or for now


 * now return the current date/time information in a list


 * time-of-day return milliseconds since the start of today till now

date-value and now work in UT, not your local time. date can take account of the time difference between your local time and UT.

The current time and date
All four functions can be used to return information about the current time. date-value returns the number of seconds between 1970 and the current time (in UT):

and now returns a list of integers containing information about the current date and time (in UT):

This provides the following information:


 * year, month, day (2006, 3, 19)


 * hour, minute, second, microsecond (20, 5, 2, 125475)


 * day of current year (78)


 * day of current week (1)


 * local time zone offset (in minutes west of GMT) (0)


 * daylight savings time flag (0)

To extract the information you want, use a slice or pick out the elements:

date used on its own will give you the current date and time for the local time zone (now and date-value return values in UCT/UTC, not relative to your local time zone):

It can also tell you the date of an integer number of seconds since 1970 (the start of the Unix epoch), adjusted for your local time zone:

date-value can calculate the number of seconds for a specific date or date/time (in UT):

Because date-value can accept the year, month, day, hours, minutes, and seconds as input, it can be applied to the output of now:

By converting different times to these date values, you can do calculations. For example, to subtract November 13 2003 from January 3 2005:

You can find out the date that is 12 days after Christmas Day 2005 by adding 12 days-worth of seconds to the date:

This seconds value can be converted to a human-friendly date by date in its longer form, when it takes a seconds-since-1970 value and converts it to a local time zone representation of this UT-based value:

Of course (date (date-value)) is the same as (date), but you'll have to use the longer form if you want to change the date format. date accepts an additional formatting string (preceded by a time-zone offset in minutes). If you're familiar with C-style strftime formatting, you'll know what to do:

Reading dates and times: parse-date
The parse-date function (which is, unfortunately, not available on Windows) can convert date and time strings to seconds-since-1970 values. You supply a date-time format string after the string:

Timing and timers
For timing purposes, you can use these functions:


 * time return the time taken to evaluate an expression, in milliseconds


 * timer set a timer to wait for a certain number of seconds and then evaluate expression


 * sleep stop working for a certain number of milliseconds

time is useful for finding out how much time expressions take to evaluate:

You can supply a repetition count as well, which probably gives a more accurate picture:

If you can't or don't want to enclose expressions, more simple timing can be done using time-of-day:

timer is basically an alarm clock. Set it and then forget about it until the time comes. You supply a symbol specifying the alarm action, followed by the number of seconds to wait:

and three minutes later you'll see this:

Without any arguments, this function returns the name of the current symbol that's been assigned as the alarm action:

If you're waiting for the alarm to go off, and you're impatient to see how much time has elapsed so far, use the function with the name of the assigned symbol but without a seconds value:

For another example of the use of these functions, see Simple countdown timer.