readable

Module up

Source
Available on crate feature up only.
Expand description

Uptime formatting

“Uptime”-style strings, e.g:

const SECONDS: usize = 158079;

assert_eq!(Uptime::from(SECONDS),     "1d, 19h, 54m, 39s");
assert_eq!(UptimeFull::from(SECONDS), "1 day, 19 hours, 54 minutes, 39 seconds");
assert_eq!(Htop::from(SECONDS),       "1 day, 19:54:39");

§Input

The input is always assumed to be in seconds.

From input can be:

§Errors

The max input is u32::MAX seconds.

A Uptime::UNKNOWN (or a variant’s version of it) will be returned if the input is:

§Uptime

This module contains Uptime which is a trait that allows direct conversion from the live system uptime to a type within this module, e.g:

// Introduce trait into scope.
use readable::up::Uptime;

// Capture the _current_ system uptime,
// and format it into a `Uptime`.
let uptime: Uptime = Uptime::sys_uptime();
std::thread::sleep(std::time::Duration::from_secs(1));
assert!(uptime >= 1);

Only the types within readable::up implement this trait.

§From other Uptime types

All types in this module support lossless conversion with each other using From.

If the type is an unknown variant, that will also be maintained.

// Uptime
let uptime = Uptime::from(86461);
assert_eq!(uptime, "1d, 1m, 1s");

// UptimeFull
let uptime_full = UptimeFull::from(uptime);
assert_eq!(uptime_full, "1 day, 1 minute, 1 second");

// Htop
let htop = Htop::from(uptime_full);
assert_eq!(htop, "1 day, 00:01:01");

// ... wrapping full circle.
let uptime2 = Uptime::from(htop);
assert_eq!(uptime, uptime2);

// Maintain the `unknown` variant.
let unknown = Uptime::UNKNOWN;
assert_eq!(unknown, Uptime::UNKNOWN);
assert_eq!(Htop::from(unknown), Htop::UNKNOWN);

§Naive Uptime

These types naively assume that:

  1. Each day is 86400 seconds
  2. Each month is 31 days
  3. Each year is 365 days

This is incorrect as not all months are 31 days long and leap years exist.

§Formatting

The formatting for Uptime & UptimeFull is:

  • The lowest unit is second
  • The highest is year
  • week is skipped in favor of 7 days

See Htop for its formatting rules.

§Copy

Copy is available.

The actual strings used internally are not String’s, but byte array buffer(s). See the specific type for more details.

The documentation will still refer to the inner buffer as a String. Anything returned will also be a String.

let a = Uptime::from(100_000);

// Copy 'a', use 'b'.
let b = a;
assert_eq!(b, 100_000);

// We can still use 'a'
assert_eq!(a, 100_000);

§Math

These operators are overloaded. They will always output a new Self:

  • Add +
  • Sub -
  • Div /
  • Mul *
  • Rem %

They can either be:

  • Combined with another Self: Uptime::from(1) + Uptime::from(1)
  • Or with the inner number itself: Uptime::from(1) + 1
assert!(Uptime::from(10_u32) + 10 == Uptime::from(20_u32));
assert!(Uptime::from(10_u32) - 10 == Uptime::from(0_u32));
assert!(Uptime::from(10_u32) / 10 == Uptime::from(1_u32));
assert!(Uptime::from(10_u32) * 10 == Uptime::from(100_u32));
assert!(Uptime::from(10_u32) % 10 == Uptime::from(0_u32));

Structs§

Htop
htop-style uptime formatting
Uptime
Human-readable uptime
UptimeFull
Uptime but with full specified words

Traits§

SysUptime
System uptime

Functions§

uptime
Get the current system uptime in seconds