{ "category": "Date and time functions", "display_name": "TODAY", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.TODAY", "implementation_state": { "answer_bank": null, "detail": "Recorded: 2 workbook cells. A volatile function: the recorded formulas hold it fixed, for example RAND()*0, so these cells show that the call works and not a clock or random value.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 2 recorded answers", "workbook_corpus": { "cells": 2, "matched": 2 } }, "implementations": [ { "commit": "9e1884369a678158dd82d3d74188daf986995e87", "flavour": "excel-compatibility-candidate", "language": "Rust", "name": "CalcFunc", "own_code": [ "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/dates.rs#L341-L344" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/dates::environment", "catalogue/dates::system", "catalogue/dates::from_1900", "catalogue/dates::serial_out", "catalogue/dates::now" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/dates.rs#L341-L344", "state": "matches", "suite": null, "summary": "Matches all 2 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.TODAY.json", "name": "TODAY", "notes": [], "schema": "efh.function-reference/v1", "section_order": [ "what-it-does", "try-it", "quirks", "how-to-implement", "version-differences", "alternatives" ], "sections": { "alternatives": "\n### Relationships\n\n\n- **[NOW](FUNC.NOW.md)** — the instant-reading sibling. `TODAY()` is expected to equal `INT(NOW())`;\n unverified here and interesting exactly at midnight.\n- **[DATEDIF](FUNC.DATEDIF.md)** — `DATEDIF(birthdate, TODAY(), \"Y\")` is the canonical age formula,\n and the reason `TODAY`'s volatility is tolerated in so many workbooks.\n- **[DATEVALUE](FUNC.DATEVALUE.md)** — shares an under-appreciated property: its documented\n year-omitted rule reads the system clock, making it clock-dependent too, though it is not declared\n volatile. `TODAY` is honest about depending on the clock; `DATEVALUE` is not.\n- **[DATE](FUNC.DATE.md)** — the deterministic constructor. Any formula that can name its date\n explicitly should, because it then becomes reproducible and testable.\n- **Volatile peers** — `NOW`, `RAND`, `RANDBETWEEN`, `OFFSET`, `INDIRECT`, `CELL`, `INFO`.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n1. **Inject the clock.** A time provider supplied through the execution context is what makes\n everything *around* this function testable, even though the function is not. The reference\n engine declares exactly such a dependency.\n2. **Derive `TODAY` from the same instant as `NOW` within a recalculation pass.** If the two read\n the clock independently, a pass that spans midnight can produce a `TODAY` and a `NOW` that\n disagree about the date — an inconsistency no formula author can defend against.\n3. **Truncate, do not round.** `TODAY` is the whole-day part of the current instant; rounding would\n make it flip at noon.\n4. **Declare volatility** so the recalculation engine propagates it.\n5. **Record the time zone with any captured observation.** A logged `TODAY` value without its zone\n is ambiguous for several hours a day.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns a `Number`: a whole date serial, with the fractional part zero.\n\n- **Local date, not UTC.** The same workbook opened in two time zones can show two different dates\n for several hours each day.\n- **Midnight is a discontinuity**, and it is the only interesting moment in the function's\n behaviour. A recalculation that spans it, or two cells evaluated either side of it, can disagree.\n- **Whole-day exactness.** Because the result is an integer-valued double, `TODAY()` is safe for\n equality comparison against other whole serials in a way [NOW](FUNC.NOW.md) is not. This is the\n practical reason to prefer `TODAY` whenever the time of day is not wanted: `A1 = TODAY()` works,\n `A1 = NOW()` almost never does.\n- **A static date is not this function.** Excel's shortcut for entering today's date inserts a\n literal serial; it looks identical in the cell and never changes.\n\n\n\n### Errors\n\n\n`TODAY` takes no arguments and has no documented error return. Its failure modes are host-level — an\nunavailable clock, or a system date outside the representable serial range — and are not observable\nas worksheet error values.\n\n\n", "sources": "\n- Microsoft 365 support, **TODAY function** —\n .\n- Microsoft 365 support, **NOW function** —\n .\n- Handbook call-model chapters [01 value universe](../model/01-value-universe.md) and\n [03 call pipeline](../model/03-call-pipeline.md), which name `NOW` and `TODAY` as the documented\n host-side-adaptation seed examples.\n- [FUNC.DATE](FUNC.DATE.md) — the serial model whose value `TODAY` reports.\n- `data/functions/FUNC.TODAY.json` (the `TimeDependent` / `VolatileFull` / `ApplicationState` /\n `HostSerialized` / `TimeProvider` classification), `data/presence/FUNC.TODAY.json`,\n `data/battery/FUNC.TODAY.json` (the declined-call rows).\n\n", "version-differences": "No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.", "what-it-does": "\n`TODAY` returns the current date as a whole date serial, with no time component. It reads the\nhost's clock and takes no arguments.\n\nLike [NOW](FUNC.NOW.md), it is not a function in the mathematical sense: it maps nothing to a value\nthat changes. Three facts govern it, and they are the same three, with one difference that turns\nout to matter.\n\n### It is volatile\n\nHere is the difference that matters: `TODAY`'s value is *constant for a day*, so the volatility is\nalmost always invisible. A `TODAY`-driven model recalculates constantly and produces the same\nanswer, right up until midnight, when everything changes at once. That combination — expensive and\nsilent, then abruptly different — is why `TODAY` in a large dependency tree is a well-known\nperformance and reproducibility hazard.\n\n### The battery refuses it, correctly\n\nThis is worth stating plainly because `TODAY` looks so much more tractable than `NOW` — its value is\nstable for twenty-four hours, so a naive suite could \"pass\" for a day and then fail. Stability is\nnot determinism.\n\n### It carries a formatting hint\n\n`TODAY` is, with `NOW`, one of the documented seed examples for the presentation-hint model: the\nfunction returns a plain number and the host applies a date format when the formula is entered into\na General-formatted cell. The value itself is core; the formatting is host-side adaptation at the\nworksheet boundary. See [the value universe](../model/01-value-universe.md) and\n[the call pipeline](../model/03-call-pipeline.md), stage 4.\n\n\n\n### Arguments\n\n\n`TODAY()` — no arguments. The parentheses are syntax; there is no parameter slot and therefore no\n`Missing` marker.\n\nEverything that varies about the result comes from outside the call: the machine's clock and time\nzone, and the workbook's date system.\n\n\n" }, "signature": { "display": "TODAY()", "parameters": [], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 0, "min": 0 }, "category": "Date and time functions", "classification": { "arg_preparation_profile": "ValuesOnlyPreAdapter", "coercion_lift_profile": "None", "determinism_class": "TimeDependent", "error_collapse_profile": "None", "fec_dependency_profile": "TimeProvider", "host_interaction_class": "ApplicationState", "kernel_signature_class": "Custom", "rich_value_usage": "ProducesPresentation", "surface_fec_dependency_profile": "TimeProvider", "thread_safety_class": "HostSerialized", "volatility_class": "VolatileFull" }, "descriptions": { "long": null, "short": "Current date as a serial number", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the serial number of today's date", "microsoft_url": "https://support.microsoft.com/en-us/office/today-function-5eb3078d-a82c-4736-8930-2f51a028fdd9" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "اليوم" }, { "locale": "bg-BG", "name": "ДНЕС" }, { "locale": "cs-CZ", "name": "DNES" }, { "locale": "da-DK", "name": "I DAG" }, { "locale": "de-DE", "name": "HEUTE" }, { "locale": "el-GR", "name": "ΣΗΜΕΡΑ" }, { "locale": "en-AU", "name": "TODAY" }, { "locale": "en-GB", "name": "TODAY" }, { "locale": "en-US", "name": "TODAY" }, { "locale": "es-ES", "name": "HOY" }, { "locale": "et-EE", "name": "TODAY" }, { "locale": "fi-FI", "name": "TODAY" }, { "locale": "fr-FR", "name": "AUJOURDHUI" }, { "locale": "he-IL", "name": "היום" }, { "locale": "hr-HR", "name": "DANAS" }, { "locale": "hu-HU", "name": "MA" }, { "locale": "id-ID", "name": "HARI INI" }, { "locale": "it-IT", "name": "OGGI" }, { "locale": "ja-JP", "name": "TODAY" }, { "locale": "ko-KR", "name": "오늘" }, { "locale": "lt-LT", "name": "ŠIANDIEN" }, { "locale": "lv-LV", "name": "ŠODIEN" }, { "locale": "nb-NO", "name": "I DAG" }, { "locale": "nl-NL", "name": "VANDAAG" }, { "locale": "pl-PL", "name": "DZIŚ" }, { "locale": "pt-BR", "name": "HOJE" }, { "locale": "pt-PT", "name": "HOJE" }, { "locale": "ro-RO", "name": "ASTĂZI" }, { "locale": "ru-RU", "name": "СЕГОДНЯ" }, { "locale": "sk-SK", "name": "TODAY" }, { "locale": "sl-SI", "name": "DANES" }, { "locale": "sr-Latn-RS", "name": "TODAY" }, { "locale": "sv-SE", "name": "I DAG" }, { "locale": "th-TH", "name": "วันนี้" }, { "locale": "tr-TR", "name": "BUGÜN" }, { "locale": "uk-UA", "name": "СЬОГОДНІ" }, { "locale": "vi-VN", "name": "HÔM NAY" }, { "locale": "zh-CN", "name": "TODAY" }, { "locale": "zh-HK", "name": "今天" }, { "locale": "zh-TW", "name": "今天" } ], "signature": { "display": "TODAY()", "parameters": [], "trailing_repeats": false }, "surface_name": "TODAY", "version_marker": null, "xlcall": { "code": "221", "symbol": "xlfToday" } }, "microsoft": "https://support.microsoft.com/en-us/office/today-function-5eb3078d-a82c-4736-8930-2f51a028fdd9" }, "try_it": { "formula": "=TODAY()" }, "url": "https://handbook.dnacalc.com/functions/TODAY.html", "variants": [], "versions": [] }