Struct determinator::Paths0

pub struct Paths0 { /* fields omitted */ }

A store for null-separated paths.

This manages paths on Unix and Windows platforms, including converting / on Windows to \.

Null-separated paths

Paths as produced by tools like git diff --name-only are typically separated by newline characters (\n). However, on Unix platforms filenames can themselves have newlines embedded in them, so source control systems often end up quoting newlines and other "unusual" characters.

A robust, lossless way to retrieve a list of paths is by separating them with null characters. Both Unix and Windows platforms guarantee that a path can never have embedded null characters.

Examples

Most source control systems can provide null-separated paths. These examples are expected to be run from the Cargo workspace root (which is assumed to be the same as the repository root).

In most cases, you'll want to compare the current working directory against the merge base, or nearest/greatest/lowest common ancestor, of the current commit with a specified upstream revision, such as origin/main. To do so, run:

• Git: git diff -z --name-only $(git merge-base <upstream rev> HEAD)
• Mercurial: hg status --print0 -mard --no-status --rev 'ancestor(<upstream rev>,.)'

---

NOTE:

• The $() syntax in Bash and other shells means "run the command and insert its contents here".
• Git provides a syntax <upstream rev>... which purports to use the merge base, but it ignores uncommitted changes. Executing git merge-base as a separate command is the only way to include uncommitted changes.
• The -mard flag to hg status means that untracked files are not included. git diff does not have an option to display untracked files. For more discussion, see the documentation for add_changed_paths.

---

In general, to obtain a list of changed paths between two revisions (omit <new rev> if comparing against the working directory):

• Git: git diff -z --name-only <old rev> <new rev>
• Mercurial: hg status --print0 -mard --no-status <old rev> <new rev>

To obtain a list of all files in the working directory that are tracked by the source control system:

• Git: git ls-files -z
• Mercurial: hg files --print0

Null-separated paths are produced through the -z option to Git commands, or the --print0 option to Mercurial. If you're using a different system, check its help for instructions.

Implementations

&'a Paths0 implements IntoIterator<Item = &'a Path>.

Implementations

impl Paths0

pub fn new(buf: impl Into<Vec<u8>>) -> Result<Self, (Vec<u8>, Utf8Error)>

Creates a new instance of Paths0 from a buffer.

The buffer may, but does not need to, have a trailing byte.

Errors

On Unixes this supports arbitrary paths and is infallible.

On other platforms like Windows, this only supports paths encoded as UTF-8. Any others will return an error containing:

• the first path that failed to parse
• the Utf8Error that it returned.

pub fn new_forward_slashes(
    buf: impl Into<Vec<u8>>
) -> Result<Self, (Vec<u8>, Utf8Error)>

Creates a new instance of Paths0, converting / to \ on platforms like Windows.

Some tools like Git (but not Mercurial) return paths with / on Windows, even though the canonical separator on the platform is \. This constructor changes all instances of / to \.

pub fn new_unix(buf: impl Into<Vec<u8>>) -> Self

Creates a new instance of Paths0 on Unix platforms.

This is infallible, but is only available on Unix platforms.

pub fn iter<'a>(&'a self) -> Box<dyn Iterator<Item = &'a Path> + 'a>

Iterates over the paths in this buffer.

Trait Implementations

impl Clone for Paths0

fn clone(&self) -> Paths0

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Paths0

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

Formats the value using the given formatter.

impl Eq for Paths0

impl<'a> IntoIterator for &'a Paths0

type Item = &'a Path

The type of the elements being iterated over.

type IntoIter = Box<dyn Iterator<Item = &'a Path> + 'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl Ord for Paths0

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

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<Paths0> for Paths0

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl PartialOrd<Paths0> for Paths0

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl StructuralEq for Paths0

impl StructuralPartialEq for Paths0