Trait gstreamer::format::CompatibleFormattedValue

source · 
pub trait CompatibleFormattedValue<V: FormattedValue> {
    type Original: FormattedValue;

    // Required methods
    fn try_into_checked(
        self,
        other: V
    ) -> Result<Self::Original, FormattedValueError>;
    fn try_into_checked_explicit(
        self,
        format: Format
    ) -> Result<Self::Original, FormattedValueError>;
}
Expand description

A trait implemented on types which can hold FormattedValues compatible with parameter F.

This trait is auto-implemented based on FormattedValues additional traits such as SpecificFormattedValue.

§Example

Consider the following function:

fn with_compatible_formats<V: FormattedValue>(
    arg1: V,
    arg2: impl CompatibleFormattedValue<V>,
) {
    // This is required to access arg2 as a FormattedValue:
    let _arg2 = arg2.try_into_checked(arg1).unwrap();
}

// This is Ok because arg1 is a ClockTime and arg2 is
// an Option<ClockTime> which are compatible format-wise.
with_compatible_formats(ClockTime::ZERO, ClockTime::NONE);

// This is Ok because arg1 is a ClockTime and arg2 is
// a GenericFormattedValue which are compatible format-wise.
with_compatible_formats(
    ClockTime::ZERO,
    GenericFormattedValue::Time(None),
);

Users are able to call the function with arguments:

  1. of the same type (e.g. ClockTime),
  2. of different types, but able to hold a value of the same Format (e.g. ClockTime and Option<ClockTime>).
  3. One of a Formatted Value (specific or generic), the other being a GenericFormattedValue.

Format compatibility for cases 1 and 2 is enforced by the type system, while case 3 will be checked at runtime time.

ⓘ
// This doesn't compile because the arguments are not compatible:
let _ = with_compatible_formats(ClockTime::ZERO, Bytes(Some(42)));

Note: users will not be able use arg2 directly unless format check succeeds:

ⓘ
fn with_compatible_formats<V: FormattedValue>(
    arg1: V,
    arg2: impl CompatibleFormattedValue<V>,
) {
    // This doesn't compile because arg2 hasn't been checked:
    let _format = arg2.format();
}

Required Associated Types§

source

type Original: FormattedValue

Required Methods§

source

fn try_into_checked( self, other: V ) -> Result<Self::Original, FormattedValueError>

Returns Ok(self) with its type restored if it is compatible with the format of other.

When used with compatible SpecificFormattedValues, checks are enforced by the type system, no runtime checks are performed.

When used with FormattedValue / GenericFormattedValue and vice versa, a runtime format check is performed. If the check fails, Err(FormattedValueError) is returned.

source

fn try_into_checked_explicit( self, format: Format ) -> Result<Self::Original, FormattedValueError>

Returns Ok(self) with its type restored if it is compatible with the format of V.

When possible, prefer using Self::try_into_checked which reduces the risk of misuse.

When used with compatible SpecificFormattedValues, checks are enforced by the type system, no runtime checks are performed.

When used with SpecificFormattedValue as a parameter and a GenericFormattedValue as Self, a runtime check is performed against the default format of the parameter. If the check fails, Err(FormattedValueError) is returned.

When used with GenericFormattedValue as a parameter and a SpecificFormattedValue as Self, the format argument used. If the check fails, Err(FormattedValueError) is returned.

Implementors§