{ "category": "Date and time functions", "display_name": "ISOWEEKNUM", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.ISOWEEKNUM", "implementation_state": { "answer_bank": { "excel_builds": [ "20430" ], "larger_numeric": 0, "last_bit": 0, "matched": 10153, "other_mismatch": 0, "refused": 0, "rows": 10153, "unread": 0, "worst_ulp": 0 }, "detail": "Recorded: 10,153 in the answer bank and 4 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 10,157 recorded answers", "workbook_corpus": { "cells": 4, "matched": 4 } }, "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#L315-L318", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/date_kernels.rs#L302-L304" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/dates::environment", "catalogue/dates::system", "catalogue/dates::to_1900", "catalogue/dates::date_arg", "locale::days_from_civil", "locale::civil_from_days", "locale::ymd_from_excel_serial", "ported/date_kernels::days_from_civil", "ported/date_kernels::serial_unbounded_1900", "ported/date_kernels::whole_serial", "ported/date_kernels::weekday_sunday_one_based", "ported/date_kernels::remap_weekday", "ported/date_kernels::weekday_of", "ported/date_kernels::iso_weeknum_serial" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/dates.rs#L315-L318", "state": "matches", "suite": null, "summary": "Matches all 10,157 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.ISOWEEKNUM.json", "name": "ISOWEEKNUM", "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- **[WEEKNUM](FUNC.WEEKNUM.md) with `return_type` 21** — the same definition reached through the\n general function. Whether the two agree on every input is an equivalence that is widely assumed,\n easy to test, and **not verified here**.\n- **[WEEKDAY](FUNC.WEEKDAY.md) with `return_type` 3** — Monday-zero-based day numbering, the\n natural building block for hand-rolled ISO arithmetic and for the ISO-year expression above.\n- **[YEAR](FUNC.YEAR.md)** — the trap: calendar year is not ISO year.\n- **Confusable.** `ISOWEEKNUM` and `WEEKNUM` with its default `return_type` disagree for a large\n share of January and December dates, and the difference is routinely reported as a bug in one or\n the other.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n1. **Compute via the Thursday.** Shift the date to the Thursday of its ISO week\n (`d − isoweekday(d) + 4`, with Monday = 1), take that Thursday's calendar year and its\n day-of-year, and the week number is `⌈doy/7⌉`. This formulation has no year-boundary special\n cases at all, which is why it is the one to use.\n2. **Do not compute week numbers by dividing the day-of-year.** Every naive variant needs\n corrections at both ends of the year, and the corrections are where the bugs live.\n3. **Share the weekday kernel** with `WEEKDAY` and `WEEKNUM`, so the 1900 phase behaviour is\n identical across the three by construction.\n4. **Resist the urge to return an ISO year.** The function's contract is a bare number; adding a\n year would be a different function.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns a `Number` in 1…53.\n\n- **The boundary days are the whole story.** Late December and early January are where the ISO week\n number stops agreeing with intuition, and where implementations diverge.\n- **53-week years.** A year has 53 ISO weeks when it starts on a Thursday, or is a leap year\n starting on a Wednesday. Any suite for this function must contain several of them.\n- **The missing ISO year.** As above: the result is incomplete information at year boundaries, by\n design of the function rather than by defect.\n\n\n\n### Errors\n\n\nAs documented for this function:\n\n- `#NUM!` when the argument is out of range for the current date-base value.\n- `#VALUE!` when the argument is not a valid date — the ordinary coercion outcome.\n\nAn error value passed in propagates.\n\n\n", "sources": "\n- Microsoft 365 support, **ISOWEEKNUM function** —\n .\n- Microsoft 365 support, **WEEKNUM function** —\n .\n Source of the quoted ISO 8601 / System 2 definition.\n- [FUNC.WEEKDAY](FUNC.WEEKDAY.md) — the weekday kernel and Microsoft's documented pre-March-1900\n phase problem.\n- [FUNC.DATE](FUNC.DATE.md) — the serial-number model.\n- `data/functions/FUNC.ISOWEEKNUM.json`, `data/presence/FUNC.ISOWEEKNUM.json`,\n `data/battery/FUNC.ISOWEEKNUM.json`.\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 | 10,153 |\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.ISOWEEKNUM.json).", "what-it-does": "\n`ISOWEEKNUM` returns the ISO 8601 week number of the week that a date falls in.\n\nMicrosoft states the ISO rule on the [WEEKNUM](FUNC.WEEKNUM.md) page, as that function's System 2:\n\"The week containing the first Thursday of the year is the first week of the year, and is numbered\nas week 1. This system is the methodology specified in ISO 8601, which is commonly known as the\nEuropean week numbering system.\"\n\nThe full ISO definition has three parts, all of which follow from that rule and are worth stating\nbecause they are what makes the function non-trivial:\n\n1. **Weeks always start on Monday and always contain seven days.** There are no stub weeks.\n2. **Week 1 is the week containing the year's first Thursday** — equivalently, the week containing\n 4 January, equivalently the first week with the majority of its days in the new year.\n3. **A calendar year has 52 or 53 ISO weeks**, and the days at either end of the calendar year can\n belong to the neighbouring ISO year. 31 December 2019 is ISO week 1 (of 2020); 1 January 2021 is\n ISO week 53 (of 2020).\n\nPoint 3 is the one that bites. `ISOWEEKNUM` returns a bare week number with **no ISO year\nattached**, and Excel provides no function that returns the ISO year. A worksheet that pairs\n`ISOWEEKNUM(d)` with `YEAR(d)` produces a wrong label for exactly the boundary days ISO exists to\nhandle — reporting \"week 53 of 2021\" for 1 January 2021, which no ISO calendar contains. The\ncorrect ISO year has to be derived by hand, typically via the Thursday of the same week:\n`YEAR(d - WEEKDAY(d, 3) + 3)`.\n\n\n\n### Arguments\n\n\n`ISOWEEKNUM(date)` — one required argument, the date whose ISO week number is wanted.\n\nThere is no `return_type`: ISO 8601 admits no variants, which is the point of having a separate\nfunction. Argument coercion is the ordinary scalar behaviour described in\n[coercion and lifting](../model/02-coercion-and-lifting.md); as everywhere in this category,\nMicrosoft's guidance is to supply serials from [DATE](FUNC.DATE.md) or another formula rather than\ntext.\n\n`ISOWEEKNUM` is one of the newer members of the category — it does not appear in the oldest\nfunction sets, and workbooks that must open in very old Excel versions use a `WEEKNUM(d, 21)` or a\nhand-rolled expression instead. The Handbook's version-history data, rendered elsewhere on this\npage, is the authority on exactly which release introduced it; this prose does not restate it.\n\n\n" }, "signature": { "display": "ISOWEEKNUM(date)", "parameters": [ { "description": null, "name": "date", "optional": false, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 1, "min": 1 }, "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": "ISO 8601 week number of a date", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the number of the ISO week number of the year for a given date", "microsoft_url": "https://support.microsoft.com/en-us/office/isoweeknum-function-1c2d0afe-d25b-4ab1-8894-8d0520e90e0e" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "ISOWEEKNUM" }, { "locale": "bg-BG", "name": "ISOWEEKNUM" }, { "locale": "cs-CZ", "name": "ISOWEEKNUM" }, { "locale": "da-DK", "name": "ISOUGE.NR" }, { "locale": "de-DE", "name": "ISOWEEKNUM" }, { "locale": "el-GR", "name": "ISOWEEKNUM" }, { "locale": "en-AU", "name": "ISOWEEKNUM" }, { "locale": "en-GB", "name": "ISOWEEKNUM" }, { "locale": "en-US", "name": "ISOWEEKNUM" }, { "locale": "es-ES", "name": "ISO.NUM.DE.SEMANA" }, { "locale": "et-EE", "name": "ISOWEEKNUM" }, { "locale": "fi-FI", "name": "VIIKKO.ISO.NRO" }, { "locale": "fr-FR", "name": "NO.SEMAINE.ISO*" }, { "locale": "he-IL", "name": "ISOWEEKNUM" }, { "locale": "hr-HR", "name": "ISOWEEKNUM" }, { "locale": "hu-HU", "name": "ISO.HÉT.SZÁMA" }, { "locale": "id-ID", "name": "ISOWEEKNUM" }, { "locale": "it-IT", "name": "ISOWEEKNUM" }, { "locale": "ja-JP", "name": "ISOWEEKNUM" }, { "locale": "ko-KR", "name": "ISOWEEKNUM" }, { "locale": "lt-LT", "name": "ISOWEEKNUM" }, { "locale": "lv-LV", "name": "ISOWEEKNUM" }, { "locale": "nb-NO", "name": "ISOWEEKNUM" }, { "locale": "nl-NL", "name": "ISO.WEEKNUMMER" }, { "locale": "pl-PL", "name": "ISO.NUM.TYG" }, { "locale": "pt-BR", "name": "ISOWEEKNUM" }, { "locale": "pt-PT", "name": "NUMSEMANAISO" }, { "locale": "ro-RO", "name": "ISOWEEKNUM" }, { "locale": "ru-RU", "name": "НОМНЕДЕЛИ.ISO" }, { "locale": "sk-SK", "name": "ISOWEEKNUM" }, { "locale": "sl-SI", "name": "ISOWEEKNUM" }, { "locale": "sr-Latn-RS", "name": "ISOWEEKNUM" }, { "locale": "sv-SE", "name": "ISOVECKONR" }, { "locale": "th-TH", "name": "ISOWEEKNUM" }, { "locale": "tr-TR", "name": "ISOHAFTASAY" }, { "locale": "uk-UA", "name": "ISOWEEKNUM" }, { "locale": "vi-VN", "name": "ISOWEEKNUM" }, { "locale": "zh-CN", "name": "ISOWEEKNUM" }, { "locale": "zh-HK", "name": "ISOWEEKNUM" }, { "locale": "zh-TW", "name": "ISOWEEKNUM" } ], "signature": { "display": "ISOWEEKNUM(date)", "parameters": [ { "description": null, "name": "date", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "ISOWEEKNUM", "version_marker": null, "xlcall": { "code": "584", "symbol": "xlfIsoweeknum" } }, "microsoft": "https://support.microsoft.com/en-us/office/isoweeknum-function-1c2d0afe-d25b-4ab1-8894-8d0520e90e0e" }, "try_it": { "formula": "=ISOWEEKNUM(1)" }, "url": "https://handbook.dnacalc.com/functions/ISOWEEKNUM.html", "variants": [], "versions": [ { "behaviour": "10,153 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.ISOWEEKNUM.json" ] } ] }