Struct Interval

pub struct Interval { /* private fields */ }

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

Conventions:

1. 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.

2. Unbounded endpoints: If the lower or upper bounds are indeterminate, they are labeled as unbounded. This is represented using a NULL.

3. 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.

4. 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

impl Interval

pub const CERTAINLY_FALSE: Interval = _

pub const UNCERTAIN: Interval = _

pub const CERTAINLY_TRUE: Interval = _

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.

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.

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

Creates a singleton zero interval if the datatype supported.

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

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

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

Creates an interval between -1 to 1.

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

Create an interval from -π to π.

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

Create an interval from -π/2 to π/2.

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

Create an interval from 0 to infinity.

pub fn lower(&self) -> &ScalarValue

Returns a reference to the lower bound.

pub fn upper(&self) -> &ScalarValue

Returns a reference to the upper bound.

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.

pub fn data_type(&self) -> DataType

This function returns the data type of this interval.

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

Casts this interval to data_type using cast_options.

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

where T: Borrow<Interval>,

Decide if this interval is certainly greater than, possibly greater than, or can’t be greater than 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.

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

where T: Borrow<Interval>,

Decide if this interval is certainly greater than or equal to, possibly greater than or equal to, or can’t be greater than or equal to 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.

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

where T: Borrow<Interval>,

Decide if this interval is certainly less than, possibly less than, or can’t be less than 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.

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

where T: Borrow<Interval>,

Decide if this interval is certainly less than or equal to, possibly less than or equal to, or can’t be less than or equal to 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.

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

where T: Borrow<Interval>,

Decide if this interval is certainly equal to, possibly equal to, or can’t be equal to 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.

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

where T: Borrow<Interval>,

Compute the logical conjunction of this (boolean) interval with the given boolean interval.

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

where T: Borrow<Interval>,

Compute the logical disjunction of this boolean interval with the given boolean interval.

pub fn not(&self) -> Result<Interval, DataFusionError>

Compute the logical negation of this (boolean) interval.

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.

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.

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.

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.

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.

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.

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.

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.

pub fn arithmetic_negate(self) -> Result<Interval, DataFusionError>

Reflects an Interval around the point zero.

This method computes the arithmetic negation of the interval, reflecting it about the origin of the number line. This operation swaps and negates the lower and upper bounds of the interval.

Trait Implementations

impl Clone for Interval

fn clone(&self) -> Interval

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Interval

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for Interval

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl PartialEq for Interval

fn eq(&self, other: &Interval) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Interval

impl StructuralPartialEq for Interval