Skip to content

Commit 3cf4a5e

Browse files
sharkdpDavid Peter
sharkdp
authored and
David Peter
committed
Date and time documentation updates
1 parent ae3e7f0 commit 3cf4a5e

File tree

2 files changed

+50
-24
lines changed

2 files changed

+50
-24
lines changed

‎book/src/date-and-time.md

+39-24
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ now() - 1 million seconds
1616
parse_datetime("2024-11-01 12:30:00") - now() -> days
1717
1818
# What time is it in Nepal right now?
19-
now() -> "Asia/Kathmandu"
19+
now() -> "Asia/Kathmandu" # use tab completion to find time zone names
2020
2121
# What is the local time when it is 2024-11-01 12:30:00 in Australia?
2222
parse_datetime("2024-11-01 12:30:00 Australia/Sydney") -> "local"
@@ -26,44 +26,59 @@ now() // to_unixtime
2626
2727
# What is the date corresponding to the UNIX timestamp 1707568901?
2828
from_unixtime(1707568901)
29-
```
30-
31-
As you can see from the examples, datetimes are either created using the `now()` function or by
32-
parsing a string using the `parse_datetime` function. The following formats are supported.
33-
UTC offsets are mandatory for the RFC 3339 and RFC 2822 formats. The other formats can optionally
34-
include a time zone name or UTC offset. If no time zone is specified, the local time zone is used.
35-
36-
| Format | Examples |
37-
| ------ | ------- |
38-
| [RFC 3339](https://tools.ietf.org/html/rfc3339) | `2024-02-10T12:30:00Z`<br>`2024-02-10T06:30:00-06:00` |
39-
| [RFC 2822](https://tools.ietf.org/html/rfc2822) | `Sat, 10 Feb 2024 12:30:00 Z`<br>`Sat, 10 Feb 2024 06:30:00 -0600` |
40-
| `%Y-%m-%d %H:%M:%S%.f` | `2024-02-10 12:30:00`<br>`2024-02-10 06:30:00 -0600`<br>`2024-02-10 07:30:00 US/Eastern`<br>`2024-02-10 12:30:00.123456` |
41-
| `%Y/%m/%d %H:%M:%S%.f` | same, but with `/` separator |
42-
| `%Y-%m-%d %H:%M` | `2024-02-10 12:30`<br>`2024-02-10 06:30 -0600`<br>`2024-02-10 07:30 US/Eastern` |
43-
| `%Y/%m/%d %H:%M` | same, but with `/` separator |
44-
| `%Y-%m-%d %I:%M:%S%.f %p` | `2024-02-10 12:30:00 PM`<br>`2024-02-10 06:30:00 AM -0600`<br>`2024-02-10 07:30:00 AM US/Eastern`<br>`2024-02-10 12:30:00.123456 PM` |
45-
| `%Y/%m/%d %I:%M:%S%.f %p` | same, but with `/` separator |
46-
| `%Y-%m-%d %I:%M %p` | `2024-02-10 12:30 PM`<br>`2024-02-10 06:30 AM -0600`<br>`2024-02-10 07:30 AM US/Eastern` |
47-
| `%Y/%m/%d %I:%M %p` | same, but with `/` separator |
4829
30+
# How long are one million seconds in days, hours, minutes, seconds
31+
1 million seconds // human
32+
```
4933

5034
## Date and time arithmetic
5135

5236
The following operations are supported for `DateTime` objects:
5337

5438
| Left | Operator | Right | Result |
5539
| ---- | -------- | ----- | ------ |
56-
| `DateTime` | `-` | `DateTime` | Duration between the two dates as a `Time` |
40+
| `DateTime` | `-` | `DateTime` | Duration between the two dates as a `Time`. In `seconds`, by default. Use normal conversion for other time units. |
5741
| `DateTime` | `+` | `Time` | New `DateTime` by adding the duration to the date |
5842
| `DateTime` | `-` | `Time` | New `DateTime` by subtracting the duration from the date |
59-
| `DateTime` | `->` | `String` | Converts the datetime to the specified time zone |
43+
| `DateTime` | `->` | `String` | Converts the datetime to the specified time zone. Note that you can use tab-completion for time zone names. |
44+
45+
<div class="warning">
6046

61-
## Date and time functions
47+
**Warning**: You can add `years` or `months` to a given date (`now() + 3 months`), but note that the result might not be what you expect.
48+
The unit `year` is defined as the *average* length of a year (a [tropical year](https://en.wikipedia.org/wiki/Tropical_year), to be precise), and
49+
`month` is defined as the *average* length of a month (1/12 of a `year`). So this does not take into account the actual length of the months or the leap years.
50+
However, note that adding or subtracting "one year" or "one month" is not a well-defined operation anyway. For example, what should "one month after March 31st"
51+
be? April 30th or May 1st? If your answer is April 30th, then what is "one month after March 30th"? If your answer is May 1st, then what is "one month after
52+
April 1st"?
53+
54+
</div>
55+
56+
## Date, time, and duration functions
6257

6358
The following functions are available for date and time handling:
6459

6560
- `now() -> DateTime`: Returns the current date and time.
6661
- `parse_datetime(input: String) -> DateTime`: Parses a string into a `DateTime` object.
67-
- `format_datetime(format: String, dt: DateTime) -> String`: Formats a `DateTime` object as a string.
62+
- `format_datetime(format: String, dt: DateTime) -> String`: Formats a `DateTime` object as a string. See [this page](https://docs.rs/chrono/latest/chrono/format/strftime/index.html#specifiers) for possible format specifiers.
6863
- `to_unixtime(dt: DateTime) -> Scalar`: Converts a `DateTime` to a UNIX timestamp.
6964
- `from_unixtime(ut: Scalar) -> DateTime`: Converts a UNIX timestamp to a `DateTime` object.
65+
- `human(duration: Time) -> String`: Converts a `Time` to a human-readable string in days, hours, minutes and seconds
66+
67+
## Date time formats
68+
69+
The following formats are supported by `parse_datetime`. UTC offsets are mandatory for the RFC 3339 and
70+
RFC 2822 formats. The other formats can optionally include a time zone name or UTC offset. If no time
71+
zone is specified, the local time zone is used.
72+
73+
| Format | Examples |
74+
| ------ | ------- |
75+
| [RFC 3339](https://tools.ietf.org/html/rfc3339) | `2024-02-10T12:30:00Z`<br>`2024-02-10T06:30:00-06:00` |
76+
| [RFC 2822](https://tools.ietf.org/html/rfc2822) | `Sat, 10 Feb 2024 12:30:00 Z`<br>`Sat, 10 Feb 2024 06:30:00 -0600` |
77+
| `%Y-%m-%d %H:%M:%S%.f` | `2024-02-10 12:30:00`<br>`2024-02-10 06:30:00 -0600`<br>`2024-02-10 07:30:00 US/Eastern`<br>`2024-02-10 12:30:00.123456` |
78+
| `%Y/%m/%d %H:%M:%S%.f` | same, but with `/` separator |
79+
| `%Y-%m-%d %H:%M` | `2024-02-10 12:30`<br>`2024-02-10 06:30 -0600`<br>`2024-02-10 07:30 US/Eastern` |
80+
| `%Y/%m/%d %H:%M` | same, but with `/` separator |
81+
| `%Y-%m-%d %I:%M:%S%.f %p` | `2024-02-10 12:30:00 PM`<br>`2024-02-10 06:30:00 AM -0600`<br>`2024-02-10 07:30:00 AM US/Eastern`<br>`2024-02-10 12:30:00.123456 PM` |
82+
| `%Y/%m/%d %I:%M:%S%.f %p` | same, but with `/` separator |
83+
| `%Y-%m-%d %I:%M %p` | `2024-02-10 12:30 PM`<br>`2024-02-10 06:30 AM -0600`<br>`2024-02-10 07:30 AM US/Eastern` |
84+
| `%Y/%m/%d %I:%M %p` | same, but with `/` separator |

‎book/src/list-functions.md

+11
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,17 @@ fn sphere_area<L>(radius: L) -> L^2
9999
fn sphere_volume<L>(radius: L) -> L^3
100100
```
101101

102+
## Date and time
103+
104+
```nbt
105+
fn now() -> DateTime
106+
fn parse_datetime(input: String) -> DateTime
107+
fn format_datetime(format: String, dt: DateTime) -> String
108+
fn from_unixtime(t: Scalar) -> DateTime
109+
fn to_unixtime(dt: DateTime) -> Scalar
110+
fn human(t: Time) -> String
111+
```
112+
102113
## Physics
103114

104115
### Temperature conversion

0 commit comments

Comments
 (0)