lune-std-datetime 0.3.1

Lune standard library - DateTime
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
--[[
	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

	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

--[=[
	@prop unixTimestamp number
	@within DateTime
	Number of seconds passed since the UNIX epoch.
]=]

--[=[
	@prop unixTimestampMillis number
	@within DateTime
	Number of milliseconds passed since the UNIX epoch.
]=]
local DateTime = {
	unixTimestamp = (nil :: any) :: number,
	unixTimestampMillis = (nil :: any) :: number,
}

--[=[
	@within DateTime
	@tag Method

	Formats this `DateTime` using the given `formatString` and `locale`, as local time.

	The given `formatString` is parsed using a `strftime`/`strptime`-inspired
	date and time formatting syntax, allowing tokens such as the following:

	| Token | Example  | Description   |
	|-------|----------|---------------|
	| `%Y`  | `1998`   | Year number   |
	| `%m`  | `04`     | Month number  |
	| `%d`  | `29`     | Day number    |
	| `%A`  | `Monday` | Weekday name  |
	| `%M`  | `59`     | Minute number |
	| `%S`  | `10`     | Second number |

	For a full reference of all available tokens, see the
	[chrono documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).

	If not provided, `formatString` and `locale` will default
	to `"%Y-%m-%d %H:%M:%S"` and `"en"` (english) respectively.

	@param formatString -- A string containing formatting tokens
	@param locale -- The locale the time should be formatted in
	@return string -- The formatting string
]=]
function DateTime.formatLocalTime(self: DateTime, formatString: string?, locale: Locale?): string
	return nil :: any
end

--[=[
	@within DateTime
	@tag Method

	Formats this `DateTime` using the given `formatString` and `locale`, as UTC (universal) time.

	The given `formatString` is parsed using a `strftime`/`strptime`-inspired
	date and time formatting syntax, allowing tokens such as the following:

	| Token | Example  | Description   |
	|-------|----------|---------------|
	| `%Y`  | `1998`   | Year number   |
	| `%m`  | `04`     | Month number  |
	| `%d`  | `29`     | Day number    |
	| `%A`  | `Monday` | Weekday name  |
	| `%M`  | `59`     | Minute number |
	| `%S`  | `10`     | Second number |

	For a full reference of all available tokens, see the
	[chrono documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).

	If not provided, `formatString` and `locale` will default
	to `"%Y-%m-%d %H:%M:%S"` and `"en"` (english) respectively.

	@param formatString -- A string containing formatting tokens
	@param locale -- The locale the time should be formatted in
	@return string -- The formatting string
]=]
function DateTime.formatUniversalTime(self: DateTime, formatString: string?, locale: Locale?): string
	return nil :: any
end

--[=[
	@within DateTime
	@tag Method

	**DEPRECATED**: Use `DateTime.toRfc3339` instead.

	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

	Formats this `DateTime` as an RFC 2822 date-time string.

	Some examples of RFC 2822 date-time strings are:

	- `Fri, 21 Nov 1997 09:55:06 -0600`
	- `Tue, 1 Jul 2003 10:52:37 +0200`
	- `Mon, 23 Dec 2024 01:58:48 GMT`

	@return string -- The RFC 2822 formatted string
]=]
function DateTime.toRfc2822(self: DateTime): string
	return nil :: any
end

--[=[
	@within DateTime
	@tag Method

	Formats this `DateTime` as an RFC 3339 date-time string.

	Some examples of RFC 3339 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 RFC 3339 formatted string
]=]
function DateTime.toRfc3339(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)

--[=[
	@class DateTime

	Built-in library for date & time

	### Example usage

	```lua
	local DateTime = require("@lune/datetime")

	-- Creates a DateTime for the current exact moment in time
	local now = DateTime.now()

	-- Formats the current moment in time as an RFC 3339 string
	print(now:toRfc3339())

	-- Formats the current moment in time as an RFC 2822 string
	print(now:toRfc2822())

	-- Formats the current moment in time, using the local
	-- time, the French locale, and the specified time string
	print(now:formatLocalTime("%A, %d %B %Y", "fr"))

	-- Returns a specific moment in time as a DateTime instance
	local someDayInTheFuture = DateTime.fromLocalTime({
		year = 3033,
		month = 8,
		day = 26,
		hour = 16,
		minute = 56,
		second = 28,
		millisecond = 892,
	})

	-- Extracts the current local date & time as separate values (same values as above table)
	print(now:toLocalTime())

	-- Returns a DateTime instance from a given float, where the whole
	-- denotes the seconds and the fraction denotes the milliseconds
	-- Note that the fraction for millis here is completely optional
	DateTime.fromUnixTimestamp(871978212313.321)

	-- Extracts the current universal (UTC) date & time as separate values
	print(now:toUniversalTime())
	```
]=]
local dateTime = {}

--[=[
	@within DateTime
	@tag Constructor

	Returns a `DateTime` representing the current moment in time.

	@return DateTime -- The new DateTime object
]=]
function dateTime.now(): DateTime
	return nil :: any
end

--[=[
	@within DateTime
	@tag Constructor

	Creates a new `DateTime` from the given UNIX timestamp.

	This timestamp may contain both a whole and fractional part -
	where the fractional part denotes milliseconds / nanoseconds.

	Example usage of fractions:

	- `DateTime.fromUnixTimestamp(123456789.001)` - one millisecond
	- `DateTime.fromUnixTimestamp(123456789.000000001)` - one nanosecond

	Note that the fractional part has limited precision down to exactly
	one nanosecond, any fraction that is more precise will get truncated.

	@param unixTimestamp -- Seconds passed since the UNIX epoch
	@return DateTime -- The new DateTime object
]=]
function dateTime.fromUnixTimestamp(unixTimestamp: number): DateTime
	return nil :: any
end

--[=[
	@within DateTime
	@tag Constructor

	Creates a new `DateTime` from the given date & time values table, in universal (UTC) time.

	The given table must contain 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`      |

	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) 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: 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 contain 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`      |

	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) 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: DateTimeValueArguments): DateTime
	return nil :: any
end

--[=[
	@within DateTime
	@tag Constructor

	**DEPRECATED**: Use `DateTime.fromRfc3339` instead.

	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 are:

	- `2020-02-22T18:12:08Z`
	- `2000-01-31T12:34:56+05:00`
	- `1970-01-01T00:00:00.055Z`

	@param isoDate -- An ISO 8601 formatted string
	@return DateTime -- The new DateTime object
]=]
function dateTime.fromIsoDate(isoDate: string): DateTime
	return nil :: any
end

--[=[
	@within DateTime
	@tag Constructor

	Creates a new `DateTime` from an RFC 3339 date-time string.

	### Errors

	This constructor is fallible and may throw an error if the given
	string does not strictly follow the RFC 3339 date-time string format.

	Some examples of valid RFC 3339 date-time strings are:

	- `2020-02-22T18:12:08Z`
	- `2000-01-31T12:34:56+05:00`
	- `1970-01-01T00:00:00.055Z`

	@param rfc3339Date -- An RFC 3339 formatted string
	@return DateTime -- The new DateTime object
]=]
function dateTime.fromRfc3339(rfc3339Date: string): DateTime
	return nil :: any
end

--[=[
	@within DateTime
	@tag Constructor

	Creates a new `DateTime` from an RFC 2822 date-time string.

	### Errors

	This constructor is fallible and may throw an error if the given
	string does not strictly follow the RFC 2822 date-time string format.

	Some examples of valid RFC 2822 date-time strings are:

	- `Fri, 21 Nov 1997 09:55:06 -0600`
	- `Tue, 1 Jul 2003 10:52:37 +0200`
	- `Mon, 23 Dec 2024 01:58:48 GMT`

	@param rfc2822Date -- An RFC 2822 formatted string
	@return DateTime -- The new DateTime object
]=]
function dateTime.fromRfc2822(rfc2822Date: string): DateTime
	return nil :: any
end

return dateTime