Time Calculations

These functions perform calendrical computations using time values (see Time of Day). As with any time value, a value of nil for any of their time-value arguments stands for the current system time, and a finite number stands for the number of seconds since the epoch.

Function: time-less-p t1 t2

This returns t if the time value t1 is less than the time value t2.

Function: time-equal-p t1 t2

This returns t if the two time values t1 and t2 are equal. The result is nil if either argument is a NaN. For the purpose of comparison, a nil argument represents the current time with infinite resolution, so this function returns nil if one argument is nil and the other is not, and callers can therefore use nil to represent an unknown time value that does not equal any timestamp.

Function: time-subtract t1 t2

This returns the time difference t1 − t2 between two time values, as a Lisp timestamp. The result is exact and its clock resolution is no worse than the worse of its two arguments’ resolutions. If you need the difference in units of elapsed seconds, you can convert it with time-convert or float-time. See Time Conversion.

Function: time-add t1 t2

This returns the sum of two time values, using the same conversion rules as time-subtract. One argument should represent a time difference rather than a point in time, as a time value that is often just a single number of elapsed seconds. Here is how to add a number of seconds to a time value:

(time-add time seconds)

Function: time-to-days time-value

This function returns the number of days between the beginning of year 1 and time-value, assuming the default time zone. The operating system limits the range of time and zone values.

Function: days-to-time days

This is not quite the inverse of the time-to-days function, as it uses the Emacs epoch (instead of the year 1) for historical reasons. To get the inverse, subtract (time-to-days 0) from days, in which case days-to-time may return nil if days is negative.

Function: time-to-day-in-year time-value

This returns the day number within the year corresponding to time-value, assuming the default time zone. The operating system limits the range of time and zone values.

Function: date-leap-year-p year

This function returns t if year is a leap year.

Function: date-days-in-month year month

Return the number of days in month in year. For instance, February 2020 has 29 days.

Function: date-ordinal-to-time year ordinal

Return the date of ordinal in year as a decoded time structure. For instance, the 120th day in 2004 is April 29th.

Function: seconds-to-string delay &optional readable abbrev precision

Return a string describing a given delay (in seconds). By default, this function formats the returned string as a floating-point number in units selected according to the value of delay. For example, a delay of 9861.5 seconds yields ‘2.74h’, since the value of delay is longer than 1 hour, but shorter than 1 day. The output formatting can be further controlled by the optional arguments, if optional argument readable is non-nil. If readable’s value is expanded, the returned string will describe delay using two units; for example, a delay of 9861.5 seconds with readable set to the symbol expanded returns ‘2 hours 44 minutes’, but if readable is t, the function returns ‘3 hours’. Optional argument abbrev, if non-nil, means to abbreviate the units: use ‘h’ instead of ‘hours’, ‘m’ instead of ‘minutes’, etc. If precision is a whole integer number, the function rounds the value of the smallest unit it produces to that many digits after the decimal point; thus, 9861.5 with precision set to 3 yields ‘2.739 hours’. If precision is a non-negative float smaller than 1, the function rounds to that value.