Struct Source

pub struct Source {
    pub id: SourceId,
    /* private fields */
}

Available on crate feature source-tracking only.

A full source. This is usually a file, but may also be passed in the form of a string for testing.

Fields

id: SourceId

Globally (process-wide) unique Source ID.

It is fequently useful to have a consistient way to sort sources and check for equality between sources. This cannot be done with the Source::name since that can be FileName::None, and checking for equality of content can be an expensive process.

The id of a Source is an identifier that’s globally unique for the runtime of the program, and is assigned to the Source when it is instantiated.

Implementations

impl Source

pub fn new_from_string(name: FileName, source: String) -> Self

Create a Source using a heap allocated String.

pub fn new_from_static_str(name: FileName, source: &'static str) -> Self

Create a Source from a &'static str.

pub fn new_mapped_from_disk(path: PathBuf) -> Result<Self>

Available on crate feature file_memmap only.

Attempt to memory map a file from the disk into a Source. This will likely be faster than reading the file in some cases, and almost always more memory efficient.

This requires the “file_memmap” feature.

pub fn new_read_from_disk(path: PathBuf) -> Result<Self>

Read a file from the disk into a source. This reads the file, which may take longer than memory mapping it as done in Self::new_mapped_from_disk. This does not require the same features and dependencies as memory mapped operations though. This stores the whole file in memory, rather than mapping virtual memory to the disk. That makes this less memory efficient than Self::new_mapped_from_disk, which may be important on systems where ram is constrained.

Use this if the “file_memmap” is not available for some reason.

pub fn line_starts(&self) -> &[usize]

Get byte indices of where lines start in this Source.

pub fn count_lines(&self) -> usize

Get the number of lines in this Source. This is identical to Self::line_starts length.

pub fn line_index(&self, byte_index: usize) -> usize

Get the line index that a byte index is on in this Source.

If the byte index is greater than the length of the Source then the highest possible index will be returned.

pub fn get_line(self: Arc<Source>, line_index: usize) -> Fragment

Get a line of this Source as a Fragment. The returned Fragment will contain the line terminating characters at the end of it. If you don’t want those, use Fragment::trim_end.

Note that this uses line_index which is considered 0-indexed – when displaying line numbers to the user, remember to add 1.

Panics

• This will panic if you ask for a line index that’s higher than or equal to the number returned by Self::count_lines.

pub fn lines(self: SourceRef) -> impl Iterator<Item = Fragment>

Get an iterator over all the lines of this Source. This calls Source::get_line for each element of the returned iterator.

The returned Fragments will contain the line terminating characters at the end of them. If you don’t want those, use Iterator::map and Fragment::trim_end.

pub const fn source(&self) -> &ImmutableString

Get the the source code stored.

pub const fn name(&self) -> &FileName

Get the name of this Source.

pub fn as_fragment(self: SourceRef) -> Fragment

Get the entire content of this Source as a Fragment.

Trait Implementations

impl Debug for Source

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

Formats the value using the given formatter.