{ "category": "Financial functions", "display_name": "COUPNCD", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.COUPNCD", "implementation_state": { "answer_bank": { "excel_builds": [ "20131", "20430", "?" ], "larger_numeric": 0, "last_bit": 0, "matched": 5584, "other_mismatch": 0, "refused": 0, "rows": 5584, "unread": 0, "worst_ulp": 0 }, "detail": "Recorded: 5,584 in the answer bank and 7 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 5,591 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/bonds.rs#L179-L182", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/coupon_family.rs#L347-L356" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/bonds::basis", "catalogue/bonds::date_out", "catalogue/bonds::coupon_args", "catalogue/financial::date_1900", "locale::days_from_civil", "locale::civil_from_days", "locale::excel_serial_from_ymd", "locale::ymd_from_excel_serial", "ported/coupon_family::max_excel_serial", "ported/coupon_family::days_in_month", "ported/coupon_family::days_from_civil", "ported/coupon_family::excel_serial_from_ymd_unbounded_1900", "ported/coupon_family::parse_basis", "ported/coupon_family::parse_frequency", "ported/coupon_family::check_coupon_dates", "ported/coupon_family::parse_coupon_date", "ported/coupon_family::parse_coupon_context", "ported/coupon_family::coupon_date_before_maturity", "ported/coupon_family::locate_coupon_period" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/bonds.rs#L179-L182", "state": "matches", "suite": null, "summary": "Matches all 5,591 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.COUPNCD.json", "name": "COUPNCD", "notes": [ { "basis": "All 5,584 rows of three recorded sets: 3,012 and 1,512 rows from build 20430, 1,060 from build 20131. The rule was recomputed independently from the calendar and matched all 5,566 number rows with settlement at serial 61 or later, on every basis. The other two number rows have settlement 0 and basis 0, and read 180. In a study of 42 ways to walk and measure the schedule, this was the only one to match all 965 rows with basis exactly 1.", "documentation": null, "evidence": [ { "commit": "14910720ec396f241b46460ecab093f71733c5f5", "locator": "coupdays_kernel", "note": "the rule as implemented", "path": "crates/calc-func/src/ported/coupon_family.rs", "repository": "DnaCalc" }, { "commit": "14910720ec396f241b46460ecab093f71733c5f5", "locator": "coupdays_actual_actual_uses_its_recorded_calendar_interval", "note": "six recorded calls pinned", "path": "crates/calc-func/tests/f3_financial.rs", "repository": "DnaCalc" }, { "commit": "19d810d45ad46fe5d2ddf0f4f582dd603a881a91", "locator": null, "note": "the 42 schedule variants compared on 965 basis 1 rows", "path": "evidence/round24/coupon/coupon-calendar-summary.json", "repository": "DnaCalc-Research" }, { "commit": "19d810d45ad46fe5d2ddf0f4f582dd603a881a91", "locator": null, "note": "5,584 of 5,584 rows matched", "path": "evidence/round24/coupon/coupdays-registered-delta.json", "repository": "DnaCalc-Research" }, { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "COUPDAYS", "note": "matched rows per function", "path": "crates/calc-func/witness-status.tsv", "repository": "DnaCalc" }, { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": null, "note": "1,512 recorded rows, inputs read again", "path": "runs/w111-5-20260924/answers/answers-w1115-coupdays.json.gz", "repository": "CalcFunc-Evidence" } ], "functions": [ "FUNC.COUPDAYS", "FUNC.COUPNCD", "FUNC.COUPPCD" ], "inferred": "The rule reproduces every recorded row; that Excel's code works this way is inferred. For basis 1 no settlement or maturity before serial 61, where Excel's calendar differs from the Gregorian one, is in the recorded rows.", "kind": "quirk", "note_id": "FN-COUPDAYS-001", "open": [], "recorded_on": "2026-11-04", "repros": [ { "call": "COUPDAYS(35748, 35976, 2, 1)", "correct": null, "excel": { "bits": "0x4066e00000000000", "display": "183", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "settlement", "value": { "bits": "0x40e1748000000000", "display": "35748", "kind": "number" } }, { "name": "maturity", "value": { "bits": "0x40e1910000000000", "display": "35976", "kind": "number" } }, { "name": "frequency", "value": { "bits": "0x4000000000000000", "display": "2", "kind": "number" } }, { "name": "basis", "value": { "bits": "0x3ff0000000000000", "display": "1", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, AMD Ryzen 7 4800H", "source": { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": "COUPDAYS|0x40e1748000000000|0x40e1910000000000|0x4000000000000000|0x3ff0000000000000", "note": null, "path": "cache/oracle-20430/build-20430/COUPDAYS.jsonl.gz", "repository": "CalcFunc-Evidence" } }, { "call": "COUPDAYS(36452, 36891, 4, 1)", "correct": null, "excel": { "bits": "0x4056c00000000000", "display": "91", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "settlement", "value": { "bits": "0x40e1cc8000000000", "display": "36452", "kind": "number" } }, { "name": "maturity", "value": { "bits": "0x40e2036000000000", "display": "36891", "kind": "number" } }, { "name": "frequency", "value": { "bits": "0x4010000000000000", "display": "4", "kind": "number" } }, { "name": "basis", "value": { "bits": "0x3ff0000000000000", "display": "1", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, AMD Ryzen 7 4800H", "source": { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": "COUPDAYS|0x40e1cc8000000000|0x40e2036000000000|0x4010000000000000|0x3ff0000000000000", "note": null, "path": "cache/oracle-20430/build-20430/COUPDAYS.jsonl.gz", "repository": "CalcFunc-Evidence" } }, { "call": "COUPDAYS(36812, 47907, 4, 1)", "correct": null, "excel": { "bits": "0x4057000000000000", "display": "92", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "settlement", "value": { "bits": "0x40e1f98000000000", "display": "36812", "kind": "number" } }, { "name": "maturity", "value": { "bits": "0x40e7646000000000", "display": "47907", "kind": "number" } }, { "name": "frequency", "value": { "bits": "0x4010000000000000", "display": "4", "kind": "number" } }, { "name": "basis", "value": { "bits": "0x3ff0000000000000", "display": "1", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, AMD Ryzen 7 4800H", "source": { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": "COUPDAYS|0x40e1f98000000000|0x40e7646000000000|0x4010000000000000|0x3ff0000000000000", "note": null, "path": "cache/oracle-20430/build-20430/COUPDAYS.jsonl.gz", "repository": "CalcFunc-Evidence" } }, { "call": "COUPDAYS(37015, 38137, 4, 1)", "correct": null, "excel": { "bits": "0x4056400000000000", "display": "89", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "settlement", "value": { "bits": "0x40e212e000000000", "display": "37015", "kind": "number" } }, { "name": "maturity", "value": { "bits": "0x40e29f2000000000", "display": "38137", "kind": "number" } }, { "name": "frequency", "value": { "bits": "0x4010000000000000", "display": "4", "kind": "number" } }, { "name": "basis", "value": { "bits": "0x3ff0000000000000", "display": "1", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, AMD Ryzen 7 4800H", "source": { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": "COUPDAYS|0x40e212e000000000|0x40e29f2000000000|0x4010000000000000|0x3ff0000000000000", "note": null, "path": "cache/oracle-20430/build-20430/COUPDAYS.jsonl.gz", "repository": "CalcFunc-Evidence" } }, { "call": "COUPDAYS(38044, 38411, 2, 1)", "correct": null, "excel": { "bits": "0x4067000000000000", "display": "184", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "settlement", "value": { "bits": "0x40e2938000000000", "display": "38044", "kind": "number" } }, { "name": "maturity", "value": { "bits": "0x40e2c16000000000", "display": "38411", "kind": "number" } }, { "name": "frequency", "value": { "bits": "0x4000000000000000", "display": "2", "kind": "number" } }, { "name": "basis", "value": { "bits": "0x3ff0000000000000", "display": "1", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, AMD Ryzen 7 4800H", "source": { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": "COUPDAYS|0x40e2938000000000|0x40e2c16000000000|0x4000000000000000|0x3ff0000000000000", "note": null, "path": "cache/oracle-20430/build-20430/COUPDAYS.jsonl.gz", "repository": "CalcFunc-Evidence" } }, { "call": "COUPDAYS(34911, 35216, 2, 1)", "correct": null, "excel": { "bits": "0x4066e00000000000", "display": "183", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "settlement", "value": { "bits": "0x40e10be000000000", "display": "34911", "kind": "number" } }, { "name": "maturity", "value": { "bits": "0x40e1320000000000", "display": "35216", "kind": "number" } }, { "name": "frequency", "value": { "bits": "0x4000000000000000", "display": "2", "kind": "number" } }, { "name": "basis", "value": { "bits": "0x3ff0000000000000", "display": "1", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, AMD Ryzen 7 4800H", "source": { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": "COUPDAYS|0x40e10be000000000|0x40e1320000000000|0x4000000000000000|0x3ff0000000000000", "note": null, "path": "cache/oracle-20430/build-20430/COUPDAYS.jsonl.gz", "repository": "CalcFunc-Evidence" } }, { "call": "COUPPCD(44043, 2958465, 2, 1)", "correct": null, "excel": { "bits": "0x40e57d8000000000", "display": "44012", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "settlement", "value": { "bits": "0x40e5816000000000", "display": "44043", "kind": "number" } }, { "name": "maturity", "value": { "bits": "0x4146924080000000", "display": "2958465", "kind": "number" } }, { "name": "frequency", "value": { "bits": "0x4000000000000000", "display": "2", "kind": "number" } }, { "name": "basis", "value": { "bits": "0x3ff0000000000000", "display": "1", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, AMD Ryzen 7 4800H", "source": { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": "COUPPCD|0x40e5816000000000|0x4146924080000000|0x4000000000000000|0x3ff0000000000000", "note": null, "path": "cache/oracle-20430/build-20430/COUPPCD.jsonl.gz", "repository": "CalcFunc-Evidence" } }, { "call": "COUPNCD(44043, 2958465, 2, 1)", "correct": null, "excel": { "bits": "0x40e5948000000000", "display": "44196", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "settlement", "value": { "bits": "0x40e5816000000000", "display": "44043", "kind": "number" } }, { "name": "maturity", "value": { "bits": "0x4146924080000000", "display": "2958465", "kind": "number" } }, { "name": "frequency", "value": { "bits": "0x4000000000000000", "display": "2", "kind": "number" } }, { "name": "basis", "value": { "bits": "0x3ff0000000000000", "display": "1", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, AMD Ryzen 7 4800H", "source": { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": "COUPNCD|0x40e5816000000000|0x4146924080000000|0x4000000000000000|0x3ff0000000000000", "note": null, "path": "cache/oracle-20430/build-20430/COUPNCD.jsonl.gz", "repository": "CalcFunc-Evidence" } }, { "call": "COUPDAYS(44043, 2958465, 2, 1)", "correct": null, "excel": { "bits": "0x4066e00000000000", "display": "183", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "settlement", "value": { "bits": "0x40e5816000000000", "display": "44043", "kind": "number" } }, { "name": "maturity", "value": { "bits": "0x4146924080000000", "display": "2958465", "kind": "number" } }, { "name": "frequency", "value": { "bits": "0x4000000000000000", "display": "2", "kind": "number" } }, { "name": "basis", "value": { "bits": "0x3ff0000000000000", "display": "1", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, AMD Ryzen 7 4800H", "source": { "commit": "4d5320dfdc385354469b4d506153357bb932ab08", "locator": "COUPDAYS|0x40e5816000000000|0x4146924080000000|0x4000000000000000|0x3ff0000000000000", "note": null, "path": "cache/oracle-20430/build-20430/COUPDAYS.jsonl.gz", "repository": "CalcFunc-Evidence" } } ], "schema": "efh.function-note/v1", "statement": "On basis 1 (actual/actual) COUPDAYS does not always equal COUPNCD minus COUPPCD. Its rule: start at maturity and step back by 12/frequency months. Each step keeps the day of the month and clamps it to the length of the target month, and the clamped date is the start of the next step, so passing through February lowers the day for every earlier date. Stop at the last date still after settlement, call it next. The answer is the number of actual days from one period before next up to next, and this last step keeps month ends: if next is the last day of its month, the start is the last day of its month. On the other bases the answer is 360/frequency (bases 0, 2, 4) or 365/frequency (basis 3). With this rule, all 5,584 recorded rows match (4,072 distinct inputs): 5,568 numbers and 16 #NUM!, from Excel builds 20131 and 20430. Of the 967 basis 1 rows, 81 (49 distinct inputs) differ from the day count between the dates of a schedule anchored on maturity with month ends kept. For maturity 1998-06-30 with semi-annual coupons, COUPDAYS(35748,35976,2,1) is 183, from 1997-06-30 to 1997-12-30; the anchored schedule gives 184. In one recorded case all three functions were read on the same inputs: COUPNCD(44043,2958465,2,1) less COUPPCD is 44196 - 44012 = 184, and COUPDAYS is 183.", "status": "measured", "title": "On basis 1 COUPDAYS walks back from maturity by its own rule, not COUPPCD to COUPNCD" }, { "basis": "The rule matches all 429 recorded COUPNUM readings (325 #NUM!, 104 counts) when recomputed independently from the calendar, and the 24 COUPNUM readings of the date-boundary sheets. COUPPCD, COUPNCD, COUPDAYS, COUPDAYBS and COUPDAYSNC companions come from the same sheets.", "documentation": null, "evidence": [ { "commit": "2033d9feb7d9f99817b4b2b34837509bf5af843c", "locator": "coupnum_kernel", "note": "the limit as implemented", "path": "crates/calc-func/src/ported/coupon_family.rs", "repository": "DnaCalc" }, { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "delivered_fn4_coupon_counts_at_calendar_start", "note": "recorded answers pinned", "path": "apps/dna-onecalc/tests/acceptance.rs", "repository": "DnaCalc" }, { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": null, "note": "429 recorded readings", "path": "crates/calc-func/tests/captures/fn4_questions/COUPNUM.reading.json", "repository": "DnaCalc" }, { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheets qd153 to qd236", "note": "boundary sheets for all six coupon functions", "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-date-domain.capture.json", "repository": "DnaCalc" } ], "functions": [ "FUNC.COUPNCD", "FUNC.COUPNUM", "FUNC.COUPPCD" ], "inferred": null, "kind": "quirk", "note_id": "FN-COUPNUM-001", "open": [], "recorded_on": "2026-11-04", "repros": [ { "call": "COUPNUM(33, 400, 2, 0)", "correct": null, "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "cell-value2", "inputs": [ { "name": "settlement", "value": { "bits": "0x4040800000000000", "display": "33", "kind": "number" } }, { "name": "maturity", "value": { "bits": "0x4079000000000000", "display": "400", "kind": "number" } }, { "name": "frequency", "value": { "bits": "0x4000000000000000", "display": "2", "kind": "number" } }, { "name": "basis", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } } ], "recorded_in": "Excel 16.0.20527.20088, Windows, bitness and CPU not recorded in this reading file", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "fn7-COUPNUM-calendar-boundary-127", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/COUPNUM.reading.json", "repository": "DnaCalc" } }, { "call": "COUPNUM(34, 400, 2, 0)", "correct": null, "excel": { "bits": "0x4000000000000000", "display": "2", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "settlement", "value": { "bits": "0x4041000000000000", "display": "34", "kind": "number" } }, { "name": "maturity", "value": { "bits": "0x4079000000000000", "display": "400", "kind": "number" } }, { "name": "frequency", "value": { "bits": "0x4000000000000000", "display": "2", "kind": "number" } }, { "name": "basis", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } } ], "recorded_in": "Excel 16.0.20527.20088, Windows, bitness and CPU not recorded in this reading file", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "fn7-COUPNUM-calendar-boundary-128", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/COUPNUM.reading.json", "repository": "DnaCalc" } }, { "call": "COUPNUM(0, 367, 2, 0)", "correct": null, "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "cell-value2", "inputs": [ { "name": "settlement", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } }, { "name": "maturity", "value": { "bits": "0x4076f00000000000", "display": "367", "kind": "number" } }, { "name": "frequency", "value": { "bits": "0x4000000000000000", "display": "2", "kind": "number" } }, { "name": "basis", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } } ], "recorded_in": "Excel 16.0.20527.20088, Windows, bitness and CPU not recorded in this reading file", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "fn7-COUPNUM-calendar-boundary-85", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/COUPNUM.reading.json", "repository": "DnaCalc" } }, { "call": "=COUPNUM(0,182,2,0)", "correct": null, "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet qd230, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-date-domain.capture.json", "repository": "DnaCalc" } }, { "call": "=COUPNUM(A1,400,2,0)", "correct": null, "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "cell-value2", "inputs": [ { "name": "A1", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } } ], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet qd205, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-date-domain.capture.json", "repository": "DnaCalc" } }, { "call": "=COUPPCD(A1,400,2,0)", "correct": null, "excel": { "bits": "0x0000000000000000", "display": "0", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "A1", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } } ], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet qd217, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-date-domain.capture.json", "repository": "DnaCalc" } }, { "call": "=COUPNCD(A1,400,2,0)", "correct": null, "excel": { "bits": "0x4041000000000000", "display": "34", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "A1", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } } ], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet qd193, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-date-domain.capture.json", "repository": "DnaCalc" } } ], "schema": "efh.function-note/v1", "statement": "If the coupon date before settlement, counted back from maturity, falls before 1 January 1900, COUPNUM gives #NUM!. The other coupon functions still answer for the same inputs: COUPPCD returns 0, COUPNCD the next coupon, and COUPDAYS, COUPDAYBS and COUPDAYSNC a day count. With maturity serial 400 (1901-02-03) and semi-annual coupons, the coupon dates are serials 34 and 216: settlement 33 gives #NUM!, settlement 34 gives 2. With maturity 367, settlement 0 gives #NUM! and settlement 1 gives 2. This covers settlement 0 too: COUPNUM(0,m,2,0) was #NUM! for every maturity read.", "status": "measured", "title": "COUPNUM is #NUM! when the coupon before settlement falls before 1900" } ], "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- **[COUPPCD](FUNC.COUPPCD.md)** — the backward end of the same period. `COUPPCD` and `COUPNCD`\n bracket `settlement`, and together they define the current coupon period.\n- **[COUPDAYBS](FUNC.COUPDAYBS.md)**, **[COUPDAYSNC](FUNC.COUPDAYSNC.md)**,\n **[COUPDAYS](FUNC.COUPDAYS.md)** — the three day counts taken against those two dates, though\n on basis 1 `COUPDAYS` can use another interval (FN-COUPDAYS-001). Note\n that the three do not always add up; see the additivity discussion on\n [COUPDAYS](FUNC.COUPDAYS.md).\n- **[COUPNUM](FUNC.COUPNUM.md)** — how many coupon dates remain from `settlement` to `maturity`\n on the same ladder.\n- **`PRICE`, `YIELD`, `DURATION`, `MDURATION`** — the consumers. They rebuild this same schedule\n internally rather than calling these functions, which is why a schedule disagreement between\n Excel's `COUPNCD` and Excel's `PRICE` is possible in principle and has been observed for the\n *day counts* in this family; see [COUPDAYS](FUNC.COUPDAYS.md).\n- **[EDATE](FUNC.EDATE.md)** and **[EOMONTH](FUNC.EOMONTH.md)** — the general-purpose\n month-stepping functions. `EDATE` clamps the day of month; it does **not** implement\n \"month-end sticks to month-end\". Rebuilding a coupon schedule with `EDATE` therefore\n reproduces `COUPNCD` for ordinary maturities and diverges for month-end ones.\n- **Confused with**: `EDATE(maturity, ±n × 12/frequency)`, for exactly that reason.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\nThere is no floating-point content here worth the name: the answer is an integer-valued date\nserial. The engineering content is all in the schedule.\n\n1. **Iterate or jump, but be consistent.** Stepping back one period at a time and computing the\n period index directly give different answers under a clamping month rule. The reference\n engine iterates.\n2. **The month-end predicate is a decision, not a fact.** \"Is this date the last day of its\n month?\" is cheap; deciding that the answer should *propagate* to every generated date is a\n modelling choice with no documentary support.\n3. **Cost is linear in the settlement-to-maturity gap** under an iterating implementation. A\n 30-year quarterly bond settled at issue costs 120 iterations, which is fine; a synthetic test\n with a maturity centuries out is not.\n4. **Do not route this through a day-count routine.** `basis` must be *validated* and then\n ignored. An implementation that computes the answer via a year fraction will introduce\n basis-dependence into a function that has none.\n\n\n", "quirks": "\n### The coupon schedule\n\n\nNone of the six coupon functions is given a coupon schedule. They are given a **maturity date**\nand a **frequency**, and they reconstruct the schedule from those two facts:\n\n> the coupon dates are maturity, maturity − p, maturity − 2p, maturity − 3p, …\n> where p = 12 / frequency months\n\nCoupon dates are therefore anchored at *maturity*, counted **backwards**, and there is no issue\ndate to stop the schedule; FN-COUPNUM-001 records what Excel does when it runs back past the start\nof 1900. `settlement` selects a period from that ladder: the one whose start is at or before\n`settlement` and whose end is after it.\n\nThree consequences do most of the work on all six pages:\n\n1. **The day of the month comes from maturity, not from settlement.** A bond maturing on the\n 15th has coupons on the 15th. Everything else about the trade is irrelevant to the schedule.\n\n\nThe schedule is *quasi*-periodic, not periodic: because the month-end rule clamps, stepping back\n`n` periods is not always the same as stepping back one period `n` times from an intermediate\ndate. Implementations that step iteratively and implementations that compute the offset in one\njump can disagree.\n\n\n### Result and edge cases\n\n- **`settlement` on a coupon date** returns the *following* coupon date under the reference\n engine, not `settlement` itself. See the schedule section above; this is undocumented.\n- **`settlement` one day before maturity** returns `maturity`, which is always a coupon date by\n construction.\n- **`settlement` ≥ `maturity`** is a documented error.\n- **Month-end maturities** propagate month-end coupon dates: a 31 August maturity at\n `frequency` 2 gives a 28 or 29 February coupon, not a 28th-of-the-month coupon.\n- Empty, missing and error arguments follow the shared call model.\n\n\n\n### Errors\n\n\nDocumented on Microsoft's Learn page for this function, in these words (it says \"generates an\nerror\" without naming a worksheet error value):\n\n| Condition (documented) | Documented outcome |\n|---|---|\n| `settlement` or `maturity` is not a valid date | error |\n| `frequency` is any number other than 1, 2 or 4 | error |\n| `basis` < 0 or `basis` > 4 | error |\n| `settlement` ≥ `maturity` | error |\n\n", "sources": "- Microsoft Learn, **WorksheetFunction.CoupNcd method (Excel)** —\n . Source of\n the one-line description, the parameter table with its quoted argument descriptions, the\n five-row basis table, the `Double` return type, the \"All arguments are truncated to integers\"\n rule, the date-entry warning, and the four error conditions.\n- Microsoft 365 support, **COUPNCD function** —\n .\n The worksheet-surface page; **not retrieved** for this entry (the host returned HTTP 403), so\n nothing here is quoted from it.\n- Handbook evidence record `EV-FIN-0030` — what the six `COUP*` figures are, and are not.\n- Handbook chapters [01 the value universe](../model/01-value-universe.md),\n [02 coercion and lifting](../model/02-coercion-and-lifting.md),\n [06 claim language](../model/06-claim-language.md).\n- `data/functions/FUNC.COUPNCD.json`, `data/presence/FUNC.COUPNCD.json`,\n `data/battery/FUNC.COUPNCD.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| 20131 | Windows, bitness not recorded, AMD Ryzen 7 4800H with Radeon Graphics | 1,060 |\n| 20430 | Windows, 64-bit, AMD Ryzen 7 4800H with Radeon Graphics | 3,012 |\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.COUPNCD.json).", "what-it-does": "\n`COUPNCD(settlement, maturity, frequency, [basis])` returns **the next coupon date strictly\nafter the settlement date** — as a date serial, which Excel's date formatting renders as a date.\n\nMicrosoft's Learn page describes it as returning \"a number that represents the next coupon date\nafter the settlement date\", and declares the return type as `Double`. It is a date-valued\nfunction returning a plain number.\n\nThe whole content of the function is the schedule it derives, so this page hosts the\ndescription that the other five coupon functions refer to.\n\n\n\n### Arguments\n\n\n`COUPNCD(settlement, maturity, frequency, [basis])` — the same four arguments as every other\nmember of the family.\n\n| Argument | Meaning | Required? |\n|---|---|---|\n| `settlement` | The security's settlement date — \"the date after the issue date when the security is traded to the buyer\". | Required |\n| `maturity` | The security's maturity date — \"the date when the security expires\". | Required |\n| `frequency` | Coupon payments per year. Microsoft: \"For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.\" | Required |\n| `basis` | The day-count basis, 0–4. | Optional, defaults to 0 |\n\nThe argument descriptions are quoted from Microsoft's Learn page.\n\n`basis` is documented on this page with the standard five-row table:\n\n| `basis` | Day count basis |\n|---|---|\n| 0 or omitted | US (NASD) 30/360 |\n| 1 | Actual/actual |\n| 2 | Actual/360 |\n| 3 | Actual/365 |\n| 4 | European 30/360 |\n\n**`basis` cannot change this function's answer.** A coupon date is a calendar date; no day-count\nconvention moves it. `COUPNCD` nevertheless accepts `basis` and validates it, so an out-of-range\n`basis` turns a perfectly well-defined date into an error. That is a real, observable dependency\non an argument that does not participate in the computation — worth knowing when a `COUPNCD`\nformula starts erroring after someone edits a shared basis cell.\n\nMicrosoft documents that **\"All arguments are truncated to integers.\"** Dates should be produced\nby `DATE` or by other formulas rather than typed as text; ordinary coercion rules are in\n[Coercion and lifting](../model/02-coercion-and-lifting.md).\n\n\n" }, "signature": { "display": "COUPNCD(settlement, maturity, frequency, [basis])", "parameters": [ { "description": null, "name": "settlement", "optional": false, "repeats": false }, { "description": null, "name": "maturity", "optional": false, "repeats": false }, { "description": null, "name": "frequency", "optional": false, "repeats": false }, { "description": null, "name": "basis", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 4, "min": 3 }, "category": "Financial 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": "Coupon date that follows the settlement date", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the next coupon date after the settlement date", "microsoft_url": "https://support.microsoft.com/en-us/office/coupncd-function-fd962fef-506b-4d9d-8590-16df5393691f" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "COUPNCD" }, { "locale": "bg-BG", "name": "COUPNCD" }, { "locale": "cs-CZ", "name": "COUPNCD" }, { "locale": "da-DK", "name": "KUPONDAG.NÆSTE" }, { "locale": "de-DE", "name": "COUPNCD" }, { "locale": "el-GR", "name": "COUPNCD" }, { "locale": "en-AU", "name": "COUPNCD" }, { "locale": "en-GB", "name": "COUPNCD" }, { "locale": "en-US", "name": "COUPNCD" }, { "locale": "es-ES", "name": "CUPON.FECHA.L2" }, { "locale": "et-EE", "name": "COUPNCD" }, { "locale": "fi-FI", "name": "KORKOPÄIVÄ.SEURAAVA" }, { "locale": "fr-FR", "name": "DATE.COUPON.SUIV*" }, { "locale": "he-IL", "name": "COUPNCD" }, { "locale": "hr-HR", "name": "COUPNCD" }, { "locale": "hu-HU", "name": "ELSŐ.SZELVÉNYDÁTUM" }, { "locale": "id-ID", "name": "COUPNCD" }, { "locale": "it-IT", "name": "COUPNCD" }, { "locale": "ja-JP", "name": "COUPNCD" }, { "locale": "ko-KR", "name": "COUPNCD" }, { "locale": "lt-LT", "name": "COUPNCD" }, { "locale": "lv-LV", "name": "COUPNCD" }, { "locale": "nb-NO", "name": "COUPNCD" }, { "locale": "nl-NL", "name": "COUP.DATUM.NB" }, { "locale": "pl-PL", "name": "WYPŁ.DATA.NAST" }, { "locale": "pt-BR", "name": "COUPNCD" }, { "locale": "pt-PT", "name": "CUPDATAPRÓX" }, { "locale": "ro-RO", "name": "COUPNCD" }, { "locale": "ru-RU", "name": "ДАТАКУПОНПОСЛЕ" }, { "locale": "sk-SK", "name": "COUPNCD" }, { "locale": "sl-SI", "name": "COUPNCD" }, { "locale": "sr-Latn-RS", "name": "COUPNCD" }, { "locale": "sv-SE", "name": "KUPNKD" }, { "locale": "th-TH", "name": "COUPNCD" }, { "locale": "tr-TR", "name": "KUPONGÜNSKT işlevi" }, { "locale": "uk-UA", "name": "COUPNCD" }, { "locale": "vi-VN", "name": "COUPNCD" }, { "locale": "zh-CN", "name": "COUPNCD" }, { "locale": "zh-HK", "name": "COUPNCD" }, { "locale": "zh-TW", "name": "COUPNCD" } ], "signature": { "display": "COUPNCD(settlement, maturity, frequency, [basis])", "parameters": [ { "description": null, "name": "settlement", "optional": false, "repeats": false }, { "description": null, "name": "maturity", "optional": false, "repeats": false }, { "description": null, "name": "frequency", "optional": false, "repeats": false }, { "description": null, "name": "basis", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "COUPNCD", "version_marker": null, "xlcall": { "code": "455", "symbol": "xlfCoupncd" } }, "microsoft": "https://support.microsoft.com/en-us/office/coupncd-function-fd962fef-506b-4d9d-8590-16df5393691f" }, "try_it": { "formula": "=COUPNCD(44043, 2958465, 2, 1)" }, "url": "https://handbook.dnacalc.com/functions/COUPNCD.html", "variants": [], "versions": [ { "behaviour": "COUPNCD(44043, 2958465, 2, 1) returned 44196 (0x40e5948000000000). 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": "COUPNCD(44043, 2958465, 2, 1)", "excel": { "bits": "0x40e5948000000000", "display": "44196", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "settlement", "value": { "bits": "0x40e5816000000000", "display": "44043", "kind": "number" } }, { "name": "maturity", "value": { "bits": "0x4146924080000000", "display": "2958465", "kind": "number" } }, { "name": "frequency", "value": { "bits": "0x4000000000000000", "display": "2", "kind": "number" } }, { "name": "basis", "value": { "bits": "0x3ff0000000000000", "display": "1", "kind": "number" } } ], "recorded_in": "Excel 16.0 build 20430, Windows 64-bit, AMD Ryzen 7 4800H" } ], "platform": "Windows 64-bit, AMD Ryzen 7 4800H", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/3345a87/content/notes/FN-COUPDAYS-001.json" ] }, { "behaviour": "=COUPNCD(A1,400,2,0) returned 34 (0x4041000000000000). 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.20527.20088", "observations": [ { "call": "=COUPNCD(A1,400,2,0)", "excel": { "bits": "0x4041000000000000", "display": "34", "kind": "number" }, "input_route": "cell-value2", "inputs": [ { "name": "A1", "value": { "bits": "0x0000000000000000", "display": "0", "kind": "number" } } ], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA" } ], "platform": "Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/3345a87/content/notes/FN-COUPNUM-001.json" ] }, { "behaviour": "1,060 captured inputs are indexed for this environment. Capture dates: 2026-07-19 to 2026-07-19. This is a reading count, not a comparison with another build.", "excel_build": "16.0 build 20131", "platform": "Windows, bitness not recorded, AMD Ryzen 7 4800H with Radeon Graphics", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.COUPNCD.json" ] }, { "behaviour": "3,012 captured inputs are indexed for this environment. Capture dates: 2026-09-24 to 2026-09-25. This is a reading count, not a comparison with another build.", "excel_build": "16.0 build 20430", "platform": "Windows, 64-bit, AMD Ryzen 7 4800H with Radeon Graphics", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.COUPNCD.json" ] } ] }