Struct TextRange

pub struct TextRange { /* private fields */ }

Expand description

A range in text, represented as a pair of TextSize.

It is a logic error for start to be greater than end.

Implementations§

§

impl TextRange

pub const fn new(start: TextSize, end: TextSize) -> TextRange

Creates a new TextRange with the given start and end (start..end).

§Panics

Panics if end < start.

§Examples

let start = TextSize::from(5);
let end = TextSize::from(10);
let range = TextRange::new(start, end);

assert_eq!(range.start(), start);
assert_eq!(range.end(), end);
assert_eq!(range.len(), end - start);

pub const fn at(offset: TextSize, len: TextSize) -> TextRange

Create a new TextRange with the given offset and len (offset..offset + len).

§Examples

let text = "0123456789";

let offset = TextSize::from(2);
let length = TextSize::from(5);
let range = TextRange::at(offset, length);

assert_eq!(range, TextRange::new(offset, offset + length));
assert_eq!(&text[range], "23456")

pub const fn empty(offset: TextSize) -> TextRange

Create a zero-length range at the specified offset (offset..offset).

§Examples

let point: TextSize;
let range = TextRange::empty(point);
assert!(range.is_empty());
assert_eq!(range, TextRange::new(point, point));

pub const fn up_to(end: TextSize) -> TextRange

Create a range up to the given end (..end).

§Examples

let point: TextSize;
let range = TextRange::up_to(point);

assert_eq!(range.len(), point);
assert_eq!(range, TextRange::new(0.into(), point));
assert_eq!(range, TextRange::at(0.into(), point));

§

impl TextRange

Identity methods.

pub const fn start(self) -> TextSize

The start point of this range.

pub const fn end(self) -> TextSize

The end point of this range.

pub const fn len(self) -> TextSize

The size of this range.

pub const fn is_empty(self) -> bool

Check if this range is empty.

§

impl TextRange

Manipulation methods.

pub fn contains(self, offset: TextSize) -> bool

Check if this range contains an offset.

The end index is considered excluded.

§Examples

let (start, end): (TextSize, TextSize);
let range = TextRange::new(start, end);
assert!(range.contains(start));
assert!(!range.contains(end));

pub fn contains_inclusive(self, offset: TextSize) -> bool

Check if this range contains an offset.

The end index is considered included.

§Examples

let (start, end): (TextSize, TextSize);
let range = TextRange::new(start, end);
assert!(range.contains_inclusive(start));
assert!(range.contains_inclusive(end));

pub fn contains_range(self, other: TextRange) -> bool

Check if this range completely contains another range.

§Examples

let larger = TextRange::new(0.into(), 20.into());
let smaller = TextRange::new(5.into(), 15.into());
assert!(larger.contains_range(smaller));
assert!(!smaller.contains_range(larger));

// a range always contains itself
assert!(larger.contains_range(larger));
assert!(smaller.contains_range(smaller));

pub fn intersect(self, other: TextRange) -> Option<TextRange>

The range covered by both ranges, if it exists. If the ranges touch but do not overlap, the output range is empty.

§Examples

assert_eq!(
    TextRange::intersect(
        TextRange::new(0.into(), 10.into()),
        TextRange::new(5.into(), 15.into()),
    ),
    Some(TextRange::new(5.into(), 10.into())),
);

pub fn cover(self, other: TextRange) -> TextRange

Extends the range to cover other as well.

§Examples

assert_eq!(
    TextRange::cover(
        TextRange::new(0.into(), 5.into()),
        TextRange::new(15.into(), 20.into()),
    ),
    TextRange::new(0.into(), 20.into()),
);

pub fn cover_offset(self, offset: TextSize) -> TextRange

Extends the range to cover other offsets as well.

§Examples

assert_eq!(
    TextRange::empty(0.into()).cover_offset(20.into()),
    TextRange::new(0.into(), 20.into()),
)

pub fn checked_add(self, offset: TextSize) -> Option<TextRange>

Add an offset to this range.

Note that this is not appropriate for changing where a TextRange is within some string; rather, it is for changing the reference anchor that the TextRange is measured against.

The unchecked version (Add::add) will always panic on overflow, in contrast to primitive integers, which check in debug mode only.

pub fn checked_sub(self, offset: TextSize) -> Option<TextRange>

Subtract an offset from this range.

Note that this is not appropriate for changing where a TextRange is within some string; rather, it is for changing the reference anchor that the TextRange is measured against.

The unchecked version (Sub::sub) will always panic on overflow, in contrast to primitive integers, which check in debug mode only.

pub fn ordering(self, other: TextRange) -> Ordering

Relative order of the two ranges (overlapping ranges are considered equal).

This is useful when, for example, binary searching an array of disjoint ranges.

§Examples


let a = TextRange::new(0.into(), 3.into());
let b = TextRange::new(4.into(), 5.into());
assert_eq!(a.ordering(b), Ordering::Less);

let a = TextRange::new(0.into(), 3.into());
let b = TextRange::new(3.into(), 5.into());
assert_eq!(a.ordering(b), Ordering::Less);

let a = TextRange::new(0.into(), 3.into());
let b = TextRange::new(2.into(), 5.into());
assert_eq!(a.ordering(b), Ordering::Equal);

let a = TextRange::new(0.into(), 3.into());
let b = TextRange::new(2.into(), 2.into());
assert_eq!(a.ordering(b), Ordering::Equal);

let a = TextRange::new(2.into(), 3.into());
let b = TextRange::new(2.into(), 2.into());
assert_eq!(a.ordering(b), Ordering::Greater);