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

    Format a civil date as exact YYYY-MM-DD text.

    toIso() -> string
    Module
    std.date
    Receiver
    Date
    Minimum arity
    0
    Maximum arity
    0

    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.parseIso accepts exactly ten ASCII characters in the form YYYY-MM-DD. The year has four digits and the month and day each have two digits. Hyphens occur after the year and month.

    The components must form a valid Gregorian date in the same range as Date.fromYmd. Valid text returns Ok containing that date. Invalid grammar or an invalid calendar date returns Err containing a descriptive nonempty string.

    Parsing does not trim whitespace or normalize another spelling. Signs, omitted zero padding, alternate separators, non ASCII digits, timestamps, time zones, and extra characters are rejected.

    Date.toIso returns exactly the same ten character form using ASCII digits and zero padding. It has no locale or time zone parameter and leaves the receiver unchanged.

    Parsing the formatted text recovers the original date. Formatting accepted input returns that same text. Date.fromYmd and Date.parseIso establish the same component and range invariants.

    The receiver or argument is evaluated once before the operation. These operations do not change the input or perform external effects. Error strings have no stable machine readable format.

    Related rule: Exchange dates in one fixed ISO form

    Result

    Additional contracts are Pending.

    The declared result type is string.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    The result uses ASCII digits and zero padding and round trips through Date.parseIso.

    Resolved contracts

    Link

    Related entries

    Link

    std.date

    Exchange dates in one fixed ISO form

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

    Exchange dates in one fixed ISO form

    Date.parseIso accepts exactly ten ASCII characters in the form YYYY-MM-DD. The year has four digits and the month and day each have two digits. Hyphens occur after the year and month.

    The components must form a valid Gregorian date in the same range as Date.fromYmd. Valid text returns Ok containing that date. Invalid grammar or an invalid calendar date returns Err containing a descriptive nonempty string.

    Parsing does not trim whitespace or normalize another spelling. Signs, omitted zero padding, alternate separators, non ASCII digits, timestamps, time zones, and extra characters are rejected.

    Date.toIso returns exactly the same ten character form using ASCII digits and zero padding. It has no locale or time zone parameter and leaves the receiver unchanged.

    Parsing the formatted text recovers the original date. Formatting accepted input returns that same text. Date.fromYmd and Date.parseIso establish the same component and range invariants.

    The receiver or argument is evaluated once before the operation. These operations do not change the input or perform external effects. Error strings have no stable machine readable format.

    Why

    One fixed calendar format makes date text predictable to store, compare lexically, and exchange. Sharing validation with component construction prevents two constructors from assigning different meanings to the same date.

    Examples Parse canonical date text and preserve its componentsReject alternate spellings and invalid calendar datesReject year zero in ISO text

    Source evidence

    Parse canonical date text and preserve its components

    Link

    run · running · Verification: not-run

    main.tpzParse canonical date text and preserve its componentsOpen in Playground
    1. import std.date { Date }
    2. import std.test
    3. import std.io
    5. for text in (["0001-01-01", "1582-10-10", "2000-02-29", "9999-12-31"]) {
    6. let date = test.assertOk(Date.parseIso(text))
    7. io.writeLine(date.toIso())
    8. }
    9. let leap = test.assertOk(Date.parseIso("2000-02-29"))
    10. io.writeLine("{leap.year()} {leap.month()} {leap.day()}")
    Expected outputexit 0
    0001-01-01
1582-10-10
2000-02-29
9999-12-31
2000 2 29
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 0001-01-01
    2. 1582-10-10
    3. 2000-02-29
    4. 9999-12-31
    5. 2000 2 29

    This exact example has not been executed.

    Source evidence

    Reject alternate spellings and invalid calendar dates

    Link

    run · running · Verification: not-run

    main.tpzReject alternate spellings and invalid calendar datesOpen in Playground
    1. import std.date { Date }
    2. import std.io
    4. for text in (["", "2024-2-09", "2024-02-9", "2024/02/09", " 2024-02-09", "2024-02-09 ", "2024-02-09T00:00:00Z", "+2024-02-09", "２０２４-02-09", "2024-02-30", "1900-02-29", "10000-01-01"]) {
    5. match (Date.parseIso(text)) {
    6. case Err(_) => io.writeLine("rejected")
    7. case Ok(_) => io.writeLine("accepted")
    8. }
    9. }
    Expected outputexit 0
    rejected
rejected
rejected
rejected
rejected
rejected
rejected
rejected
rejected
rejected
rejected
rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. rejected
    2. rejected
    3. rejected
    4. rejected
    5. rejected
    6. rejected
    7. rejected
    8. rejected
    9. rejected
    10. rejected
    11. rejected
    12. rejected

    This exact example has not been executed.

    Source evidence

    Reject year zero in ISO text

    Link

    run · running · Verification: not-run

    main.tpzReject year zero in ISO textOpen in Playground
    1. import std.date { Date }
    2. import std.io
    4. match (Date.parseIso("0000-01-01")) {
    5. case Err(_) => io.writeLine("year zero rejected")
    6. case Ok(_) => io.writeLine("accepted")
    7. }
    Expected outputexit 0
    year zero rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. year zero rejected

    This exact example has not been executed.

    Source evidence

    Menu

    Download