diff --git a/src/lune/builtins/datetime/date_time.rs b/src/lune/builtins/datetime/date_time.rs index 3e95a25..0428593 100644 --- a/src/lune/builtins/datetime/date_time.rs +++ b/src/lune/builtins/datetime/date_time.rs @@ -94,7 +94,7 @@ impl DateTime { } } - /// Returns a new `DateTime` using the given units from a UTC time. The + /// Returns a new `DateTime` using the given units from a local time. The /// values accepted are similar to those found in the time value table /// returned by `to_local_time`. /// diff --git a/types/datetime.luau b/types/datetime.luau index 1e1756c..7733636 100644 --- a/types/datetime.luau +++ b/types/datetime.luau @@ -1,4 +1,4 @@ --- TODO: Add docs +-- TODO: Add more docs export type Locale = "en" | "de" | "es" | "fr" | "it" | "ja" | "pl" | "pt-br" | "pt" | "tr" @@ -49,6 +49,7 @@ export type DateTime = { toIsoDate: (self: DateTime) -> string, toLocalTime: (self: DateTime) -> DateTimeValues, toUniversalTime: (self: DateTime) -> DateTimeValues, + formatTime: ( self: DateTime, timezone: Timezone, @@ -66,6 +67,33 @@ export type DateTime = { ```lua local DateTime = require("@lune/datetime") + + -- Returns the current moment in time as a ISO 8601 string + DateTime.now():toIsoDate() + + -- Returns the current moment in time as per the format template in French + DateTime.now():formatTime("utc", "%A, %d %B %Y", "fr") + + -- Returns a specific moment in time as a DateTime instance + DateTime.fromLocalTime({ + ["year"] = 2023, + ["month"] = "aug", + ["day"] = 26, + ["hour"] = 16, + ["minute"] = 56, + ["second"] = 28, + ["millisecond"] = 892, + }) + + -- Returns the current local time as a DateTime instance + DateTime.fromLocalTime() + + -- Returns a DateTime instance from a given float, where the whole denotes the + -- seconds and the fraction denotes the milliseconds + DateTime.fromUnixTimestamp(871978212313.321) + + -- Returns the current time in terms of UTC + DateTime.now():toUniversalTime() ``` ]=] local dateTime = {} @@ -94,14 +122,57 @@ function dateTime.fromUnixTimestamp(unixTimestamp: number?): DateTime return nil :: any end +--[=[ + @within DateTime + + Returns a new `DateTime` using the given units from a UTC time. The + values accepted are similar to those found in the time value table + returned by `to_universal_time`. + + - Date units (year, month, day) that produce an invalid date will raise an error. For example, January 32nd or February 29th on a non-leap year. + - Time units (hour, minute, second, millisecond) that are outside their normal range are valid. For example, 90 minutes will cause the hour to roll over by 1; -10 seconds will cause the minute value to roll back by 1. + - Non-integer values are rounded down. For example, providing 2.5 hours will be equivalent to providing 2 hours, not 2 hours 30 minutes. + - Omitted values are assumed to be their lowest value in their normal range, except for year which defaults to 1970. + + @param dateTime Optional values for the dateTime instance, defaults to the current time + @return A DateTime instance +]=] function dateTime.fromUniversalTime(dateTime: DateTimeValues?): DateTime return nil :: any end +--[=[ + @within DateTime + + Returns a new `DateTime` using the given units from a local time. The + values accepted are similar to those found in the time value table + returned by `to_local_time`. + + - Date units (year, month, day) that produce an invalid date will raise an error. For example, January 32nd or February 29th on a non-leap year. + - Time units (hour, minute, second, millisecond) that are outside their normal range are valid. For example, 90 minutes will cause the hour to roll over by 1; -10 seconds will cause the minute value to roll back by 1. + - Non-integer values are rounded down. For example, providing 2.5 hours will be equivalent to providing 2 hours, not 2 hours 30 minutes. + - Omitted values are assumed to be their lowest value in their normal range, except for year which defaults to 1970. + + @param dateTime Optional values for the dateTime instance, defaults to the current time + @return A DateTime instance +]=] function dateTime.fromLocalTime(dateTime: DateTimeValues?): DateTime return nil :: any end +--[=[ + @within DateTime + + Returns a `DateTime` from an ISO 8601 date-time string in UTC + time, such as those returned by `to_iso_date`. If the + string parsing fails, the function returns `nil`. + + An example ISO 8601 date-time string would be `2020-01-02T10:30:45Z`, + which represents January 2nd 2020 at 10:30 AM, 45 seconds. + + @param isoDate An ISO 8601 formatted string + @return A DateTime instance +]=] function dateTime.fromIsoDate(iso_date: string): DateTime? return nil :: any end