Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Example decorators #566

Merged
merged 10 commits into from
Oct 8, 2024
Merged

Example decorators #566

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
efe5921
Add @examples decorator
Bzero Sep 14, 2024
0210b9c
Automatically add examples to the documentation
Bzero Sep 15, 2024
04e1772
Expand documentation by adding examples
Bzero Sep 15, 2024
f6dd12a
Move details closing tag inside conditional
Bzero Sep 16, 2024
b32bb20
Remove example for the time function
Bzero Sep 24, 2024
42f2976
Apply suggested example formatting
Bzero Sep 24, 2024
17c2a9f
Clone example context instead of re-interpreting
Bzero Sep 24, 2024
45cba26
Apply example suggestions from code review
Bzero Sep 29, 2024
024f2d3
More compact examples
Bzero Oct 4, 2024
1cf1bb9
Merge branch 'master' into example_decorator
Bzero Oct 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 4 additions & 0 deletions book/build.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import subprocess
from pathlib import Path
import urllib.parse
import os


SCRIPT_DIR = Path(__file__).parent.resolve()
Expand Down Expand Up @@ -119,6 +120,8 @@ def list_of_functions(file_name, document):
print(
f"Generating list of functions for module '{module}'...", flush=True
)
env = os.environ.copy()
env["TZ"] = "UTC"
subprocess.run(
[
"cargo",
Expand All @@ -132,6 +135,7 @@ def list_of_functions(file_name, document):
],
stdout=f,
text=True,
env=env,
)


Expand Down
136 changes: 136 additions & 0 deletions book/src/list-functions-datetime.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,41 +18,116 @@ Parses a string (date and time) into a `DateTime` object. See [here](./date-and-
fn datetime(input: String) -> DateTime
```

<details>
<summary>Examples</summary>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=datetime%28%222022%2D07%2D20T21%3A52%2B0200%22%29')""></button></div><code class="language-nbt hljs numbat">>>> datetime("2022-07-20T21:52+0200")

= 2022-07-20 19:52:00 UTC [DateTime]
</code></pre>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=datetime%28%222022%2D07%2D20%2021%3A52%20Europe%2FBerlin%22%29')""></button></div><code class="language-nbt hljs numbat">>>> datetime("2022-07-20 21:52 Europe/Berlin")

= 2022-07-20 21:52:00 CEST (UTC +02), Europe/Berlin [DateTime]
</code></pre>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=datetime%28%222022%2F07%2F20%2009%3A52%20PM%20%2B0200%22%29')""></button></div><code class="language-nbt hljs numbat">>>> datetime("2022/07/20 09:52 PM +0200")

= 2022-07-20 21:52:00 (UTC +02) [DateTime]
</code></pre>

</details>

### `format_datetime`
Formats a `DateTime` object as a string.

```nbt
fn format_datetime(format: String, input: DateTime) -> String
```

<details>
<summary>Examples</summary>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=format%5Fdatetime%28%22This%20is%20a%20date%20in%20%25B%20in%20the%20year%20%25Y%2E%22%2C%20datetime%28%222022%2D07%2D20%2021%3A52%20%2B0200%22%29%29')""></button></div><code class="language-nbt hljs numbat">>>> format_datetime("This is a date in %B in the year %Y.", datetime("2022-07-20 21:52 +0200"))

= "This is a date in July in the year 2022." [String]
</code></pre>

</details>

### `get_local_timezone`
Returns the users local timezone.

```nbt
fn get_local_timezone() -> String
```

<details>
<summary>Examples</summary>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=get%5Flocal%5Ftimezone%28%29')""></button></div><code class="language-nbt hljs numbat">>>> get_local_timezone()

= "UTC" [String]
</code></pre>

</details>

### `tz`
Returns a timezone conversion function, typically used with the conversion operator.

```nbt
fn tz(tz: String) -> Fn[(DateTime) -> DateTime]
```

<details>
<summary>Examples</summary>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=datetime%28%222022%2D07%2D20%2021%3A52%20%2B0200%22%29%20%2D%3E%20tz%28%22Europe%2FAmsterdam%22%29')""></button></div><code class="language-nbt hljs numbat">>>> datetime("2022-07-20 21:52 +0200") -> tz("Europe/Amsterdam")

= 2022-07-20 21:52:00 CEST (UTC +02), Europe/Amsterdam [DateTime]
</code></pre>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=datetime%28%222022%2D07%2D20%2021%3A52%20%2B0200%22%29%20%2D%3E%20tz%28%22Asia%2FTaipei%22%29')""></button></div><code class="language-nbt hljs numbat">>>> datetime("2022-07-20 21:52 +0200") -> tz("Asia/Taipei")

= 2022-07-21 03:52:00 CST (UTC +08), Asia/Taipei [DateTime]
</code></pre>

</details>

### `unixtime`
Converts a `DateTime` to a UNIX timestamp. Can be used on the right hand side of a conversion operator: `now() -> unixtime`.

```nbt
fn unixtime(input: DateTime) -> Scalar
```

<details>
<summary>Examples</summary>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=datetime%28%222022%2D07%2D20%2021%3A52%20%2B0200%22%29%20%2D%3E%20unixtime')""></button></div><code class="language-nbt hljs numbat">>>> datetime("2022-07-20 21:52 +0200") -> unixtime

= 1_658_346_720
</code></pre>

</details>

### `from_unixtime`
Converts a UNIX timestamp to a `DateTime` object.

```nbt
fn from_unixtime(input: Scalar) -> DateTime
```

<details>
<summary>Examples</summary>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=from%5Funixtime%282%5E31%29')""></button></div><code class="language-nbt hljs numbat">>>> from_unixtime(2^31)

= 2038-01-19 03:14:08 UTC [DateTime]
</code></pre>

</details>

### `today`
Returns the current date at midnight (in the local time).

Expand All @@ -67,6 +142,16 @@ Parses a string (only date) into a `DateTime` object.
fn date(input: String) -> DateTime
```

<details>
<summary>Examples</summary>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=date%28%222022%2D07%2D20%22%29')""></button></div><code class="language-nbt hljs numbat">>>> date("2022-07-20")

= 2022-07-20 00:00:00 UTC [DateTime]
</code></pre>

</details>

### `time`
Parses a string (time only) into a `DateTime` object.

Expand All @@ -81,20 +166,50 @@ Adds the given time span to a `DateTime`. This uses leap-year and DST-aware cale
fn calendar_add(dt: DateTime, span: Time) -> DateTime
```

<details>
<summary>Examples</summary>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=calendar%5Fadd%28datetime%28%222022%2D07%2D20%2021%3A52%20%2B0200%22%29%2C%202%20years%29')""></button></div><code class="language-nbt hljs numbat">>>> calendar_add(datetime("2022-07-20 21:52 +0200"), 2 years)

= 2024-07-20 21:52:00 (UTC +02) [DateTime]
</code></pre>

</details>

### `calendar_sub`
Subtract the given time span from a `DateTime`. This uses leap-year and DST-aware calendar arithmetic with variable-length days, months, and years.

```nbt
fn calendar_sub(dt: DateTime, span: Time) -> DateTime
```

<details>
<summary>Examples</summary>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=calendar%5Fsub%28datetime%28%222022%2D07%2D20%2021%3A52%20%2B0200%22%29%2C%203%20years%29')""></button></div><code class="language-nbt hljs numbat">>>> calendar_sub(datetime("2022-07-20 21:52 +0200"), 3 years)

= 2019-07-20 21:52:00 (UTC +02) [DateTime]
</code></pre>

</details>

### `weekday`
Get the day of the week from a given `DateTime`.

```nbt
fn weekday(dt: DateTime) -> String
```

<details>
<summary>Examples</summary>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=weekday%28datetime%28%222022%2D07%2D20%2021%3A52%20%2B0200%22%29%29')""></button></div><code class="language-nbt hljs numbat">>>> weekday(datetime("2022-07-20 21:52 +0200"))

= "Wednesday" [String]
</code></pre>

</details>

### `julian_date` (Julian date)
Convert a `DateTime` to a Julian date, the number of days since the origin of the Julian date system (noon on November 24, 4714 BC in the proleptic Gregorian calendar).
More information [here](https://en.wikipedia.org/wiki/Julian_day).
Expand All @@ -103,6 +218,16 @@ More information [here](https://en.wikipedia.org/wiki/Julian_day).
fn julian_date(dt: DateTime) -> Time
```

<details>
<summary>Examples</summary>

<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=julian%5Fdate%28datetime%28%222022%2D07%2D20%2021%3A52%20%2B0200%22%29%29')""></button></div><code class="language-nbt hljs numbat">>>> julian_date(datetime("2022-07-20 21:52 +0200"))

= 2.45978e+6 day [Time]
</code></pre>

</details>

### `human` (Human-readable time duration)
Converts a time duration to a human-readable string in days, hours, minutes and seconds.
More information [here](https://numbat.dev/doc/date-and-time.html).
Expand All @@ -111,3 +236,14 @@ More information [here](https://numbat.dev/doc/date-and-time.html).
fn human(time: Time) -> String
```

<details>
<summary>Examples</summary>

How long is a microcentury?
<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code" onclick=" window.open('https://numbat.dev/?q=century%2F1e6%20%2D%3E%20human')""></button></div><code class="language-nbt hljs numbat">>>> century/1e6 -> human

= "52 minutes + 35.692505184 seconds" [String]
</code></pre>

</details>

Loading
Loading