Struct Timestamp 

pub struct Timestamp { /* private fields */ }

A timestamp in a track’s timescale (units per second).

All timestamps within a track are relative, so zero for one track is not zero for another. The underlying value is constrained to fit within a QUIC VarInt (2^62 - 1) so it can be encoded and decoded easily; the scale is carried alongside so frames from different sources can be compared and converted without lossy detours through a single fixed scale.

The scale is a Timescale (always non-zero), so unit conversions (as_secs, as_millis, etc.) are infallible. Use Option<Timestamp> at call sites that need a “missing” sentinel instead of relying on a magic value.

An instant, not a number

A Timestamp is a point in time (like std::time::Instant), not a scalar, so it has no arithmetic operators: adding two instants is meaningless, and a scale mismatch can’t be a silent panic. Use Self::checked_add / Self::checked_sub, which require both operands to share a scale and return TimeOverflow otherwise. To combine timestamps from different scales, Self::convert one to the other’s scale first.

Equality vs ordering

These two intentionally disagree, so pick the one you mean:

• Eq / Hash are structural (field-wise): from_secs(1) != from_millis(1000), because they encode as different (value, scale) pairs on the wire. Two timestamps are equal only when both their value and scale match.
• Ord is temporal: it cross-multiplies scales, so from_millis(1000) orders after from_millis(999) and from_secs(1) slots in between. When a cross-scale comparison is otherwise a tie, it breaks by (scale, value) to stay consistent with Eq.

So from_secs(1).cmp(&from_millis(1000)) is not Equal, and neither is == true. If you want “same instant regardless of encoding”, compare after a Self::convert to a common scale.

Implementations

impl Timestamp

pub const ZERO: Self

The zero timestamp: value 0 at Timescale::SECOND.

The scale is not incidental. Equality and ordering are scale-aware (see the type docs), so this is not interchangeable with 0 at another scale; use Self::is_zero to test a zero value regardless of scale. In particular, don’t seed a .max() accumulator with this: a later value at a finer scale would lose the tie-break. Reach for Option<Timestamp> instead.

pub const fn new(value: u64, scale: Timescale) -> Result<Self, TimeOverflow>

Construct a timestamp directly from a raw value at the given scale. Returns TimeOverflow if value exceeds 2^62 - 1.

pub const fn new_const(value: u64, scale: Timescale) -> Self

Const-context twin of Self::new that panics on overflow.

For building const timestamps where ?/unwrap on the Result isn’t available. The panic fires only on a compile-time-known out-of-range literal, so it’s a build-time assertion, not a runtime failure path. Use Self::new everywhere else.

pub fn from_scale( value: u64, units_per_second: u64, ) -> Result<Self, TimeOverflow>

Construct a timestamp from a raw value and a units_per_second scale. Returns TimeOverflow if the scale is zero or the value is out of range.

pub const fn from_secs(seconds: u64) -> Result<Self, TimeOverflow>

Convert a number of seconds to a timestamp at Timescale::SECOND.

pub const fn from_millis(millis: u64) -> Result<Self, TimeOverflow>

Convert a number of milliseconds to a timestamp at Timescale::MILLI.

pub const fn from_micros(micros: u64) -> Result<Self, TimeOverflow>

Convert a number of microseconds to a timestamp at Timescale::MICRO.

pub const fn from_nanos(nanos: u64) -> Result<Self, TimeOverflow>

Convert a number of nanoseconds to a timestamp at Timescale::NANO.

pub const fn value(self) -> u64

The raw value in the timestamp’s own scale.

pub const fn scale(self) -> Timescale

The scale (units per second) attached to this timestamp.

pub const fn is_zero(self) -> bool

Whether the raw value is zero. Does not consider scale.

pub const fn convert(self, new_scale: Timescale) -> Result<Self, TimeOverflow>

Re-express this timestamp at a new scale. Returns TimeOverflow if the new value would exceed 2^62 - 1.

pub const fn as_scale(self, target: Timescale) -> u128

The value re-expressed at target as a u128.

pub const fn as_secs(self) -> u64

The value re-expressed in seconds.

pub const fn as_millis(self) -> u128

The value re-expressed in milliseconds.

pub const fn as_micros(self) -> u128

The value re-expressed in microseconds.

pub const fn as_nanos(self) -> u128

The value re-expressed in nanoseconds.

pub const fn checked_add(self, rhs: Self) -> Result<Self, TimeOverflow>

Add two timestamps. Returns TimeOverflow if the sum exceeds 2^62 - 1 or if the scales differ.

pub const fn checked_sub(self, rhs: Self) -> Result<Self, TimeOverflow>

Subtract rhs from self. Returns TimeOverflow if rhs > self or if the scales differ.

pub fn now() -> Self

Current point on the local monotonic clock, expressed in the default timescale (Timescale::MILLI).

This is the one-way bridge from a local clock to a track timestamp: there is deliberately no inverse (a Timestamp is relative and jittered, never a clock). Used to stamp frames that arrive without one, e.g. on protocols whose wire can’t carry a timestamp. Uses web_async::time::Instant::now so it works on wasm and honors tokio::time::pause in tests.

Trait Implementations

impl Clone for Timestamp

fn clone(&self) -> Timestamp

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Timestamp

impl Debug for Timestamp

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Timestamp

impl From<Instant> for Timestamp

fn from(instant: Instant) -> Self

Convert an std::time::Instant into a millisecond-scale timestamp (the default timescale), anchored at 2020-01-01 plus a per-process jitter (see TIME_ANCHOR).

One-way only: there is no inverse, since the anchor is jittered to keep a Timestamp from being read back as a clock.

impl From<Timestamp> for Duration

fn from(time: Timestamp) -> Self

Converts to this type from the input type.

impl Hash for Timestamp

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Timestamp

fn cmp(&self, other: &Self) -> Ordering

Temporal comparison, normalizing across scales (see the type-level docs for how this relates to structural Eq).

• Equal scales compare raw values directly.
• Otherwise cross-multiplies in 128-bit so e.g. 1s > 2ms orders correctly.
• A would-be cross-scale tie (e.g. from_secs(1) vs from_millis(1000)) breaks by (scale, value), keeping Ord consistent with the field-wise Eq/Hash.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Timestamp

fn eq(&self, other: &Timestamp) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for Timestamp

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralPartialEq for Timestamp

impl TryFrom<Duration> for Timestamp

fn try_from(duration: Duration) -> Result<Self, Self::Error>

Convert a std::time::Duration into a nanosecond-scale timestamp.

type Error = TimeOverflow

The type returned in the event of a conversion error.