Struct Utf8Paths0

pub struct Utf8Paths0 { /* private fields */ }

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 Utf8Paths0 implements IntoIterator<Item = &'a Utf8Path>.

Implementations

impl Utf8Paths0

pub fn new(buf: impl Into<String>) -> Self

Creates a new instance of Utf8Paths0 from a string with embedded nulls.

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

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

Creates a new instance of Utf8Paths0 from a Vec<u8>, performing a UTF-8 validation check on the buffer.

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

Errors

If any paths inside the string weren’t valid UTF-8, this returns the first path that failed to parse and the error returned.

pub fn new_forward_slashes(buf: impl Into<String>) -> Self

Creates a new instance of Utf8Paths0, 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 iter<'a>(&'a self) -> Box<dyn Iterator<Item = &'a Utf8Path> + 'a>

Iterates over the paths in this buffer.

Trait Implementations

impl Clone for Utf8Paths0

fn clone(&self) -> Utf8Paths0

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Utf8Paths0

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

Formats the value using the given formatter.

impl<'a> IntoIterator for &'a Utf8Paths0

type Item = &'a Utf8Path

The type of the elements being iterated over.

type IntoIter = Box<dyn Iterator<Item = &'a Utf8Path> + '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 Utf8Paths0

fn cmp(&self, other: &Utf8Paths0) -> 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 Utf8Paths0

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

fn partial_cmp(&self, other: &Utf8Paths0) -> 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 Eq for Utf8Paths0

impl StructuralPartialEq for Utf8Paths0