mirror of
https://github.com/lune-org/lune.git
synced 2024-12-12 13:00:37 +00:00
Typedefs & docs improvements for DateTime
This commit is contained in:
Filip Tibell
parent
ac186190e5
commit
be6b2c8a71
1 changed files with 177 additions and 89 deletions
|
|
@ -1,94 +1,102 @@
|
|||
export type Locale = "en" | "de" | "es" | "fr" | "it" | "ja" | "pl" | "pt-br" | "pt" | "tr"
|
||||
--[[
|
||||
NOTE: We export a couple different DateTimeValues types below to ensure
|
||||
that types are completely accurate, for method args milliseconds will
|
||||
always be optional, but for return values millis are always included
|
||||
|
||||
export type DateTimeValues = {
|
||||
--- Year(s), in the range 1400 -> 9999
|
||||
year: number,
|
||||
--- Month(s), in the range 1 -> 12
|
||||
month: number,
|
||||
--- Day(s), in the range 1 -> 31
|
||||
day: number,
|
||||
--- Hour(s), in the range 0 -> 23
|
||||
hour: number,
|
||||
--- Minute(s), in the range 0 -> 59
|
||||
minute: number,
|
||||
--- Second(s), in the range 0 -> 60, where 60 is a leap second
|
||||
second: number,
|
||||
--- Millisecond(s), in the range 0 -> 999
|
||||
If we figure out some better strategy here where we can
|
||||
export just a single type while maintaining accuracy we
|
||||
can change to that in a future breaking semver release
|
||||
]]
|
||||
|
||||
type OptionalMillisecond = {
|
||||
millisecond: number?,
|
||||
}
|
||||
|
||||
type Millisecond = {
|
||||
millisecond: number,
|
||||
}
|
||||
|
||||
--[=[
|
||||
@interface Locale
|
||||
@within DateTime
|
||||
|
||||
Enum type representing supported DateTime locales.
|
||||
|
||||
Currently supported locales are:
|
||||
|
||||
- `en` - English
|
||||
- `de` - German
|
||||
- `es` - Spanish
|
||||
- `fr` - French
|
||||
- `it` - Italian
|
||||
- `ja` - Japanese
|
||||
- `pl` - Polish
|
||||
- `pt-br` - Brazilian Portuguese
|
||||
- `pt` - Portuguese
|
||||
- `tr` - Turkish
|
||||
]=]
|
||||
export type Locale = "en" | "de" | "es" | "fr" | "it" | "ja" | "pl" | "pt-br" | "pt" | "tr"
|
||||
|
||||
--[=[
|
||||
@interface DateTimeValues
|
||||
@within DateTime
|
||||
|
||||
Individual date & time values, representing the primitives that make up a `DateTime`.
|
||||
|
||||
This is a dictionary that will contain the following values:
|
||||
|
||||
- `year` - Year(s), in the range 1400 -> 9999
|
||||
- `month` - Month(s), in the range 1 -> 12
|
||||
- `day` - Day(s), in the range 1 -> 31
|
||||
- `hour` - Hour(s), in the range 0 -> 23
|
||||
- `minute` - Minute(s), in the range 0 -> 59
|
||||
- `second` - Second(s), in the range 0 -> 60, where 60 is a leap second
|
||||
|
||||
An additional `millisecond` value may also be included,
|
||||
and should be within the range `0 -> 999`, but is optional.
|
||||
|
||||
However, any method returning this type should be guaranteed
|
||||
to include milliseconds - see individual methods to verify.
|
||||
]=]
|
||||
export type DateTimeValues = {
|
||||
year: number,
|
||||
month: number,
|
||||
day: number,
|
||||
hour: number,
|
||||
minute: number,
|
||||
second: number,
|
||||
}
|
||||
|
||||
--[=[
|
||||
@interface DateTimeValueArguments
|
||||
@within DateTime
|
||||
|
||||
Alias for `DateTimeValues` with an optional `millisecond` value.
|
||||
|
||||
Refer to the `DateTimeValues` documentation for additional information.
|
||||
]=]
|
||||
export type DateTimeValueArguments = DateTimeValues & OptionalMillisecond
|
||||
|
||||
--[=[
|
||||
@interface DateTimeValueReturns
|
||||
@within DateTime
|
||||
|
||||
Alias for `DateTimeValues` with a mandatory `millisecond` value.
|
||||
|
||||
Refer to the `DateTimeValues` documentation for additional information.
|
||||
]=]
|
||||
export type DateTimeValueReturns = DateTimeValues & Millisecond
|
||||
|
||||
local DateTime = {
|
||||
--- Number of seconds passed since the UNIX epoch.
|
||||
unixTimestamp = 0,
|
||||
unixTimestamp = (nil :: any) :: number,
|
||||
--- Number of milliseconds passed since the UNIX epoch.
|
||||
unixTimestampMillis = 0,
|
||||
unixTimestampMillis = (nil :: any) :: number,
|
||||
}
|
||||
|
||||
--[=[
|
||||
@within DateTime
|
||||
|
||||
Formats this `DateTime` as an ISO 8601 date-time string.
|
||||
|
||||
Some examples of ISO 8601 date-time strings:
|
||||
|
||||
- `2020-02-22T18:12:08Z`
|
||||
- `2000-01-31T12:34:56+05:00`
|
||||
- `1970-01-01T00:00:00.055Z`
|
||||
|
||||
@return string -- The ISO 8601 formatted string
|
||||
]=]
|
||||
function DateTime.toIsoDate(self: DateTime): string
|
||||
return nil :: any
|
||||
end
|
||||
|
||||
--[=[
|
||||
@within DateTime
|
||||
|
||||
Extracts local time values from this `DateTime`.
|
||||
|
||||
The returned table contains the following values:
|
||||
|
||||
| Key | Type | Range |
|
||||
|---------------|----------|----------------|
|
||||
| `year` | `number` | `1400 -> 9999` |
|
||||
| `month` | `number` | `1 -> 12` |
|
||||
| `day` | `number` | `1 -> 31` |
|
||||
| `hour` | `number` | `0 -> 23` |
|
||||
| `minute` | `number` | `0 -> 59` |
|
||||
| `second` | `number` | `0 -> 60` |
|
||||
| `millisecond` | `number` | `0 -> 999` |
|
||||
|
||||
@return DateTimeValues -- A table of DateTime values
|
||||
]=]
|
||||
function DateTime.toLocalTime(self: DateTime): DateTimeValues
|
||||
return nil :: any
|
||||
end
|
||||
|
||||
--[=[
|
||||
@within DateTime
|
||||
|
||||
Extracts UTC (universal) time values from this `DateTime`.
|
||||
|
||||
The returned table contains the following values:
|
||||
|
||||
| Key | Type | Range |
|
||||
|---------------|----------|----------------|
|
||||
| `year` | `number` | `1400 -> 9999` |
|
||||
| `month` | `number` | `1 -> 12` |
|
||||
| `day` | `number` | `1 -> 31` |
|
||||
| `hour` | `number` | `0 -> 23` |
|
||||
| `minute` | `number` | `0 -> 59` |
|
||||
| `second` | `number` | `0 -> 60` |
|
||||
| `millisecond` | `number` | `0 -> 999` |
|
||||
|
||||
@return DateTimeValues -- A table of DateTime values
|
||||
]=]
|
||||
function DateTime.toUniversalTime(self: DateTime): DateTimeValues
|
||||
return nil :: any
|
||||
end
|
||||
|
||||
--[=[
|
||||
@within DateTime
|
||||
@tag Method
|
||||
|
||||
Formats this `DateTime` using the given `formatString` and `locale`, as local time.
|
||||
|
||||
|
|
@ -120,6 +128,7 @@ end
|
|||
|
||||
--[=[
|
||||
@within DateTime
|
||||
@tag Method
|
||||
|
||||
Formats this `DateTime` using the given `formatString` and `locale`, as UTC (universal) time.
|
||||
|
||||
|
|
@ -153,6 +162,72 @@ function DateTime.formatUniversalTime(
|
|||
return nil :: any
|
||||
end
|
||||
|
||||
--[=[
|
||||
@within DateTime
|
||||
@tag Method
|
||||
|
||||
Formats this `DateTime` as an ISO 8601 date-time string.
|
||||
|
||||
Some examples of ISO 8601 date-time strings are:
|
||||
|
||||
- `2020-02-22T18:12:08Z`
|
||||
- `2000-01-31T12:34:56+05:00`
|
||||
- `1970-01-01T00:00:00.055Z`
|
||||
|
||||
@return string -- The ISO 8601 formatted string
|
||||
]=]
|
||||
function DateTime.toIsoDate(self: DateTime): string
|
||||
return nil :: any
|
||||
end
|
||||
|
||||
--[=[
|
||||
@within DateTime
|
||||
@tag Method
|
||||
|
||||
Extracts separated local date & time values from this `DateTime`.
|
||||
|
||||
The returned table contains the following values:
|
||||
|
||||
| Key | Type | Range |
|
||||
|---------------|----------|----------------|
|
||||
| `year` | `number` | `1400 -> 9999` |
|
||||
| `month` | `number` | `1 -> 12` |
|
||||
| `day` | `number` | `1 -> 31` |
|
||||
| `hour` | `number` | `0 -> 23` |
|
||||
| `minute` | `number` | `0 -> 59` |
|
||||
| `second` | `number` | `0 -> 60` |
|
||||
| `millisecond` | `number` | `0 -> 999` |
|
||||
|
||||
@return DateTimeValueReturns -- A table of DateTime values
|
||||
]=]
|
||||
function DateTime.toLocalTime(self: DateTime): DateTimeValueReturns
|
||||
return nil :: any
|
||||
end
|
||||
|
||||
--[=[
|
||||
@within DateTime
|
||||
@tag Method
|
||||
|
||||
Extracts separated UTC (universal) date & time values from this `DateTime`.
|
||||
|
||||
The returned table contains the following values:
|
||||
|
||||
| Key | Type | Range |
|
||||
|---------------|----------|----------------|
|
||||
| `year` | `number` | `1400 -> 9999` |
|
||||
| `month` | `number` | `1 -> 12` |
|
||||
| `day` | `number` | `1 -> 31` |
|
||||
| `hour` | `number` | `0 -> 23` |
|
||||
| `minute` | `number` | `0 -> 59` |
|
||||
| `second` | `number` | `0 -> 60` |
|
||||
| `millisecond` | `number` | `0 -> 999` |
|
||||
|
||||
@return DateTimeValueReturns -- A table of DateTime values
|
||||
]=]
|
||||
function DateTime.toUniversalTime(self: DateTime): DateTimeValueReturns
|
||||
return nil :: any
|
||||
end
|
||||
|
||||
export type DateTime = typeof(DateTime)
|
||||
|
||||
--[=[
|
||||
|
|
@ -202,6 +277,7 @@ local dateTime = {}
|
|||
|
||||
--[=[
|
||||
@within DateTime
|
||||
@tag Constructor
|
||||
|
||||
Returns a `DateTime` representing the current moment in time.
|
||||
|
||||
|
|
@ -213,6 +289,7 @@ end
|
|||
|
||||
--[=[
|
||||
@within DateTime
|
||||
@tag Constructor
|
||||
|
||||
Creates a new `DateTime` from the given UNIX timestamp.
|
||||
|
||||
|
|
@ -236,10 +313,11 @@ end
|
|||
|
||||
--[=[
|
||||
@within DateTime
|
||||
@tag Constructor
|
||||
|
||||
Creates a new `DateTime` from the given date & time values table, in universal (UTC) time.
|
||||
|
||||
The given table must contains the following values:
|
||||
The given table must contain the following values:
|
||||
|
||||
| Key | Type | Range |
|
||||
|----------|----------|----------------|
|
||||
|
|
@ -253,24 +331,28 @@ end
|
|||
An additional `millisecond` value may also be included,
|
||||
and should be within the range `0 -> 999`, but is optional.
|
||||
|
||||
Any non-integer values in the given table will be rounded down.
|
||||
|
||||
### Errors
|
||||
|
||||
This constructor is fallible and may throw an error in the following situations:
|
||||
|
||||
- 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.
|
||||
- Non-integer values are rounded down. For example, providing 2.5 hours is equivalent to providing 2 hours, not 2 hours and 30 minutes.
|
||||
- Date units (year, month, day) were given that produce an invalid date. For example, January 32nd or February 29th on a non-leap year.
|
||||
|
||||
@param values -- Table containing date & time values
|
||||
@return DateTime -- The new DateTime object
|
||||
]=]
|
||||
function dateTime.fromUniversalTime(values: DateTimeValues): DateTime
|
||||
function dateTime.fromUniversalTime(values: DateTimeValueArguments): DateTime
|
||||
return nil :: any
|
||||
end
|
||||
|
||||
--[=[
|
||||
@within DateTime
|
||||
@tag Constructor
|
||||
|
||||
Creates a new `DateTime` from the given date & time values table, in local time.
|
||||
|
||||
The given table must contains the following values:
|
||||
The given table must contain the following values:
|
||||
|
||||
| Key | Type | Range |
|
||||
|----------|----------|----------------|
|
||||
|
|
@ -284,27 +366,33 @@ end
|
|||
An additional `millisecond` value may also be included,
|
||||
and should be within the range `0 -> 999`, but is optional.
|
||||
|
||||
Any non-integer values in the given table will be rounded down.
|
||||
|
||||
### Errors
|
||||
|
||||
This constructor is fallible and may throw an error in the following situations:
|
||||
|
||||
- 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.
|
||||
- Non-integer values are rounded down. For example, providing 2.5 hours is equivalent to providing 2 hours, not 2 hours and 30 minutes.
|
||||
- Date units (year, month, day) were given that produce an invalid date. For example, January 32nd or February 29th on a non-leap year.
|
||||
|
||||
@param values -- Table containing date & time values
|
||||
@return DateTime -- The new DateTime object
|
||||
]=]
|
||||
function dateTime.fromLocalTime(values: DateTimeValues): DateTime
|
||||
function dateTime.fromLocalTime(values: DateTimeValueArguments): DateTime
|
||||
return nil :: any
|
||||
end
|
||||
|
||||
--[=[
|
||||
@within DateTime
|
||||
@tag Constructor
|
||||
|
||||
Creates a new `DateTime` from an ISO 8601 date-time string.
|
||||
|
||||
### Errors
|
||||
|
||||
This constructor is fallible and may throw an error if the given
|
||||
string does not strictly follow the ISO 8601 date-time string format.
|
||||
|
||||
Some examples of valid ISO 8601 date-time strings:
|
||||
Some examples of valid ISO 8601 date-time strings are:
|
||||
|
||||
- `2020-02-22T18:12:08Z`
|
||||
- `2000-01-31T12:34:56+05:00`
|
||||
|
|
|
|||
Loading…
Reference in a new issue