{ "category": "Date and time functions", "display_name": "WEEKNUM", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.WEEKNUM", "implementation_state": { "answer_bank": { "excel_builds": [ "20430" ], "larger_numeric": 0, "last_bit": 0, "matched": 12889, "other_mismatch": 443, "refused": 0, "rows": 13332, "unread": 0, "worst_ulp": 0 }, "detail": "Of 13,339 recorded answers (13,332 in the answer bank and 7 workbook cells), 443 do not match: 443 differ in kind or value. Excel's own recorded readings disagree with each other on 479 of these inputs.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "differs", "state_label": "Known larger differences", "summary": "Known larger differences on 443 of 13,339 recorded answers", "workbook_corpus": { "cells": 7, "matched": 7 } }, "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#L310-L314", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/date_kernels.rs#L286-L300" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/dates::environment", "catalogue/dates::system", "catalogue/dates::to_1900", "catalogue/dates::date_arg", "catalogue/dates::strict_date_arg", "catalogue/dates::strict_num", "catalogue/dates::return_type", "locale::days_from_civil", "locale::civil_from_days", "locale::ymd_from_excel_serial", "ported/date_kernels::days_from_civil", "ported/date_kernels::civil_from_days", "ported/date_kernels::serial_unbounded_1900", "ported/date_kernels::ymd_1900", "ported/date_kernels::whole_serial", "ported/date_kernels::whole", "ported/date_kernels::weekday_sunday_one_based", "ported/date_kernels::remap_weekday", "ported/date_kernels::weekday_of", "ported/date_kernels::weekday", "ported/date_kernels::iso_weeknum_serial", "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#L310-L314", "state": "differs", "suite": null, "summary": "Known larger differences on 443 of 13,339 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.WEEKNUM.json", "name": "WEEKNUM", "notes": [ { "basis": "The readings conflict with each other. The 479 comes from the DnaCalc witness differences file. The 1,926 pairs come from one request of 3,852 calls, with exact input read-backs, compared pair by pair.", "documentation": { "claim": "If Return_type is out of the range specified in the table above, a #NUM! error is returned.", "source": "https://support.microsoft.com/en-us/office/weeknum-function-e5c43a03-b4ab-426c-b411-b18c13c75340" }, "evidence": [ { "commit": "9c23dde1dfd6d93e742d763a4bad3eaec229b29c", "locator": "WEEKNUM", "note": "index of the conflicting readings", "path": "crates/calc-func/witness-differences.tsv", "repository": "DnaCalc" }, { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "dc-zmk.2", "note": "the repeat comparison of 3,852 calls in build 20527", "path": ".beads/issues.jsonl", "repository": "DnaCalc" } ], "functions": [ "FUNC.WEEKNUM" ], "inferred": null, "kind": "quirk", "note_id": "FN-WEEKNUM-001", "open": [ "What decides the answer for an undocumented return_type is not known.", "The raw readings of build 20527 are not yet in a published capture. Their counts are recorded in the DnaCalc issue tracker." ], "recorded_on": "2026-11-04", "repros": [ { "call": "WEEKNUM(0, 23)", "correct": null, "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "cell-value2", "inputs": [ { "name": "serial_number", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } }, { "name": "return_type", "value": { "bits": "0x4037000000000000", "display": "23", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, CPU not recorded in this capture", "source": { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": "date-boundary-WEEKNUM-00188", "note": null, "path": "runs/w111-date-boundaries-20260929/answers/answers-weeknum.json.gz", "repository": "CalcFunc-Evidence" } }, { "call": "WEEKNUM(0, 23)", "correct": null, "excel": { "bits": "0x3ff0000000000000", "display": "1", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "serial_number", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } }, { "name": "return_type", "value": { "bits": "0x4037000000000000", "display": "23", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, CPU not recorded in this capture", "source": { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": "date-conversion-WEEKNUM-01331", "note": null, "path": "runs/w111-date-conversion-20260929/answers/answers-weeknum.json.gz", "repository": "CalcFunc-Evidence" } }, { "call": "WEEKNUM(0, 33)", "correct": null, "excel": { "bits": "0x0000000000000000", "display": "0", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "serial_number", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } }, { "name": "return_type", "value": { "bits": "0x4040800000000000", "display": "33", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, CPU not recorded in this capture", "source": { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": "date-boundary-WEEKNUM-00940", "note": null, "path": "runs/w111-date-boundaries-20260929/answers/answers-weeknum.json.gz", "repository": "CalcFunc-Evidence" } }, { "call": "WEEKNUM(0, 33)", "correct": null, "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "cell-value2", "inputs": [ { "name": "serial_number", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } }, { "name": "return_type", "value": { "bits": "0x4040800000000000", "display": "33", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, CPU not recorded in this capture", "source": { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": "date-conversion-WEEKNUM-00133", "note": null, "path": "runs/w111-date-conversion-20260929/answers/answers-weeknum.json.gz", "repository": "CalcFunc-Evidence" } } ], "schema": "efh.function-note/v1", "statement": "The documentation says an out-of-range return_type gives #NUM!. Excel usually does, but not always, and the same call can give different answers. In recorded captures of build 20430, 479 (serial_number, return_type) pairs were read with different results: usually #NUM!, sometimes a number (0, 1, 9, 10, 53 or 54), and some pairs differ within one run file. In build 20527 a matrix of 1,926 pairs (serial_number 0, 1, 59, 60, 61 and 43831, return_type -32 to 288) was read twice in one request, and 623 pairs differed between the two readings: 619 between a number and #NUM!, and 4 between 9 and 10. Every difference has an undocumented return_type. The ten documented return_types (1, 2, 11 to 17 and 21) gave the same answer both times. No rule for the undocumented values is claimed.", "status": "measured", "title": "WEEKNUM with an invalid return_type can answer differently each time it is called" } ], "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- **[ISOWEEKNUM](FUNC.ISOWEEKNUM.md)** — the dedicated ISO 8601 function, which on the documented\n reading computes the same thing as `WEEKNUM(s, 21)`. Having two spellings of one definition is\n itself a fact about the surface, and whether they agree on every input is a natural equivalence\n test that nobody has run for this Handbook.\n- **[WEEKDAY](FUNC.WEEKDAY.md)** — the day-of-week function whose `return_type` table looks similar\n and is not interchangeable.\n- **[DATE](FUNC.DATE.md)** — the recommended way to construct the argument.\n- **Confusable.** `WEEKNUM(s,1)` and `WEEKNUM(s,21)` differ for a large fraction of January and\n December dates; reports that \"Excel gives the wrong week number\" are almost always this.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n1. **Implement System 1 and System 2 as separate algorithms.** They are not the same computation\n with a different start day; System 2's week 1 is defined by the first Thursday, System 1's by 1\n January. A single parameterized routine that tries to cover both usually gets the year boundary\n wrong in one of them.\n2. **Validate `return_type` against the exact set** {1, 2, 11, 12, 13, 14, 15, 16, 17, 21}. It is\n not a range; 3 is valid for `WEEKDAY` and invalid here, which is a genuinely easy mistake given\n how the two tables are usually read side by side.\n3. **Do not compute ISO weeks by rounding day-of-year.** The standard `⌊(doy + 6 − isoweekday)/7⌋`\n style formula needs its year-boundary corrections; get them from the ISO definition rather than\n by patching failures.\n4. **Reuse the weekday kernel** shared with `WEEKDAY`, so that the 1900 phase behaviour is the same\n in both functions by construction rather than by coincidence.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns a `Number`: a week ordinal.\n\n- **Early January.** This is where the two systems visibly disagree. A 1 January falling on a\n Friday is week 1 under System 1 and week 53 of the *previous* year under ISO.\n- **Late December.** Under System 1 a year can reach week 53 or 54 depending on the start day;\n under ISO the last days of December may be week 1 of the next year.\n- **The result carries no year.** `WEEKNUM` returns a number, not a (year, week) pair, so ISO week\n numbers obtained from it must be paired with an ISO year computed separately — Excel provides no\n ISO-year function.\n- **Serials in 1900.** Week numbering near the start of the serial line inherits the phase problem\n described on [WEEKDAY](FUNC.WEEKDAY.md), because week boundaries are weekday boundaries.\n\n\n\n### Errors\n\n\nAs documented on the Microsoft page:\n\n- `#NUM!` when `serial_number` is out of range for the current date-base value.\n- `#NUM!` when `return_type` is outside the range specified in the table.\n\nExcel does not always follow the second of these: for an undocumented `return_type` it usually\ngives `#NUM!`, sometimes a number, and the same call can answer differently (FN-WEEKNUM-001).\n\nOrdinary coercion failures give `#VALUE!`, and an error argument propagates; those are engine\nbehaviours (see [coercion and lifting](../model/02-coercion-and-lifting.md)), not `WEEKNUM` rules.\n\n\n", "sources": "\n- Microsoft 365 support, **WEEKNUM function** —\n .\n Source of the `return_type` table, the System 1 and System 2 definitions quoted above, the\n serial-number remark, and both `#NUM!` conditions.\n- Microsoft 365 support, **ISOWEEKNUM function** —\n .\n- [FUNC.WEEKDAY](FUNC.WEEKDAY.md) — the weekday kernel and the documented 1900 phase problem.\n- [FUNC.DATE](FUNC.DATE.md) — the serial-number model.\n- `data/functions/FUNC.WEEKNUM.json`, `data/presence/FUNC.WEEKNUM.json`,\n `data/battery/FUNC.WEEKNUM.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 | 13,332 |\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.WEEKNUM.json).", "what-it-does": "\n`WEEKNUM` returns the ordinal number of the week within the year that a date falls in. The\nfunction carries **two genuinely different definitions**, selected by `return_type`, and confusing\nthem is the source of nearly every disagreement between spreadsheets about \"which week is it\".\n\nMicrosoft states the two systems as follows:\n\n- **System 1** — \"The week containing January 1 is the first week of the year, and is numbered\n week 1.\" Under this system week 1 can be a stub of a single day, and a year can contain 54\n partial weeks' worth of numbering in the worst case.\n- **System 2** — \"The week containing the first Thursday of the year is the first week of the year,\n and is numbered as week 1. This system is the methodology specified in ISO 8601, which is\n commonly known as the European week numbering system.\"\n\nThe documented `return_type` table:\n\n| `return_type` | Week begins on | System |\n|---|---|---|\n| 1 or omitted | Sunday | 1 |\n| 2 | Monday | 1 |\n| 11 | Monday | 1 |\n| 12 | Tuesday | 1 |\n| 13 | Wednesday | 1 |\n| 14 | Thursday | 1 |\n| 15 | Friday | 1 |\n| 16 | Saturday | 1 |\n| 17 | Sunday | 1 |\n| 21 | Monday | 2 |\n\nNote the shape: **nine of the ten options are System 1** and differ only in which weekday starts\nthe week; the tenth, 21, is the ISO system and is the only one where the week-1 rule itself\nchanges. `return_type` 2 and 11 are duplicates, as are 1 and 17 — the same redundancy the\n[WEEKDAY](FUNC.WEEKDAY.md) table has, for the same historical reason.\n\nUnder System 1, the algorithm is: week `n` runs from the `n`-th week-start day on or before the\nfirst week-start day following 1 January, with the partial week containing 1 January counted as\nweek 1. Under System 2 the algorithm is the ISO 8601 one, in which weeks always have seven days,\nalways begin on Monday, and the last days of December can belong to week 1 of the *following*\nyear — which is why an ISO week number alone is ambiguous without its ISO year.\n\n\n\n### Arguments\n\n\n`WEEKNUM(serial_number, [return_type])` — one required argument and one optional.\n\n**serial_number** — \"a date within the week\". Microsoft's page repeats the serial-number model:\n\"Excel stores dates as sequential serial numbers so they can be used in calculations. By default,\nJanuary 1, 1900 is serial number 1.\" Supply dates from `DATE` or from another formula rather than\nas text.\n\n**return_type** — optional; the week-start day and system, per the table. Omitted means 1 (weeks\nbegin Sunday, System 1).\n\nThe misunderstood argument is again `return_type`, in three distinct ways: readers assume its\nvalues match `WEEKDAY`'s (they overlap but do not mean the same thing), assume 21 is \"just Monday\"\n(it changes the entire week-1 rule), and assume there is a System 2 variant for other start days\n(there is not — ISO weeks are Monday-based by definition).\n\n\n" }, "signature": { "display": "WEEKNUM(serial_number, [return_type])", "parameters": [ { "description": null, "name": "serial_number", "optional": false, "repeats": false }, { "description": null, "name": "return_type", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 2, "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": "Week of the year a date falls in", "short_source": "dna-calc-own" }, "docs": { "english_description": "Converts a serial number to a number representing where the week falls numerically with a year", "microsoft_url": "https://support.microsoft.com/en-us/office/weeknum-function-e5c43a03-b4ab-426c-b411-b18c13c75340" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "WEEKNUM" }, { "locale": "bg-BG", "name": "WEEKNUM" }, { "locale": "cs-CZ", "name": "WEEKNUM" }, { "locale": "da-DK", "name": "UGE.NR" }, { "locale": "de-DE", "name": "WEEKNUM" }, { "locale": "el-GR", "name": "WEEKNUM" }, { "locale": "en-AU", "name": "WEEKNUM" }, { "locale": "en-GB", "name": "WEEKNUM" }, { "locale": "en-US", "name": "WEEKNUM" }, { "locale": "es-ES", "name": "NUM.DE.SEMANA" }, { "locale": "et-EE", "name": "WEEKNUM" }, { "locale": "fi-FI", "name": "WEEKNUM" }, { "locale": "fr-FR", "name": "NO.SEMAINE*" }, { "locale": "he-IL", "name": "WEEKNUM" }, { "locale": "hr-HR", "name": "WEEKNUM" }, { "locale": "hu-HU", "name": "HÉT.SZÁMA" }, { "locale": "id-ID", "name": "WEEKNUM" }, { "locale": "it-IT", "name": "WEEKNUM" }, { "locale": "ja-JP", "name": "WEEKNUM" }, { "locale": "ko-KR", "name": "WEEKNUM" }, { "locale": "lt-LT", "name": "WEEKNUM" }, { "locale": "lv-LV", "name": "WEEKNUM" }, { "locale": "nb-NO", "name": "WEEKNUM" }, { "locale": "nl-NL", "name": "WEEKNUM" }, { "locale": "pl-PL", "name": "NUM.TYG" }, { "locale": "pt-BR", "name": "WEEKNUM" }, { "locale": "pt-PT", "name": "NÚMSEMANA" }, { "locale": "ro-RO", "name": "WEEKNUM" }, { "locale": "ru-RU", "name": "НОМНЕДЕЛИ" }, { "locale": "sk-SK", "name": "WEEKNUM" }, { "locale": "sl-SI", "name": "WEEKNUM" }, { "locale": "sr-Latn-RS", "name": "WEEKNUM" }, { "locale": "sv-SE", "name": "VECKONR" }, { "locale": "th-TH", "name": "WEEKNUM" }, { "locale": "tr-TR", "name": "HAFTASAY işlevi" }, { "locale": "uk-UA", "name": "WEEKNUM" }, { "locale": "vi-VN", "name": "WEEKNUM" }, { "locale": "zh-CN", "name": "WEEKNUM" }, { "locale": "zh-HK", "name": "WEEKNUM" }, { "locale": "zh-TW", "name": "WEEKNUM" } ], "signature": { "display": "WEEKNUM(serial_number, [return_type])", "parameters": [ { "description": null, "name": "serial_number", "optional": false, "repeats": false }, { "description": null, "name": "return_type", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "WEEKNUM", "version_marker": null, "xlcall": { "code": "465", "symbol": "xlfWeeknum" } }, "microsoft": "https://support.microsoft.com/en-us/office/weeknum-function-e5c43a03-b4ab-426c-b411-b18c13c75340" }, "try_it": { "formula": "=WEEKNUM(0)" }, "url": "https://handbook.dnacalc.com/functions/WEEKNUM.html", "variants": [ { "code": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/dates.rs#L310-L314", "difference": "Two capture runs in one environment disagree on 479 recorded inputs: one recorded #NUM! where the other recorded a week number. The recorded cause is unresolved.", "error_bound": null, "evidence": [ { "commit": "4287ba192d2e3a7fd54671ea1cee1c34cb2e84e2", "locator": "", "note": "compared with runs/w111-date-conversion-20260929/answers/answers-weeknum.json.gz", "path": "runs/w111-date-boundaries-20260929/answers/answers-weeknum.json.gz", "repository": "CalcFunc-Evidence" } ], "key": { "cpu": "CPU not recorded (Windows, 64-bit)", "excel_build_range": "16.0 build 20430" }, "kind": "environment", "name": "WEEKNUM conflicting readings, Excel 16.0 build 20430", "onecalc_udf": null, "state": "differs", "state_summary": "One implementation can match only one reading of each conflicting input." } ], "versions": [ { "behaviour": "WEEKNUM(0, 23) returned #NUM!. WEEKNUM(0, 23) returned 1 (0x3ff0000000000000). 2 further recorded controls are attached. Inputs were supplied through cells using Value2. These are controls from this environment, not a same-input comparison with another build.", "excel_build": "16.0 build 20430", "observations": [ { "call": "WEEKNUM(0, 23)", "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "cell-value2", "inputs": [ { "name": "serial_number", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } }, { "name": "return_type", "value": { "bits": "0x4037000000000000", "display": "23", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, CPU not recorded in this capture" }, { "call": "WEEKNUM(0, 23)", "excel": { "bits": "0x3ff0000000000000", "display": "1", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "serial_number", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } }, { "name": "return_type", "value": { "bits": "0x4037000000000000", "display": "23", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, CPU not recorded in this capture" }, { "call": "WEEKNUM(0, 33)", "excel": { "bits": "0x0000000000000000", "display": "0", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "serial_number", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } }, { "name": "return_type", "value": { "bits": "0x4040800000000000", "display": "33", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, CPU not recorded in this capture" }, { "call": "WEEKNUM(0, 33)", "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "cell-value2", "inputs": [ { "name": "serial_number", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } }, { "name": "return_type", "value": { "bits": "0x4040800000000000", "display": "33", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, CPU not recorded in this capture" } ], "platform": "Windows 64-bit, CPU not recorded in this capture", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/3345a87/content/notes/FN-WEEKNUM-001.json" ] }, { "behaviour": "13,332 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.WEEKNUM.json" ] } ] }