Struct Span

pub struct Span { /* private fields */ }

A closed interval of coordinates in one dimension.

Represents the range [start, stop].

Implementations

impl Span

pub const fn until(stop: i64) -> Self

Creates a new Span from 0 until the specified stop.

Panics

This function panics if stop is less than 0.

pub const unsafe fn new_unchecked(start: i64, stop: i64) -> Self

Creates a new Span between two integers.

Safety

The caller must ensure that start is less than or equal to stop.

pub fn new(start: i64, stop: i64) -> Self

Creates a new Span between two integers.

pub const fn from_point(x: i64) -> Self

Creates a span of zero length encompassing the given point.

pub const fn with_start_and_length(start: i64, length: i64) -> Self

Creates a span of the given length starting from start.

pub const fn with_stop_and_length(stop: i64, length: i64) -> Self

Creates a span of the given length ending at stop.

pub const fn with_point_and_length(sign: Sign, point: i64, length: i64) -> Self

Creates a span with the given endpoint and length.

If sign is Sign::Pos, point is treated as the ending/stopping point of the span. If sign is Sign::Neg, point is treated as the beginning/starting point of the span.

pub const fn expand(self, sign: Sign, amount: i64) -> Self

Creates a new Span expanded by amount in the direction indicated by pos.

pub const fn expand_all(self, amount: i64) -> Self

Creates a new Span expanded by amount in both directions.

pub const fn endpoint(&self, sign: Sign) -> i64

Gets the starting (Sign::Neg) or stopping (Sign::Pos) endpoint of a span.

pub fn dist_to(&self, point: i64) -> i64

Gets the shortest distance between this span and a point.

Example

let span = Span::new(10, 20);
assert_eq!(span.dist_to(4), 6);
assert_eq!(span.dist_to(12), 0);
assert_eq!(span.dist_to(27), 7);

pub fn from_center_span(center: i64, span: i64) -> Self

Creates a new Span with center center and length span.

span must be a positive, even integer.

Example

let span = Span::from_center_span(0, 40);
assert_eq!(span, Span::new(-20, 20));

Panics

Passing an odd span to this method results in a panic:

let span = Span::from_center_span(0, 25);

Passing a negative span to this method also results in a panic:

let span = Span::from_center_span(0, -200);

pub fn from_center_span_gridded(center: i64, span: i64, grid: i64) -> Self

Creates a new Span with center center and length span and snap the edges to the grid.

Example

let span = Span::from_center_span_gridded(0, 40, 5);
assert_eq!(span, Span::new(-20, 20));

let span = Span::from_center_span_gridded(35, 40, 5);
assert_eq!(span, Span::new(15, 55));

Panics

This function panics if span is negative, odd, or not an integer multiple of grid.

pub const fn center(&self) -> i64

Gets the center of the span.

pub const fn length(&self) -> i64

Gets the length of the span.

pub const fn start(&self) -> i64

Gets the start of the span.

pub const fn stop(&self) -> i64

Gets the stop of the span.

pub const fn intersects(&self, other: &Self) -> bool

Checks if the span intersects with the Span other.

pub fn merge(spans: impl IntoIterator<Item = Self>) -> Self

Creates a new minimal Span that contains all of the elements of spans.

pub fn union(self, other: Self) -> Self

Calculates the smallest interval containing this span and other.

pub fn union_all<T>(spans: impl Iterator<Item = T>) -> Self

where T: Into<Self>,

Calculates the minimal bounding interval of all spans provided.

Example

let spans = vec![
    Span::new(10, 40),
    Span::new(35, 60),
    Span::new(20, 30),
    Span::new(-10, 5),
];
assert_eq!(Span::union_all(spans.into_iter()), Span::new(-10, 60));

Panics

This function panics if the provided iterator has no elements. If your iterator may be empty, consider using Span::union_all_option.

pub fn union_all_option<T>(spans: impl Iterator<Item = T>) -> Option<Self>

where T: Into<Option<Self>>,

Calculates the minimal bounding interval of all Option<Span>s provided.

All None elements in the iterator are ignored. If the iterator has no Some(_) elements, this function returns None.

Example

let spans = vec![
    Some(Span::new(10, 40)),
    Some(Span::new(35, 60)),
    None,
    Some(Span::new(20, 30)),
    None,
    Some(Span::new(-10, 5)),
];
assert_eq!(Span::union_all_option(spans.into_iter()), Some(Span::new(-10, 60)));

pub fn intersection(self, other: Self) -> Option<Self>

Calculates the intersection of this span with other.

pub fn add_point(self, pos: i64) -> Self

Returns a new Span representing the union of the current span with the given point.

pub fn shrink(self, side: Sign, amount: i64) -> Self

Shrinks the given side by the given amount.

Behavior is controlled by the given Sign:

• If side is Sign::Pos, shrinks from the positive end (ie. decreases the stop).
• If side is Sign::Neg, shrinks from the negative end (ie. increases the start).

pub const fn shrink_all(self, amount: i64) -> Self

Shrinks the span by the given amount on all sides.

pub const fn translate(self, amount: i64) -> Self

Translates the span by the given amount.

pub fn dist_to_span(self, other: Span) -> i64

The minimum separation between this span and other.

Example

let s1 = Span::new(10, 20);
let s2 = Span::new(30, 50);
let s3 = Span::new(25, 40);
assert_eq!(s1.dist_to_span(s2), 10);
assert_eq!(s1.dist_to_span(s3), 5);
assert_eq!(s2.dist_to_span(s3), 0);
assert_eq!(s3.dist_to_span(s3), 0);

pub fn has_integer_center(&self) -> bool

Returns whether the span’s center is at an integer coordinate.

Example

let span = Span::new(0, 100);
assert!(span.has_integer_center());

let span = Span::new(0, 99);
assert!(!span.has_integer_center());

Trait Implementations

impl BoundingUnion<Span> for Span

type Output = Span

The type of the output shape representing the bounding union.

fn bounding_union(&self, other: &Span) -> Self::Output

Calculates the bounding union of this shape with other.

impl Clone for Span

fn clone(&self) -> Span

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Contains<Span> for Span

fn contains(&self, other: &Span) -> Containment

Returns a Containment indicating how other is enclosed within this shape.

fn encloses(&self, other: &T) -> bool

Returns true if other is fully enclosed in this shape.

fn partially_intersects(&self, other: &T) -> bool

Returns true if other is fully or partially enclosed in this shape.

impl Debug for Span

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

Formats the value using the given formatter.

impl Default for Span

fn default() -> Span

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Span

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<(i64, i64)> for Span

fn from(tup: (i64, i64)) -> Self

Converts to this type from the input type.

impl From<Span> for (i64, i64)

fn from(s: Span) -> Self

Converts to this type from the input type.

impl Hash for Span

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Intersect<Span> for Span

type Output = Span

The type of the output shape representing the intersection.

fn intersect(&self, other: &Span) -> Option<Self::Output>

Calculates the intersection of this shape with other.

impl Ord for Span

fn cmp(&self, other: &Span) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Span

fn eq(&self, other: &Span) -> 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 PartialOrd for Span

fn partial_cmp(&self, other: &Span) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Span

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for Span

impl Eq for Span

impl StructuralPartialEq for Span