Skip to content
Topaz6.0 · Before release
Download

Search documentation

Specification 6.0 · Not released · Tested product 5.21.3

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Library · std.date

    Date.addDays

    Add signed whole days within the civil date range.

    addDays(days: int) -> Date
    Module
    std.date
    Receiver
    Date
    Minimum arity
    1
    Maximum arity
    1

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.date in language mode 5.21.

    The current compiler selects std/date.tpz for this language mode. Availability in other released editions and inclusion in each installed distribution are Pending.

    Source evidence

    Receiver

    Date

    Parameter constraints

    Additional contracts are Pending.

    Date.addDays accepts a signed int count of whole calendar days. Positive values move forward, negative values move backward, and zero returns the same date value.

    The result follows the same proleptic Gregorian calendar as Date.fromYmd. Month boundaries, leap days, and year boundaries are crossed by counting calendar days. Historical calendar cutovers and daylight saving changes do not alter the result.

    The result must remain from 0001-01-01 through 9999-12-31. A count whose mathematical result is outside that range raises TPZ4004 during execution. An intermediate integer overflow also raises TPZ4004.

    An invalid result does not wrap, saturate, return a partial date, or change the receiver. Evaluation stops at the fault before later statements run.

    The receiver is evaluated before the day count and each is evaluated once. An earlier fault prevents later evaluation. The operation has no external effects.

    Adding a count and then its negative recovers the starting date when both results lie in range. Date.toIso and the component accessors observe the resulting date without changing it.

    Related rule: Add whole calendar days within the civil date range

    Result

    Additional contracts are Pending.

    The declared result type is Date.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Calendar arithmetic preserves the receiver. A result outside years 1 through 9999 raises TPZ4004.

    Resolved contracts

    Link

    Related entries

    Link

    std.date

    Add whole calendar days within the civil date range

    Link
    Ruletopaz.stdlib.contract.date-arithmetic.rule

    Add whole calendar days within the civil date range

    Date.addDays accepts a signed int count of whole calendar days. Positive values move forward, negative values move backward, and zero returns the same date value.

    The result follows the same proleptic Gregorian calendar as Date.fromYmd. Month boundaries, leap days, and year boundaries are crossed by counting calendar days. Historical calendar cutovers and daylight saving changes do not alter the result.

    The result must remain from 0001-01-01 through 9999-12-31. A count whose mathematical result is outside that range raises TPZ4004 during execution. An intermediate integer overflow also raises TPZ4004.

    An invalid result does not wrap, saturate, return a partial date, or change the receiver. Evaluation stops at the fault before later statements run.

    The receiver is evaluated before the day count and each is evaluated once. An earlier fault prevents later evaluation. The operation has no external effects.

    Adding a count and then its negative recovers the starting date when both results lie in range. Date.toIso and the component accessors observe the resulting date without changing it.

    Why

    Calendar arithmetic should depend on a date and a day count. A bounded result with an explicit overflow fault prevents wraparound from silently producing a different civil date.

    Examples Cross leap days, years, and the full supported intervalReject the day after the final supported dateReject the day before the first supported dateReject a day count that overflows signed arithmeticEvaluate a date receiver before its day count

    Diagnostics TPZ4004

    Source evidence

    Cross leap days, years, and the full supported interval

    Link

    run · running · Verification: not-run

    main.tpzCross leap days, years, and the full supported intervalOpen in Playground
    1. import std.date { Date }
    2. import std.test
    3. import std.io
    5. let leap = test.assertOk(Date.fromYmd(2000, 2, 28))
    6. io.writeLine(leap.addDays(1).toIso())
    7. io.writeLine(leap.addDays(2).toIso())
    8. io.writeLine(leap.toIso())
    9. io.writeLine(test.assertOk(Date.fromYmd(1900, 2, 28)).addDays(1).toIso())
    10. io.writeLine(test.assertOk(Date.fromYmd(1582, 10, 4)).addDays(1).toIso())
    11. io.writeLine(test.assertOk(Date.fromYmd(2000, 1, 1)).addDays(-1).toIso())
    12. io.writeLine(leap.addDays(0).toIso())
    13. io.writeLine(test.assertOk(Date.fromYmd(1, 1, 1)).addDays(3652058).toIso())
    14. io.writeLine(test.assertOk(Date.fromYmd(9999, 12, 31)).addDays(-3652058).toIso())
    Expected outputexit 0
    2000-02-29
2000-03-01
2000-02-28
1900-03-01
1582-10-05
1999-12-31
2000-02-28
9999-12-31
0001-01-01
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 2000-02-29
    2. 2000-03-01
    3. 2000-02-28
    4. 1900-03-01
    5. 1582-10-05
    6. 1999-12-31
    7. 2000-02-28
    8. 9999-12-31
    9. 0001-01-01

    This exact example has not been executed.

    Source evidence

    Reject the day after the final supported date

    Link

    run · running · Verification: not-run

    main.tpzReject the day after the final supported dateOpen in Playground
    1. import std.date { Date }
    2. import std.test
    3. import std.io
    5. let date = test.assertOk(Date.fromYmd(9999, 12, 31))
    6. date.addDays(1)
    7. io.writeLine("after")
    Expected outputNonzero exit
    No stdout.
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ4004 stdlib-date-range-overflow at main.tpz:6:1

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject the day before the first supported date

    Link

    run · running · Verification: not-run

    main.tpzReject the day before the first supported dateOpen in Playground
    1. import std.date { Date }
    2. import std.test
    3. import std.io
    5. let date = test.assertOk(Date.fromYmd(1, 1, 1))
    6. date.addDays(-1)
    7. io.writeLine("after")
    Expected outputNonzero exit
    No stdout.
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ4004 stdlib-date-range-overflow at main.tpz:6:1

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject a day count that overflows signed arithmetic

    Link

    run · running · Verification: not-run

    main.tpzReject a day count that overflows signed arithmeticOpen in Playground
    1. import std.date { Date }
    2. import std.test
    3. import std.io
    5. let date = test.assertOk(Date.fromYmd(1, 1, 1))
    6. date.addDays(-9223372036854775808)
    7. io.writeLine("after")
    Expected outputNonzero exit
    No stdout.
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ4004 stdlib-date-range-overflow at main.tpz:6:1

    No stdout.

    This exact example has not been executed.

    Source evidence

    Evaluate a date receiver before its day count

    Link

    run · running · Verification: not-run

    main.tpzEvaluate a date receiver before its day countOpen in Playground
    1. import std.date { Date }
    2. import std.test
    3. import std.io
    5. function receiver() -> Date {
    6. io.writeLine("date")
    7. return test.assertOk(Date.fromYmd(2024, 2, 28))
    8. }
    9. function days() -> int {
    10. io.writeLine("days")
    11. return 1
    12. }
    13. let next = receiver().addDays(days())
    14. io.writeLine(next.toIso())
    Expected outputexit 0
    date
days
2024-02-29
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. date
    2. days
    3. 2024-02-29

    This exact example has not been executed.

    Source evidence

    Diagnostics

    Link

    Integer overflow

    Menu

    Download