Time, countdowns and plots

Count the seconds to a market close, run a countdown in the Calculator, and sample an expression over a range with plot to draw a curve.

What the group is for

The time functions turn clock times into seconds, so a formula can count the time to an event or since it. timer runs a countdown in the Calculator or a Sheet. plot works out an expression over a range of values and returns the curve as a Series.

Durations

secs(n): n seconds, returned unchanged.

mins(n): n minutes in seconds, n × 60.

hours(n): n hours in seconds, n × 3600.

days(n): n days in seconds, n × 86400.

Every time function works in seconds. Use these four to write a length of time in minutes, hours or days. Divide a result by 60, 3600 or 86400 to show it in minutes, hours or days.

mins(5) => 300
hours(6.5) => 23400
days(1) => 86400
secs(90) + mins(1) => 150

Clock times

now(): the current time, as seconds since 1970-01-01 00:00 UTC.

time(text): the time given by the text, as seconds since 1970-01-01 00:00 UTC.

The text for time takes one of two forms, in quotes:

  • "YYYY-MM-DD HH:MM": a date and a time, such as "2026-11-03 16:00". A T in place of the space also works.
  • "HH:MM": a time today, such as "16:00". Today is the date of the clock in use. In step, it is the date of the stopped clock.

Both forms take optional seconds, such as "16:00:30", and the hour takes one or two digits. The time is in the time zone of your own computer. Across a daylight saving change, the difference between two times is one hour more or less than the difference in clock time.

Text in any other form returns the error E_DOMAIN, and a number in place of the text returns E_TYPE. A value past its range, such as "25:00" or "2026-02-31 16:00", gives no error: it carries into the next day or month.

The value of now() is a very large number. Take the difference between two times instead.

time("2026-11-03 16:00") - time("2026-11-03 09:30") => 23400
(time("2026-11-03 16:00") - time("2026-11-03 09:30")) / 3600 => 6.5
now() - time("09:30") => a number of seconds since 09:30 today

Count to an event

until(t): the seconds from now to the time t. The result is negative once t has passed.

since(t): the seconds from the time t to now. The result is negative while t is still ahead.

until(time("16:00")) => a number of seconds to 16:00 today
until(time("16:00")) / 60 => a number of minutes to 16:00 today
since(time("09:30")) / 3600 => a number of hours since 09:30 today
until(time("16:00")) > mins(15) => a number that is 1 while more than 15 minutes remain, else 0

Run a countdown

timer(n): a countdown from n seconds. It returns n minus the seconds since the countdown started, and stops at 0.

In live, the countdown starts at the first run of the formula text and the result updates once a second. An edit to the text starts the countdown again.

To step the countdown by hand in the Calculator:

  1. Type timer(mins(5)).
  2. Click the clock button until it shows step. The clock stops at the current whole second and the countdown starts from it.
  3. Click +1s or +1m to move the clock forward. The result shows the seconds left, such as 240 after +1m.
  4. Click the reset button to start the countdown again from the current clock.

The reset button also shows in live, where it starts the countdown again from the current clock. Click the clock button back to live to start a new countdown from the current clock.

A Sheet timer cell counts down by the same rule. In step, every timer cell counts from the second the clock stopped. In live, each cell counts from the first run of its formula.

timer(mins(5)) => a number of seconds left
timer(mins(5)) / 60 => a number of minutes left

How the clock updates

In live, the Calculator uses the computer's clock, corrected once by a reading of the site's clock. A Calculator formula runs again once a second when it calls now, time, until, since, timer, secs, mins, hours, days, sheet or sheet.mat. A formula with none of these functions runs once.

In step, the clock stays at the whole second it stopped at. The clock moves only when you click +1s or +1m, and the formula runs again on each click.

A Sheet has the same clock button with live and step. In live, the cells that call these functions run again once a second while the Sheet is on screen.

Plot a curve

plot(expr, var, lo, hi, n): works out expr at n evenly spaced values of var from lo to hi. It returns a Series. The x values of the Series are the values of var, and the y values are the results of expr.

  • expr: any formula that uses the variable.
  • var: the variable name, typed without quotes, such as x. The name stands for the sampled value only inside plot.
  • lo, hi: the first and the last value of the variable. Both are included.
  • n: the number of points, from 2 to 2001. A fraction rounds down. A count below 2 or above 2001 returns the error E_DOMAIN.

A point where expr is not a finite number, such as 1 / x at 0, stays in the Series as an empty point. The x values keep their even spacing.

In the Calculator, the result line shows the number of points, such as 11 samples, and a line chart of the Series appears below it. In a Sheet, the y values fill the column down from the cell.

plot(x^2, x, 0, 10, 11) => a Series of 11 points, x squared from 0 to 10
plot(sin(x), x, 0, 360, 181) => a Series of 181 points, one full turn of a sine wave
sum(plot(x, x, 1, 10, 10)) => 55
sum(plot(x, x, 0, 1, 5)) => 2.5

The Calculator angle button applies inside plot: with rad, sin(x) from 0 to 360 covers 360 radians, about 57 full turns. A Sheet always uses degrees.

Combine with other groups

A plotted Series works with the functions that take a history, such as sum in the example above. Series covers them. Numbers and math covers the functions inside an expression such as sin(x). The loan payment solver is part of the Calculator with its own form: see Solve a loan payment.

The Function reference lists the signature of every function, and Errors explains E_DOMAIN and E_TYPE.