Proxmox/proxmox
5
0
Fork 1
Code Issues Pull Requests Releases Activity

time: add module level docs for time span

Browse Source 
There was basically no documentation at all, so try to document the
basic format syntax and where it comes from. The text is partially
adapted from the systemd docs.

Could be still expanded with some example code and the methods might
do good with getting some docs too, but those parts can be relatively
easily be figured out from the code itself, the basic underlying
design and format background is much harder to guess..

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
This commit is contained in:
Thomas Lamprecht 2024-10-17 13:55:46 +02:00
parent 191299605f
commit 17bf3ec9fe
1 changed files with 40 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
proxmox-time/src/time_span.rs
View File

@ -1,3 +1,43 @@
//! Timespans that try to be compatible with the systemd time span format.
//!
//! Time spans refer to time durations, like [std::time::Duration] but in the format that is
//! targetting human interfaces and that systemd understands. Parts of this documentation have been
//! adapted from the systemd.time manual page.
//!
//! The following time units are understood:
//! - `nsec`, `ns` (not always accepted by systemd.time)
//! - `usec`, `us`, `µs`
//! - `msec`, `ms`
//! - `seconds`, s`econd`, `sec`, `s`
//! - `minutes`, `minute`, `min`, `m`
//! - `hours`, `hour`, `hr`, `h`
//! - `days`, `day`, `d`
//! - `weeks`, `week`, `w`
//! - `months`, `month`, `M` (defined as 30.44 days)
//! - `years`, `year`, `y` (defined as 365.25 days)
//!
//! On display, time spans are formatted as space-separated series of time values each
//! suffixed by the single-character time unit, for example
//!
//! - `2h 30m`
//! - `1w 2m 3s`
//!
//! For parsing a time stamp the same syntax applies, all time units from above are supported, and
//! spaces between units and/or values can be added or omitted. The order of the time values does
//! not matter.
//!
//! The following examples are all represeting the exact same time span of 1 day 2 hours and 3
//! minutes:
//!
//! - `1d 2h 3m`
//! - `1d2h3m`
//! - `26h 180s`
//! - `1 day 2 hours 3 minutes`
//! - `0y 0M 0w 1d 2h 3m`
//! - `2h 1d 3m`
//!
//! This module also supports transforming a [std::time::Duration] to a [TimeSpan].
use std::collections::HashMap;
use std::sync::LazyLock;