pub struct TimeRange { /* private fields */ }Expand description
A half-open time range [start, end) in a given Timebase.
Represents the extent of a detected event — for example, a fade-out →
fade-in span. When start == end, the range is degenerate (an instant);
see Self::instant.
Both endpoints share the same Timebase. To compare ranges across
different timebases, rescale one of them first (e.g., by calling
Timestamp::rescale_to on each endpoint).
§Equality and ordering
Equality is derived, and so structural: both counts are compared as
written, and only the timebase is compared by value. [1500, 3250) @ 1/1000
therefore equals the same pair over 2/2000 but not [135_000, 292_500)
over 1/90000, though they cover the same stretch of time. Hash agrees
with that equality.
There is no Ord, the posture SignedDuration takes as well.
Ranges have no single order to derive: by start, by end and by length are
three different answers, and overlapping ranges are not ordered at all.
Compare the part you mean — Self::start and Self::end hand back
Timestamps, which are ordered, and by the instant rather than by the
count.
Implementations§
Source§impl TimeRange
impl TimeRange
Sourcepub const fn new(start: i64, end: i64, timebase: Timebase) -> TimeRange
pub const fn new(start: i64, end: i64, timebase: Timebase) -> TimeRange
Creates a new TimeRange with the given start/end PTS and shared timebase.
§Panics
- Panics if
end < start(negative duration).
Sourcepub const fn try_new(
start: i64,
end: i64,
timebase: Timebase,
) -> Option<TimeRange>
pub const fn try_new( start: i64, end: i64, timebase: Timebase, ) -> Option<TimeRange>
Fallible variant of Self::new: returns None if end < start
instead of panicking. Accepts start == end (degenerate instant range).
Sourcepub const fn instant(ts: Timestamp) -> TimeRange
pub const fn instant(ts: Timestamp) -> TimeRange
Creates a degenerate (instant) range where start == end == ts.pts().
Sourcepub const fn with_start(self, val: i64) -> TimeRange
pub const fn with_start(self, val: i64) -> TimeRange
Sets the start PTS.
Sourcepub const fn with_timebase(self, timebase: Timebase) -> TimeRange
pub const fn with_timebase(self, timebase: Timebase) -> TimeRange
Sets the shared timebase.
Sourcepub const fn set_timebase(&mut self, timebase: Timebase) -> &mut TimeRange
pub const fn set_timebase(&mut self, timebase: Timebase) -> &mut TimeRange
Sets the shared timebase in place.
Sourcepub const fn is_instant(&self) -> bool
pub const fn is_instant(&self) -> bool
Returns true if start == end (a degenerate instant range).
Sourcepub const fn total_pts(&self) -> i64
pub const fn total_pts(&self) -> i64
Returns the span in PTS units (end - start) in this timebase.
Always non-negative given the start <= end constructor invariant.
Saturates at i64::MAX in the pathological case where end - start
would overflow i64 (e.g., start = i64::MIN, end = i64::MAX).
Sourcepub const fn duration(&self) -> Duration
pub const fn duration(&self) -> Duration
Returns the elapsed Duration from start to end.
§Panics
Panics if end precedes start, which every constructor refuses and
Self::rescale_to preserves — so this is unreachable for a range
built through the public API. It is reachable through the buffa
decoder, which admits an inverted range from the wire.
Sourcepub const fn rescale_to(self, target: Timebase) -> TimeRange
pub const fn rescale_to(self, target: Timebase) -> TimeRange
Returns a new TimeRange representing the same span in a different timebase.
Rescales both endpoints via Timebase::saturating_rescale, to the
nearest tick of target; round-tripping through a coarser timebase can
lose precision. Because rescaling is monotonic, the start <= end
invariant is preserved.
§Panics
Panics if target.num() == 0, as Timebase::saturating_rescale does.
Sourcepub const fn interpolate(&self, t: f64) -> Timestamp
pub const fn interpolate(&self, t: f64) -> Timestamp
Linearly interpolates between start and end: t = 0.0 returns
start, t = 1.0 returns end, t = 0.5 the midpoint. t is
clamped to [0.0, 1.0]. Rounds toward zero.
Use this to map an old-style bias value b ∈ [-1, 1] onto the range:
range.interpolate((b + 1.0) * 0.5).
Trait Implementations§
Source§impl<'a> Arbitrary<'a> for TimeRange
impl<'a> Arbitrary<'a> for TimeRange
Source§fn arbitrary(u: &mut Unstructured<'a>) -> Result<TimeRange, Error>
fn arbitrary(u: &mut Unstructured<'a>) -> Result<TimeRange, Error>
Self from the given unstructured data. Read moreSource§fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>
fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>
Self from the entirety of the given
unstructured data. Read moreSource§fn size_hint(depth: usize) -> (usize, Option<usize>)
fn size_hint(depth: usize) -> (usize, Option<usize>)
Unstructured this type
needs to construct itself. Read moreSource§fn try_size_hint(
depth: usize,
) -> Result<(usize, Option<usize>), MaxRecursionReached>
fn try_size_hint( depth: usize, ) -> Result<(usize, Option<usize>), MaxRecursionReached>
Unstructured this type
needs to construct itself. Read moreimpl Copy for TimeRange
Source§impl<'de> Deserialize<'de> for TimeRange
impl<'de> Deserialize<'de> for TimeRange
Source§fn deserialize<__D>(
__deserializer: __D,
) -> Result<TimeRange, <__D as Deserializer<'de>>::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(
__deserializer: __D,
) -> Result<TimeRange, <__D as Deserializer<'de>>::Error>where
__D: Deserializer<'de>,
Source§impl Display for TimeRange
Writes both endpoints as clocks inside interval notation:
[0:00:01.500, 0:00:03.250).
impl Display for TimeRange
Writes both endpoints as clocks inside interval notation:
[0:00:01.500, 0:00:03.250).
The mismatched brackets are the point rather than decoration. This type is
half-open — closed at start, open at end — and […) is the notation
that says so, where a dash or an ellipsis would leave a reader to guess
whether end is inside. The rendering therefore teaches the semantics the
type documents.
{:#} prints the raw endpoints and names the shared timebase once,
after both — [1500, 3250) @ 1/1000 — because both endpoints are in one
timebase by construction and repeating it would suggest they need not be.
The derived Debug is exact as well, and {:#} is the form
FromStr reads back.
Each endpoint is rendered by Timestamp’s Display, and inherits its
truncation, its lossiness, and its indifference to width and alignment
flags.
impl Eq for TimeRange
Source§impl FromStr for TimeRange
Parses [start, end) @ num/den — the form TimeRange’s Display
writes under {:#}.
impl FromStr for TimeRange
Parses [start, end) @ num/den — the form TimeRange’s Display
writes under {:#}.
The half-open brackets are required, in that asymmetry, because they are
what the rendering means. Whitespace around each part is trimmed. The
default {} form, a pair of clocks, is not accepted, for the reason
Timestamp’s is not.
§Errors
Returns ParseTimeRangeError if the bracket, comma, or @ is missing,
if an endpoint is not an i64, if the timebase half is not one
Timebase accepts, or if the endpoints run backwards.