1// Take a look at the license at the top of the repository in the LICENSE file.
2
3// rustdoc-stripper-ignore-next
4//! This modules gathers GStreamer's formatted value concepts together.
5//!
6//! GStreamer uses formatted values to differentiate value units in some APIs.
7//! In C this is done by qualifying an integer value by a companion enum
8//! [`GstFormat`]. In Rust, most APIs can use a specific type for each format.
9//! Each format type embeds the actual value using the new type pattern.
10//!
11//! # Specific Formatted Values
12//!
13//! Examples of specific formatted values include [`ClockTime`], [`Buffers`], etc.
14//! These types represent both the quantity and the unit making it possible for Rust
15//! to perform runtime and, to a certain extent, compile time invariants enforcement.
16//!
17//! Specific formatted values are also guaranteed to always represent a valid value.
18//! For instance:
19//!
20//! - [`Percent`] only allows values in the integer range [0, 1_000_000] or
21//! float range [0.0, 1.0].
22//! - [`ClockTime`] can use all `u64` values except `u64::MAX` which is reserved by
23//! the C constant `GST_CLOCK_TIME_NONE`.
24//!
25//! ## Examples
26//!
27//! ### Querying the pipeline for a time position
28//!
29//! ```
30//! # use gstreamer as gst;
31//! # use gst::prelude::ElementExtManual;
32//! # gst::init();
33//! # let pipeline = gst::Pipeline::new();
34//! let res = pipeline.query_position::<gst::ClockTime>();
35//! ```
36//!
37//! ## Seeking to a specific time position
38//!
39//! ```
40//! # use gstreamer as gst;
41//! # use gst::{format::prelude::*, prelude::ElementExtManual};
42//! # gst::init();
43//! # let pipeline = gst::Pipeline::new();
44//! # let seek_flags = gst::SeekFlags::FLUSH | gst::SeekFlags::KEY_UNIT;
45//! let seek_pos = gst::ClockTime::from_seconds(10);
46//! let res = pipeline.seek_simple(seek_flags, seek_pos);
47//! ```
48//!
49//! ### Downcasting a `Segment` for specific formatted value use
50//!
51//! ```
52//! # use gstreamer as gst;
53//! # use gst::format::FormattedValue;
54//! # gst::init();
55//! # let segment = gst::FormattedSegment::<gst::ClockTime>::new().upcast();
56//! // Downcasting the generic `segment` for `gst::ClockTime` use.
57//! let time_segment = segment.downcast_ref::<gst::ClockTime>().expect("time segment");
58//! // Setters and getters conform to `gst::ClockTime`.
59//! // This is enforced at compilation time.
60//! let start = time_segment.start();
61//! assert_eq!(start.format(), gst::Format::Time);
62//! ```
63//!
64//! ### Building a specific formatted value
65//!
66//! ```
67//! # use gstreamer as gst;
68//! use gst::prelude::*;
69//! use gst::format::{Buffers, Bytes, ClockTime, Default, Percent};
70//!
71//! // Specific formatted values implement the faillible `try_from` constructor:
72//! let default = Default::try_from(42).unwrap();
73//! assert_eq!(*default, 42);
74//! assert_eq!(Default::try_from(42), Ok(default));
75//! assert_eq!(Default::try_from(42).ok(), Some(default));
76//!
77//! // `ClockTime` provides specific `const` constructors,
78//! // which can panic if the requested value is out of range.
79//! let time = ClockTime::from_nseconds(45_834_908_569_837);
80//! let time = ClockTime::from_seconds(20);
81//!
82//! // Other formatted values also come with (panicking) `const` constructors:
83//! let buffers_nb = Buffers::from_u64(512);
84//! let received = Bytes::from_u64(64);
85//! let quantity = Default::from_u64(42);
86//!
87//! // `Bytes` can be built from an `usize` too (not `const`):
88//! let sample_size = Bytes::from_usize([0u8; 4].len());
89//!
90//! // This can be convenient (not `const`):
91//! assert_eq!(
92//! 7.seconds() + 250.mseconds(),
93//! ClockTime::from_nseconds(7_250_000_000),
94//! );
95//!
96//! // Those too (not `const`):
97//! assert_eq!(512.buffers(), Buffers::from_u64(512));
98//! assert_eq!(64.bytes(), Bytes::from_u64(64));
99//! assert_eq!(42.default_format(), Default::from_u64(42));
100//!
101//! // The `ZERO` and `NONE` constants can come in handy sometimes:
102//! assert_eq!(*Buffers::ZERO, 0);
103//! assert!(ClockTime::NONE.is_none());
104//!
105//! // Specific formatted values provide the constant `ONE` value:
106//! assert_eq!(*Buffers::ONE, 1);
107//!
108//! // `Bytes` also comes with usual multipliers (not `const`):
109//! assert_eq!(*(512.kibibytes()), 512 * 1024);
110//! assert_eq!(*(8.mebibytes()), 8 * 1024 * 1024);
111//! assert_eq!(*(4.gibibytes()), 4 * 1024 * 1024 * 1024);
112//!
113//! // ... and the matching constants:
114//! assert_eq!(512 * Bytes::KiB, 512.kibibytes());
115//!
116//! // `Percent` can be built from a percent integer value:
117//! let a_quarter = 25.percent();
118//! // ... from a floating point ratio:
119//! let a_quarter_from_ratio = 0.25.percent_ratio();
120//! assert_eq!(a_quarter, a_quarter_from_ratio);
121//! // ... from a part per million integer value:
122//! let a_quarter_from_ppm = (25 * 10_000).ppm();
123//! assert_eq!(a_quarter, a_quarter_from_ppm);
124//! // ... `MAX` which represents 100%:
125//! assert_eq!(Percent::MAX / 4, a_quarter);
126//! // ... `ONE` which is 1%:
127//! assert_eq!(25 * Percent::ONE, a_quarter);
128//! // ... and `SCALE` which is 1% in ppm:
129//! assert_eq!(Percent::SCALE, 10_000.ppm());
130//! ```
131//!
132//! ### Displaying a formatted value
133//!
134//! Formatted values implement the [`Display`] trait which allows getting
135//! human readable representations.
136//!
137//! ```
138//! # use gstreamer as gst;
139//! # use gst::prelude::*;
140//! let time = 45_834_908_569_837.nseconds();
141//!
142//! assert_eq!(format!("{time}"), "12:43:54.908569837");
143//! assert_eq!(format!("{time:.0}"), "12:43:54");
144//!
145//! let percent = 0.1234.percent_ratio();
146//! assert_eq!(format!("{percent}"), "12.34 %");
147//! assert_eq!(format!("{percent:5.1}"), " 12.3 %");
148//! ```
149//!
150//! ## Some operations available on specific formatted values
151//!
152//! ```
153//! # use gstreamer as gst;
154//! # use gst::prelude::*;
155//! let cur_pos = gst::ClockTime::ZERO;
156//!
157//! // All four arithmetic operations can be used:
158//! let fwd = cur_pos + 2.seconds() / 3 - 5.mseconds();
159//!
160//! // Examples of operations which make sure not to overflow:
161//! let bwd = cur_pos.saturating_sub(2.seconds());
162//! let further = cur_pos.checked_mul(2).expect("Overflowed");
163//!
164//! // Specific formatted values can be compared:
165//! assert!(fwd > bwd);
166//! assert_ne!(fwd, cur_pos);
167//!
168//! # fn next() -> gst::ClockTime { gst::ClockTime::ZERO };
169//! // Use `gst::ClockTime::MAX` for the maximum valid value:
170//! let mut min_pos = gst::ClockTime::MAX;
171//! for _ in 0..4 {
172//! min_pos = min_pos.min(next());
173//! }
174//!
175//! // And `gst::ClockTime::ZERO` for the minimum value:
176//! let mut max_pos = gst::ClockTime::ZERO;
177//! for _ in 0..4 {
178//! max_pos = max_pos.max(next());
179//! }
180//!
181//! // Specific formatted values implement the `MulDiv` trait:
182//! # use gst::prelude::MulDiv;
183//! # let (samples, rate) = (1024u64, 48_000u64);
184//! let duration = samples
185//! .mul_div_round(*gst::ClockTime::SECOND, rate)
186//! .map(gst::ClockTime::from_nseconds);
187//! ```
188//!
189//! ## Types in operations
190//!
191//! Additions and substractions are available with the specific formatted value type
192//! as both left and right hand side operands.
193//!
194//! On the other hand, multiplications are only available with plain integers.
195//! This is because multiplying a `ClockTime` by a `ClockTime` would result in
196//! `ClockTime²`, whereas a `u64 * ClockTime` (or `ClockTime * u64`) still
197//! results in `ClockTime`.
198//!
199//! Divisions are available with both the specific formatted value and plain
200//! integers as right hand side operands. The difference is that
201//! `ClockTime / ClockTime` results in `u64` and `ClockTime / u64` results in
202//! `ClockTime`.
203//!
204//! # Optional specific formatted values
205//!
206//! Optional specific formatted values are represented as a standard Rust
207//! `Option<F>`. This departs from the C APIs which use a sentinel that must
208//! be checked in order to figure out whether the value is defined.
209//!
210//! Besides giving access to the usual `Option` features, this ensures the APIs
211//! enforce mandatory or optional variants whenever possible.
212//!
213//! Note: for each specific formatted value `F`, the constant `F::NONE` is defined
214//! as a shortcut for `Option::<F>::None`. For `gst::ClockTime`, this constant is
215//! equivalent to the C constant `GST_CLOCK_TIME_NONE`.
216//!
217//! ## Examples
218//!
219//! ### Building a seek `Event` with undefined `stop` time
220//!
221//! ```
222//! # use gstreamer as gst;
223//! # use gst::format::prelude::*;
224//! # gst::init();
225//! # let seek_flags = gst::SeekFlags::FLUSH | gst::SeekFlags::KEY_UNIT;
226//! let seek_evt = gst::event::Seek::new(
227//! 1.0f64,
228//! seek_flags,
229//! gst::SeekType::Set,
230//! 10.seconds(), // start at 10s
231//! gst::SeekType::Set,
232//! gst::ClockTime::NONE, // stop is undefined
233//! );
234//! ```
235//!
236//! ### Displaying an optional formatted value
237//!
238//! Optional formatted values can take advantage of the [`Display`] implementation
239//! of the base specific formatted value. We have to workaround the [orphan rule]
240//! that forbids the implementation of [`Display`] for `Option<FormattedValue>`
241//! though. This is why displaying an optional formatted value necessitates calling
242//! [`display()`].
243//!
244//! ```
245//! # use gstreamer as gst;
246//! # use gst::prelude::*;
247//! let opt_time = Some(45_834_908_569_837.nseconds());
248//!
249//! assert_eq!(format!("{}", opt_time.display()), "12:43:54.908569837");
250//! assert_eq!(format!("{:.0}", opt_time.display()), "12:43:54");
251//! assert_eq!(format!("{:.0}", gst::ClockTime::NONE.display()), "--:--:--");
252//! ```
253//!
254//! ### Some operations available on optional formatted values
255//!
256//! ```
257//! # use gstreamer as gst;
258//! # use gst::prelude::*;
259//! let pts = Some(gst::ClockTime::ZERO);
260//! assert!(pts.is_some());
261//!
262//! // All four arithmetic operations can be used. Ex.:
263//! let fwd = pts.opt_add(2.seconds());
264//! // `pts` is defined, so `fwd` will contain the addition result in `Some`,
265//! assert!(fwd.is_some());
266//! // otherwise `fwd` would be `None`.
267//!
268//! // Examples of operations which make sure not to overflow:
269//! let bwd = pts.opt_saturating_sub(2.seconds());
270//! let further = pts.opt_checked_mul(2).expect("Overflowed");
271//!
272//! // Optional specific formatted values can be compared:
273//! assert_eq!(fwd.opt_gt(bwd), Some(true));
274//! assert_ne!(fwd, pts);
275//! assert_eq!(fwd.opt_min(bwd), bwd);
276//!
277//! // Optional specific formatted values operations also apply to non-optional values:
278//! assert_eq!(fwd.opt_lt(gst::ClockTime::SECOND), Some(false));
279//! assert_eq!(gst::ClockTime::SECOND.opt_lt(fwd), Some(true));
280//!
281//! // Comparing a defined values to an undefined value results in `None`:
282//! assert_eq!(bwd.opt_gt(gst::ClockTime::NONE), None);
283//! assert_eq!(gst::ClockTime::ZERO.opt_lt(gst::ClockTime::NONE), None);
284//! ```
285//!
286//! # Signed formatted values
287//!
288//! Some APIs can return a signed formatted value. See [`Segment::to_running_time_full`]
289//! for an example. In Rust, we use the [`Signed`] enum wrapper around the actual
290//! formatted value.
291//!
292//! For each signed specific formatted value `F`, the constants `F::MIN_SIGNED` and
293//! `F::MAX_SIGNED` represent the minimum and maximum signed values for `F`.
294//!
295//! ## Examples
296//!
297//! ### Handling a signed formatted value
298//!
299//! ```
300//! # use gstreamer as gst;
301//! # use gst::prelude::*;
302//! # gst::init();
303//! # let segment = gst::FormattedSegment::<gst::ClockTime>::new();
304//! use gst::Signed::*;
305//! match segment.to_running_time_full(2.seconds()) {
306//! Some(Positive(pos_rtime)) => println!("positive rtime {pos_rtime}"),
307//! Some(Negative(neg_rtime)) => println!("negative rtime {neg_rtime}"),
308//! None => println!("undefined rtime"),
309//! }
310//! ```
311//!
312//! ### Converting a formatted value into a signed formatted value
313//!
314//! ```
315//! # use gstreamer as gst;
316//! # use gst::prelude::*;
317//! let step = 10.mseconds();
318//!
319//! let positive_step = step.into_positive();
320//! assert!(positive_step.is_positive());
321//!
322//! let negative_step = step.into_negative();
323//! assert!(negative_step.is_negative());
324//! ```
325//!
326//! ### Handling one sign only
327//!
328//! ```
329//! # use gstreamer as gst;
330//! # use gst::prelude::*;
331//! # struct NegativeError;
332//! let pos_step = 10.mseconds().into_positive();
333//! assert!(pos_step.is_positive());
334//!
335//! let abs_step_or_panic = pos_step.positive().expect("positive");
336//! let abs_step_or_zero = pos_step.positive().unwrap_or(gst::ClockTime::ZERO);
337//!
338//! let abs_step_or_err = pos_step.positive_or(NegativeError);
339//! let abs_step_or_else_err = pos_step.positive_or_else(|step| {
340//! println!("{step} is negative");
341//! NegativeError
342//! });
343//! ```
344//!
345//! ### Displaying a signed formatted value
346//!
347//! ```
348//! # use gstreamer as gst;
349//! # use gst::prelude::*;
350//! # gst::init();
351//! # let mut segment = gst::FormattedSegment::<gst::ClockTime>::new();
352//! # segment.set_start(10.seconds());
353//! let start = segment.start().unwrap();
354//! assert_eq!(format!("{start:.0}"), "0:00:10");
355//!
356//! let p_rtime = segment.to_running_time_full(20.seconds());
357//! // Use `display()` with optional signed values.
358//! assert_eq!(format!("{:.0}", p_rtime.display()), "+0:00:10");
359//!
360//! let p_rtime = segment.to_running_time_full(gst::ClockTime::ZERO);
361//! assert_eq!(format!("{:.0}", p_rtime.display()), "-0:00:10");
362//!
363//! let p_rtime = segment.to_running_time_full(gst::ClockTime::NONE);
364//! assert_eq!(format!("{:.0}", p_rtime.display()), "--:--:--");
365//! ```
366//!
367//! ## Some operations available for signed formatted values
368//!
369//! All the operations available for formatted values can be used with
370//! signed formatted values.
371//!
372//! ```
373//! # use gstreamer as gst;
374//! # use gst::prelude::*;
375//! let p_one_sec = gst::ClockTime::SECOND.into_positive();
376//! let p_two_sec = 2.seconds().into_positive();
377//! let n_one_sec = gst::ClockTime::SECOND.into_negative();
378//!
379//! assert_eq!(p_one_sec + p_one_sec, p_two_sec);
380//! assert_eq!(p_two_sec - p_one_sec, p_one_sec);
381//! assert_eq!(gst::ClockTime::ZERO - p_one_sec, n_one_sec);
382//! assert_eq!(p_one_sec * 2u64, p_two_sec);
383//! assert_eq!(n_one_sec * -1i64, p_one_sec);
384//! assert_eq!(p_two_sec / 2u64, p_one_sec);
385//! assert_eq!(p_two_sec / p_one_sec, 2);
386//!
387//! // Examples of operations which make sure not to overflow:
388//! assert_eq!(p_one_sec.saturating_sub(p_two_sec), n_one_sec);
389//! assert_eq!(p_one_sec.checked_mul(2), Some(p_two_sec));
390//!
391//! // Signed formatted values can be compared:
392//! assert!(p_one_sec > n_one_sec);
393//!
394//! # fn next() -> gst::Signed<gst::ClockTime> { gst::ClockTime::ZERO.into_positive() };
395//! // Use `gst::ClockTime::MAX_SIGNED` for the maximum valid signed value:
396//! let mut min_signed_pos = gst::ClockTime::MAX_SIGNED;
397//! for _ in 0..4 {
398//! min_signed_pos = min_signed_pos.min(next());
399//! }
400//!
401//! // And `gst::ClockTime::MIN_SIGNED` for the minimum valid signed value:
402//! let mut max_signed_pos = gst::ClockTime::MIN_SIGNED;
403//! for _ in 0..4 {
404//! max_signed_pos = max_signed_pos.max(next());
405//! }
406//!
407//! // Signed formatted values implement the `MulDiv` trait:
408//! # use gst::prelude::*;
409//! # let rate = 48_000u64;
410//! let samples = 1024.default_format().into_negative();
411//! let duration = samples
412//! .mul_div_round(*gst::ClockTime::SECOND, rate)
413//! .map(|signed_default| {
414//! let signed_u64 = signed_default.into_inner_signed();
415//! gst::Signed::<gst::ClockTime>::from_nseconds(signed_u64)
416//! })
417//! .unwrap();
418//! assert!(duration.is_negative());
419//! ```
420//!
421//! ### Some operations available for optional signed formatted values
422//!
423//! All the operations available for optional formatted values can be used
424//! with signed formatted values.
425//!
426//! ```
427//! # use gstreamer as gst;
428//! # use gst::prelude::*;
429//! let p_one_sec = 1.seconds().into_positive();
430//! let p_two_sec = 2.seconds().into_positive();
431//! let n_one_sec = 1.seconds().into_negative();
432//!
433//! // Signed `ClockTime` addition with optional and non-optional operands.
434//! assert_eq!(Some(p_one_sec).opt_add(p_one_sec), Some(p_two_sec));
435//! assert_eq!(p_two_sec.opt_add(Some(n_one_sec)), Some(p_one_sec));
436//!
437//! // This can also be used with unsigned formatted values.
438//! assert_eq!(Some(p_one_sec).opt_add(gst::ClockTime::SECOND), Some(p_two_sec));
439//!
440//! // Etc...
441//! ```
442//!
443//! # Generic Formatted Values
444//!
445//! Sometimes, generic code can't assume a specific format will be used. For such
446//! use cases, the [`GenericFormattedValue`] enum makes it possible to select
447//! the appropriate behaviour at runtime.
448//!
449//! Most variants embed an optional specific formatted value.
450//!
451//! ## Example
452//!
453//! ### Generic handling of the position from a `SegmentDone` event
454//!
455//! ```
456//! # use gstreamer as gst;
457//! # use gst::prelude::*;
458//! # gst::init();
459//! # let event = gst::event::SegmentDone::new(512.buffers());
460//! if let gst::EventView::SegmentDone(seg_done_evt) = event.view() {
461//! use gst::GenericFormattedValue::*;
462//! match seg_done_evt.get() {
463//! Buffers(buffers) => println!("Segment done @ {}", buffers.display()),
464//! Bytes(bytes) => println!("Segment done @ {}", bytes.display()),
465//! Time(time) => println!("Segment done @ {}", time.display()),
466//! other => println!("Unexpected format for Segment done position {other:?}"),
467//! }
468//! }
469//! ```
470//!
471//! [`GstFormat`]: https://gstreamer.freedesktop.org/documentation/gstreamer/gstformat.html?gi-language=c
472//! [`ClockTime`]: struct.ClockTime.html
473//! [`Buffers`]: struct.Buffers.html
474//! [`Percent`]: struct.Percent.html
475//! [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html
476//! [`display()`]: ../prelude/trait.Displayable.html
477//! [orphan rule]: https://doc.rust-lang.org/book/ch10-02-traits.html?highlight=orphan#implementing-a-trait-on-a-type
478//! [`Segment::to_running_time_full`]: ../struct.FormattedSegment.html#method.to_running_time_full
479//! [`Signed`]: enum.Signed.html
480//! [`GenericFormattedValue`]: generic/enum.GenericFormattedValue.html
481
482use thiserror::Error;
483
484#[macro_use]
485mod macros;
486
487mod clock_time;
488pub use clock_time::*;
489#[cfg(feature = "serde")]
490mod clock_time_serde;
491
492mod compatible;
493pub use compatible::*;
494
495#[cfg(feature = "serde")]
496mod format_serde;
497
498mod generic;
499pub use generic::*;
500
501mod signed;
502pub use signed::*;
503
504mod specific;
505pub use specific::*;
506
507mod undefined;
508pub use undefined::*;
509
510pub mod prelude {
511 pub use super::{
512 BuffersFormatConstructor, BytesFormatConstructor, DefaultFormatConstructor, FormattedValue,
513 FormattedValueNoneBuilder, NoneSignedBuilder, OtherFormatConstructor,
514 PercentFormatFloatConstructor, PercentFormatIntegerConstructor, TimeFormatConstructor,
515 UndefinedFormatConstructor, UnsignedIntoSigned,
516 };
517}
518
519use crate::Format;
520
521#[derive(Clone, Copy, Debug, PartialEq, Eq, Error)]
522#[error("invalid formatted value format {:?}", .0)]
523pub struct FormattedValueError(Format);
524
525pub trait FormattedValue: Copy + Clone + Sized + Into<GenericFormattedValue> + 'static {
526 // rustdoc-stripper-ignore-next
527 /// Type which allows building a `FormattedValue` of this format from any raw value.
528 type FullRange: FormattedValueFullRange + From<Self>;
529
530 #[doc(alias = "get_default_format")]
531 fn default_format() -> Format;
532
533 #[doc(alias = "get_format")]
534 fn format(&self) -> Format;
535
536 // rustdoc-stripper-ignore-next
537 /// Returns `true` if this `FormattedValue` represents a defined value.
538 fn is_some(&self) -> bool;
539
540 // rustdoc-stripper-ignore-next
541 /// Returns `true` if this `FormattedValue` represents an undefined value.
542 fn is_none(&self) -> bool {
543 !self.is_some()
544 }
545
546 unsafe fn into_raw_value(self) -> i64;
547}
548
549// rustdoc-stripper-ignore-next
550/// A [`FormattedValue`] which can be built from any raw value.
551///
552/// # Examples:
553///
554/// - `GenericFormattedValue` is the `FormattedValueFullRange` type for `GenericFormattedValue`.
555/// - `Undefined` is the `FormattedValueFullRange` type for `Undefined`.
556/// - `Option<Percent>` is the `FormattedValueFullRange` type for `Percent`.
557pub trait FormattedValueFullRange: FormattedValue + TryFrom<GenericFormattedValue> {
558 unsafe fn from_raw(format: Format, value: i64) -> Self;
559}
560
561// rustdoc-stripper-ignore-next
562/// A trait implemented on the intrinsic type of a `FormattedValue`.
563///
564/// # Examples
565///
566/// - `GenericFormattedValue` is the intrinsic type for `GenericFormattedValue`.
567/// - `Undefined` is the intrinsic type for `Undefined`.
568/// - `Bytes` is the intrinsic type for `Option<Bytes>`.
569pub trait FormattedValueIntrinsic: FormattedValue {}
570
571pub trait FormattedValueNoneBuilder: FormattedValueFullRange {
572 // rustdoc-stripper-ignore-next
573 /// Returns the `None` value for `Self` as a `FullRange` if such a value can be represented.
574 ///
575 /// - For `SpecificFormattedValue`s, this results in `Option::<FormattedValueIntrinsic>::None`.
576 /// - For `GenericFormattedValue`, this can only be obtained using [`Self::none_for_format`]
577 /// because the `None` is an inner value of some of the variants.
578 ///
579 /// # Panics
580 ///
581 /// Panics if `Self` is `GenericFormattedValue` in which case, the `Format` must be known.
582 fn none() -> Self;
583
584 // rustdoc-stripper-ignore-next
585 /// Returns the `None` value for `Self` if such a value can be represented.
586 ///
587 /// - For `SpecificFormattedValue`s, this is the same as `Self::none()`
588 /// if the `format` matches the `SpecificFormattedValue`'s format.
589 /// - For `GenericFormattedValue` this is the variant for the specified `format`,
590 /// initialized with `None` as a value, if the `format` can represent that value.
591 ///
592 /// # Panics
593 ///
594 /// Panics if `None` can't be represented by `Self` for `format` or by the requested
595 /// `GenericFormattedValue` variant.
596 #[track_caller]
597 #[inline]
598 fn none_for_format(format: Format) -> Self {
599 skip_assert_initialized!();
600 // This is the default impl. `GenericFormattedValue` must override.
601 if Self::default_format() != format {
602 panic!(
603 "Expected: {:?}, requested {format:?}",
604 Self::default_format()
605 );
606 }
607
608 Self::none()
609 }
610}
611
612use std::fmt;
613impl fmt::Display for Format {
614 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
615 match self {
616 Self::Undefined => f.write_str(data:"undefined"),
617 Self::Default => f.write_str(data:"default"),
618 Self::Bytes => f.write_str(data:"bytes"),
619 Self::Time => f.write_str(data:"time"),
620 Self::Buffers => f.write_str(data:"buffers"),
621 Self::Percent => f.write_str(data:"%"),
622 Self::__Unknown(format: &i32) => write!(f, "(format: {format})"),
623 }
624 }
625}
626
627#[cfg(test)]
628mod tests {
629 use super::*;
630 use crate::utils::Displayable;
631
632 fn with_compatible_formats<V1, V2>(
633 arg1: V1,
634 arg2: V2,
635 ) -> Result<V2::Original, FormattedValueError>
636 where
637 V1: FormattedValue,
638 V2: CompatibleFormattedValue<V1>,
639 {
640 skip_assert_initialized!();
641 arg2.try_into_checked(arg1)
642 }
643
644 #[test]
645 fn compatible() {
646 assert_eq!(
647 with_compatible_formats(ClockTime::ZERO, ClockTime::ZERO),
648 Ok(ClockTime::ZERO),
649 );
650 assert_eq!(
651 with_compatible_formats(ClockTime::ZERO, ClockTime::NONE),
652 Ok(ClockTime::NONE),
653 );
654 assert_eq!(
655 with_compatible_formats(ClockTime::NONE, ClockTime::ZERO),
656 Ok(ClockTime::ZERO),
657 );
658 assert_eq!(
659 with_compatible_formats(
660 ClockTime::ZERO,
661 GenericFormattedValue::Time(Some(ClockTime::ZERO)),
662 ),
663 Ok(GenericFormattedValue::Time(Some(ClockTime::ZERO))),
664 );
665 assert_eq!(
666 with_compatible_formats(
667 GenericFormattedValue::Time(Some(ClockTime::ZERO)),
668 ClockTime::NONE,
669 ),
670 Ok(ClockTime::NONE),
671 );
672 }
673
674 #[test]
675 fn incompatible() {
676 with_compatible_formats(
677 ClockTime::ZERO,
678 GenericFormattedValue::Buffers(Some(42.buffers())),
679 )
680 .unwrap_err();
681 with_compatible_formats(
682 GenericFormattedValue::Buffers(Some(42.buffers())),
683 ClockTime::NONE,
684 )
685 .unwrap_err();
686 }
687
688 fn with_compatible_explicit<T, V>(arg: V, f: Format) -> Result<V::Original, FormattedValueError>
689 where
690 T: FormattedValue,
691 V: CompatibleFormattedValue<T>,
692 {
693 skip_assert_initialized!();
694 arg.try_into_checked_explicit(f)
695 }
696
697 #[test]
698 fn compatible_explicit() {
699 assert_eq!(
700 with_compatible_explicit::<ClockTime, _>(ClockTime::ZERO, Format::Time),
701 Ok(ClockTime::ZERO),
702 );
703 assert_eq!(
704 with_compatible_explicit::<ClockTime, _>(ClockTime::NONE, Format::Time),
705 Ok(ClockTime::NONE),
706 );
707 assert_eq!(
708 with_compatible_explicit::<ClockTime, _>(ClockTime::ZERO, Format::Time),
709 Ok(ClockTime::ZERO),
710 );
711 assert_eq!(
712 with_compatible_explicit::<ClockTime, _>(
713 GenericFormattedValue::Time(None),
714 Format::Time
715 ),
716 Ok(GenericFormattedValue::Time(None)),
717 );
718 assert_eq!(
719 with_compatible_explicit::<GenericFormattedValue, _>(ClockTime::NONE, Format::Time),
720 Ok(ClockTime::NONE),
721 );
722 }
723
724 #[test]
725 fn incompatible_explicit() {
726 with_compatible_explicit::<Buffers, _>(GenericFormattedValue::Time(None), Format::Buffers)
727 .unwrap_err();
728 with_compatible_explicit::<GenericFormattedValue, _>(Buffers::ZERO, Format::Time)
729 .unwrap_err();
730 with_compatible_explicit::<GenericFormattedValue, _>(
731 GenericFormattedValue::Time(None),
732 Format::Buffers,
733 )
734 .unwrap_err();
735 }
736
737 #[test]
738 fn none_builder() {
739 let ct_none: Option<ClockTime> = Option::<ClockTime>::none();
740 assert!(ct_none.is_none());
741
742 let ct_none: Option<ClockTime> = Option::<ClockTime>::none_for_format(Format::Time);
743 assert!(ct_none.is_none());
744
745 let gen_ct_none: GenericFormattedValue =
746 GenericFormattedValue::none_for_format(Format::Time);
747 assert!(gen_ct_none.is_none());
748
749 assert!(ClockTime::ZERO.is_some());
750 assert!(!ClockTime::ZERO.is_none());
751 }
752
753 #[test]
754 #[should_panic]
755 fn none_for_inconsistent_format() {
756 let _ = Option::<ClockTime>::none_for_format(Format::Percent);
757 }
758
759 #[test]
760 #[should_panic]
761 fn none_for_unsupported_format() {
762 let _ = GenericFormattedValue::none_for_format(Format::Undefined);
763 }
764
765 #[test]
766 fn none_signed_builder() {
767 let ct_none: Option<Signed<ClockTime>> = Option::<ClockTime>::none_signed();
768 assert!(ct_none.is_none());
769
770 let ct_none: Option<Signed<ClockTime>> =
771 Option::<ClockTime>::none_signed_for_format(Format::Time);
772 assert!(ct_none.is_none());
773
774 let gen_ct_none: GenericSignedFormattedValue =
775 GenericFormattedValue::none_signed_for_format(Format::Time);
776 assert!(gen_ct_none.abs().is_none());
777 }
778
779 #[test]
780 fn signed_optional() {
781 let ct_1 = Some(ClockTime::SECOND);
782
783 let signed = ct_1.into_positive().unwrap();
784 assert_eq!(signed, Signed::Positive(ClockTime::SECOND));
785 assert!(signed.is_positive());
786 assert_eq!(signed.positive_or(()).unwrap(), ClockTime::SECOND);
787 assert_eq!(signed.positive_or_else(|_| ()).unwrap(), ClockTime::SECOND);
788 signed.negative_or(()).unwrap_err();
789 assert_eq!(
790 signed.negative_or_else(|val| val).unwrap_err(),
791 ClockTime::SECOND
792 );
793
794 let signed = ct_1.into_negative().unwrap();
795 assert_eq!(signed, Signed::Negative(ClockTime::SECOND));
796 assert!(signed.is_negative());
797 assert_eq!(signed.negative_or(()).unwrap(), ClockTime::SECOND);
798 assert_eq!(signed.negative_or_else(|_| ()).unwrap(), ClockTime::SECOND);
799 signed.positive_or(()).unwrap_err();
800 assert_eq!(
801 signed.positive_or_else(|val| val).unwrap_err(),
802 ClockTime::SECOND
803 );
804
805 let ct_none = ClockTime::NONE;
806 assert!(ct_none.into_positive().is_none());
807 assert!(ct_none.into_negative().is_none());
808 }
809
810 #[test]
811 fn signed_mandatory() {
812 let ct_1 = ClockTime::SECOND;
813
814 let signed = ct_1.into_positive();
815 assert_eq!(signed, Signed::Positive(ct_1));
816 assert!(signed.is_positive());
817 assert_eq!(signed.positive(), Some(ct_1));
818 assert!(!signed.is_negative());
819 assert!(signed.negative().is_none());
820 assert_eq!(signed.signum(), 1);
821
822 let signed = ct_1.into_negative();
823 assert_eq!(signed, Signed::Negative(ct_1));
824 assert!(signed.is_negative());
825 assert_eq!(signed.negative(), Some(ct_1));
826 assert!(!signed.is_positive());
827 assert!(signed.positive().is_none());
828 assert_eq!(signed.signum(), -1);
829
830 let signed = Default::ONE.into_positive();
831 assert_eq!(signed, Signed::Positive(Default::ONE));
832 assert!(signed.is_positive());
833 assert_eq!(signed.positive(), Some(Default::ONE));
834 assert!(!signed.is_negative());
835 assert!(signed.negative().is_none());
836 assert_eq!(signed.signum(), 1);
837
838 let signed = Default::ONE.into_negative();
839 assert_eq!(signed, Signed::Negative(Default::ONE));
840 assert!(signed.is_negative());
841 assert_eq!(signed.negative(), Some(Default::ONE));
842 assert!(!signed.is_positive());
843 assert!(signed.positive().is_none());
844 assert_eq!(signed.signum(), -1);
845
846 let ct_zero = ClockTime::ZERO;
847 let p_ct_zero = ct_zero.into_positive();
848 assert!(p_ct_zero.is_positive());
849 assert!(!p_ct_zero.is_negative());
850 assert_eq!(p_ct_zero.signum(), 0);
851 let n_ct_zero = ct_zero.into_negative();
852 assert!(n_ct_zero.is_negative());
853 assert!(!n_ct_zero.is_positive());
854 assert_eq!(n_ct_zero.signum(), 0);
855 }
856
857 #[test]
858 fn signed_generic() {
859 let ct_1 = GenericFormattedValue::Time(Some(ClockTime::SECOND));
860 assert!(ct_1.is_some());
861
862 let signed = ct_1.into_positive();
863 assert_eq!(
864 signed,
865 GenericSignedFormattedValue::Time(Some(Signed::Positive(ClockTime::SECOND))),
866 );
867 assert_eq!(signed.is_positive(), Some(true));
868 assert_eq!(signed.is_negative(), Some(false));
869 assert_eq!(signed.signum(), Some(1));
870
871 let signed = ct_1.into_negative();
872 assert_eq!(
873 signed,
874 GenericSignedFormattedValue::Time(Some(Signed::Negative(ClockTime::SECOND))),
875 );
876 assert_eq!(signed.is_negative(), Some(true));
877 assert_eq!(signed.is_positive(), Some(false));
878 assert_eq!(signed.signum(), Some(-1));
879
880 let ct_none = GenericFormattedValue::Time(ClockTime::NONE);
881 assert!(ct_none.is_none());
882
883 let signed = ct_none.into_positive();
884 assert_eq!(signed, GenericSignedFormattedValue::Time(None),);
885 assert!(signed.is_positive().is_none());
886 assert!(signed.is_negative().is_none());
887 assert!(signed.signum().is_none());
888
889 let signed = ct_none.into_negative();
890 assert_eq!(signed, GenericSignedFormattedValue::Time(None),);
891 assert!(signed.is_negative().is_none());
892 assert!(signed.is_positive().is_none());
893 assert!(signed.signum().is_none());
894
895 let ct_zero = GenericFormattedValue::Time(Some(ClockTime::ZERO));
896 assert!(ct_zero.is_some());
897
898 let signed = ct_zero.into_positive();
899 assert_eq!(
900 signed,
901 GenericSignedFormattedValue::Time(Some(Signed::Positive(ClockTime::ZERO))),
902 );
903 assert_eq!(signed.is_positive(), Some(true));
904 assert_eq!(signed.is_negative(), Some(false));
905 assert_eq!(signed.signum(), Some(0));
906 }
907
908 #[test]
909 fn signed_roundtrip() {
910 let ct_1 = Some(ClockTime::SECOND);
911 let raw_ct_1 = unsafe { ct_1.into_raw_value() };
912
913 let signed = unsafe { Option::<ClockTime>::from_raw(Format::Time, raw_ct_1) }
914 .into_signed(1)
915 .unwrap();
916 assert_eq!(signed, Signed::Positive(ClockTime::SECOND));
917 assert!(signed.is_positive());
918
919 let signed = unsafe { Option::<ClockTime>::from_raw(Format::Time, raw_ct_1) }
920 .into_signed(-1)
921 .unwrap();
922 assert_eq!(signed, Signed::Negative(ClockTime::SECOND));
923 assert!(signed.is_negative());
924
925 let ct_none = ClockTime::NONE;
926 let raw_ct_none = unsafe { ct_none.into_raw_value() };
927
928 let signed =
929 unsafe { Option::<ClockTime>::from_raw(Format::Time, raw_ct_none) }.into_signed(1);
930 assert!(signed.is_none());
931
932 let signed =
933 unsafe { Option::<ClockTime>::from_raw(Format::Time, raw_ct_none) }.into_signed(-1);
934 assert!(signed.is_none());
935 }
936
937 #[test]
938 fn display_new_types() {
939 let bytes = 42.bytes();
940 assert_eq!(&format!("{bytes}"), "42 bytes");
941 assert_eq!(&format!("{}", bytes.display()), "42 bytes");
942
943 assert_eq!(&format!("{}", Some(bytes).display()), "42 bytes");
944 assert_eq!(&format!("{}", Bytes::NONE.display()), "undef. bytes");
945
946 let gv_1 = GenericFormattedValue::Percent(Some(42.percent()));
947 assert_eq!(&format!("{gv_1}"), "42 %");
948 assert_eq!(
949 &format!("{}", GenericFormattedValue::Percent(None)),
950 "undef. %"
951 );
952
953 let percent = Percent::try_from(0.1234).unwrap();
954 assert_eq!(&format!("{percent}"), "12.34 %");
955 assert_eq!(&format!("{percent:5.1}"), " 12.3 %");
956
957 let other: Other = 42.try_into().unwrap();
958 assert_eq!(&format!("{other}"), "42");
959
960 let g_other = GenericFormattedValue::new(Format::__Unknown(128), 42);
961 assert_eq!(&format!("{g_other}"), "42 (format: 128)");
962 assert_eq!(&format!("{}", g_other.display()), "42 (format: 128)");
963
964 let g_other_none = GenericFormattedValue::Other(Format::__Unknown(128), None);
965 assert_eq!(&format!("{g_other_none}"), "undef. (format: 128)");
966 assert_eq!(
967 &format!("{}", g_other_none.display()),
968 "undef. (format: 128)"
969 );
970 }
971
972 #[test]
973 fn display_signed() {
974 let bytes_42 = 42.bytes();
975 let p_bytes = bytes_42.into_positive();
976 assert_eq!(&format!("{p_bytes}"), "+42 bytes");
977 assert_eq!(&format!("{}", p_bytes.display()), "+42 bytes");
978
979 let some_p_bytes = Some(p_bytes);
980 assert_eq!(&format!("{}", some_p_bytes.display()), "+42 bytes");
981
982 let p_some_bytes = Signed::Positive(Some(bytes_42));
983 assert_eq!(&format!("{}", p_some_bytes.display()), "+42 bytes");
984
985 let n_bytes = bytes_42.into_negative();
986 assert_eq!(&format!("{n_bytes}"), "-42 bytes");
987 assert_eq!(&format!("{}", n_bytes.display()), "-42 bytes");
988
989 let some_n_bytes = Some(n_bytes);
990 assert_eq!(&format!("{}", some_n_bytes.display()), "-42 bytes");
991
992 let n_some_bytes = Signed::Negative(Some(bytes_42));
993 assert_eq!(&format!("{}", n_some_bytes.display()), "-42 bytes");
994
995 let p_none_bytes = Signed::Positive(Bytes::NONE);
996 assert_eq!(&format!("{}", p_none_bytes.display()), "undef. bytes");
997 let n_none_bytes = Signed::Negative(Bytes::NONE);
998 assert_eq!(&format!("{}", n_none_bytes.display()), "undef. bytes");
999
1000 let none_s_bytes = Option::<Signed<Bytes>>::None;
1001 assert_eq!(&format!("{}", none_s_bytes.display()), "undef. bytes");
1002
1003 let ct_1 = 45_834_908_569_837 * ClockTime::NSECOND;
1004 assert_eq!(&format!("{ct_1}"), "12:43:54.908569837");
1005 assert_eq!(&format!("{}", ct_1.display()), "12:43:54.908569837");
1006
1007 let g_ct_1 = GenericFormattedValue::Time(Some(ct_1));
1008 assert_eq!(&format!("{g_ct_1}"), "12:43:54.908569837");
1009 assert_eq!(&format!("{}", g_ct_1.display()), "12:43:54.908569837");
1010
1011 let p_g_ct1 = g_ct_1.into_positive();
1012 assert_eq!(&format!("{p_g_ct1}"), "+12:43:54.908569837");
1013 assert_eq!(&format!("{}", p_g_ct1.display()), "+12:43:54.908569837");
1014
1015 let n_g_ct1 = g_ct_1.into_negative();
1016 assert_eq!(&format!("{n_g_ct1}"), "-12:43:54.908569837");
1017 assert_eq!(&format!("{}", n_g_ct1.display()), "-12:43:54.908569837");
1018 }
1019}
1020