[go: up one dir, main page]

SortedChain

enterpolation

Trait SortedChain 

Source 
pub trait SortedChain: Chain {
    // Provided methods
    fn strict_upper_bound_clamped(
        &self,
        element: Self::Output,
        min: usize,
        max: usize,
    ) -> usize
       where Self::Output: PartialOrd + Copy { ... }
    fn strict_upper_bound(&self, element: Self::Output) -> usize
       where Self::Output: PartialOrd + Copy { ... }
    fn upper_border(
        &self,
        element: Self::Output,
    ) -> (usize, usize, Self::Output)
       where Self::Output: PartialOrd + Sub<Output = Self::Output> + Div<Output = Self::Output> + Zero + Copy + Debug { ... }
    fn linear_factor_unchecked(
        &self,
        min_index: usize,
        max_index: usize,
        element: Self::Output,
    ) -> Self::Output
       where Self::Output: Sub<Output = Self::Output> + Div<Output = Self::Output> + Copy { ... }
    fn linear_factor(
        &self,
        min_index: usize,
        max_index: usize,
        element: Self::Output,
    ) -> Self::Output
       where Self::Output: Sub<Output = Self::Output> + Div<Output = Self::Output> + Zero + Copy { ... }
}
Expand description

Trait to mark a chain as sorted.

This guarantees that the generated elements of a chain are

  • comparable (you could define the trait Ord for the set of all generated elements)
  • non-strictly increasing

Also it implements default search functions which can be overridden to achieve better performance and accuracy.

§Panics

Some or all of this functions may panic. Each function has it’s own panic segment which describes its needs. To guarantee no panics at runtime, one should use struct or traits which guarantee the needs of the functions. The MinSize trait was created just for this.

§Implementation

If a default implementation of a function is overwritten, the documentation should be copied and the examples only slightly changed such that they are working. The values and equations in the examples given should always be true. If some values in the examples can’t be reproduced, the example doesn’t have to be copied. These cases (if applicable) should be tested:

  • stricly increasing array with values
    • outside of the array (both sides)
    • first knot
    • last knot
    • a knot inside the array
    • value inbetween two knots
  • semi-constant array with values outside of the array (both_sides)

Provided Methods§

Source

fn strict_upper_bound_clamped( &self, element: Self::Output, min: usize, max: usize, ) -> usize
where Self::Output: PartialOrd + Copy,

Returns the smallest index between min and max for which the corresponding element is bigger then the input. If all elements are smaller, this function will return the given maximum.

#Panic

Panics if min or max are not within [0,self.len()].

§Examples
let arr = Sorted::new_unchecked([0.0,0.1,0.2,0.7,0.7,0.7,0.8,1.0]);
assert_eq!(arr.strict_upper_bound_clamped(-1.0,1,5),1);
assert_eq!(arr.strict_upper_bound_clamped(0.15,1,5),2);
assert_eq!(arr.strict_upper_bound_clamped(0.7,1,5),5);
assert_eq!(arr.strict_upper_bound_clamped(20.0,1,5),5);
Source

fn strict_upper_bound(&self, element: Self::Output) -> usize
where Self::Output: PartialOrd + Copy,

Returns the smallest index for which the corresponding element is bigger then the input. If all elements are bigger, this function will return self.len().

#Panic

Panics if self is empty.

§Examples
let arr = Sorted::new_unchecked([0.0,0.1,0.2,0.7,0.7,0.7,0.8,1.0]);
assert_eq!(arr.strict_upper_bound(-1.0),0);
assert_eq!(arr.strict_upper_bound(0.15),2);
assert_eq!(arr.strict_upper_bound(0.7),6);
assert_eq!(arr.strict_upper_bound(20.0),8);
Source

fn upper_border(&self, element: Self::Output) -> (usize, usize, Self::Output)
where Self::Output: PartialOrd + Sub<Output = Self::Output> + Div<Output = Self::Output> + Zero + Copy + Debug,

Find the values inside the collection for which the given element is inbetween and a linear factor at how close it is to which value.

This function in general returns indices corresponding to values (first and second) such that first <= value <= second is true.

If the given element is smaller/bigger than every element in the collection, then the indices given will be the smallest/biggest possible and if the corresponding values are the same the factor is only guaranteed to be a valid number.

§Remark

There are collections for which the returned values of this function are not uniquely defined. You may not assume any other invariant except first * factor + second * (1.0 - factor) == value, if first <= value <= second holds true, where value is the value inserted into this function, and the function returned (index_of_first, index_of_second, factor).

Otherwise it may return any valid factor such that first * factor + second * (1.0 - factor) == first == second holds true.

§Panics

Panics if self is has less than two elements.

§Examples
let arr = Sorted::new_unchecked([0.0,0.1,0.2,0.7,0.7,0.7,0.8,1.0]);
let values = vec![-1.0,0.0,0.15,0.7,1.0,20.0];
for value in values {
    let (min_index, max_index, factor) = arr.upper_border(value);
    let min = arr.eval(min_index);
    let max = arr.eval(max_index);
    assert_f64_near!(utils::lerp(min,max,factor),value);
}
let arr = Sorted::new_unchecked([0.0,0.0,5.0,5.0,5.0]);
let values = vec![-1.0,20.0];
let results = vec![0.0,5.0];
for (value, result) in values.into_iter().zip(results) {
    let (min_index, max_index, factor) = arr.upper_border(value);
    println!("min_index: {:?}, max_index: {:?}, factor: {:?}", min_index, max_index, factor);
    let min = arr.eval(min_index);
    let max = arr.eval(max_index);
    assert_f64_near!(utils::lerp(min,max,factor),result);
}
Source

fn linear_factor_unchecked( &self, min_index: usize, max_index: usize, element: Self::Output, ) -> Self::Output
where Self::Output: Sub<Output = Self::Output> + Div<Output = Self::Output> + Copy,

Calculate the factor of element inbetween min and max.

That is, the factor would be needed to generate element from a linear interpolation of min and max, with min being the element generated by min_index and the same holds for max_index.

This function may try to divide by zero if both elements behind the indices are the same. This is not checked.

Source

fn linear_factor( &self, min_index: usize, max_index: usize, element: Self::Output, ) -> Self::Output
where Self::Output: Sub<Output = Self::Output> + Div<Output = Self::Output> + Zero + Copy,

Calculate the factor of element inbetween min and max.

That is, the factor would be needed to generate element from a linear interpolation of min and max, with min being the element generated by min_index and the same holds for max_index.

If the factor could be anything, as both elements are the same, 1.0 is returned.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§