Skip to content

Commit 39f3979

Browse files
committed
docs(formula): clarify d: dates default to local time, ! is opt-in UTC
1 parent e0d248a commit 39f3979

1 file changed

Lines changed: 13 additions & 4 deletions

File tree

FORMULA-SUPPORT.md

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1368,10 +1368,10 @@ The mode is **mandatory** — `ts:` alone is not enough, you must pick a mode. F
13681368

13691369
Grammar:
13701370

1371-
- `[ [fill]align ] d:strftime_pattern` local time
1372-
- `[ [fill]align ] d:!strftime_pattern` — UTC
1371+
- `[ [fill]align ] d:strftime_pattern` **local time** (the everyday form)
1372+
- `[ [fill]align ] d:!strftime_pattern`**UTC** (opt-in)
13731373

1374-
Treats the value as a Unix timestamp (seconds since 1970-01-01 UTC) and formats it through `strftime`. The optional `!` prefix forces UTC; without it the system's local time zone is used. This follows the same convention as Lua's `os.date()`. An optional frame may precede the marker (see [Frame before a marker](#frame-before-a-marker)).
1374+
Treats the value as a Unix timestamp (seconds since 1970-01-01 UTC) and formats it through `strftime`. A bare `d:` is all you need — it renders in the machine's local time zone. The `!` prefix is **optional** and only switches the output to UTC; it is not required for `d:` to work and follows Lua's `os.date()` convention. An optional frame may precede the marker (see [Frame before a marker](#frame-before-a-marker)).
13751375

13761376
The pattern accepts any standard strftime specifier. Literal text between specifiers is passed through verbatim. Common specifiers:
13771377

@@ -1397,7 +1397,16 @@ The pattern accepts any standard strftime specifier. Literal text between specif
13971397

13981398
Weekday/month names follow the system locale. The full list of `strftime` specifiers is platform-defined and passes through verbatim — anything your C library supports works here.
13991399

1400-
| Spec | Timestamp | Output (UTC) |
1400+
**Local vs. UTC.** The same timestamp formatted both ways differs by your UTC offset. `d:` is the normal, local form; add `!` only when you specifically want UTC:
1401+
1402+
| Spec | Timestamp | Output |
1403+
|--------------------------|---------------|---------------------------------------|
1404+
| `d:%Y-%m-%d %H:%M:%S` | `1700000000` | `2023-11-14 23:13:20` (local, CET) |
1405+
| `d:!%Y-%m-%d %H:%M:%S` | `1700000000` | `2023-11-14 22:13:20` (UTC) |
1406+
1407+
The examples below use `!` only so the output is reproducible here regardless of your time zone — drop the `!` for local time.
1408+
1409+
| Spec | Timestamp | Output |
14011410
|----------------------------|---------------|------------------------------------|
14021411
| `d:!%Y-%m-%d` | `1700000000` | `2023-11-14` |
14031412
| `>15 d:!%Y-%m-%d` | `1700000000` | ` 2023-11-14` |

0 commit comments

Comments
 (0)