{ "category": "Date and time functions", "display_name": "DATE", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.DATE", "implementation_state": { "answer_bank": { "excel_builds": [ "20430" ], "larger_numeric": 0, "last_bit": 0, "matched": 22250, "other_mismatch": 0, "refused": 0, "rows": 22250, "unread": 0, "worst_ulp": 0 }, "detail": "Recorded: 22,250 in the answer bank and 18 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 22,268 recorded answers", "workbook_corpus": { "cells": 18, "matched": 18 } }, "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#L227-L231", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/date_kernels.rs#L93-L143" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/dates::environment", "catalogue/dates::system", "ported/date_kernels::days_from_civil", "ported/date_kernels::serial_unbounded_1900", "ported/text_kernels::text", "ported/text_kernels::text_from_str", "ported/text_kernels::date_integer_floor", "ported/text_kernels::push_singleton_or_original", "ported/text_kernels::push_upper", "ported/text_kernels::upper" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/dates.rs#L227-L231", "state": "matches", "suite": null, "summary": "Matches all 22,268 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.DATE.json", "name": "DATE", "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- **Inverses.** [YEAR](FUNC.YEAR.md), [MONTH](FUNC.MONTH.md) and [DAY](FUNC.DAY.md) decompose a\n serial back into the three components `DATE` composes. `DATE(YEAR(s), MONTH(s), DAY(s))` should\n return the whole-day part of `s` for any in-range serial; whether it does across the leap-year\n discontinuity is a natural metamorphic probe nobody has run here.\n- **Sibling constructor.** [TIME](FUNC.TIME.md) builds the fractional part the same way `DATE`\n builds the integer part, and with the same normalizing (rather than validating) philosophy.\n- **Text parser.** [DATEVALUE](FUNC.DATEVALUE.md) reaches the same serials from text instead of\n from three numbers, and is locale-dependent where `DATE` is not.\n- **Month arithmetic.** [EDATE](FUNC.EDATE.md) and [EOMONTH](FUNC.EOMONTH.md) offset by whole\n months, which is *not* what `DATE`'s month rollover does. `DATE(2008,1,31)` rewritten as\n `DATE(2008,2,31)` gives 2 March 2008, because `DATE` carries the excess days forward; `EDATE`\n is widely understood to clamp instead, though its Microsoft page does not state the clamping\n rule and this Handbook has not verified it. This is the most common confusion in the category.\n- **Confusable.** `DATEVALUE` and `DATE` are frequently interchanged in advice; so are `DATE` and\n the `TEXT` function, which formats rather than constructs.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n1. **Do the month arithmetic before the day arithmetic, and do it in integers.** Resolve\n `(y, m)` to a normalized year and 1–12 month with a floor-division carry (not truncating\n division — `month = -3` must go *backwards*), then add `day − 1` days. Getting the negative\n branch right is the whole trick.\n2. **The leap-year artefact is a coordinate shift, not a calendar rule.** The cleanest\n implementation computes a proper proleptic Gregorian day number and then adds 1 for days on or\n after 1 March 1900. Trying to make a real calendar library believe in 29 February 1900 is the\n route to subtle bugs.\n3. **The date system is workbook state, not function state.** A kernel that hard-codes the 1900\n origin cannot serve a 1904 workbook. Model the origin as an input to the function, sourced from\n the execution context.\n4. **`year` in 0…1899 is add-1900, not a two-digit-window rule.** It is not the sliding pivot\n convention used elsewhere in date parsing; 99 means 1999 and 5 means 1905.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns a `Number`: a whole date serial. The cell will usually display it as a date, because Excel\napplies a date format to the result — that is host-side adaptation, not part of the value (see\n[the call pipeline](../model/03-call-pipeline.md), stage 4).\n\nArgument coercion follows the ordinary scalar rules of\n[coercion and lifting](../model/02-coercion-and-lifting.md): numeric text converts, logicals\nconvert to 1 and 0, error inputs propagate. Nothing on this page overrides those.\n\n\n### Errors\n\n\nAs documented on the Microsoft page linked below:\n\n- `#NUM!` when `year` is negative or 10000 or greater.\n\nBeyond that single documented condition, the errors reachable from `DATE` are the ordinary ones\nthat any numeric-argument function can produce: `#VALUE!` from an argument that cannot convert to\na number, and any error value passed in as an argument propagating out. Microsoft's page does not\nenumerate a `#NUM!` for a *resulting* date outside 1 January 1900 – 31 December 9999 — for example\n`DATE(1900,1,-5)`, which resolves below serial 0 — and this Handbook has not checked what Excel\nreturns there.\n\n\n", "sources": "- Microsoft 365 support, **DATE function** —\n .\n Source of the year/month/day rules, the rollover examples, and the `#NUM!` condition.\n- Microsoft Learn, **Excel incorrectly assumes that the year 1900 is a leap year** —\n .\n Source of the Lotus 1-2-3 compatibility explanation and of the statement that `WEEKDAY` returns\n incorrect values before 1 March 1900.\n- Microsoft 365 support, **Date systems in Excel** —\n .\n Source of the 1900/1904 definitions, the 1,462-day offset, and the 5 July 2011 example.\n- Handbook call-model chapters\n [01 value universe](../model/01-value-universe.md),\n [02 coercion and lifting](../model/02-coercion-and-lifting.md),\n [03 call pipeline](../model/03-call-pipeline.md) — for the value kinds, coercion rules and\n publication stage this page refers to rather than restates.\n\n\n", "version-differences": "The recorded environments below distinguish a reading from a same-input comparison. Counts describe captured inputs in each environment; overlapping captures and comparisons are not totals of unique worksheet calls.\n\n| Excel 16.0 build | Platform and CPU | Captured inputs |\n|---|---|---:|\n| 20430 | Windows, 64-bit, CPU not recorded | 22,250 |\n\nThe record contains no same-input comparison between these environments. Reading different inputs on different builds does not establish either a version change or cross-build agreement.\n\n[Recorded environments and comparison details](https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.DATE.json).", "what-it-does": "\n`DATE` is the constructor of the date category. It takes three numbers — a year, a month and a\nday — and returns the **date serial number** that denotes the calendar day those three numbers\nname. Everything else in the category either consumes a serial (`YEAR`, `MONTH`, `WEEKDAY`,\n`EOMONTH`) or produces one (`TODAY`, `EDATE`, `WORKDAY`). `DATE` is where the mapping is defined.\n\nThe important thing to understand is that `DATE` is **not** a validator. It is a normalizing\nconstructor: it does not reject 14 as a month or 35 as a day, it carries them. The documented\nrule is arithmetic, not calendrical. Given `(y, m, d)`, Excel first resolves the year–month pair\nby ordinary integer division — month 14 of 2008 means month 2 of 2009, month −3 of 2008 means\nmonth 9 of 2007 — and then counts `d` days from the day before the first of that resolved month.\nSo `DATE(2008,1,35)` is 4 February 2008 and `DATE(2008,1,-15)` is 16 December 2007, both of which\nMicrosoft's page gives as worked examples.\n\nRead that way, `DATE(y, m, d)` is the serial of\n\n> the first day of month `m` of year `y`, resolved by carrying month overflow into the year,\n> then advanced by `d − 1` days.\n\nThat single sentence explains all four documented rollover cases at once, and it is why\n`DATE(2008,2,30)` quietly becomes 1 March 2008 rather than an error.\n\n### The serial-number model\n\nA date serial is a plain `Number` (see [the value universe](../model/01-value-universe.md)); the\ndate-ness lives in the cell format, not in the value. Under the default **1900 date system**,\nMicrosoft documents that 1 January 1900 is serial 1 and 1 January 2008 is serial 39448. Those two\nanchors, together with the leap-year artefact below, pin the whole mapping:\n\n| Serial | Calendar day |\n|---|---|\n| 0 | no real day — displays as \"0 January 1900\" |\n| 1 … 59 | 1 January … 28 February 1900 (serial = days after 31 December 1899) |\n| 60 | **29 February 1900 — a day that never existed** |\n| 61 … 2958465 | 1 March 1900 … 31 December 9999 (serial = days after 30 December 1899) |\n\nThe fractional part of a serial carries time of day: 0.5 is noon. `DATE` returns a whole number,\nso its result has no time component. See [TIME](FUNC.TIME.md) for the other half of that model.\n\n### The 1900 leap-year artefact\n\n1900 was not a leap year — it is divisible by 100 and not by 400 — but Excel's serial line\ncontains a 29 February 1900 anyway. Microsoft documents both the fact and the reason: Lotus 1-2-3\nmade the assumption first, and Multiplan and Excel adopted it so that serial numbers would be\ninterchangeable between the programs. Microsoft's article is explicit that the behaviour is\nretained deliberately and that only the year 1900 is affected; century years such as 2100 are\nhandled correctly.\n\nTwo consequences bite in this category:\n\n1. **Every serial from 61 upwards is one greater than the true day count from 1 January 1900.**\n This is invisible in day-difference arithmetic as long as both endpoints are on the same side\n of the discontinuity, and wrong by one when they straddle it.\n2. **Weekday alignment before 1 March 1900 is off by one.** Microsoft's own article names this as\n the single residual problem: `WEEKDAY` \"returns incorrect values for dates before March 1,\n 1900\". See [WEEKDAY](FUNC.WEEKDAY.md).\n\nWhether `DATE(1900,2,29)` returns serial 60 rather than rolling into 1 March, and what\n`DATE(1900,2,30)` does, are exactly the questions the artefact makes interesting. Neither has\nbeen checked against Excel for this Handbook.\n\n### The 1900 and 1904 date systems\n\nA workbook carries a date-system flag. Microsoft documents the **1900 date system** (the default)\nand the **1904 date system** (the default in earlier versions of Excel for Mac), and states that\nthe difference between the two is 1,462 days — \"four years and one day (including one leap day)\" —\nso that the same calendar day has a serial 1,462 higher in the 1900 system than in the 1904\nsystem. Microsoft's worked example is 5 July 2011: serial 40729 in the 1900 system, 39267 in the\n1904 system.\n\n`DATE` is the function where this flag is consumed rather than merely observed: the same\n`DATE(2011,7,5)` call produces a different number in the two systems. Note that the 1904 system\nhas no leap-year artefact, because 1904 genuinely was a leap year.\n\nOne honest inconsistency in the documentation, worth naming because implementers trip on it:\nMicrosoft's date-systems page describes a serial as \"the number of days elapsed since January 1,\n1900\", while the `DATE`, `WEEKDAY` and `WEEKNUM` pages state that 1 January 1900 *is* serial 1.\nThose two statements do not reconcile — \"days elapsed since 1 January 1900\" would make that day\nserial 0. The serial-1 anchor is the one consistent with the documented 39448 for 1 January 2008,\nso it is the one this Handbook uses.\n\n\n\n### Arguments\n\n\n`DATE(year, month, day)` — all three required, no optional argument, no repeats.\n\n**year** — Microsoft documents a three-branch rule, and it is the argument that surprises people:\n\n| Value of `year` | Documented interpretation |\n|---|---|\n| 0 … 1899 | 1900 is **added**: `DATE(108,1,2)` is 2 January 2008 |\n| 1900 … 9999 | used as the year directly |\n| < 0 or ≥ 10000 | `#NUM!` |\n\nThe documentation also says Excel \"interprets the year argument according to the date system your\ncomputer is using\", which is the hook for 1904-system workbooks. The practical advice that follows\nfrom the table: always pass a four-digit year, because `DATE(24,1,1)` is 1 January 1924, not 2024.\n\n**month** — an integer, documented as \"positive or negative\", nominally 1–12. Out-of-range values\ncarry into the year as described above.\n\n**day** — an integer, documented as \"positive or negative\", nominally 1–31. Out-of-range values\ncarry into the month, and through the month into the year.\n\nNon-integer arguments are the commonly misunderstood case that the documentation does not settle\non this page. `YEARFRAC`'s page states the truncation rule for *its* arguments explicitly; the\n`DATE` page does not, and this Handbook has not checked whether `DATE(2008.9, 1.9, 1.9)`\ntruncates, rounds, or does something else.\n\n\n" }, "signature": { "display": "DATE(year, month, day)", "parameters": [ { "description": null, "name": "year", "optional": false, "repeats": false }, { "description": null, "name": "month", "optional": false, "repeats": false }, { "description": null, "name": "day", "optional": false, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 3, "min": 3 }, "category": "Date and time functions", "classification": { "arg_preparation_profile": "ValuesOnlyPreAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "None", "fec_dependency_profile": "None", "host_interaction_class": "None", "kernel_signature_class": "Custom", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "RefOnly", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "Serial date number for a year, month and day", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the serial number of a particular date", "microsoft_url": "https://support.microsoft.com/en-us/office/date-function-e36c0c8c-4104-49da-ab83-82328b832349" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "DATE" }, { "locale": "bg-BG", "name": "DATE" }, { "locale": "cs-CZ", "name": "DATE" }, { "locale": "da-DK", "name": "DATO" }, { "locale": "de-DE", "name": "DATE" }, { "locale": "el-GR", "name": "DATE" }, { "locale": "en-AU", "name": "DATE" }, { "locale": "en-GB", "name": "DATE" }, { "locale": "en-US", "name": "DATE" }, { "locale": "es-ES", "name": "FECHA" }, { "locale": "et-EE", "name": "DATE" }, { "locale": "fi-FI", "name": "DATE" }, { "locale": "fr-FR", "name": "DATE" }, { "locale": "he-IL", "name": "DATE" }, { "locale": "hr-HR", "name": "DATE" }, { "locale": "hu-HU", "name": "DATE" }, { "locale": "id-ID", "name": "DATE" }, { "locale": "it-IT", "name": "DATA" }, { "locale": "ja-JP", "name": "DATE" }, { "locale": "ko-KR", "name": "DATE" }, { "locale": "lt-LT", "name": "DATE" }, { "locale": "lv-LV", "name": "DATE" }, { "locale": "nb-NO", "name": "DATO" }, { "locale": "nl-NL", "name": "DATUM" }, { "locale": "pl-PL", "name": "DATE" }, { "locale": "pt-BR", "name": "DATE" }, { "locale": "pt-PT", "name": "DATA" }, { "locale": "ro-RO", "name": "DATE" }, { "locale": "ru-RU", "name": "DATE" }, { "locale": "sk-SK", "name": "DATE" }, { "locale": "sl-SI", "name": "DATE" }, { "locale": "sr-Latn-RS", "name": "DATE()" }, { "locale": "sv-SE", "name": "DATE" }, { "locale": "th-TH", "name": "DATE" }, { "locale": "tr-TR", "name": "TARİH" }, { "locale": "uk-UA", "name": "DATE" }, { "locale": "vi-VN", "name": "DATE" }, { "locale": "zh-CN", "name": "DATE" }, { "locale": "zh-HK", "name": "DATE" }, { "locale": "zh-TW", "name": "DATE" } ], "signature": { "display": "DATE(year, month, day)", "parameters": [ { "description": null, "name": "year", "optional": false, "repeats": false }, { "description": null, "name": "month", "optional": false, "repeats": false }, { "description": null, "name": "day", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "DATE", "version_marker": null, "xlcall": { "code": "65", "symbol": "xlfDate" } }, "microsoft": "https://support.microsoft.com/en-us/office/date-function-e36c0c8c-4104-49da-ab83-82328b832349" }, "try_it": { "formula": "=DATE(2026,11,6)" }, "url": "https://handbook.dnacalc.com/functions/DATE.html", "variants": [], "versions": [ { "behaviour": "22,250 captured inputs are indexed for this environment. Capture dates: 2026-09-29 to 2026-09-29. This is a reading count, not a comparison with another build.", "excel_build": "16.0 build 20430", "platform": "Windows, 64-bit, CPU not recorded", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.DATE.json" ] } ] }