This commit makes the formatted values' main constructors `const`,
so that they can be used in constant definitions.
`from_usize` constructors can't be made const because `try_into`
can't be used in `const` functions as of rustc 1.64.0. Same for
`Percent::from_ratio`: floating point arithmetic is not allowed.
Introduce a set of Constructor traits which are implemented on
integer of float depending on the formatted values. This traits
allows building formatted values using expressions such as:
```rust
let buffer_nb = 20.buffers();
let size = 42.k_bytes();
let duration = 15.minutes() + 30.seconds();
let quantity = 42.default_format();
let progress = 20.percent();
let progress = 0.2.percent_ratio();
```
Previous proposition for constructing specific formatted values was
to use an operation such as `42 * Default::ONE` which, in retrospect,
doesn't seem idiomatic.
This commit adds `from_u64` and `from_usize` constructors for most
formatted values. Having `from_usize` is convenient when dealing with
quantities related to containers indices or length.
This also fixes the `Percent` from float constructors from which was
derived the `ONE` constant as well as previous display implementation.
Also removed the `pub` specifier for `Undefined` inner value. It wasn't
removed in a previous commit as `Undefined` can use the full range of
the inner type. But now, it seems preferable not to expose the inner
value for proper encapsulation and so as to reduce the differences with
other formatted values (kind of least astonishment principle).
... users would be able to bypass the range checks and build a
defined Rust value which would be interpreted as `None` in C code.
Added format module examples for formatted values constructions.
- The `GST_FORMAT_PERCENT_SCALE` was not used to compute the value
to display.
- Added `Display` examples in the format module documentation.
- Simplified `glib_newtype_display` macro.
The `Signed` version for `GenericFormattedValue` was implemented as
`Signed<GenericFormattedValue>`, which failed to represent properly
the `None` variants when applicable and could represent inconsistent
`Signed` variant combined with `GenericFormattedValue` formats which
are internaly represented as signed integers.
Some operations were implemented on types that wouldn't result in
the expected physical unit. E.g.:
- `ClockTime / ClockTime` results in a unit-less factor.
- `u64 / ClockTime` would result in a `1 / ClockTime`. Since we don't
use any `Frequency` type, this operation is removed. Users should
use the `ClockTime` accessors to compute the expected value.
This commit also adds:
- multiplications with integers as the left hand side operands.
- `Partial{Eq,Ord} for `Signed<T>` with `T` as left hand side operand.
- `opt_add` / `opt_sub` for `Signed<T>` with `T` as left or right hand
side operands.
- missing tests for `Partial{Eq,Ord}` and `OptionOrd`.
This implementation can interfere with unrelated code and was removed:
- `Signed<usize>.` `PartialOrd` makes existing code computing the len
of slices needing type annotation because the len is later used in
a comparison for which the compiler is unable to determine if
the len is `Signed<usize>` or `usize`.
The `SpecificFormattedValue` types are newtypes of `u64` or `u32`
and they all implement `Copy`. It shouldn't be needed to implement
operations on `&Type` nor `&inner_type`.
The functions `into_{signed,positive,negative}` used to be implemented
on the `FormattedValue` trait for convenience. This was wrong for the
following reasons:
- They aren't specific to `FormattedValue`s: they can also be
implemented for regular unsigned integers such as `u64`, `usize` or
`u32`.
- They were implemented for `format::Undefined` and all variants of
`GenericFormattedValue`, some of which are already signed.
This commit introduces the new trait `UnsignedIntoSigned`, which makes
it possible to fix both of the above problems.
Users can build a `Signed` from an `Undefined`, an `i64`, `isize` or
`i32` thanks to the `From` trait implementations.
Previous implementation for the glib format new types built a
`String` for the displayable value. This commit uses `fmt`
mechanisms so as to limit useless allocations.
Using `ClockTime::from_nseconds` it was possible to build a valid
`ClockTime` which would match `GST_CLOCK_TIME_NONE` when passed to
the C API, leading to unexpected behaviour as `GST_CLOCK_TIME_NONE`
is represented as an `Option::<ClockTime>::None` in Rust.
This commit panics when this function is called with
`GST_CLOCK_TIME_NONE` (defined as `u64::MAX`). This is similar to
what happens when calling other `ClockTime` constructors (e.g.
`from_seconds`) with too large a value: the internal multiplication
overflows leading to a panic.
When the `format_args!` macro is used, formatted args are evaluated
in order to form the argument collection that ends up being formatted
when requested to do so.
For the log macro, this means that any argument that is an expression
was evaluated even if the log level was below current threshold. This
can be examplified by the following code:
```rust
gst::debug!(CAT, "{}", {
println!("fmt arg executed");
"A debug log"
});
```
This used to print "fmt arg executed" even when the log threshold for
`CAT` was filtering `debug` out.
Note that this could break existing code that would incorrectly rely
on the side effect.
When I introduced the 'ser_de' feature, I couldn't find a way to
name it 'serde' while also make it pull the optional 'serde'
crate together with the other related dependencies.
With rustc >= 1.60 we can use 'dep:serde' to refer to the 'serde'
dependency as part of the 'serde' feature.
warning: unused return value of `std::boxed::Box::<T>::from_raw` that must be used
--> gstreamer-rtsp-server/src/rtsp_session_pool.rs:23:5
|
23 | Box::<F>::from_raw(ptr as *mut _);
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= note: `#[warn(unused_must_use)]` on by default
= note: call `drop(from_raw(ptr))` if you intend to drop the `Box`
Functions such as Segment::to_running_time_full replicate the C
signature for the return type: an integer indicates whether the
resulting value must be interpreted as positive or negative.
In Rust, alternatives are usually represented using an enum.
This commit implements an enum wrapper to represent the sign
and adds functions to FormattedValue to ease Signed handling.
The trait CompatibleFormattedValue can be used to check argument
compatibility to a certain Format. This is convenient to define
function which accept several FormattedValues which must hold
values of the same Format.
This trait enforces format compatibility at compilation time for
SpecificFormattedValues and at runtime when a GenericFormattedValue
is provided.
See https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/-/merge_requests/1059
The trait FormattedValue was only implemented on types which
could implement the full range of values for a Format. In order
to declare a function which could take both the intrinsic type
of any Format (e.g. `ClockTime`) as well the full range of values
(e.g. `Option<ClockTime>`), the argument was declared:
```rust
impl Into<GenericFormattedValue>,
```
This commit implements `FormattedValue` for any type representing
a format. E.g.: both `ClockTime` and `Option<ClockTime>` will now
implement `FormattedValue`. The trait `FormattedValueFullRange`
is implemented on types which can be built from any raw value.
These changes are intended to help for the implementation of a
means to enforce format conformity at compilation time for
functions with multiple formatted value arguments.
The following signatures were found to be incorrect and are fixed:
- `message::StepDone`: forced the type for `amount` and `duration`
to be of the same type, when `duration` is expected to be of the
`Time` format.
- `query::Convert::set`: the two arguments were forced to the same
type, so potentialy the same format, unless a
`GenericFormattedValue` was used.
See https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/-/merge_requests/1059
And only allow setting documentation caps via that. It's not actually
allowed to update the documentation caps at random times as it is not
thread-safe.
