Skip to main content

Module macros

deep_time

Module macros 

Source
Expand description

Macros for easy unit conversion and Dt construction.

Each macro expands to a call on an equivalent Dt method.

§Overview

§Unit → attoseconds

Returns total attoseconds as i128.

§Attoseconds → unit

Returns a whole-unit count as i128, or a lossy Real for the _f forms.

§Instant / duration

Returns a Dt.

§Import paths

All macros can be imported from this module:

use deep_time::macros::{from_ns, ms, sec};

These are also available at the crate root via use deep_time::{…}:

The rest are available only under deep_time::macros. use deep_time::macros::* brings in every macro listed above.

§How they work

  • Attosecond storage unit. Forward converters such as ms! and sec! return total attoseconds as i128. Reverse converters such as as_ms! and as_sec! take total attoseconds and return a count in the named unit.
  • Truncation toward zero. Integer reverse converters use ordinary i128 division (attos / unit). Any leftover below one whole unit is dropped, and the result moves toward zero—not toward −∞. For example, −0.5 s as whole seconds is 0, and −1.5 s is -1. The floating reverse converters (as_sec_f!, as_days_f!) are lossy Real casts instead.
  • Signed remainders on constructors. Macros such as from_sec! and from_ns! accept an optional fractional remainder in attoseconds. Both signs of the remainder are valid; the total is whole × unit + frac (with saturating arithmetic on the underlying method). The same total can often be written with a signed remainder or as a floor-style split with a non-negative remainder.
  • Scale labels vs conversion. Most from_* macros only set the returned Dt’s scale / target fields; they do not convert the attosecond count between time scales. from_ymd!, from_jd!, from_jd_f!, from_mjd!, and from_mjd_f! are the exceptions: they build a Dt on TAI (converting from the on= scale when needed) and set target from on=, as documented on each macro.
  • const contexts. Expansions call const methods on Dt, so these macros work in const contexts where the underlying method does.

§Examples

use deep_time::{Dt, Scale, dt, from_ymd, ms, ns};
use deep_time::macros::{as_sec, from_sec, sec};

// Unit helpers avoid hand-counting zeros in attosecond literals.
assert_eq!(ms!(300), Dt::ms_to_attos(300));
assert_eq!(ns!(1), 1_000_000_000);

// Whole seconds + sub-second remainder (remainder is attoseconds).
let a = from_sec!(1, ms!(300));
assert_eq!(a, dt!(1_300_000_000_000_000_000));

// Reverse conversion truncates toward zero.
assert_eq!(as_sec!(sec!(1) + ms!(900)), 1);
assert_eq!(as_sec!(-ms!(500)), 0);
assert_eq!(as_sec!(-sec!(1) - ms!(500)), -1);

// Calendar construction: builds a Dt, converting civil time to TAI.
assert_eq!(from_ymd!(2000, 1, 1; 12, on=Scale::TAI), Dt::ZERO);

See each macro’s own documentation for accepted forms, defaults, and links to the corresponding Dt methods.

Macros§

as_days
Converts total attoseconds (i128) → whole days (i128).
as_days_f
Converts total attoseconds (i128) → lossy float days (Real).
as_fs
Converts total attoseconds (i128) → whole femtoseconds (i128).
as_hours
Converts total attoseconds (i128) → whole hours (i128).
as_mins
Converts total attoseconds (i128) → whole minutes (i128).
as_ms
Converts total attoseconds (i128) → whole milliseconds (i128).
as_ns
Converts total attoseconds (i128) → whole nanoseconds (i128).
as_ps
Converts total attoseconds (i128) → whole picoseconds (i128).
as_sec
Converts total attoseconds (i128) → whole seconds (i128).
as_sec_f
Converts total attoseconds (i128) → lossy float seconds (Real).
as_us
Converts total attoseconds (i128) → whole microseconds (i128).
as_weeks
Converts total attoseconds (i128) → whole weeks (i128).
days
Converts whole days (i128) to total attoseconds (i128).
days_f
Converts a floating-point day count (Real) to total attoseconds (i128).
dt
Builds a Dt from total attoseconds with optional scale labels.
from_days_f
Builds a Dt from a floating-point day count with optional scale labels.
from_fs
Builds a Dt from whole femtoseconds and an optional signed fractional remainder in attoseconds.
from_jd
Builds a TAI Dt from a Julian Date (whole days plus optional attosecond remainder).
from_jd_f
Builds a TAI Dt from a floating-point Julian Date.
from_mjd
Builds a TAI Dt from a Modified Julian Date (whole days plus optional attosecond remainder).
from_mjd_f
Builds a TAI Dt from a floating-point Modified Julian Date.
from_ms
Builds a Dt from whole milliseconds and an optional signed fractional remainder in attoseconds.
from_ns
Builds a Dt from whole nanoseconds and an optional signed fractional remainder in attoseconds.
from_ps
Builds a Dt from whole picoseconds and an optional signed fractional remainder in attoseconds.
from_sec
Builds a Dt from whole seconds and an optional signed sub-second remainder (attoseconds).
from_sec_f
Builds a Dt from a floating-point seconds count with optional scale labels.
from_us
Builds a Dt from whole microseconds and an optional signed fractional remainder in attoseconds.
from_ymd
Builds a Dt from a Gregorian calendar date and optional time.
fs
Converts whole femtoseconds (i128) to total attoseconds (i128).
hours
Converts whole hours (i128) to total attoseconds (i128).
mins
Converts whole minutes (i128) to total attoseconds (i128).
ms
Converts whole milliseconds (i128) to total attoseconds (i128).
ns
Converts whole nanoseconds (i128) to total attoseconds (i128).
ps
Converts whole picoseconds (i128) to total attoseconds (i128).
sec
Converts whole seconds (i128) to total attoseconds (i128).
sec_f
Converts a floating-point second count (Real) to total attoseconds (i128).
us
Converts whole microseconds (i128) to total attoseconds (i128).
weeks
Converts whole weeks (i128) to total attoseconds (i128).