COUPDAYS Function (Gnumeric)

• Release history: NEWS records initial work in 0.57 and implementation in 1.0.2. Initial development is not proof of a complete working 0.57 implementation; the exact first functioning release is unverified.
• 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.

=COUPDAYS(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 =COUPDAYS($B$2,$B$3,$B$4,$B$5,$B$6). The independent expected result is 180, the basis-zero semiannual period denominator.

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 basis 0, 2, 4 or the source extension 5, the helper returns 360/frequency. For basis 3 it returns 365/frequency. Only basis 1 calculates the actual distance between the previous and next coupon dates.

For the original dates and frequency 2, these rules give 180 for bases 0/2/4/5, 182.5 for basis 3, and 181 for basis 1. The 182.5 is not an impossible half-day payment event; it is the fixed annual denominator divided into two periods.

These source-model controls make basis and frequency effects explicit. A result displayed as a date would be misleading: COUPDAYS is a numeric count or denominator, not a coupon-date result.

For the original settlement and maturity, frequency 1 puts settlement between December 31, 2025 and December 31, 2026. Basis-zero COUPDAYS is 360 and basis-one COUPDAYS is 365.

Frequency 4 puts settlement between March 31 and June 30, 2026. Basis zero gives 90, basis one 91, and basis three 91.25. The frequency changes both the scheduled boundaries and, for fixed-denominator bases, the number of divisions of the nominal year.

These calculations do not change the coupon rate or amount because neither is an argument. A payment model must specify those separately rather than treating the day denominator as a monetary result.

In the original actual/actual case, elapsed days are 135 and remaining days are 46, summing to the full 181 days. That is an ordinary calendar partition.

Under basis 2, COUPDAYBS and COUPDAYSNC still use actual differences, so their sum is 181, while COUPDAYS is 180. Under basis 3 the same numerator sum is 181 while COUPDAYS is 182.5. These differences are specified by the helper’s separate branches, not necessarily an error in the workbook.

Under basis 0 the original fixture has 135+45=180, but endpoint adjustments can prevent treating such an identity as a universal rule. Compare functions only after checking both the schedule and each basis-specific computation.

Moving settlement from May 15 to June 15 leaves it within the same coupon period. COUPDAYS stays 180 under basis 0 and 181 under basis 1, even though elapsed and remaining counts change.

At settlement June 30, the next period begins. Its boundaries are June 30 and December 31. Basis zero remains 180, while basis one becomes 184. A constant basis-zero result therefore does not prove that settlement remained in the same calendar interval.

For settlement November 29, 2002, maturity February 29, 2004 and frequency 4, eom TRUE gives the interval August 31–November 30, 2002; eom FALSE gives November 29, 2002–February 28, 2003. Both happen to contain 91 actual days, and both have the basis-zero denominator 90.

The equal outputs do not establish equal coupon boundaries. Use COUPPCD and COUPNCD to inspect the schedule instead of inferring it from a single period-length number.

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, COUPDAYSNC, COUPNCD.