COUPDAYBS 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.

=COUPDAYBS(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 =COUPDAYBS($B$2,$B$3,$B$4,$B$5,$B$6). The independent expected result is 135, a number of convention days, not a date serial.

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.

Under basis 0, the December 31 start is adjusted to day 30. Moving five 30-day months to May and ending on day 15 gives 5×30+15−30=135. Ordinary calendar subtraction happens to give 135 for this fixture too, but that coincidence does not make the methods identical.

Change settlement B2 to =DATE(2026,6,15) in a copy. The period still starts on December 31, 2025 and the basis-zero elapsed count becomes 165. With basis 1 the actual count is 166, because the date system counts real days rather than twelve artificial 30-day months.

The table changes one control at a time from the original setup unless it explicitly names the separate historical fixture. Counts are independent source-model calculations, not native worksheet output.

With the original basis-zero inputs, COUPDAYS supplies 180 and the fraction elapsed is 135/180=0.75. For an illustrative principal of 1000 and annual coupon rate 6% paid twice per year, the full regular coupon is 30. Multiplying that coupon by the elapsed fraction gives 22.5.

This is a deliberately regular-period arithmetic illustration, not a valuation of a particular security or a treatment of irregular first/last coupons. COUPDAYBS itself takes neither a rate nor a principal and returns no currency amount. Keep the day-count convention and payment contract explicit before using the fraction elsewhere.

With basis 1, the complete period has 181 actual days and the fraction becomes 135/181, not 0.75. Mixing a numerator from one basis with a denominator from another silently changes the model.

Change B2 to =DATE(2026,6,30). The schedule now starts at June 30 and ends at December 31, so COUPDAYBS returns 0. It does not report the entire period that ended on the settlement date.

The result is consistent with COUPPCD returning the settlement date at this boundary and COUPNCD advancing to the following coupon. This exact-boundary rule matters when a workbook is used on payment dates rather than only between them.

Use settlement November 29, 2002, maturity February 29, 2004 and frequency 4, matching the pinned help’s dates. With eom TRUE, the previous coupon is August 31, 2002 and basis-zero COUPDAYBS is 89. With eom FALSE, the previous coupon is November 29 itself and the elapsed result is 0.

Both cases have the same settlement, maturity and nominal frequency. The difference comes from the maturity-anchored schedule, not from changing the day-count basis. Do not remove the fifth Gnumeric argument while assuming the coupon boundaries stay the same.

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

COUPDAYS, COUPDAYSNC, COUPNCD.