Struct Fragment

pub struct Fragment {
    pub source: SourceRef,
    pub range: Range<usize>,
}

Available on crate feature source-tracking only.

A fragment of source code.

This can be part of (or all of) a Source.

Fields

source: SourceRef

The Source that this fragment is in.

range: Range<usize>

Fragments are represented using byte ranges in the Source referenced by Fragment::source.

This Fragment is considered invalid if this range is out of order or either end of it is not on a char boundary in source according to str::is_char_boundary.

Implementations

impl Fragment

pub fn is_valid(&self) -> bool

Check that this Fragment is valid, and references a real existing (though possibly empty) part of the Fragment::source.

pub fn as_str(&self) -> &str

Get the str represented by this Fragment.

Panics

• This will panic in the unlikely event that Fragment::range is out of bounds or lands between char boundaries for Fragment::source.

pub const fn len(&self) -> usize

Get the length (in bytes) of this Fragment. Does not check this Fragment for validity.

pub const fn is_empty(&self) -> bool

Check if this fragment has a Fragment::len == 0. Does not check this Fragment for validity.

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

Return true if this Fragment entirely contains another Fragment and they’re from the same Source by Source::id.

If other is empty, it can still be considered to be contained in this Fragment if its Fragment::range is entirely within self’s Fragment::range (basically whether the location of the empty fragment is in this one).

pub fn offset_from(&self, origin: &Self) -> usize

Get the number of bytes between the beginning of origin and the beginning of self.

Panics:

• Panics if self is not a Fragment within origin according to Fragment::contains.

pub fn chars(&self) -> Chars<'_>

Get a Chars Iterator over the characters in this Fragment.

pub fn trimmed(self) -> Self

Get a sub-fragment of this fragment (see Fragment::contains) with the whitespace at either end trimmed off. This will return the fragment unchanged if it is empty.

This calls Fragment::trim_start and then Fragment::trim_end internally and should match the behavior of str::trim.

If this returns an empty Fragment it will be at the end of the parent Fragment.

pub fn trim_end(self) -> Self

Get a sub-fragment of this fragment (see Fragment::contains) with the whitespace trimmed off the end. This will return it unchanged if empty.

See str::trim_end for exact behaviors.

pub fn trim_start(self) -> Self

Get a sub-fragment of this fragment (see Fragment::contains) with the whitespace trimmed off the start. This will return it unchanged if empty.

See str::trim_start for exact behaviors.

pub fn split_at(&self, bytes_from_start: usize) -> (Self, Self)

Split this Fragment into two sub-Fragments, the left containing the first bytes_from_start bytes, and the right containing the rest.

Panics

• This will panic if the provided bytes_from_start does not land on a unicode character boundary or is larger than the length of this fragment according to str::is_char_boundary.

pub fn split_at_unchecked(&self, bytes_from_start: usize) -> (Self, Self)

This is the same as Fragment::split_at except it does not check that the created fragments are valid or that either can call Fragment::as_str without panicking. Use with caution.

pub fn advance_by(&mut self, bytes: usize)

Move the start of this Fragment forward by a given number of bytes.

Panics

• Panics if the advancing by bytes would create an invalid Fragment.

pub fn advance_by_unchecked(&mut self, bytes: usize)

This is the same as Fragment::advance_by except without the bounds checking. Use carefully or the created Fragments will be invalid.

pub fn retain(&mut self, bytes: usize)

Retain up to bytes bytes of this Fragment.

Panics

• Panics if the updated Fragment would be invalid.

pub fn retain_unchecked(&mut self, bytes: usize)

This is the same as Fragment::retain except without the bounds checking. Use carefully or the created Fragments will be invalid.

pub fn line_indices(&self) -> Range<usize>

Get a Range of line indices (0-indexed, see Source::get_line) that this fragment overlaps.

pub fn starts_on_line(&self) -> usize

Get the line number (not index) that this line starts on.

This re-calculates Fragment::line_indices, which may be expensive on very large files, so use with care.

pub fn starting_col_index(&self) -> usize

Get the number of bytes between the start of the line that this Fragment starts on and the start of this Fragment

Trait Implementations

impl Clone for Fragment

fn clone(&self) -> Fragment

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Fragment

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

Formats the value using the given formatter.

impl Display for Fragment

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

Formats the value using the given formatter.

impl PartialEq for Fragment

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

Fragment equality is based on referencing the same Source using Arc::ptr_eq and having the same Fragment::range.

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 Fragment