Struct datafusion::logical_expr::interval_arithmetic::Interval

source ·

pub struct Interval { /* private fields */ }

Expand description

The Interval type represents a closed interval used for computing reliable bounds for mathematical expressions.

Conventions:

Closed bounds: The interval always encompasses its endpoints. We accommodate operations resulting in open intervals by incrementing or decrementing the interval endpoint value to its successor/predecessor.
Unbounded endpoints: If the lower or upper bounds are indeterminate, they are labeled as unbounded. This is represented using a NULL.
Overflow handling: If the lower or upper endpoints exceed their limits after any operation, they either become unbounded or they are fixed to the maximum/minimum value of the datatype, depending on the direction of the overflowing endpoint, opting for the safer choice.
Floating-point special cases:
- INF values are converted to NULLs while constructing an interval to ensure consistency, with other data types.
- NaN (Not a Number) results are conservatively result in unbounded endpoints.

Implementations§

source §

impl Interval

source

pub fn try_new( lower: ScalarValue, upper: ScalarValue ) -> Result<Interval, DataFusionError>

Attempts to create a new Interval from the given lower and upper bounds.

Notes

This constructor creates intervals in a “canonical” form where:

Boolean intervals:
- Unboundedness (NULL) for boolean endpoints is converted to false for lower and true for upper bounds.
Floating-point intervals:
- Floating-point endpoints with NaN, INF, or NEG_INF are converted to NULLs.

source

pub fn make<T>( lower: Option<T>, upper: Option<T> ) -> Result<Interval, DataFusionError>
where ScalarValue: From<Option<T>>,

Convenience function to create a new Interval from the given (optional) bounds, for use in tests only. Absence of either endpoint indicates unboundedness on that side. See Interval::try_new for more information.

source

pub fn make_unbounded(data_type: &DataType) -> Result<Interval, DataFusionError>

Creates an unbounded interval from both sides if the datatype supported.

source

pub fn lower(&self) -> &ScalarValue

Returns a reference to the lower bound.

source

pub fn upper(&self) -> &ScalarValue

Returns a reference to the upper bound.

source

pub fn into_bounds(self) -> (ScalarValue, ScalarValue)

Converts this Interval into its boundary scalar values. It’s useful when you need to work with the individual bounds directly.

source

pub fn data_type(&self) -> DataType

This function returns the data type of this interval.

source

pub fn cast_to( &self, data_type: &DataType, cast_options: &CastOptions<'_> ) -> Result<Interval, DataFusionError>

Casts this interval to data_type using cast_options.

source

pub fn intersect<T>( &self, other: T ) -> Result<Option<Interval>, DataFusionError>
where T: Borrow<Interval>,

Compute the intersection of this interval with the given interval. If the intersection is empty, return None.

NOTE: This function only works with intervals of the same data type. Attempting to compare intervals of different data types will lead to an error.

source

pub fn contains_value<T>(&self, other: T) -> Result<bool, DataFusionError>
where T: Borrow<ScalarValue>,

Decide if this interval certainly contains, possibly contains, or can’t contain a ScalarValue (other) by returning [true, true], [false, true] or [false, false] respectively.

NOTE: This function only works with intervals of the same data type. Attempting to compare intervals of different data types will lead to an error.

source

pub fn contains<T>(&self, other: T) -> Result<Interval, DataFusionError>
where T: Borrow<Interval>,

Decide if this interval is a superset of, overlaps with, or disjoint with other by returning [true, true], [false, true] or [false, false] respectively.

NOTE: This function only works with intervals of the same data type. Attempting to compare intervals of different data types will lead to an error.

source

pub fn add<T>(&self, other: T) -> Result<Interval, DataFusionError>
where T: Borrow<Interval>,

Add the given interval (other) to this interval. Say we have intervals [a1, b1] and [a2, b2], then their sum is [a1 + a2, b1 + b2]. Note that this represents all possible values the sum can take if one can choose single values arbitrarily from each of the operands.

source

pub fn sub<T>(&self, other: T) -> Result<Interval, DataFusionError>
where T: Borrow<Interval>,

Subtract the given interval (other) from this interval. Say we have intervals [a1, b1] and [a2, b2], then their difference is [a1 - b2, b1 - a2]. Note that this represents all possible values the difference can take if one can choose single values arbitrarily from each of the operands.

source

pub fn mul<T>(&self, other: T) -> Result<Interval, DataFusionError>
where T: Borrow<Interval>,

Multiply the given interval (other) with this interval. Say we have intervals [a1, b1] and [a2, b2], then their product is [min(a1 * a2, a1 * b2, b1 * a2, b1 * b2), max(a1 * a2, a1 * b2, b1 * a2, b1 * b2)]. Note that this represents all possible values the product can take if one can choose single values arbitrarily from each of the operands.

NOTE: This function only works with intervals of the same data type. Attempting to compare intervals of different data types will lead to an error.

source

pub fn div<T>(&self, other: T) -> Result<Interval, DataFusionError>
where T: Borrow<Interval>,

Divide this interval by the given interval (other). Say we have intervals [a1, b1] and [a2, b2], then their division is [a1, b1] * [1 / b2, 1 / a2] if 0 ∉ [a2, b2] and [NEG_INF, INF] otherwise. Note that this represents all possible values the quotient can take if one can choose single values arbitrarily from each of the operands.

NOTE: This function only works with intervals of the same data type. Attempting to compare intervals of different data types will lead to an error.

TODO: Once interval sets are supported, cases where the divisor contains zero should result in an interval set, not the universal set.

source

pub fn cardinality(&self) -> Option<u64>

Returns the cardinality of this interval, which is the number of all distinct points inside it. This function returns None if:

The interval is unbounded from either side, or
Cardinality calculations for the datatype in question is not implemented yet, or
An overflow occurs during the calculation: This case can only arise when the calculated cardinality does not fit in an u64.