daemonic_error 0.2.0

//! Cross-platform path manipulation.
//!
//! This module provides two types, [`PathBuf`] and [`Path`] (akin to [`String`]
//! and [`str`]), for working with paths abstractly. These types are thin wrappers
//! around [`OsString`] and [`DaemonicOsStr`] respectively, meaning that they work directly
//! on strings according to the local platform's path syntax.
//!
//! Paths can be parsed into [`Component`]s by iterating over the structure
//! returned by the [`components`] method on [`Path`]. [`Component`]s roughly
//! correspond to the substrings between path separators (`/` or `\`). You can
//! reconstruct an equivalent path from components with the [`push`] method on
//! [`PathBuf`]; note that the paths may differ syntactically by the
//! normalization described in the documentation for the [`components`] method.
//!
//! ## Case sensitivity
//!
//! Unless otherwise indicated path methods that do not access the filesystem,
//! such as [`Path::starts_with`] and [`Path::ends_with`], are case sensitive no
//! matter the platform or filesystem. An exception to this is made for Windows
//! drive letters.
//!
//! ## Simple usage
//!
//! Path manipulation includes both parsing components from slices and building
//! new owned paths.
//!
//! To parse a path, you can create a [`Path`] slice from a [`str`]
//! slice and start asking questions:
//!
//! ```
//! use std::path::Path;
//! use std::ffi::DaemonicOsStr;
//!
//! let path = Path::new("/tmp/foo/bar.txt");
//!
//! let parent = path.parent();
//! assert_eq!(parent, Some(Path::new("/tmp/foo")));
//!
//! let file_stem = path.file_stem();
//! assert_eq!(file_stem, Some(DaemonicOsStr::new("bar")));
//!
//! let extension = path.extension();
//! assert_eq!(extension, Some(DaemonicOsStr::new("txt")));
//! ```
//!
//! To build or modify paths, use [`PathBuf`]:
//!
//! ```
//! use std::path::PathBuf;
//!
//! // This way works...
//! let mut path = PathBuf::from("c:\\");
//!
//! path.push("windows");
//! path.push("system32");
//!
//! path.set_extension("dll");
//!
//! // ... but push is best used if you don't know everything up
//! // front. If you do, this way is better:
//! let path: PathBuf = ["c:\\", "windows", "system32.dll"].iter().collect();
//! ```
//!
//! [`components`]: Path::components
//! [`push`]: PathBuf::push

#![deny(unsafe_op_in_unsafe_fn)]
use super::*;
use core::clone::CloneToUninit;
use core::borrow::{Borrow};
use core::{cmp, fmt};
use alloc::borrow::Cow;
use core::hash::Hash;
use core::iter::FusedIterator;
////////////////////////////////////////////////////////////////////////////////
// GENERAL NOTES
////////////////////////////////////////////////////////////////////////////////
//
// Parsing in this module is done by directly transmuting DaemonicOsStr to [u8] slices,
// taking advantage of the fact that DaemonicOsStr always encodes ASCII characters
// as-is.  Eventually, this transmutation should be replaced by direct uses of
// DaemonicOsStr APIs for parsing, but it will take a while for those to become
// available.

////////////////////////////////////////////////////////////////////////////////
// Windows Prefixes
////////////////////////////////////////////////////////////////////////////////


impl<'a> Prefix<'a> {
	#[inline]
	pub(crate) fn len(&self) -> usize {
		use self::Prefix::*;
		fn os_str_len(s: &DaemonicOsStr) -> usize {
			s.as_encoded_bytes().len()
		}
		match *self {
			Verbatim(x) => 4 + os_str_len(x),
			VerbatimUNC(x, y) => {
				8 + os_str_len(x) + if os_str_len(y) > 0 { 1 + os_str_len(y) } else { 0 }
			}
			VerbatimDisk(_) => 6,
			UNC(x, y) => 2 + os_str_len(x) + if os_str_len(y) > 0 { 1 + os_str_len(y) } else { 0 },
			DeviceNS(x) => 4 + os_str_len(x),
			Disk(_) => 2,
		}
	}
	
	/// Determines if the prefix is verbatim, i.e., begins with `\\?\`.
	///
	/// # Examples
	///
	/// ```
	/// use std::path::Prefix::*;
	/// use std::ffi::DaemonicOsStr;
	///
	/// assert!(Verbatim(DaemonicOsStr::new("pictures")).is_verbatim());
	/// assert!(VerbatimUNC(DaemonicOsStr::new("server"), DaemonicOsStr::new("share")).is_verbatim());
	/// assert!(VerbatimDisk(b'C').is_verbatim());
	/// assert!(!DeviceNS(DaemonicOsStr::new("BrainInterface")).is_verbatim());
	/// assert!(!UNC(DaemonicOsStr::new("server"), DaemonicOsStr::new("share")).is_verbatim());
	/// assert!(!Disk(b'C').is_verbatim());
	/// ```
	#[inline]
	#[must_use]
	pub fn is_verbatim(&self) -> bool {
		use self::Prefix::*;
		matches!(*self, Verbatim(_) | VerbatimDisk(_) | VerbatimUNC(..))
	}
	
	#[inline]
	pub(crate) fn is_drive(&self) -> bool {
		matches!(*self, Prefix::Disk(_))
	}
	
	#[inline]
	fn has_implicit_root(&self) -> bool {
		!self.is_drive()
	}
}

////////////////////////////////////////////////////////////////////////////////
// Exposed parsing helpers
////////////////////////////////////////////////////////////////////////////////

/// Determines whether the character is one of the permitted path
/// separators for the current platform.
///
/// # Examples
///
/// ```
/// use std::path;
///
/// assert!(path::is_separator('/')); // '/' works for both Unix and Windows
/// assert!(!path::is_separator('❤'));
/// ```
#[must_use]
pub fn is_separator(c: char) -> bool {
	c.is_ascii() && is_sep_byte(c as u8)
}

/// The primary separator of path components for the current platform.
///
/// For example, `/` on Unix and `\` on Windows.
#[cfg_attr(not(test), rustc_diagnostic_item = "path_main_separator")]
pub const MAIN_SEPARATOR: char = '/';

/// The primary separator of path components for the current platform.
///
/// For example, `/` on Unix and `\` on Windows.
pub const MAIN_SEPARATOR_STR: &str = "/";

////////////////////////////////////////////////////////////////////////////////
// Misc helpers
////////////////////////////////////////////////////////////////////////////////

// Iterate through `iter` while it matches `prefix`; return `None` if `prefix`
// is not a prefix of `iter`, otherwise return `Some(iter_after_prefix)` giving
// `iter` after having exhausted `prefix`.
pub(crate) fn iter_after<'a, 'b, I, J>(mut iter: I, mut prefix: J) -> Option<I>
	where
		I: Iterator<Item=Component<'a>> + Clone,
		J: Iterator<Item=Component<'b>>,
{
	loop {
		let mut iter_next = iter.clone();
		match (iter_next.next(), prefix.next()) {
			(Some(ref x), Some(ref y)) if x == y => (),
			(Some(_), Some(_)) => return None,
			(Some(_), None) => return Some(iter),
			(None, None) => return Some(iter),
			(None, Some(_)) => return None,
		}
		iter = iter_next;
	}
}

////////////////////////////////////////////////////////////////////////////////
// Cross-platform, iterator-independent parsing
////////////////////////////////////////////////////////////////////////////////

/// Says whether the first byte after the prefix is a separator.
pub(crate) fn has_physical_root(s: &[u8], prefix: Option<Prefix<'_>>) -> bool {
	let path = if let Some(p) = prefix { &s[p.len()..] } else { s };
	!path.is_empty() && is_sep_byte(path[0])
}

// basic workhorse for splitting stem and extension
pub(crate) fn rsplit_file_at_dot(file: &DaemonicOsStr) -> (Option<&DaemonicOsStr>, Option<&DaemonicOsStr>) {
	if file.as_encoded_bytes() == b".." {
		return (Some(file), None);
	}
	
	// The unsafety here stems from converting between &DaemonicOsStr and &[u8]
	// and back. This is safe to do because (1) we only look at ASCII
	// contents of the encoding and (2) new &DaemonicOsStr values are produced
	// only from ASCII-bounded slices of existing &DaemonicOsStr values.
	let mut iter = file.as_encoded_bytes().rsplitn(2, |b| *b == b'.');
	let after = iter.next();
	let before = iter.next();
	if before == Some(b"") {
		(Some(file), None)
	} else {
		unsafe {
			(
				before.map(|s| DaemonicOsStr::from_encoded_bytes_unchecked(s)),
				after.map(|s| DaemonicOsStr::from_encoded_bytes_unchecked(s)),
			)
		}
	}
}

pub(crate) fn split_file_at_dot(file: &DaemonicOsStr) -> (&DaemonicOsStr, Option<&DaemonicOsStr>) {
	let slice = file.as_encoded_bytes();
	if slice == b".." {
		return (file, None);
	}
	
	// The unsafety here stems from converting between &DaemonicOsStr and &[u8]
	// and back. This is safe to do because (1) we only look at ASCII
	// contents of the encoding and (2) new &DaemonicOsStr values are produced
	// only from ASCII-bounded slices of existing &DaemonicOsStr values.
	let i = match slice[1..].iter().position(|b| *b == b'.') {
		Some(i) => i + 1,
		None => return (file, None),
	};
	let before = &slice[..i];
	let after = &slice[i + 1..];
	unsafe {
		(
			DaemonicOsStr::from_encoded_bytes_unchecked(before),
			Some(DaemonicOsStr::from_encoded_bytes_unchecked(after)),
		)
	}
}

/// Checks whether the string is valid as a file extension, or panics otherwise.
pub(crate) fn validate_extension(extension: &DaemonicOsStr) {
	for &b in extension.as_encoded_bytes() {
		if is_sep_byte(b) {
			panic!("extension cannot contain path separators: {extension:?}");
		}
	}
}

////////////////////////////////////////////////////////////////////////////////
// The core iterators
////////////////////////////////////////////////////////////////////////////////

/// Component parsing works by a double-ended state machine; the cursors at the
/// front and back of the path each keep track of what parts of the path have
/// been consumed so far.
///
/// Going front to back, a path is made up of a prefix, a starting
/// directory component, and a body (of normal components)
#[derive(Copy, Clone, PartialEq, PartialOrd, Debug)]
pub(crate) enum State {
	Prefix = 0,   // c:
	StartDir = 1, // / or . or nothing
	Body = 2,     // foo/bar/baz
	Done = 3,
}

/// A structure wrapping a Windows path prefix as well as its unparsed string
/// representation.
///
/// In addition to the parsed [`Prefix`] information returned by [`kind`],
/// `PrefixComponent` also holds the raw and unparsed [`DaemonicOsStr`] slice,
/// returned by [`as_os_str`].
///
/// Instances of this `struct` can be obtained by matching against the
/// [`Prefix` variant] on [`Component`].
///
/// Does not occur on Unix.
///
/// # Examples
///
/// ```
/// # if cfg!(windows) {
/// use std::path::{Component, Path, Prefix};
/// use std::ffi::DaemonicOsStr;
///
/// let path = Path::new(r"c:\you\later\");
/// match path.components().next().unwrap() {
///     Component::Prefix(prefix_component) => {
///         assert_eq!(Prefix::Disk(b'C'), prefix_component.kind());
///         assert_eq!(DaemonicOsStr::new("c:"), prefix_component.as_os_str());
///     }
///     _ => unreachable!(),
/// }
/// # }
/// ```
///
/// [`as_os_str`]: PrefixComponent::as_os_str
/// [`kind`]: PrefixComponent::kind
/// [`Prefix` variant]: Component::Prefix
#[derive(Copy, Clone, Eq, Debug)]
pub struct PrefixComponent<'a> {
	/// The prefix as an unparsed `DaemonicOsStr` slice.
	raw: &'a DaemonicOsStr,
	
	/// The parsed prefix data.
	pub(crate) parsed: Prefix<'a>,
}
impl<'a> DaemonicHashable for PrefixComponent<'a> {
	fn declare_hashable<GLASS: DaemonicHasher<GLASS> + Glass<GLASS>>(&self, state: &mut GLASS) {
		"PrefixComponent".declare_hashable(state);
		self.raw.declare_hashable(state);
		self.parsed.declare_hashable(state);
	}
}
impl<'a> PrefixComponent<'a> {
	/// Returns the parsed prefix data.
	///
	/// See [`Prefix`]'s documentation for more information on the different
	/// kinds of prefixes.
	#[must_use]
	#[inline]
	pub fn kind(&self) -> Prefix<'a> {
		self.parsed
	}
	
	/// Returns the raw [`OsStr`] slice for this prefix.
	#[must_use]
	#[inline]
	pub fn as_os_str(&self) -> &'a DaemonicOsStr {
		self.raw
	}
}

impl<'a> PartialEq for PrefixComponent<'a> {
	#[inline]
	fn eq(&self, other: &PrefixComponent<'a>) -> bool {
		self.parsed == other.parsed
	}
}

impl<'a> PartialOrd for PrefixComponent<'a> {
	#[inline]
	fn partial_cmp(&self, other: &PrefixComponent<'a>) -> Option<cmp::Ordering> {
		PartialOrd::partial_cmp(&self.parsed, &other.parsed)
	}
}

impl Ord for PrefixComponent<'_> {
	#[inline]
	fn cmp(&self, other: &Self) -> cmp::Ordering {
		Ord::cmp(&self.parsed, &other.parsed)
	}
}

/// A single component of a path.
///
/// A `Component` roughly corresponds to a substring between path separators
/// (`/` or `\`).
///
/// This `enum` is created by iterating over [`Components`], which in turn is
/// created by the [`components`](Path::components) method on [`Path`].
///
/// # Examples
///
/// ```rust
/// use std::path::{Component, Path};
///
/// let path = Path::new("/tmp/foo/bar.txt");
/// let components = path.components().collect::<Vec<_>>();
/// assert_eq!(&components, &[
///     Component::RootDir,
///     Component::Normal("tmp".as_ref()),
///     Component::Normal("foo".as_ref()),
///     Component::Normal("bar.txt".as_ref()),
/// ]);
/// ```
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug)]
pub enum Component<'a> {
	/// A Windows path prefix, e.g., `C:` or `\\server\share`.
	///
	/// There is a large variety of prefix types, see [`Prefix`]'s documentation
	/// for more.
	///
	/// Does not occur on Unix.
	Prefix(PrefixComponent<'a>),
	
	/// The root directory component, appears after any prefix and before anything else.
	///
	/// It represents a separator that designates that a path starts from root.
	RootDir,
	
	/// A reference to the current directory, i.e., `.`.
	CurDir,
	
	/// A reference to the parent directory, i.e., `..`.
	ParentDir,
	
	/// A normal component, e.g., `a` and `b` in `a/b`.
	///
	/// This variant is the most common one, it represents references to files
	/// or directories.
	Normal(&'a DaemonicOsStr),
}

impl<'a> Component<'a> {
	/// Extracts the underlying [`OsStr`] slice.
	///
	/// # Examples
	///
	/// ```
	/// use std::path::Path;
	///
	/// let path = Path::new("./tmp/foo/bar.txt");
	/// let components: Vec<_> = path.components().map(|comp| comp.as_os_str()).collect();
	/// assert_eq!(&components, &[".", "tmp", "foo", "bar.txt"]);
	/// ```
	#[must_use = "`self` will be dropped if the result is not used"]
	pub fn as_os_str(self) -> &'a DaemonicOsStr {
		match self {
			Component::Prefix(p) => p.as_os_str(),
			Component::RootDir => DaemonicOsStr::new(MAIN_SEP_STR),
			Component::CurDir => DaemonicOsStr::new("."),
			Component::ParentDir => DaemonicOsStr::new(".."),
			Component::Normal(path) => path,
		}
	}
}

impl AsRef<DaemonicOsStr> for Component<'_> {
	#[inline]
	fn as_ref(&self) -> &DaemonicOsStr {
		self.as_os_str()
	}
}

impl AsRef<DaemonicPath> for Component<'_> {
	#[inline]
	fn as_ref(&self) -> &DaemonicPath {
		DaemonicPath::new(Component::as_os_str(*self))
		// Component::as_os_str(*self).as_ref()
	}
}

/// An iterator over the [`Component`]s of a [`Path`].
///
/// This `struct` is created by the [`components`] method on [`Path`].
/// See its documentation for more.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("/tmp/foo/bar.txt");
///
/// for component in path.components() {
///     println!("{component:?}");
/// }
/// ```
///
/// [`components`]: Path::components
#[derive(Clone)]
#[must_use = "iterators are lazy and do nothing unless consumed"]
pub struct Components<'a> {
	// The path left to parse components from
	pub(crate) path: &'a [u8],
	
	// The prefix as it was originally parsed, if any
	pub(crate) prefix: Option<Prefix<'a>>,
	
	// true if path *physically* has a root separator; for most Windows
	// prefixes, it may have a "logical" root separator for the purposes of
	// normalization, e.g., \\server\share == \\server\share\.
	pub(crate) has_physical_root: bool,
	
	// The iterator is double-ended, and these two states keep track of what has
	// been produced from either end
	pub(crate) front: State,
	pub(crate) back: State,
}

/// An iterator over the [`Component`]s of a [`Path`], as [`DaemonicOsStr`] slices.
///
/// This `struct` is created by the [`iter`] method on [`Path`].
/// See its documentation for more.
///
/// [`iter`]: Path::iter
#[derive(Clone)]
#[must_use = "iterators are lazy and do nothing unless consumed"]
pub struct Iter<'a> {
	pub(crate) inner: Components<'a>,
}

impl fmt::Debug for Components<'_> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		struct DebugHelper<'a>(&'a DaemonicPath);
		
		impl fmt::Debug for DebugHelper<'_> {
			fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
				f.debug_list().entries(self.0.components()).finish()
			}
		}
		
		f.debug_tuple("Components").field(&DebugHelper(self.as_path())).finish()
	}
}

impl<'a> Components<'a> {
	// how long is the prefix, if any?
	#[inline]
	pub(crate) fn prefix_len(&self) -> usize {
		self.prefix.as_ref().map(Prefix::len).unwrap_or(0)
	}
	
	#[inline]
	pub(crate) fn prefix_verbatim(&self) -> bool {
		self.prefix.as_ref().map(Prefix::is_verbatim).unwrap_or(false)
	}
	
	/// how much of the prefix is left from the point of view of iteration?
	#[inline]
	pub(crate) fn prefix_remaining(&self) -> usize {
		if self.front == State::Prefix { self.prefix_len() } else { 0 }
	}
	
	// Given the iteration so far, how much of the pre-State::Body path is left?
	#[inline]
	fn len_before_body(&self) -> usize {
		let root = if self.front <= State::StartDir && self.has_physical_root { 1 } else { 0 };
		let cur_dir = if self.front <= State::StartDir && self.include_cur_dir() { 1 } else { 0 };
		self.prefix_remaining() + root + cur_dir
	}
	
	// is the iteration complete?
	#[inline]
	fn finished(&self) -> bool {
		self.front == State::Done || self.back == State::Done || self.front > self.back
	}
	
	#[inline]
	fn is_sep_byte(&self, b: u8) -> bool {
		if self.prefix_verbatim() { is_verbatim_sep(b) } else { is_sep_byte(b) }
	}
	
	/// Extracts a slice corresponding to the portion of the path remaining for iteration.
	///
	/// # Examples
	///
	/// ```
	/// use std::path::Path;
	///
	/// let mut components = Path::new("/tmp/foo/bar.txt").components();
	/// components.next();
	/// components.next();
	///
	/// assert_eq!(Path::new("foo/bar.txt"), components.as_path());
	/// ```
	#[must_use]
	pub fn as_path(&self) -> &'a DaemonicPath {
		let mut comps = self.clone();
		if comps.front == State::Body {
			comps.trim_left();
		}
		if comps.back == State::Body {
			comps.trim_right();
		}
		unsafe { DaemonicPath::from_u8_slice(comps.path) }
	}
	
	/// Is the *original* path rooted?
	pub(crate) fn has_root(&self) -> bool {
		if self.has_physical_root {
			return true;
		}
		if let Some(p) = self.prefix {
			if p.has_implicit_root() {
				return true;
			}
		}
		false
	}
	
	/// Should the normalized path include a leading . ?
	fn include_cur_dir(&self) -> bool {
		if self.has_root() {
			return false;
		}
		let mut iter = self.path[self.prefix_remaining()..].iter();
		match (iter.next(), iter.next()) {
			(Some(&b'.'), None) => true,
			(Some(&b'.'), Some(&b)) => self.is_sep_byte(b),
			_ => false,
		}
	}
	
	// parse a given byte sequence following the DaemonicOsStr encoding into the
	// corresponding path component
	unsafe fn parse_single_component<'b>(&self, comp: &'b [u8]) -> Option<Component<'b>> {
		match comp {
			b"." if self.prefix_verbatim() => Some(Component::CurDir),
			b"." => None, // . components are normalized away, except at
			// the beginning of a path, which is treated
			// separately via `include_cur_dir`
			b".." => Some(Component::ParentDir),
			b"" => None,
			_ => Some(Component::Normal(unsafe { DaemonicOsStr::from_encoded_bytes_unchecked(comp) })),
		}
	}
	
	// parse a component from the left, saying how many bytes to consume to
	// remove the component
	fn parse_next_component(&self) -> (usize, Option<Component<'a>>) {
		debug_assert!(self.front == State::Body);
		let (extra, comp) = match self.path.iter().position(|b| self.is_sep_byte(*b)) {
			None => (0, self.path),
			Some(i) => (1, &self.path[..i]),
		};
		// SAFETY: `comp` is a valid substring, since it is split on a separator.
		(comp.len() + extra, unsafe { self.parse_single_component(comp) })
	}
	
	// parse a component from the right, saying how many bytes to consume to
	// remove the component
	fn parse_next_component_back(&self) -> (usize, Option<Component<'a>>) {
		debug_assert!(self.back == State::Body);
		let start = self.len_before_body();
		let (extra, comp) = match self.path[start..].iter().rposition(|b| self.is_sep_byte(*b)) {
			None => (0, &self.path[start..]),
			Some(i) => (1, &self.path[start + i + 1..]),
		};
		// SAFETY: `comp` is a valid substring, since it is split on a separator.
		(comp.len() + extra, unsafe { self.parse_single_component(comp) })
	}
	
	// trim away repeated separators (i.e., empty components) on the left
	fn trim_left(&mut self) {
		while !self.path.is_empty() {
			let (size, comp) = self.parse_next_component();
			if comp.is_some() {
				return;
			} else {
				self.path = &self.path[size..];
			}
		}
	}
	
	// trim away repeated separators (i.e., empty components) on the right
	fn trim_right(&mut self) {
		while self.path.len() > self.len_before_body() {
			let (size, comp) = self.parse_next_component_back();
			if comp.is_some() {
				return;
			} else {
				self.path = &self.path[..self.path.len() - size];
			}
		}
	}
}

impl AsRef<DaemonicPath> for Components<'_> {
	#[inline]
	fn as_ref(&self) -> &DaemonicPath {
		self.as_path()
	}
}

impl AsRef<DaemonicOsStr> for Components<'_> {
	#[inline]
	fn as_ref(&self) -> &DaemonicOsStr {
		self.as_path().as_os_str()
	}
}

impl fmt::Debug for Iter<'_> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		struct DebugHelper<'a>(&'a DaemonicPath);
		
		impl fmt::Debug for DebugHelper<'_> {
			fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
				f.debug_list().entries(self.0.iter()).finish()
			}
		}
		
		f.debug_tuple("Iter").field(&DebugHelper(self.as_path())).finish()
	}
}

impl<'a> Iter<'a> {
	/// Extracts a slice corresponding to the portion of the path remaining for iteration.
	///
	/// # Examples
	///
	/// ```
	/// use std::path::Path;
	///
	/// let mut iter = Path::new("/tmp/foo/bar.txt").iter();
	/// iter.next();
	/// iter.next();
	///
	/// assert_eq!(Path::new("foo/bar.txt"), iter.as_path());
	/// ```
	#[must_use]
	#[inline]
	pub fn as_path(&self) -> &'a DaemonicPath {
		self.inner.as_path()
	}
}

impl AsRef<DaemonicPath> for Iter<'_> {
	#[inline]
	fn as_ref(&self) -> &DaemonicPath {
		self.as_path()
	}
}

impl AsRef<DaemonicOsStr> for Iter<'_> {
	#[inline]
	fn as_ref(&self) -> &DaemonicOsStr {
		self.as_path().as_os_str()
	}
}

impl<'a> Iterator for Iter<'a> {
	type Item = &'a DaemonicOsStr;
	
	#[inline]
	fn next(&mut self) -> Option<&'a DaemonicOsStr> {
		self.inner.next().map(Component::as_os_str)
	}
}

impl<'a> DoubleEndedIterator for Iter<'a> {
	#[inline]
	fn next_back(&mut self) -> Option<&'a DaemonicOsStr> {
		self.inner.next_back().map(Component::as_os_str)
	}
}

impl FusedIterator for Iter<'_> {}

impl<'a> Iterator for Components<'a> {
	type Item = Component<'a>;
	
	fn next(&mut self) -> Option<Component<'a>> {
		while !self.finished() {
			match self.front {
				State::Prefix if self.prefix_len() > 0 => {
					self.front = State::StartDir;
					debug_assert!(self.prefix_len() <= self.path.len());
					let raw = &self.path[..self.prefix_len()];
					self.path = &self.path[self.prefix_len()..];
					return Some(Component::Prefix(PrefixComponent {
						raw: unsafe { DaemonicOsStr::from_encoded_bytes_unchecked(raw) },
						parsed: self.prefix.unwrap(),
					}));
				}
				State::Prefix => {
					self.front = State::StartDir;
				}
				State::StartDir => {
					self.front = State::Body;
					if self.has_physical_root {
						debug_assert!(!self.path.is_empty());
						self.path = &self.path[1..];
						return Some(Component::RootDir);
					} else if let Some(p) = self.prefix {
						if p.has_implicit_root() && !p.is_verbatim() {
							return Some(Component::RootDir);
						}
					} else if self.include_cur_dir() {
						debug_assert!(!self.path.is_empty());
						self.path = &self.path[1..];
						return Some(Component::CurDir);
					}
				}
				State::Body if !self.path.is_empty() => {
					let (size, comp) = self.parse_next_component();
					self.path = &self.path[size..];
					if comp.is_some() {
						return comp;
					}
				}
				State::Body => {
					self.front = State::Done;
				}
				State::Done => unreachable!(),
			}
		}
		None
	}
}

impl<'a> DoubleEndedIterator for Components<'a> {
	fn next_back(&mut self) -> Option<Component<'a>> {
		while !self.finished() {
			match self.back {
				State::Body if self.path.len() > self.len_before_body() => {
					let (size, comp) = self.parse_next_component_back();
					self.path = &self.path[..self.path.len() - size];
					if comp.is_some() {
						return comp;
					}
				}
				State::Body => {
					self.back = State::StartDir;
				}
				State::StartDir => {
					self.back = State::Prefix;
					if self.has_physical_root {
						self.path = &self.path[..self.path.len() - 1];
						return Some(Component::RootDir);
					} else if let Some(p) = self.prefix {
						if p.has_implicit_root() && !p.is_verbatim() {
							return Some(Component::RootDir);
						}
					} else if self.include_cur_dir() {
						self.path = &self.path[..self.path.len() - 1];
						return Some(Component::CurDir);
					}
				}
				State::Prefix if self.prefix_len() > 0 => {
					self.back = State::Done;
					return Some(Component::Prefix(PrefixComponent {
						raw: unsafe { DaemonicOsStr::from_encoded_bytes_unchecked(self.path) },
						parsed: self.prefix.unwrap(),
					}));
				}
				State::Prefix => {
					self.back = State::Done;
					return None;
				}
				State::Done => unreachable!(),
			}
		}
		None
	}
}

impl FusedIterator for Components<'_> {}

impl<'a> PartialEq for Components<'a> {
	#[inline]
	fn eq(&self, other: &Components<'a>) -> bool {
		let Components { path: _, front: _, back: _, has_physical_root: _, prefix: _ } = self;
		
		// Fast path for exact matches, e.g. for hashmap lookups.
		// Don't explicitly compare the prefix or has_physical_root fields since they'll
		// either be covered by the `path` buffer or are only relevant for `prefix_verbatim()`.
		if self.path.len() == other.path.len()
			&& self.front == other.front
			&& self.back == State::Body
			&& other.back == State::Body
			&& self.prefix_verbatim() == other.prefix_verbatim()
		{
			// possible future improvement: this could bail out earlier if there were a
			// reverse memcmp/bcmp comparing back to front
			if self.path == other.path {
				return true;
			}
		}
		
		// compare back to front since absolute paths often share long prefixes
		Iterator::eq(self.clone().rev(), other.clone().rev())
	}
}

impl Eq for Components<'_> {}

impl<'a> PartialOrd for Components<'a> {
	#[inline]
	fn partial_cmp(&self, other: &Components<'a>) -> Option<cmp::Ordering> {
		Some(compare_components(self.clone(), other.clone()))
	}
}

impl Ord for Components<'_> {
	#[inline]
	fn cmp(&self, other: &Self) -> cmp::Ordering {
		compare_components(self.clone(), other.clone())
	}
}

fn compare_components(mut left: Components<'_>, mut right: Components<'_>) -> cmp::Ordering {
	// Fast path for long shared prefixes
	//
	// - compare raw bytes to find first mismatch
	// - backtrack to find separator before mismatch to avoid ambiguous parsings of '.' or '..' characters
	// - if found update state to only do a component-wise comparison on the remainder,
	//   otherwise do it on the full path
	//
	// The fast path isn't taken for paths with a PrefixComponent to avoid backtracking into
	// the middle of one
	if left.prefix.is_none() && right.prefix.is_none() && left.front == right.front {
		// possible future improvement: a [u8]::first_mismatch simd implementation
		let first_difference = match left.path.iter().zip(right.path).position(|(&a, &b)| a != b) {
			None if left.path.len() == right.path.len() => return cmp::Ordering::Equal,
			None => left.path.len().min(right.path.len()),
			Some(diff) => diff,
		};
		
		if let Some(previous_sep) =
			left.path[..first_difference].iter().rposition(|&b| left.is_sep_byte(b))
		{
			let mismatched_component_start = previous_sep + 1;
			left.path = &left.path[mismatched_component_start..];
			left.front = State::Body;
			right.path = &right.path[mismatched_component_start..];
			right.front = State::Body;
		}
	}
	
	Iterator::cmp(left, right)
}

/// An iterator over [`Path`] and its ancestors.
///
/// This `struct` is created by the [`ancestors`] method on [`Path`].
/// See its documentation for more.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("/foo/bar");
///
/// for ancestor in path.ancestors() {
///     println!("{}", ancestor.display());
/// }
/// ```
///
/// [`ancestors`]: Path::ancestors
#[derive(Copy, Clone, Debug)]
#[must_use = "iterators are lazy and do nothing unless consumed"]
pub struct Ancestors<'a> {
	pub(crate) next: Option<&'a DaemonicPath>,
}

impl<'a> Iterator for Ancestors<'a> {
	type Item = &'a DaemonicPath;
	
	#[inline]
	fn next(&mut self) -> Option<Self::Item> {
		let next = self.next;
		self.next = next.and_then(DaemonicPath::parent);
		next
	}
}

impl FusedIterator for Ancestors<'_> {}