From 783a5c9d372d2e9586864d6e2112b1927f5f8aa9 Mon Sep 17 00:00:00 2001 From: dkirchhof Date: Mon, 20 Feb 2023 17:40:27 +0100 Subject: [PATCH 01/10] add docs for date module (WIP) --- src/Core__Date.resi | 162 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) diff --git a/src/Core__Date.resi b/src/Core__Date.resi index 5b3eab9a..07457bda 100644 --- a/src/Core__Date.resi +++ b/src/Core__Date.resi @@ -2,7 +2,11 @@ Functions for interacting with JavaScript Dates. */ +/** +A type representing a JavaScript date +*/ type t = Js.Date.t + type time = float /** @@ -35,16 +39,125 @@ type localeOptions = { timeZoneName?: [#long | #short], } +/** +`valueOf(date)` + +Returns the time in milliseconds between 1 January 1970 UTC and the given date. +Invalid dates will return NaN. +Dates before 1 January 1970 will return negative numbers. + +The function will return the same result as Date.getTime + +## Examples +```rescript +Date.fromString("2023-02-20")->Date.valueOf +// 1676851200000 +``` +*/ @send external valueOf: t => time = "valueOf" + +/** +`make()` + +Creates a date object with the current date time as value. + +## Examples +```rescript +Date.make() +``` +*/ @new external make: unit => t = "Date" + +/** +`fromString(dateTimeString)` + +Creates a date object from given date time string. +The string has to be in the ISO 8601 format YYYY-MM-DDTHH:mm:ss.sssZ (https://tc39.es/ecma262/#sec-date-time-string-format). +Invalid date time strings will create invalid dates. + +## Examples +```rescript +Date.fromString("2023") +// 2023-01-01T00:00:00.000Z + +Date.fromString("2023-02-20") +// 2023-02-20T00:00:00.000Z + +Date.fromString("2023-02-20T16:40:00.00Z") +// 2023-02-20T16:40:00.000Z +``` +*/ @new external fromString: string => t = "Date" + +/** +`fromTime(deltaMilliseconds)` + +Creates a date object from the given time in milliseconds since / until 1 January 1970 UTC. + +## Examples +```rescript +Date.fromTime(0.0) +// 1970-01-01T00:00:00.000Z + +Date.fromTime(-86_400_000.0) +// 1969-12-31T00:00:00.000Z + +Date.fromTime(86_400_000.0) +// 1970-01-02T00:00:00.000Z +``` +*/ @new external fromTime: time => t = "Date" + +/** +Creates a date object with the given year and month. +Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). +Months are 0-indexed (0 = January, 11 = December). + +## Examples +```rescript +Date.makeWithYM(~year=2023, ~month=0) +// 2023-01-01T00:00:00.000Z + +Date.makeWithYM(~year=2023, ~month=11) +// 2023-12-01T00:00:00.000Z + +Date.makeWithYM(~year=2023, ~month=12) +// 2024-01-01T00:00:00.000Z + +Date.makeWithYM(~year=2023, ~month=-1) +// 2022-12-01T00:00:00.000Z +``` +*/ @new external makeWithYM: (~year: int, ~month: int) => t = "Date" + +/** +Creates a date object with the given year, month and date (day of month). +Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). +Months are 0-indexed (0 = January, 11 = December). +*/ @new external makeWithYMD: (~year: int, ~month: int, ~date: int) => t = "Date" + +/** +Creates a date object with the given year, month, date (day of month) and hours. +Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). +Months are 0-indexed (0 = January, 11 = December). +*/ @new external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => t = "Date" + +/** +Creates a date object with the given year, month, date (day of month), hours and minutes. +Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). +Months are 0-indexed (0 = January, 11 = December). +*/ @new external makeWithYMDHM: (~year: int, ~month: int, ~date: int, ~hours: int, ~minutes: int) => t = "Date" + +/** +Creates a date object with the given year, month, date (day of month), hours, minutes and seconds. +Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). +Months are 0-indexed (0 = January, 11 = December). +*/ @new external makeWithYMDHMS: ( ~year: int, @@ -54,6 +167,12 @@ external makeWithYMDHMS: ( ~minutes: int, ~seconds: int, ) => t = "Date" + +/** +Creates a date object with the given year, month, date (day of month), hours, minutes, seconds and milliseconds. +Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). +Months are 0-indexed (0 = January, 11 = December). +*/ @new external makeWithYMDHMSM: ( ~year: int, @@ -65,10 +184,25 @@ external makeWithYMDHMSM: ( ~milliseconds: int, ) => t = "Date" module UTC: { + /** + Same as Date.makeWithYM, but returns the time since 1 January 1970 in milliseconds. + */ @val external makeWithYM: (~year: int, ~month: int) => time = "Date.UTC" + + /** + Same as Date.makeWithYMD, but returns the time since 1 January 1970 in milliseconds. + */ @val external makeWithYMD: (~year: int, ~month: int, ~date: int) => time = "Date.UTC" + + /** + Same as Date.makeWithYMDH, but returns the time since 1 January 1970 in milliseconds. + */ @val external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => time = "Date.UTC" + + /** + Same as Date.makeWithYMDHM, but returns the time since 1 January 1970 in milliseconds. + */ @val external makeWithYMDHM: ( ~year: int, @@ -77,6 +211,10 @@ module UTC: { ~hours: int, ~minutes: int, ) => time = "Date.UTC" + + /** + Same as Date.makeWithYMDHMS, but returns the time since 1 January 1970 in milliseconds. + */ @val external makeWithYMDHMS: ( ~year: int, @@ -86,6 +224,10 @@ module UTC: { ~minutes: int, ~seconds: int, ) => time = "Date.UTC" + + /** + Same as Date.makeWithYMDHMSM, but returns the time since 1 January 1970 in milliseconds. + */ @val external makeWithYMDHMSM: ( ~year: int, @@ -97,7 +239,27 @@ module UTC: { ~milliseconds: int, ) => time = "Date.UTC" } + +/** +Returns the time in milliseconds between 1 January 1970 UTC and the current date time. +*/ @val external now: unit => time = "Date.now" + +/** +`getTime(date)` + +Returns the time in milliseconds between 1 January 1970 UTC and the given date. +Invalid dates will return NaN. +Dates before 1 January 1970 will return negative numbers. + +The function will return the same result as Date.valueOf + +## Examples +```rescript +Date.fromString("2023-02-20")->Date.getTime +// 1676851200000 +``` +*/ @send external getTime: t => time = "getTime" @send external getTimezoneOffset: t => int = "getTimezoneOffset" @send external getFullYear: t => int = "getFullYear" From 8a552754a87e898eeda1d025f0d21e5f081b7427 Mon Sep 17 00:00:00 2001 From: dkirchhof Date: Mon, 20 Feb 2023 20:09:46 +0100 Subject: [PATCH 02/10] add docs for date module --- src/Core__Date.res | 2 - src/Core__Date.resi | 684 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 674 insertions(+), 12 deletions(-) diff --git a/src/Core__Date.res b/src/Core__Date.res index 808fc48c..cde07732 100644 --- a/src/Core__Date.res +++ b/src/Core__Date.res @@ -115,7 +115,6 @@ external setMinutesSMs: (t, ~minutes: int, ~seconds: int, ~milliseconds: int) => @send external setSeconds: (t, int) => unit = "setSeconds" @send external setSecondsMs: (t, ~seconds: int, ~milliseconds: int) => unit = "setSeconds" @send external setMilliseconds: (t, int) => unit = "setMilliseconds" -@send external setDay: (t, int) => unit = "setDay" // UTC @send external getUTCFullYear: t => int = "getUTCFullYear" @@ -153,7 +152,6 @@ external setUTCMinutesSMs: (t, ~minutes: int, ~seconds: int, ~milliseconds: int) @send external setUTCSeconds: (t, int) => unit = "setUTCSeconds" @send external setUTCSecondsMs: (t, ~seconds: int, ~milliseconds: int) => unit = "setUTCSeconds" @send external setUTCMilliseconds: (t, int) => unit = "setUTCMilliseconds" -@send external setUTCDay: (t, int) => unit = "setUTCDay" @send external toDateString: t => string = "toDateString" @send external toString: t => string = "toString" diff --git a/src/Core__Date.resi b/src/Core__Date.resi index 07457bda..8e0a13ce 100644 --- a/src/Core__Date.resi +++ b/src/Core__Date.resi @@ -46,7 +46,7 @@ Returns the time in milliseconds between 1 January 1970 UTC and the given date. Invalid dates will return NaN. Dates before 1 January 1970 will return negative numbers. -The function will return the same result as Date.getTime +The function will return the same result as `Date.getTime` ## Examples ```rescript @@ -185,23 +185,23 @@ external makeWithYMDHMSM: ( ) => t = "Date" module UTC: { /** - Same as Date.makeWithYM, but returns the time since 1 January 1970 in milliseconds. + Same as Date.makeWithYM, but returns the time since 1 January 1970 UTC in milliseconds. */ @val external makeWithYM: (~year: int, ~month: int) => time = "Date.UTC" /** - Same as Date.makeWithYMD, but returns the time since 1 January 1970 in milliseconds. + Same as Date.makeWithYMD, but returns the time since 1 January 1970 UTC in milliseconds. */ @val external makeWithYMD: (~year: int, ~month: int, ~date: int) => time = "Date.UTC" /** - Same as Date.makeWithYMDH, but returns the time since 1 January 1970 in milliseconds. + Same as Date.makeWithYMDH, but returns the time since 1 January 1970 UTC in milliseconds. */ @val external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => time = "Date.UTC" /** - Same as Date.makeWithYMDHM, but returns the time since 1 January 1970 in milliseconds. + Same as Date.makeWithYMDHM, but returns the time since 1 January 1970 UTC in milliseconds. */ @val external makeWithYMDHM: ( @@ -213,7 +213,7 @@ module UTC: { ) => time = "Date.UTC" /** - Same as Date.makeWithYMDHMS, but returns the time since 1 January 1970 in milliseconds. + Same as Date.makeWithYMDHMS, but returns the time since 1 January 1970 UTC in milliseconds. */ @val external makeWithYMDHMS: ( @@ -226,7 +226,7 @@ module UTC: { ) => time = "Date.UTC" /** - Same as Date.makeWithYMDHMSM, but returns the time since 1 January 1970 in milliseconds. + Same as Date.makeWithYMDHMSM, but returns the time since 1 January 1970 UTC in milliseconds. */ @val external makeWithYMDHMSM: ( @@ -241,6 +241,8 @@ module UTC: { } /** +`now()` + Returns the time in milliseconds between 1 January 1970 UTC and the current date time. */ @val external now: unit => time = "Date.now" @@ -252,7 +254,7 @@ Returns the time in milliseconds between 1 January 1970 UTC and the given date. Invalid dates will return NaN. Dates before 1 January 1970 will return negative numbers. -The function will return the same result as Date.valueOf +The function will return the same result as `Date.valueOf` ## Examples ```rescript @@ -261,52 +263,549 @@ Date.fromString("2023-02-20")->Date.getTime ``` */ @send external getTime: t => time = "getTime" + +/** +`getTimezoneOffset(date)` + +Returns the time in minutes between the UTC time and the locale time. +The timezone of the given date doesn't matter. + +## Examples +```rescript +Date.fromString("2023-01-01")->Date.getTimezoneOffset +// -60 with local time zone = Europe/Berlin + +Date.fromString("2023-06-01")->Date.getTimezoneOffset +// -120 with local time zone = Europe/Berlin +``` +*/ @send external getTimezoneOffset: t => int = "getTimezoneOffset" + +/** +`getFullYear(date)` + +Returns the year of a given date (according to local time). + +## Examples +```rescript +Date.fromString("2023-02-20")->Date.getFullYear +// 2023 +``` +*/ @send external getFullYear: t => int = "getFullYear" + +/** +`getMonth(date)` + +Returns the month (0-indexed) of a given date (according to local time). + +## Examples +```rescript +Date.fromString("2023-01-01")->Date.getMonth +// 0 +``` +*/ @send external getMonth: t => int = "getMonth" + +/** +`getDate(date)` + +Returns the date (day of month) of a given date (according to local time). + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.getDate +// 20 +``` +*/ @send external getDate: t => int = "getDate" + +/** +`getHours(date)` + +Returns the hours of a given date (according to local time). + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.getHours +// 16 +``` +*/ @send external getHours: t => int = "getHours" + +/** +`getMinutes(date)` + +Returns the minutes of a given date (according to local time). + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.getMinutes +// 40 +``` +*/ @send external getMinutes: t => int = "getMinutes" + +/** +`getSeconds(date)` + +Returns the seconds of a given date (according to local time). + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.getSeconds +// 0 +``` +*/ @send external getSeconds: t => int = "getSeconds" + +/** +`getMilliseconds(date)` + +Returns the milliseconds of a given date (according to local time). + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.getMilliseconds +// 0 +``` +*/ @send external getMilliseconds: t => int = "getMilliseconds" + +/** +`getDay(date)` + +Returns the day of week of a given date (according to local time). +0 = Sunday, 1 = Monday, ... 6 = Saturday + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.getDay +// 1 +``` +*/ @send external getDay: t => int = "getDay" + +/** +`setFullYear(date, year)` + +Sets the year of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setFullYear(2024) +``` +*/ @send external setFullYear: (t, int) => unit = "setFullYear" + +/** +`setFullYearM(date, ~year, ~month)` + +Sets the year and month of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setFullYearM(~year=2024, ~month=0) +``` +*/ @send external setFullYearM: (t, ~year: int, ~month: int) => unit = "setFullYear" + +/** +`setFullYearMD(date, ~year, ~month, ~date)` + +Sets the year, month and date (day of month) of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setFullYearMD(~year=2024, ~month=0, ~date=1) +``` +*/ @send external setFullYearMD: (t, ~year: int, ~month: int, ~date: int) => unit = "setFullYear" + +/** +`setMonth(date, month)` + +Sets the month of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setMonth(0) +``` +*/ @send external setMonth: (t, int) => unit = "setMonth" + +/** +`setDate(date, day)` + +Sets the date (day of month) of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setDate(1) +``` +*/ @send external setDate: (t, int) => unit = "setDate" + +/** +`setHours(date, hours)` + +Sets the hours of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setHours(0) +``` +*/ @send external setHours: (t, int) => unit = "setHours" + +/** +`setHoursM(date, ~hours, ~minutes)` + +Sets the hours and minutes of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setHoursM(~hours=0, ~minutes=0) +``` +*/ @send external setHoursM: (t, ~hours: int, ~minutes: int) => unit = "setHours" + +/** +`setHoursMS(date, ~hours, ~minutes, ~seconds)` + +Sets the hours, minutes and seconds of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setHoursMS(~hours=0, ~minutes=0, ~seconds=0) +``` +*/ @send external setHoursMS: (t, ~hours: int, ~minutes: int, ~seconds: int) => unit = "setHours" + +/** +`setHoursMSMs(date, ~hours, ~minutes, ~seconds, ~milliseconds)` + +Sets the hours, minutes, seconds and milliseconds of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setHoursMSMs(~hours=0, ~minutes=0, ~seconds=0, ~milliseconds=0) +``` +*/ @send external setHoursMSMs: (t, ~hours: int, ~minutes: int, ~seconds: int, ~milliseconds: int) => unit = "setHours" + +/** +`setMinutes(date, minutes)` + +Sets the minutes of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setMinutes(0) +``` +*/ @send external setMinutes: (t, int) => unit = "setMinutes" + +/** +`setMinutesS(date, ~minutes, ~seconds)` + +Sets the minutes and seconds of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setMinutesS(~minutes=0, ~seconds=0) +``` +*/ @send external setMinutesS: (t, ~minutes: int, ~seconds: int) => unit = "setMinutes" + +/** +`setMinutesSMs(date, ~minutes, ~seconds, ~milliseconds)` + +Sets the minutes, seconds and milliseconds of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setMinutesSMs(~minutes=0, ~seconds=0, ~milliseconds=0) +``` +*/ @send external setMinutesSMs: (t, ~minutes: int, ~seconds: int, ~milliseconds: int) => unit = "setMinutes" + +/** +`setSeconds(date, seconds)` + +Sets the seconds of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setSeconds(0) +``` +*/ @send external setSeconds: (t, int) => unit = "setSeconds" + +/** +`setSecondsMs(date, ~seconds, ~milliseconds)` + +Sets the seconds and milliseconds of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setSecondsMs(~seconds=0, ~milliseconds=0) +``` +*/ @send external setSecondsMs: (t, ~seconds: int, ~milliseconds: int) => unit = "setSeconds" + +/** +`setMilliseconds(date, milliseconds)` + +Sets the milliseconds of a date (according to local time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setMilliseconds(0) +``` +*/ @send external setMilliseconds: (t, int) => unit = "setMilliseconds" -@send external setDay: (t, int) => unit = "setDay" + +/** +`getUTCFullYear(date)` + +Returns the year of a given date (according to UTC time). + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+01:00").getUTCFullYear +// 2022 +``` +*/ @send external getUTCFullYear: t => int = "getUTCFullYear" + +/** +`getUTCMonth(date)` + +Returns the month of a given date (according to UTC time). + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+01:00").getUTCMonth +// 11 +``` +*/ @send external getUTCMonth: t => int = "getUTCMonth" + +/** +`getUTCDate(date)` + +Returns the date (day of month) of a given date (according to UTC time). + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+01:00").getUTCDate +// 31 +``` +*/ @send external getUTCDate: t => int = "getUTCDate" + +/** +`getUTCHours(date)` + +Returns the hours of a given date (according to UTC time). + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+01:00").getUTCHours +// 23 +``` +*/ @send external getUTCHours: t => int = "getUTCHours" + +/** +`getUTCMinutes(date)` + +Returns the minutes of a given date (according to UTC time). + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+01:00").getUTCMinutes +// 0 +``` +*/ @send external getUTCMinutes: t => int = "getUTCMinutes" + +/** +`getUTCSeconds(date)` + +Returns the seconds of a given date (according to UTC time). + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+01:00").getUTCSeconds +// 0 +``` +*/ @send external getUTCSeconds: t => int = "getUTCSeconds" + +/** +`getUTCMilliseconds(date)` + +Returns the milliseconds of a given date (according to UTC time). + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+01:00").getUTCMilliseconds +// 0 +``` +*/ @send external getUTCMilliseconds: t => int = "getUTCMilliseconds" + +/** +`getUTCDay(date)` + +Returns the day (day of week) of a given date (according to UTC time). +0 = Sunday, 1 = Monday, ... 6 = Saturday + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+01:00").getUTCDay +// 6 +``` +*/ @send external getUTCDay: t => int = "getUTCDay" + +/** +`setUTCFullYear(date, year)` + +Sets the year of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCFullYear(2024) +``` +*/ @send external setUTCFullYear: (t, int) => unit = "setUTCFullYear" + +/** +`setUTCFullYearM(date, ~year, ~month)` + +Sets the year and month of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCFullYearM(~year=2024, ~month=0) +``` +*/ @send external setUTCFullYearM: (t, ~year: int, ~month: int) => unit = "setUTCFullYear" + +/** +`setUTCFullYearMD(date, ~year, ~month, ~date)` + +Sets the year, month and date (day of month) of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCFullYearMD(~year=2024, ~month=0, ~date=1) +``` +*/ @send external setUTCFullYearMD: (t, ~year: int, ~month: int, ~date: int) => unit = "setUTCFullYear" + +/** +`setUTCMonth(date, month)` + +Sets the month of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCMonth(0) +``` +*/ @send external setUTCMonth: (t, int) => unit = "setUTCMonth" + +/** +`setDate(date, day)` + +Sets the date (day of month) of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCDate(1) +``` +*/ @send external setUTCDate: (t, int) => unit = "setUTCDate" + +/** +`setUTCHours(date, hours)` + +Sets the hours of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCHours(0) +``` +*/ @send external setUTCHours: (t, int) => unit = "setUTCHours" + +/** +`setHoursM(date, ~hours, ~minutes)` + +Sets the hours and minutes of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCHoursM(~hours=0, ~minutes=0) +``` +*/ @send external setUTCHoursM: (t, ~hours: int, ~minutes: int) => unit = "setUTCHours" + +/** +`setUTCHoursMS(date, ~hours, ~minutes, ~seconds)` + +Sets the hours, minutes and seconds of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCHoursMS(~hours=0, ~minutes=0, ~seconds=0) +``` +*/ @send external setUTCHoursMS: (t, ~hours: int, ~minutes: int, ~seconds: int) => unit = "setUTCHours" + +/** +`setUTCHoursMSMs(date, ~hours, ~minutes, ~seconds, ~milliseconds)` + +Sets the hours, minutes, seconds and milliseconds of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCHoursMSMs(~hours=0, ~minutes=0, ~seconds=0, ~milliseconds=0) +``` +*/ @send external setUTCHoursMSMs: ( t, @@ -315,17 +814,136 @@ external setUTCHoursMSMs: ( ~seconds: int, ~milliseconds: int, ) => unit = "setUTCHours" + +/** +`setUTCMinutes(date, minutes)` + +Sets the minutes of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCMinutes(0) +``` +*/ @send external setUTCMinutes: (t, int) => unit = "setUTCMinutes" + +/** +`setUTCMinutesS(date, ~minutes, ~seconds)` + +Sets the minutes and seconds of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCMinutesS(~minutes=0, ~seconds=0) +``` +*/ @send external setUTCMinutesS: (t, ~minutes: int, ~seconds: int) => unit = "setUTCMinutes" + +/** +`setUTCMinutesSMs(date, ~minutes, ~seconds, ~milliseconds)` + +Sets the minutes, seconds and milliseconds of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCMinutesSMs(~minutes=0, ~seconds=0, ~milliseconds=0) +``` +*/ @send external setUTCMinutesSMs: (t, ~minutes: int, ~seconds: int, ~milliseconds: int) => unit = "setUTCMinutes" + +/** +`setUTCSeconds(date, seconds)` + +Sets the seconds of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCSeconds(0) +``` +*/ @send external setUTCSeconds: (t, int) => unit = "setUTCSeconds" + +/** +`setUTCSecondsMs(date, ~seconds, ~milliseconds)` + +Sets the seconds and milliseconds of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCSecondsMs(~seconds=0, ~milliseconds=0) +``` +*/ @send external setUTCSecondsMs: (t, ~seconds: int, ~milliseconds: int) => unit = "setUTCSeconds" + +/** +`setUTCMilliseconds(date, milliseconds)` + +Sets the milliseconds of a date (according to UTC time). +Beware this will *mutate* the date. + +## Examples +```rescript +Date.fromString("2023-02-20T16:40:00.00")->Date.setUTCMilliseconds(0) +``` +*/ @send external setUTCMilliseconds: (t, int) => unit = "setUTCMilliseconds" -@send external setUTCDay: (t, int) => unit = "setUTCDay" + +/** +`toDateString(date)` + +Converts a JavaScript date to a standard date string. The date will be mapped to the current time zone. +If you want to convert it to a localized string, use `Date.toLocaleDateString` instead. + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+01:00")->Date.toDateString->Console.log +// Sun Jan 01 2023 + +Date.fromString("2023-01-01T00:00:00.00+08:00")->Date.toDateString->Console.log +// Sat Dec 31 2022 +``` +*/ @send external toDateString: t => string = "toDateString" + +/** +`toString(date)` + +Converts a JavaScript date to a standard date time string. The date will be mapped to the current time zone. +If you want to convert it to a localized string, use `Date.toLocaleString` instead. + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+01:00")->Date.toString->Console.log +// Sun Jan 01 2023 00:00:00 GMT+0100 (Central European Standard Time) + +Date.fromString("2023-06-01T00:00:00.00+01:00")->Date.toString->Console.log +// Thu Jun 01 2023 01:00:00 GMT+0200 (Central European Summer Time) +``` +*/ @send external toString: t => string = "toString" + +/** +`toTimeString(date)` + +Converts a JavaScript date to a standard time string. The date will be mapped to the current time zone. +If you want to convert it to a localized string, use `Date.toLocaleStimeString` instead. + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+01:00")->Date.toTimeString->Console.log +// 00:00:00 GMT+0100 (Central European Standard Time) + +Date.fromString("2023-01-01T00:00:00.00+08:00")->Date.toTimeString->Console.log +// 17:00:00 GMT+0100 (Central European Standard Time) +``` +*/ @send external toTimeString: t => string = "toTimeString" /** @@ -468,6 +1086,52 @@ Date.make()->Date.toLocaleTimeStringWithLocaleAndOptions("de", { hour: #"2-digit external toLocaleTimeStringWithLocaleAndOptions: (t, string, localeOptions) => string = "toLocaleTimeString" +/** +`toISOString(date)` + +Converts a JavaScript date to a ISO 8601 string (YYYY-MM-DDTHH:mm:ss.sssZ). The date will be mapped to the UTC time. + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+00:00")->Date.toISOString->Console.log +// 2023-01-01T00:00:00.000Z + +Date.fromString("2023-01-01T00:00:00.00+08:00")->Date.toISOString->Console.log +// 2022-12-31T16:00:00.000Z +``` +*/ @send external toISOString: t => string = "toISOString" + +/** +`toUTCString(date)` + +Converts a JavaScript date to date time string. The date will be mapped to the UTC time. + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+00:00")->Date.toISOString->Console.log +// 2023-01-01T00:00:00.000Z + +Date.fromString("2023-01-01T00:00:00.00+08:00")->Date.toUTCString->Console.log +// Sat, 31 Dec 2022 16:00:00 GMT +``` +*/ @send external toUTCString: t => string = "toUTCString" + +/** +`toJSON(date)` + +Converts a JavaScript date to a string. +If the date is valid, the function will return the same result as `Date.toISOString`. +Invalid dates will return `None`. + +## Examples +```rescript +Date.fromString("2023-01-01T00:00:00.00+00:00")->Date.toJSON +// Some("2023-01-01T00:00:00.000Z") + +Date.fromString("")->Date.toJSON +// None +``` +*/ @return(nullable) @send external toJSON: t => option = "toJSON" From 5a2306da4c80bdf6e9275230257b273c8406a487 Mon Sep 17 00:00:00 2001 From: dkirchhof Date: Tue, 21 Feb 2023 17:52:45 +0100 Subject: [PATCH 03/10] remove Date.valueOf, add more examples for Date.makeXY functions --- src/Core__Date.res | 2 - src/Core__Date.resi | 96 +++++++++++++++++++++++++++++++++++---------- 2 files changed, 75 insertions(+), 23 deletions(-) diff --git a/src/Core__Date.res b/src/Core__Date.res index cde07732..b4edc56d 100644 --- a/src/Core__Date.res +++ b/src/Core__Date.res @@ -16,8 +16,6 @@ type localeOptions = { timeZoneName?: [#long | #short], } -@send external valueOf: t => time = "valueOf" - @new external make: unit => t = "Date" @new external fromString: string => t = "Date" @new external fromTime: time => t = "Date" diff --git a/src/Core__Date.resi b/src/Core__Date.resi index 3d145591..168dbc4e 100644 --- a/src/Core__Date.resi +++ b/src/Core__Date.resi @@ -3,7 +3,7 @@ */ /** -A type representing a JavaScript date +A type representing a JavaScript date. */ type t = Js.Date.t @@ -39,24 +39,6 @@ type localeOptions = { timeZoneName?: [#long | #short], } -/** -`valueOf(date)` - -Returns the time in milliseconds between 1 January 1970 UTC and the given date. -Invalid dates will return NaN. -Dates before 1 January 1970 will return negative numbers. - -The function will return the same result as `Date.getTime` - -## Examples -```rescript -Date.fromString("2023-02-20")->Date.valueOf -// 1676851200000 -``` -*/ -@send -external valueOf: t => time = "valueOf" - /** `make()` @@ -75,7 +57,9 @@ external make: unit => t = "Date" Creates a date object from given date time string. The string has to be in the ISO 8601 format YYYY-MM-DDTHH:mm:ss.sssZ (https://tc39.es/ecma262/#sec-date-time-string-format). + Invalid date time strings will create invalid dates. +You can use the result like any valid date, but many functions like `toString` will return "Invalid Date" or functions like `Date.getTime` will return NaN. ## Examples ```rescript @@ -87,6 +71,12 @@ Date.fromString("2023-02-20") Date.fromString("2023-02-20T16:40:00.00Z") // 2023-02-20T16:40:00.000Z + +Date.fromString("") +// Invalid Date + +Date.fromString("")->getTime +// NaN ``` */ @new @@ -116,6 +106,7 @@ external fromTime: time => t = "Date" Creates a date object with the given year and month. Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). Months are 0-indexed (0 = January, 11 = December). +Values, which are out of range, will be carried over to the next bigger unit (s. example). ## Examples ```rescript @@ -139,6 +130,19 @@ external makeWithYM: (~year: int, ~month: int) => t = "Date" Creates a date object with the given year, month and date (day of month). Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). Months are 0-indexed (0 = January, 11 = December). +Values, which are out of range, will be carried over to the next bigger unit (s. example). + +## Examples +```rescript +Date.makeWithYMD(~year=2023, ~month=1, ~date=20) +// 2023-02-20T00:00:00.000Z + +Date.makeWithYMD(~year=2023, ~month=1, ~date=-1) +// 2022-11-29T00:00:00.000Z + +Date.makeWithYMD(~year=2023, ~month=1, ~date=29) +// 2023-03-01T00:00:00.000Z +``` */ @new external makeWithYMD: (~year: int, ~month: int, ~date: int) => t = "Date" @@ -147,6 +151,19 @@ external makeWithYMD: (~year: int, ~month: int, ~date: int) => t = "Date" Creates a date object with the given year, month, date (day of month) and hours. Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). Months are 0-indexed (0 = January, 11 = December). +Values, which are out of range, will be carried over to the next bigger unit (s. example). + +## Examples +```rescript +Date.makeWithYMDH(~year=2023, ~month=1, ~date=20, ~hours=16) +// 2023-02-20T16:00:00.000Z + +Date.makeWithYMDH(~year=2023, ~month=1, ~date=20, ~hours=24) +// 2023-02-21T00:00:00.000Z + +Date.makeWithYMDH(~year=2023, ~month=1, ~date=20, ~hours=-1) +// 2023-02-19T23:00:00.000Z +``` */ @new external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => t = "Date" @@ -155,6 +172,19 @@ external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => t = Creates a date object with the given year, month, date (day of month), hours and minutes. Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). Months are 0-indexed (0 = January, 11 = December). +Values, which are out of range, will be carried over to the next bigger unit (s. example). + +## Examples +```rescript +Date.makeWithYMDHM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40) +// 2023-02-20T16:40:00.000Z + +Date.makeWithYMDHM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=60) +// 2023-02-20T17:00:00.000Z + +Date.makeWithYMDHM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=-1) +// 2023-02-20T15:59:00.000Z +``` */ @new external makeWithYMDHM: (~year: int, ~month: int, ~date: int, ~hours: int, ~minutes: int) => t = @@ -164,6 +194,19 @@ external makeWithYMDHM: (~year: int, ~month: int, ~date: int, ~hours: int, ~minu Creates a date object with the given year, month, date (day of month), hours, minutes and seconds. Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). Months are 0-indexed (0 = January, 11 = December). +Values, which are out of range, will be carried over to the next bigger unit (s. example). + +## Examples +```rescript +Date.makeWithYMDHMS(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=0) +// 2023-02-20T16:40:00.000Z + +Date.makeWithYMDHMS(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=60) +// 2023-02-20T16:41:00.000Z + +Date.makeWithYMDHMS(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=-1) +// 2023-02-20T16:39:59.000Z +``` */ @new external makeWithYMDHMS: ( @@ -179,6 +222,19 @@ external makeWithYMDHMS: ( Creates a date object with the given year, month, date (day of month), hours, minutes, seconds and milliseconds. Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). Months are 0-indexed (0 = January, 11 = December). +Values, which are out of range, will be carried over to the next bigger unit (s. example). + +## Examples +```rescript +Date.makeWithYMDHMSM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=0, ~milliseconds=0) +// 2023-02-20T16:40:00.000Z + +Date.makeWithYMDHMSM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=0, ~milliseconds=1000) +// 2023-02-20T16:40:01.000Z + +Date.makeWithYMDHMSM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=0, ~milliseconds=-1) +// 2023-02-20T16:39:59.999Z +``` */ @new external makeWithYMDHMSM: ( @@ -264,8 +320,6 @@ Returns the time in milliseconds between 1 January 1970 UTC and the given date. Invalid dates will return NaN. Dates before 1 January 1970 will return negative numbers. -The function will return the same result as `Date.valueOf` - ## Examples ```rescript Date.fromString("2023-02-20")->Date.getTime From 19a8c4801d9525df9ae9181d96b23105a836f32b Mon Sep 17 00:00:00 2001 From: dkirchhof Date: Tue, 21 Feb 2023 17:56:30 +0100 Subject: [PATCH 04/10] update CHANGELOG --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 53eb5f61..e3c1527a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ - Remove internal async/await helpers that do not need to be exposed in `Core`. - Add locale and formatting options to `localeDateString`, `localeString` and `localTimeString` functions https://github.com/rescript-association/rescript-core/pull/30 - Change `RegExp.source` to return a `string`. Was previously returning a `bool`, which is wrong. https://github.com/rescript-association/rescript-core/pull/47 +- Remove `Date.valueOf` as it returns the same as `Date.getTime`. https://github.com/rescript-association/rescript-core/pull/61 ### Documentation @@ -24,3 +25,4 @@ - Docstrings for `Int`. https://github.com/rescript-association/rescript-core/pull/37 - Docstrings for `Dict`. https://github.com/rescript-association/rescript-core/pull/40 - Docstrings for `RegExp`. https://github.com/rescript-association/rescript-core/pull/47 +- Docstrings for `Date`. https://github.com/rescript-association/rescript-core/pull/61 From aa928f2eb82bef0e2756a90b5b54c1296f180703 Mon Sep 17 00:00:00 2001 From: dkirchhof Date: Tue, 21 Feb 2023 18:08:16 +0100 Subject: [PATCH 05/10] change type time to msSinceEpoch and add doc strings --- src/Core__Date.res | 20 ++++++++++---------- src/Core__Date.resi | 25 ++++++++++++++----------- 2 files changed, 24 insertions(+), 21 deletions(-) diff --git a/src/Core__Date.res b/src/Core__Date.res index b4edc56d..d4661100 100644 --- a/src/Core__Date.res +++ b/src/Core__Date.res @@ -1,6 +1,6 @@ type t = Js.Date.t -type time = float +type msSinceEpoch = float type localeOptions = { dateStyle?: [#full | #long | #medium | #short], @@ -18,7 +18,7 @@ type localeOptions = { @new external make: unit => t = "Date" @new external fromString: string => t = "Date" -@new external fromTime: time => t = "Date" +@new external fromTime: msSinceEpoch => t = "Date" @new external makeWithYM: (~year: int, ~month: int) => t = "Date" @new external makeWithYMD: (~year: int, ~month: int, ~date: int) => t = "Date" @@ -47,10 +47,10 @@ external makeWithYMDHMSM: ( ) => t = "Date" module UTC = { - @val external makeWithYM: (~year: int, ~month: int) => time = "Date.UTC" - @val external makeWithYMD: (~year: int, ~month: int, ~date: int) => time = "Date.UTC" + @val external makeWithYM: (~year: int, ~month: int) => msSinceEpoch = "Date.UTC" + @val external makeWithYMD: (~year: int, ~month: int, ~date: int) => msSinceEpoch = "Date.UTC" @val - external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => time = "Date.UTC" + external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => msSinceEpoch = "Date.UTC" @val external makeWithYMDHM: ( ~year: int, @@ -58,7 +58,7 @@ module UTC = { ~date: int, ~hours: int, ~minutes: int, - ) => time = "Date.UTC" + ) => msSinceEpoch = "Date.UTC" @val external makeWithYMDHMS: ( ~year: int, @@ -67,7 +67,7 @@ module UTC = { ~hours: int, ~minutes: int, ~seconds: int, - ) => time = "Date.UTC" + ) => msSinceEpoch = "Date.UTC" @val external makeWithYMDHMSM: ( ~year: int, @@ -77,12 +77,12 @@ module UTC = { ~minutes: int, ~seconds: int, ~milliseconds: int, - ) => time = "Date.UTC" + ) => msSinceEpoch = "Date.UTC" } -@val external now: unit => time = "Date.now" +@val external now: unit => msSinceEpoch = "Date.now" -@send external getTime: t => time = "getTime" +@send external getTime: t => msSinceEpoch = "getTime" @send external getTimezoneOffset: t => int = "getTimezoneOffset" // Locale diff --git a/src/Core__Date.resi b/src/Core__Date.resi index 168dbc4e..8582a059 100644 --- a/src/Core__Date.resi +++ b/src/Core__Date.resi @@ -7,7 +7,10 @@ A type representing a JavaScript date. */ type t = Js.Date.t -type time = float +/** +A type representing the time since / until epoch (start of unix time = midnight 1 January 1970) in milliseconds. +*/ +type msSinceEpoch = float /** A type representing date time format options. @@ -83,7 +86,7 @@ Date.fromString("")->getTime external fromString: string => t = "Date" /** -`fromTime(deltaMilliseconds)` +`fromTime(msSinceEpoch)` Creates a date object from the given time in milliseconds since / until 1 January 1970 UTC. @@ -100,7 +103,7 @@ Date.fromTime(86_400_000.0) ``` */ @new -external fromTime: time => t = "Date" +external fromTime: msSinceEpoch => t = "Date" /** Creates a date object with the given year and month. @@ -251,19 +254,19 @@ module UTC: { Same as Date.makeWithYM, but returns the time since 1 January 1970 UTC in milliseconds. */ @val - external makeWithYM: (~year: int, ~month: int) => time = "Date.UTC" + external makeWithYM: (~year: int, ~month: int) => msSinceEpoch = "Date.UTC" /** Same as Date.makeWithYMD, but returns the time since 1 January 1970 UTC in milliseconds. */ @val - external makeWithYMD: (~year: int, ~month: int, ~date: int) => time = "Date.UTC" + external makeWithYMD: (~year: int, ~month: int, ~date: int) => msSinceEpoch = "Date.UTC" /** Same as Date.makeWithYMDH, but returns the time since 1 January 1970 UTC in milliseconds. */ @val - external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => time = "Date.UTC" + external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => msSinceEpoch = "Date.UTC" /** Same as Date.makeWithYMDHM, but returns the time since 1 January 1970 UTC in milliseconds. @@ -275,7 +278,7 @@ module UTC: { ~date: int, ~hours: int, ~minutes: int, - ) => time = "Date.UTC" + ) => msSinceEpoch = "Date.UTC" /** Same as Date.makeWithYMDHMS, but returns the time since 1 January 1970 UTC in milliseconds. @@ -288,7 +291,7 @@ module UTC: { ~hours: int, ~minutes: int, ~seconds: int, - ) => time = "Date.UTC" + ) => msSinceEpoch = "Date.UTC" /** Same as Date.makeWithYMDHMSM, but returns the time since 1 January 1970 UTC in milliseconds. @@ -302,7 +305,7 @@ module UTC: { ~minutes: int, ~seconds: int, ~milliseconds: int, - ) => time = "Date.UTC" + ) => msSinceEpoch = "Date.UTC" } /** @@ -311,7 +314,7 @@ module UTC: { Returns the time in milliseconds between 1 January 1970 UTC and the current date time. */ @val -external now: unit => time = "Date.now" +external now: unit => msSinceEpoch = "Date.now" /** `getTime(date)` @@ -327,7 +330,7 @@ Date.fromString("2023-02-20")->Date.getTime ``` */ @send -external getTime: t => time = "getTime" +external getTime: t => msSinceEpoch = "getTime" /** `getTimezoneOffset(date)` From 977eb7c055173a123bad8a121a51c364650a5e00 Mon Sep 17 00:00:00 2001 From: dkirchhof Date: Tue, 21 Feb 2023 18:24:08 +0100 Subject: [PATCH 06/10] add examples for utc make functions --- src/Core__Date.resi | 107 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 100 insertions(+), 7 deletions(-) diff --git a/src/Core__Date.resi b/src/Core__Date.resi index 8582a059..38c4d354 100644 --- a/src/Core__Date.resi +++ b/src/Core__Date.resi @@ -8,7 +8,7 @@ A type representing a JavaScript date. type t = Js.Date.t /** -A type representing the time since / until epoch (start of unix time = midnight 1 January 1970) in milliseconds. +A type representing the time since / until epoch (start of unix time = 1 January 1970) in milliseconds. */ type msSinceEpoch = float @@ -251,25 +251,88 @@ external makeWithYMDHMSM: ( ) => t = "Date" module UTC: { /** - Same as Date.makeWithYM, but returns the time since 1 January 1970 UTC in milliseconds. + Returns the time since 1 January 1970 UTC in milliseconds. + Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). + Months are 0-indexed (0 = January, 11 = December). + Values, which are out of range, will be carried over to the next bigger unit (s. example). + + ## Examples + ```rescript + Date.UTC.makeWithYM(~year=2023, ~month=0) + // 1672531200000 + + Date.UTC.makeWithYM(~year=2023, ~month=11) + // 1701388800000 + + Date.UTC.makeWithYM(~year=2023, ~month=12) + // 1704067200000 + + Date.UTC.makeWithYM(~year=2023, ~month=-1) + // 1669852800000 + ``` */ @val external makeWithYM: (~year: int, ~month: int) => msSinceEpoch = "Date.UTC" /** - Same as Date.makeWithYMD, but returns the time since 1 January 1970 UTC in milliseconds. + Returns the time since 1 January 1970 UTC in milliseconds. + Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). + Months are 0-indexed (0 = January, 11 = December). + Values, which are out of range, will be carried over to the next bigger unit (s. example). + + ## Examples + ```rescript + Date.UTC.makeWithYMD(~year=2023, ~month=1, ~date=20) + // 1676851200000 + + Date.UTC.makeWithYMD(~year=2023, ~month=1, ~date=-1) + // 1675036800000 + + Date.UTC.makeWithYMD(~year=2023, ~month=1, ~date=29) + // 1677628800000 + ``` */ @val external makeWithYMD: (~year: int, ~month: int, ~date: int) => msSinceEpoch = "Date.UTC" /** - Same as Date.makeWithYMDH, but returns the time since 1 January 1970 UTC in milliseconds. + Returns the time since 1 January 1970 UTC in milliseconds. + Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). + Months are 0-indexed (0 = January, 11 = December). + Values, which are out of range, will be carried over to the next bigger unit (s. example). + + ## Examples + ```rescript + Date.UTC.makeWithYMDH(~year=2023, ~month=1, ~date=20, ~hours=16) + // 1676908800000 + + Date.UTC.makeWithYMDH(~year=2023, ~month=1, ~date=20, ~hours=24) + // 1676937600000 + + Date.UTC.makeWithYMDH(~year=2023, ~month=1, ~date=20, ~hours=-1) + // 1676847600000 + ``` */ @val external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => msSinceEpoch = "Date.UTC" /** - Same as Date.makeWithYMDHM, but returns the time since 1 January 1970 UTC in milliseconds. + Returns the time since 1 January 1970 UTC in milliseconds. + Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). + Months are 0-indexed (0 = January, 11 = December). + Values, which are out of range, will be carried over to the next bigger unit (s. example). + + ## Examples + ```rescript + Date.UTC.makeWithYMDHM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40) + // 1676911200000 + + Date.UTC.makeWithYMDHM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=60) + // 1676912400000 + + Date.UTC.makeWithYMDHM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=-1) + // 1676908740000 + ``` */ @val external makeWithYMDHM: ( @@ -281,7 +344,22 @@ module UTC: { ) => msSinceEpoch = "Date.UTC" /** - Same as Date.makeWithYMDHMS, but returns the time since 1 January 1970 UTC in milliseconds. + Returns the time since 1 January 1970 UTC in milliseconds. + Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). + Months are 0-indexed (0 = January, 11 = December). + Values, which are out of range, will be carried over to the next bigger unit (s. example). + + ## Examples + ```rescript + Date.UTC.makeWithYMDHMS(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=0) + // 1676911200000 + + Date.UTC.makeWithYMDHMS(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=60) + // 1676911260000 + + Date.UTC.makeWithYMDHMS(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=-1) + // 1676911199000 + ``` */ @val external makeWithYMDHMS: ( @@ -294,7 +372,22 @@ module UTC: { ) => msSinceEpoch = "Date.UTC" /** - Same as Date.makeWithYMDHMSM, but returns the time since 1 January 1970 UTC in milliseconds. + Returns the time since 1 January 1970 UTC in milliseconds. + Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). + Months are 0-indexed (0 = January, 11 = December). + Values, which are out of range, will be carried over to the next bigger unit (s. example). + + ## Examples + ```rescript + ``` + Date.UTC.makeWithYMDHMSM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=0, ~milliseconds=0)->Console.log + // 1676911200000 + + Date.UTC.makeWithYMDHMSM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=0, ~milliseconds=1000)->Console.log + // 1676911201000 + + Date.UTC.makeWithYMDHMSM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=0, ~milliseconds=-1)->Console.log + // 1676911199999 */ @val external makeWithYMDHMSM: ( From 34124d7609ee574078c30e1d83a9cfeea7854157 Mon Sep 17 00:00:00 2001 From: dkirchhof Date: Tue, 21 Feb 2023 17:25:18 +0000 Subject: [PATCH 07/10] fix formatting --- src/Core__Date.resi | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/Core__Date.resi b/src/Core__Date.resi index 38c4d354..2a0b92c3 100644 --- a/src/Core__Date.resi +++ b/src/Core__Date.resi @@ -314,7 +314,8 @@ module UTC: { ``` */ @val - external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => msSinceEpoch = "Date.UTC" + external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => msSinceEpoch = + "Date.UTC" /** Returns the time since 1 January 1970 UTC in milliseconds. From b31f63c1c6e032abea543f276a19ec951b85c19d Mon Sep 17 00:00:00 2001 From: dkirchhof Date: Tue, 21 Feb 2023 20:41:53 +0100 Subject: [PATCH 08/10] add more information about epoch --- src/Core__Date.resi | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/src/Core__Date.resi b/src/Core__Date.resi index 2a0b92c3..cb933c05 100644 --- a/src/Core__Date.resi +++ b/src/Core__Date.resi @@ -8,7 +8,8 @@ A type representing a JavaScript date. type t = Js.Date.t /** -A type representing the time since / until epoch (start of unix time = 1 January 1970) in milliseconds. +Time, in milliseconds, since / until the UNIX epoch (January 1, 1970 00:00:00 UTC). +Positive numbers represent dates after, negative numbers dates before epoch. */ type msSinceEpoch = float @@ -88,7 +89,8 @@ external fromString: string => t = "Date" /** `fromTime(msSinceEpoch)` -Creates a date object from the given time in milliseconds since / until 1 January 1970 UTC. +Creates a date object from the given time in milliseconds since / until UNIX epoch (January 1, 1970 00:00:00 UTC). +Positive numbers create dates after epoch, negative numbers create dates before epoch. ## Examples ```rescript @@ -251,7 +253,7 @@ external makeWithYMDHMSM: ( ) => t = "Date" module UTC: { /** - Returns the time since 1 January 1970 UTC in milliseconds. + Returns the time, in milliseconds, since UNIX epoch (January 1, 1970 00:00:00 UTC). Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). Months are 0-indexed (0 = January, 11 = December). Values, which are out of range, will be carried over to the next bigger unit (s. example). @@ -275,7 +277,7 @@ module UTC: { external makeWithYM: (~year: int, ~month: int) => msSinceEpoch = "Date.UTC" /** - Returns the time since 1 January 1970 UTC in milliseconds. + Returns the time, in milliseconds, since UNIX epoch (January 1, 1970 00:00:00 UTC). Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). Months are 0-indexed (0 = January, 11 = December). Values, which are out of range, will be carried over to the next bigger unit (s. example). @@ -296,7 +298,7 @@ module UTC: { external makeWithYMD: (~year: int, ~month: int, ~date: int) => msSinceEpoch = "Date.UTC" /** - Returns the time since 1 January 1970 UTC in milliseconds. + Returns the time, in milliseconds, since UNIX epoch (January 1, 1970 00:00:00 UTC). Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). Months are 0-indexed (0 = January, 11 = December). Values, which are out of range, will be carried over to the next bigger unit (s. example). @@ -318,7 +320,7 @@ module UTC: { "Date.UTC" /** - Returns the time since 1 January 1970 UTC in milliseconds. + Returns the time, in milliseconds, since UNIX epoch (January 1, 1970 00:00:00 UTC). Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). Months are 0-indexed (0 = January, 11 = December). Values, which are out of range, will be carried over to the next bigger unit (s. example). @@ -345,7 +347,7 @@ module UTC: { ) => msSinceEpoch = "Date.UTC" /** - Returns the time since 1 January 1970 UTC in milliseconds. + Returns the time, in milliseconds, since UNIX epoch (January 1, 1970 00:00:00 UTC). Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). Months are 0-indexed (0 = January, 11 = December). Values, which are out of range, will be carried over to the next bigger unit (s. example). @@ -373,7 +375,7 @@ module UTC: { ) => msSinceEpoch = "Date.UTC" /** - Returns the time since 1 January 1970 UTC in milliseconds. + Returns the time, in milliseconds, since UNIX epoch (January 1, 1970 00:00:00 UTC). Be aware of using a value for year < 100, because it behaves inconsistent (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). Months are 0-indexed (0 = January, 11 = December). Values, which are out of range, will be carried over to the next bigger unit (s. example). @@ -405,7 +407,7 @@ module UTC: { /** `now()` -Returns the time in milliseconds between 1 January 1970 UTC and the current date time. +Returns the time, in milliseconds, between UNIX epoch (January 1, 1970 00:00:00 UTC) and the current date time. */ @val external now: unit => msSinceEpoch = "Date.now" @@ -413,9 +415,9 @@ external now: unit => msSinceEpoch = "Date.now" /** `getTime(date)` -Returns the time in milliseconds between 1 January 1970 UTC and the given date. +Returns the time, in milliseconds, between UNIX epoch (January 1, 1970 00:00:00 UTC) and the current date time. Invalid dates will return NaN. -Dates before 1 January 1970 will return negative numbers. +Dates before epoch will return negative numbers. ## Examples ```rescript From efd89bb7ef87ff5df5a3bd397a93675bff8759ad Mon Sep 17 00:00:00 2001 From: dkirchhof Date: Tue, 21 Feb 2023 21:00:05 +0100 Subject: [PATCH 09/10] added disclaimer to examples and fixed one example and its output --- src/Core__Date.resi | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/src/Core__Date.resi b/src/Core__Date.resi index cb933c05..b97a16f2 100644 --- a/src/Core__Date.resi +++ b/src/Core__Date.resi @@ -126,6 +126,10 @@ Date.makeWithYM(~year=2023, ~month=12) Date.makeWithYM(~year=2023, ~month=-1) // 2022-12-01T00:00:00.000Z + +// Note: The output depends on your local time zone. +// In nodejs you can change it by using the TZ env (`export TZ='Europe/London' && node index.bs.js`) + ``` */ @new @@ -168,6 +172,10 @@ Date.makeWithYMDH(~year=2023, ~month=1, ~date=20, ~hours=24) Date.makeWithYMDH(~year=2023, ~month=1, ~date=20, ~hours=-1) // 2023-02-19T23:00:00.000Z + +// Note: The output depends on your local time zone. +// In nodejs you can change it by using the TZ env (`export TZ='Europe/London' && node index.bs.js`) + ``` */ @new @@ -189,6 +197,10 @@ Date.makeWithYMDHM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=60) Date.makeWithYMDHM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=-1) // 2023-02-20T15:59:00.000Z + +// Note: The output depends on your local time zone. +// In nodejs you can change it by using the TZ env (`export TZ='Europe/London' && node index.bs.js`) + ``` */ @new @@ -211,6 +223,10 @@ Date.makeWithYMDHMS(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~sec Date.makeWithYMDHMS(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=-1) // 2023-02-20T16:39:59.000Z + +// Note: The output depends on your local time zone. +// In nodejs you can change it by using the TZ env (`export TZ='Europe/London' && node index.bs.js`) + ``` */ @new @@ -239,6 +255,10 @@ Date.makeWithYMDHMSM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~se Date.makeWithYMDHMSM(~year=2023, ~month=1, ~date=20, ~hours=16, ~minutes=40, ~seconds=0, ~milliseconds=-1) // 2023-02-20T16:39:59.999Z + +// Note: The output depends on your local time zone. +// In nodejs you can change it by using the TZ env (`export TZ='Europe/London' && node index.bs.js`) + ``` */ @new @@ -1318,8 +1338,8 @@ Converts a JavaScript date to date time string. The date will be mapped to the U ## Examples ```rescript -Date.fromString("2023-01-01T00:00:00.00+00:00")->Date.toISOString->Console.log -// 2023-01-01T00:00:00.000Z +Date.fromString("2023-01-01T00:00:00.00+00:00")->Date.toUTCString->Console.log +// Sun, 01 Jan 2023 00:00:00 GMT Date.fromString("2023-01-01T00:00:00.00+08:00")->Date.toUTCString->Console.log // Sat, 31 Dec 2022 16:00:00 GMT From eea4fcc63d5efffd73910c7c32970e94f02d93f9 Mon Sep 17 00:00:00 2001 From: dkirchhof Date: Tue, 21 Feb 2023 21:01:16 +0100 Subject: [PATCH 10/10] fixed formatting of date module --- src/Core__Date.res | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/Core__Date.res b/src/Core__Date.res index d4661100..02f639b9 100644 --- a/src/Core__Date.res +++ b/src/Core__Date.res @@ -50,7 +50,8 @@ module UTC = { @val external makeWithYM: (~year: int, ~month: int) => msSinceEpoch = "Date.UTC" @val external makeWithYMD: (~year: int, ~month: int, ~date: int) => msSinceEpoch = "Date.UTC" @val - external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => msSinceEpoch = "Date.UTC" + external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => msSinceEpoch = + "Date.UTC" @val external makeWithYMDHM: ( ~year: int,