# Time and Timers

This page is the "Time and Timers" section of the Voxlang language reference. It is generated from LANGUAGE.md in the Voxlang compiler's own repository, so it says what the specification says and nothing more.

A URL is the heading, lowercased, with punctuation dropped and spaces turned into hyphens. Each "##" section of the spec is a page under /docs/, and every heading inside it is a fragment on that page, so "File I/O" is /docs/file-io/ and "Reading a whole file" inside it is /docs/file-io/#reading-a-whole-file.

As data: https://vox-lang.dev/docs/index.json lists every section and every heading with its URL, https://vox-lang.dev/docs/search.json carries one entry per heading with its first sentence and keywords, and https://vox-lang.dev/docs/anchors.json maps every slug to the page it lives on. Search is also a JSON endpoint: https://vox-lang.dev/docs/search?q=<words> returns ranked results as JSON, no page load.

Source: LANGUAGE.md at bf2cba0, 2026-08-22. https://github.com/Vox-lang/vox/blob/bf2cba037976586c30d22a48e7b7246d347f54a1/LANGUAGE.md

[Reference](https://vox-lang.dev/docs/) > Time and Timers

## Getting Current Time

Get the current date/time as a `time` value:

```vox fragment
Get current time into now.
a time called now is current time.
```

## Time Properties

Access components of a time value using the `'s` property syntax:

| Property | Description | Type |
| --- | --- | --- |
| `hour` | Hour of day (0-23) | Number |
| `minute` | Minute (0-59) | Number |
| `second` | Second (0-59) | Number |
| `day` | Day of month (1-31) | Number |
| `month` | Month (1-12) | Number |
| `year` | Year (e.g., 2026) | Number |
| `unix` | Unix timestamp (seconds since epoch) | Number |

**Example:**

```
Get current time into now.
Print "Current time: ".
Print the now's hour.
Print ":".
Print the now's minute.
Print ":".
Print the now's second.

Print "Date: ".
Print the now's year.
Print "-".
Print the now's month.
Print "-".
Print the now's day.
```

## Inline Time Access

Access current time properties directly without storing:

```
Print "It is currently hour ".
Print current time's hour.
Print " of the day.".
```

## Sleep / Wait

Pause program execution for a specified duration:

```
Wait 1 second.
Wait 2 seconds.
Wait 500 milliseconds.
Sleep for 3 seconds.
```

**Syntax variations:**

- `Wait <N> second.` / `Wait <N> seconds.`
- `Wait <N> millisecond.` / `Wait <N> milliseconds.`
- `Sleep for <N> seconds.`
- `Sleep for <N> milliseconds.`

## Timers

Timers are stopwatches for measuring durations. They track start time, end time, and elapsed duration.

### Creating a Timer

```
Create a timer called 'job timer'.
a timer called benchmark.
```

### Starting and Stopping

```
Start the 'job timer'.
(... do work ...)
Stop the 'job timer'.
```

**Alternative spellings:**

- `Start` / `Begin`
- `Stop` / `Finish`

These four words are **contextual, not reserved**. They open a timer statement only when a name operand follows — `Start the t.`, `stop t.` — and everywhere else they are ordinary identifiers, so `a number called stop is 0.` compiles, and a program may define and call its own zero-argument `start.` function. (`End` is not a Stop spelling: `end` belongs to the `exit` family of keywords and remains reserved.)

### Timer Properties

| Property | Description | Type |
| --- | --- | --- |
| `duration` | Total duration (requires cast) | Duration |
| `elapsed` | Elapsed time while running (requires cast) | Duration |
| `start time` | When timer was started (unix timestamp) | Number |
| `end time` | When timer was stopped (unix timestamp) | Number |
| `running` | Whether timer is currently running | Boolean |

### Getting Duration

Use `in` to cast duration to a specific unit:

```
Print the 'job timer''s duration in seconds.
Print the 'job timer''s duration in milliseconds.
Print the 'job timer''s elapsed in seconds.
```

### Complete Timer Example

```
(Measure job duration)
Print "Starting job...".
Create a timer called 'job timer'.
Start the 'job timer'.

(... do work ...)
Wait 1 second.
Print "Seconds elapsed so far: ".
Print the 'job timer''s elapsed in seconds.

Wait 500 milliseconds.
Stop the 'job timer'.

Print "Finished the job in: ".
Print the 'job timer''s duration in seconds.
Print " seconds".

(Access raw timestamps)
Print "Started at unix time: ".
Print the 'job timer''s start time.
Print "Stopped at unix time: ".
Print the 'job timer''s end time.
```

### Formatted Time Output

Combine time properties with the zero-pad format specifier (see [Format Specifiers](https://vox-lang.dev/docs/inputoutput/#format-specifiers)) for formatted output. A time property can be read directly inside a format slot:

```
Get current time into now.
Print "{now's hour:02}:{now's minute:02}:{now's second:02}".
(Prints: 09:05:03)
```

Or, if you want the parts as named values first:

```
Get current time into now.
a text called h is "{now's hour:02}".
a text called m is "{now's minute:02}".
a text called s is "{now's second:02}".

Print "{h}:{m}:{s}".
(Prints: 09:05:03)
```