COUPNUM Function (Gnumeric)

• Release history: NEWS explicitly implements COUPNUM and COUPNCD in Gnumeric 0.57. This is release-history evidence, not a native test of that old version.
• Source support: Registered in the Gnumeric 1.12.62 financial plugin. No retirement is established. The last functioning native application version is unverified.
• Evidence dates: Gnumeric source retained October 13–14, 2026 was reviewed October 15. The official GOffice 0.10.61 archive was retrieved October 15 and its coupon helpers reviewed that day. Gregorian calendar and exact-rational checks are independent reference calculations; no native Gnumeric, compiled GOffice, headless application or GUI execution occurred.

=COUPNUM(settlement,maturity,frequency[,basis[,eom]])

Settlement and maturity are dates; maturity must be strictly later. Use DATE formulas instead of ambiguous text dates. Frequency is 1 for annual, 2 for semiannual or 4 for quarterly payments. Basis defaults to 0, and the Gnumeric-specific end-of-month flag eom defaults to TRUE.

The documented bases are 0 US 30/360, 1 actual/actual, 2 actual/360, 3 actual/365 and 4 European 30/360. The inspected implementation also accepts 5 and maps it to the GOffice 30E+/360 rule; that source extension should not be mistaken for a universally portable option. Use explicit documented integer conventions in ordinary work.

The schedule is anchored backward from maturity in steps of 12/frequency months. If eom is TRUE and maturity is its month’s final day, intermediate coupon dates are moved to their month ends. Otherwise the maturity day is retained where possible and clipped for a shorter month. This is a scheduled-date calculation, without holiday or business-day adjustment.

Create CouponControls and enter:

In D2 enter =COUPNUM($B$2,$B$3,$B$4,$B$5,$B$6). The independent expected result is 6, a count of remaining scheduled coupons rather than a number of years or convention days.

The surrounding period runs from December 31, 2025 through June 30, 2026. The previous boundary is at or before settlement; the next is strictly after it. Keep frequency, maturity and eom consistent when comparing members of the coupon-function family.

For the original semiannual schedule, the remaining dates are June 30 and December 31, 2026; June 30 and December 31, 2027; June 30 and December 31, 2028. Maturity is included as the final coupon date.

Settlement lies before the first of these dates, so all six are counted. The count does not include the previous boundary December 31, 2025 and does not count every calendar month between the endpoints.

The independent reference count enumerates the maturity-anchored schedule and is cross-checked against the separate month-count source formula. No native coupon function was executed.

Changing settlement from May 15 to June 15, 2026 leaves 6 coupons because the next scheduled coupon is still June 30. At settlement exactly June 30, that coupon is no longer after settlement, so the remaining count becomes 5.

Thus the count is piecewise constant between coupon dates and changes at a boundary. Multiplying a rough year difference by frequency is not a substitute for identifying those boundaries, especially near month ends.

The source uses month arithmetic and integer division to implement the rounded-up count. The examples use valid ordinary dates and explicitly supported frequencies; a floating year-fraction approximation is not the algorithm being certified.

For the same settlement and maturity with frequency 1, the coupons are December 31 of 2026, 2027 and 2028: 3 in total. With frequency 4, there are three remaining 2026 coupons and four in each of 2027 and 2028, giving 11.

A change from two to four payments per year does not necessarily double the remaining count, because settlement can lie partway through the newly divided period. Here 6 becomes 11 rather than 12.

The coupon count is independent of basis in this source, although basis is still validated by the shared wrapper. Do not interpret a matching count under several bases as proof that their accrued-day calculations also match.

For settlement November 29, 2002, maturity February 29, 2004 and frequency 4, eom TRUE leaves 6 coupons, starting November 30, 2002. With eom FALSE, settlement itself is a scheduled November 29 coupon; only 5 later coupons remain, beginning February 28, 2003.

The maturity date and frequency have not changed. The count differs because the flag changes whether the current settlement day is before or on a coupon boundary. This is why the fifth argument cannot be dropped casually when porting a Gnumeric formula.

If each of the original six regular coupons were 30 currency units, their undiscounted sum would be 180. Changing settlement to the June 30 boundary would leave five such coupons, totaling 150.

These are only count-times-amount illustrations. COUPNUM has no rate, principal, yield, redemption or discounting arguments. It does not return a bond price, accrued interest or a present value, and maturity’s redemption payment is not an extra coupon count.

An actual security may have irregular or skipped payments. The regular maturity-anchored schedule cannot infer those contractual features without additional data, so do not turn this enumeration into a claim about a particular investment’s cash flows.

The shared wrapper returns #VALUE! when its date conversion fails, and #NUM! for an invalid frequency/basis or settlement greater than or equal to maturity. Explicit frequency 3 and basis 6 are rejected. Numeric frequency/basis processing includes truncation and bounds checks; use the documented integer settings rather than relying on fractional or locale-sensitive coercion.

The examples use modern DATE values, complete regular schedules and separately controlled changes. Date-system conversion, malformed text, extreme dates, native final-digit behavior and file transfers are not certified. Source review and independent calendar arithmetic do not establish actual GUI or native-library execution.

• Function help and worksheet callback
• Shared coupon validation and defaults, frequency/basis conversion, and coupon count/date wrappers
• Official GOffice 0.10.61 source archive: goffice/utils/datetime.c lines 281–417 for day-count rules and 422–547 for coupon scheduling and denominators; datetime.h lines 78–85 for basis codes.
• Documented basis descriptions
• Gnumeric official function catalogue

COUPDAYBS, COUPDAYS, COUPDAYSNC.