WORKDAY.INTL

What it does

WORKDAY.INTL(start_date, days, [weekend], [holidays])

WORKDAY.INTL returns the date lying a given number of working days before or after a start date, where which days are weekend is an argument rather than a fixed Saturday and Sunday. It is to WORKDAY what NETWORKDAYS.INTL is to NETWORKDAYS, and it shares the .INTL weekend argument with the former exactly.

The operation is unchanged from WORKDAY: step away from start_date in the direction of days, consuming one unit of the count for each working day stepped onto, and return where you land. Only the definition of "working day" is now parameterized.

Arguments

WORKDAY.INTL(start_date, days, [weekend], [holidays]) — two required and two optional.

start_date — the date to offset from.

days — the number of working days to move; positive forward, negative backward. WORKDAY's page documents that a non-integer days is truncated, and the same rule is expected here.

weekend — optional; the same two-shaped argument documented for NETWORKDAYS.INTL.

As a number:

Codes 1–7 are consecutive pairs starting one day later each time from Saturday; codes 11–17 are single days running Sunday through Saturday. The two blocks do not share an origin, and neither aligns with WEEKDAY's numbering.

As a string: seven characters, one per weekday starting with Monday, "1" for a non-workday and "0" for a workday; only those two characters are permitted. Microsoft's WORKDAY.INTL page adds a rule its sibling's page does not state in the same words: "1111111" is invalid, because at least one workday is required. That prohibition is structurally necessary here in a way it is not for a counting function — a week with no working days makes the offset non-terminating, whereas a count over such a week is simply zero.

holidays — optional range or array of dates to exclude.

The foot-gun is unchanged from the sibling and worth repeating: an unquoted 0000011 is the number 11, a valid weekend code meaning "Sunday only". It produces a plausible wrong answer, not an error.

Try it

Quirks

Result and edge cases

Returns a Number: a whole date serial.

• days = 0 exposes the counting convention, exactly as on WORKDAY, and the page is equally silent about it. Whether a start date falling on a weekend is returned unchanged or snapped is the diagnostic case.
• A six-day weekend leaves one working day per week, which is legal and makes offsets large in calendar terms — a good stress case for any closed-form implementation.
• Holidays that fall on weekend days should contribute nothing; undocumented.
• Consecutive holidays require the exclusion pass to iterate; see the implementer notes.
• Blank cells in a holidays range raise the Empty-versus-Missing question from the value universe; serial 0 is a representable date.

Errors

Documented on the Microsoft page, and this is the fullest error table in the family:

• #NUM! when "start_date is out of range for the current date base value".
• #NUM! when "any date in holidays is out of range for the current date base value".
• #NUM! when "start_date plus day-offset yields an invalid date".
• #VALUE! when "a weekend string is of invalid length or contains invalid characters".

Two observations the Handbook records rather than smooths over:

1. The holidays condition is documented here and not on WORKDAY's page, which mentions only "any argument is not a valid date" (#VALUE!). Two functions performing the same holiday exclusion, documented with different error values for an out-of-range holiday.
2. Only the string form of weekend has a documented invalidity condition. What an out-of-table numeric code does is not stated. Code 0 gives #NUM! (FN-NETWORKDAYS.INTL-001); 8, 10 and 18 are not asserted here.

How to implement

Notes for implementers

1. Normalize weekend to a seven-bit mask once start_date has been read, the order Excel uses (FN-NETWORKDAYS.INTL-001), from either shape, and reject the all-ones mask here even if the counting sibling tolerates it — an offset over a week with no working days does not terminate.
2. Use whole-week arithmetic. With w = popcount(¬mask) working days per week, days decomposes into ⌊days/w⌋ whole weeks plus a remainder resolved against the start day's position in the week. Stepping day by day is correct and unusably slow across the serial range.
3. Iterate the holiday exclusion to a fixed point. Skipping a holiday moves the target, which may itself be a holiday; a single pass is wrong for consecutive holidays.
4. Keep the days = 0 convention identical to WORKDAY's, whatever it turns out to be.
5. Do not share the error path with WORKDAY until the documented divergence above is resolved by observation.

Rust code

20 workday_intl_fn "WORKDAY.INTL" (2, 4) [V "start_date", V "days", V "weekend", R "holidays"] |s, a, sv| {
    workday(s, a, sv, true)
}

No implementation has been published with a Handbook test suite for this function.

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.

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

Recorded environments and comparison details.

Alternatives

Relationships

• WORKDAY — the un-generalized original. WORKDAY(a,n,h) should equal WORKDAY.INTL(a,n,1,h); unverified here.
• NETWORKDAYS.INTL — the inverse operation, sharing this exact weekend argument. Their weekend interpretations must agree or the family is incoherent; that they do is assumed and unchecked.
• NETWORKDAYS — the un-generalized inverse.
• EDATE — month offsetting, the other "move a date by whole units" function, with the same documented truncation rule for its offset argument.

Named variants

No named variants are recorded yet.