path.rs source code [crates/std/src/path.rs]

1	//! Cross-platform path manipulation.
2	//!
3	//! This module provides two types, [`PathBuf`] and [`Path`] (akin to [`String`]
4	//! and [`str`]), for working with paths abstractly. These types are thin wrappers
5	//! around [`OsString`] and [`OsStr`] respectively, meaning that they work directly
6	//! on strings according to the local platform's path syntax.
7	//!
8	//! Paths can be parsed into [`Component`]s by iterating over the structure
9	//! returned by the [`components`] method on [`Path`]. [`Component`]s roughly
10	//! correspond to the substrings between path separators (`/` or `\`). You can
11	//! reconstruct an equivalent path from components with the [`push`] method on
12	//! [`PathBuf`]; note that the paths may differ syntactically by the
13	//! normalization described in the documentation for the [`components`] method.
14	//!
15	//! ## Case sensitivity
16	//!
17	//! Unless otherwise indicated path methods that do not access the filesystem,
18	//! such as [`Path::starts_with`] and [`Path::ends_with`], are case sensitive no
19	//! matter the platform or filesystem. An exception to this is made for Windows
20	//! drive letters.
21	//!
22	//! ## Simple usage
23	//!
24	//! Path manipulation includes both parsing components from slices and building
25	//! new owned paths.
26	//!
27	//! To parse a path, you can create a [`Path`] slice from a [`str`]
28	//! slice and start asking questions:
29	//!
30	//! ```
31	//! use std::path::Path;
32	//! use std::ffi::OsStr;
33	//!
34	//! let path = Path::new("/tmp/foo/bar.txt");
35	//!
36	//! let parent = path.parent();
37	//! assert_eq!(parent, Some(Path::new("/tmp/foo")));
38	//!
39	//! let file_stem = path.file_stem();
40	//! assert_eq!(file_stem, Some(OsStr::new("bar")));
41	//!
42	//! let extension = path.extension();
43	//! assert_eq!(extension, Some(OsStr::new("txt")));
44	//! ```
45	//!
46	//! To build or modify paths, use [`PathBuf`]:
47	//!
48	//! ```
49	//! use std::path::PathBuf;
50	//!
51	//! // This way works...
52	//! let mut path = PathBuf::from("c:`\\`");
53	//!
54	//! path.push("windows");
55	//! path.push("system32");
56	//!
57	//! path.set_extension("dll");
58	//!
59	//! // ... but push is best used if you don't know everything up
60	//! // front. If you do, this way is better:
61	//! let path: PathBuf = ["c:`\\`", "windows", "system32.dll"].iter().collect();
62	//! ```
63	//!
64	//! [`components`]: Path::components
65	//! [`push`]: PathBuf::push
66
67	#![stable(feature = "rust1", since = "1.0.0")]
68	#![deny(unsafe_op_in_unsafe_fn)]
69
70	#[cfg(test)]
71	mod tests;
72
73	use crate::borrow::{Borrow, Cow};
74	use crate::cmp;
75	use crate::collections::TryReserveError;
76	use crate::error::Error;
77	use crate::fmt;
78	use crate::fs;
79	use crate::hash::{Hash, Hasher};
80	use crate::io;
81	use crate::iter::FusedIterator;
82	use crate::ops::{self, Deref};
83	use crate::rc::Rc;
84	use crate::str::FromStr;
85	use crate::sync::Arc;
86
87	use crate::ffi::{OsStr, OsString};
88	use crate::sys;
89	use crate::sys::path::{is_sep_byte, is_verbatim_sep, parse_prefix, MAIN_SEP_STR};
90
91	////////////////////////////////////////////////////////////////////////////////
92	// GENERAL NOTES
93	////////////////////////////////////////////////////////////////////////////////
94	//
95	// Parsing in this module is done by directly transmuting OsStr to [u8] slices,
96	// taking advantage of the fact that OsStr always encodes ASCII characters
97	// as-is. Eventually, this transmutation should be replaced by direct uses of
98	// OsStr APIs for parsing, but it will take a while for those to become
99	// available.
100
101	////////////////////////////////////////////////////////////////////////////////
102	// Windows Prefixes
103	////////////////////////////////////////////////////////////////////////////////
104
105	/// Windows path prefixes, e.g., `C:` or `\\server\share`.
106	///
107	/// Windows uses a variety of path prefix styles, including references to drive
108	/// volumes (like `C:`), network shared folders (like `\\server\share`), and
109	/// others. In addition, some path prefixes are "verbatim" (i.e., prefixed with
110	/// `\\?\`), in which case `/` is not* treated as a separator and essentially*
111	/// no normalization is performed.
112	///
113	/// # Examples
114	///
115	/// ```
116	/// use std::path::{Component, Path, Prefix};
117	/// use std::path::Prefix::*;
118	/// use std::ffi::OsStr;
119	///
120	/// fn get_path_prefix(s: &str) -> Prefix<'_> {
121	/// let path = Path::new(s);
122	/// match path.components().next().unwrap() {
123	/// Component::Prefix(prefix_component) => prefix_component.kind(),
124	/// _ => panic!(),
125	/// }
126	/// }
127	///
128	/// # if cfg!(windows) {
129	/// assert_eq!(Verbatim(OsStr::new("pictures")),
130	/// get_path_prefix(r"\\?\pictures\kittens"));
131	/// assert_eq!(VerbatimUNC(OsStr::new("server"), OsStr::new("share")),
132	/// get_path_prefix(r"\\?\UNC\server\share"));
133	/// assert_eq!(VerbatimDisk(b'C'), get_path_prefix(r"\\?\c:\"));
134	/// assert_eq!(DeviceNS(OsStr::new("BrainInterface")),
135	/// get_path_prefix(r"\\.\BrainInterface"));
136	/// assert_eq!(UNC(OsStr::new("server"), OsStr::new("share")),
137	/// get_path_prefix(r"\\server\share"));
138	/// assert_eq!(Disk(b'C'), get_path_prefix(r"C:\Users\Rust\Pictures\Ferris"));
139	/// # }
140	/// ```
141	#[derive(Copy, Clone, Debug, Hash, PartialOrd, Ord, PartialEq, Eq)]
142	#[stable(feature = "rust1", since = "1.0.0")]
143	pub enum Prefix<'a> {
144	/// Verbatim prefix, e.g., `\\?\cat_pics`.
145	///
146	/// Verbatim prefixes consist of `\\?\` immediately followed by the given
147	/// component.
148	#[stable(feature = "rust1", since = "1.0.0")]
149	Verbatim(#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr),
150
151	/// Verbatim prefix using Windows' _Uniform Naming Convention_,
152	/// e.g., `\\?\UNC\server\share`.
153	///
154	/// Verbatim UNC prefixes consist of `\\?\UNC\` immediately followed by the
155	/// server's hostname and a share name.
156	#[stable(feature = "rust1", since = "1.0.0")]
157	VerbatimUNC(
158	#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr,
159	#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr,
160	),
161
162	/// Verbatim disk prefix, e.g., `\\?\C:`.
163	///
164	/// Verbatim disk prefixes consist of `\\?\` immediately followed by the
165	/// drive letter and `:`.
166	#[stable(feature = "rust1", since = "1.0.0")]
167	VerbatimDisk(#[stable(feature = "rust1", since = "1.0.0")] u8),
168
169	/// Device namespace prefix, e.g., `\\.\COM42`.
170	///
171	/// Device namespace prefixes consist of `\\.\` (possibly using `/`
172	/// instead of `\`), immediately followed by the device name.
173	#[stable(feature = "rust1", since = "1.0.0")]
174	DeviceNS(#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr),
175
176	/// Prefix using Windows' _Uniform Naming Convention_, e.g.
177	/// `\\server\share`.
178	///
179	/// UNC prefixes consist of the server's hostname and a share name.
180	#[stable(feature = "rust1", since = "1.0.0")]
181	UNC(
182	#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr,
183	#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr,
184	),
185
186	/// Prefix `C:` for the given disk drive.
187	#[stable(feature = "rust1", since = "1.0.0")]
188	Disk(#[stable(feature = "rust1", since = "1.0.0")] u8),
189	}
190
191	impl<'a> Prefix<'a> {
192	#[inline]
193	fn len(&self) -> usize {
194	use self::Prefix::*;
195	fn os_str_len(s: &OsStr) -> usize {
196	s.as_encoded_bytes().len()
197	}
198	match *self {
199	Verbatim(x) => `4` + os_str_len(x),
200	VerbatimUNC(x, y) => {
201	`8` + os_str_len(x) + if os_str_len(y) > `0` { `1` + os_str_len(y) } else { `0` }
202	}
203	VerbatimDisk(_) => `6`,
204	UNC(x, y) => `2` + os_str_len(x) + if os_str_len(y) > `0` { `1` + os_str_len(y) } else { `0` },
205	DeviceNS(x) => `4` + os_str_len(x),
206	Disk(_) => `2`,
207	}
208	}
209
210	/// Determines if the prefix is verbatim, i.e., begins with `\\?\`.
211	///
212	/// # Examples
213	///
214	/// ```
215	/// use std::path::Prefix::*;
216	/// use std::ffi::OsStr;
217	///
218	/// assert!(Verbatim(OsStr::new("pictures")).is_verbatim());
219	/// assert!(VerbatimUNC(OsStr::new("server"), OsStr::new("share")).is_verbatim());
220	/// assert!(VerbatimDisk(b'C').is_verbatim());
221	/// assert!(!DeviceNS(OsStr::new("BrainInterface")).is_verbatim());
222	/// assert!(!UNC(OsStr::new("server"), OsStr::new("share")).is_verbatim());
223	/// assert!(!Disk(b'C').is_verbatim());
224	/// ```
225	#[inline]
226	#[must_use]
227	#[stable(feature = "rust1", since = "1.0.0")]
228	pub fn is_verbatim(&self) -> bool {
229	use self::Prefix::*;
230	matches!(*self, Verbatim(_) \| VerbatimDisk(_) \| VerbatimUNC(..))
231	}
232
233	#[inline]
234	fn is_drive(&self) -> bool {
235	matches!(*self, Prefix::Disk(_))
236	}
237
238	#[inline]
239	fn has_implicit_root(&self) -> bool {
240	!self.is_drive()
241	}
242	}
243
244	////////////////////////////////////////////////////////////////////////////////
245	// Exposed parsing helpers
246	////////////////////////////////////////////////////////////////////////////////
247
248	/// Determines whether the character is one of the permitted path
249	/// separators for the current platform.
250	///
251	/// # Examples
252	///
253	/// ```
254	/// use std::path;
255	///
256	/// assert!(path::is_separator('/')); // '/' works for both Unix and Windows
257	/// assert!(!path::is_separator('❤'));
258	/// ```
259	#[must_use]
260	#[stable(feature = "rust1", since = "1.0.0")]
261	pub fn is_separator(c: char) -> bool {
262	c.is_ascii() && is_sep_byte(c as u8)
263	}
264
265	/// The primary separator of path components for the current platform.
266	///
267	/// For example, `/` on Unix and `\` on Windows.
268	#[stable(feature = "rust1", since = "1.0.0")]
269	pub const MAIN_SEPARATOR: char = crate::sys::path::MAIN_SEP;
270
271	/// The primary separator of path components for the current platform.
272	///
273	/// For example, `/` on Unix and `\` on Windows.
274	#[stable(feature = "main_separator_str", since = "1.68.0")]
275	pub const MAIN_SEPARATOR_STR: &str = crate::sys::path::MAIN_SEP_STR;
276
277	////////////////////////////////////////////////////////////////////////////////
278	// Misc helpers
279	////////////////////////////////////////////////////////////////////////////////
280
281	// Iterate through `iter` while it matches `prefix`; return `None` if `prefix`
282	// is not a prefix of `iter`, otherwise return `Some(iter_after_prefix)` giving
283	// `iter` after having exhausted `prefix`.
284	fn iter_after<'a, 'b, I, J>(mut iter: I, mut prefix: J) -> Option<I>
285	where
286	I: Iterator<Item = Component<'a>> + Clone,
287	J: Iterator<Item = Component<'b>>,
288	{
289	loop {
290	let mut iter_next: I = iter.clone();
291	match (iter_next.next(), prefix.next()) {
292	(Some(ref x: &Component<'_>), Some(ref y: &Component<'_>)) if x == y => (),
293	(Some(_), Some(_)) => return None,
294	(Some(_), None) => return Some(iter),
295	(None, None) => return Some(iter),
296	(None, Some(_)) => return None,
297	}
298	iter = iter_next;
299	}
300	}
301
302	// Detect scheme on Redox
303	fn has_redox_scheme(s: &[u8]) -> bool {
304	cfg!(target_os = "redox") && s.contains(&b':')
305	}
306
307	////////////////////////////////////////////////////////////////////////////////
308	// Cross-platform, iterator-independent parsing
309	////////////////////////////////////////////////////////////////////////////////
310
311	/// Says whether the first byte after the prefix is a separator.
312	fn has_physical_root(s: &[u8], prefix: Option<Prefix<'_>>) -> bool {
313	let path: &[u8] = if let Some(p: Prefix<'_>) = prefix { &s[p.len()..] } else { s };
314	!path.is_empty() && is_sep_byte(path[`0`])
315	}
316
317	// basic workhorse for splitting stem and extension
318	fn rsplit_file_at_dot(file: &OsStr) -> (Option<&OsStr>, Option<&OsStr>) {
319	if file.as_encoded_bytes() == b".." {
320	return (Some(file), None);
321	}
322
323	// The unsafety here stems from converting between &OsStr and &[u8]
324	// and back. This is safe to do because (1) we only look at ASCII
325	// contents of the encoding and (2) new &OsStr values are produced
326	// only from ASCII-bounded slices of existing &OsStr values.
327	let mut iter: RSplitN<'_, u8, impl Fn(&…) -> …> = file.as_encoded_bytes().rsplitn(n:`2`, \|b: &u8\| *b == b'.');
328	let after: Option<&[u8]> = iter.next();
329	let before: Option<&[u8]> = iter.next();
330	if before == Some(b"") {
331	(Some(file), None)
332	} else {
333	unsafe {
334	(
335	before.map(\|s: &[u8]\| OsStr::from_encoded_bytes_unchecked(bytes:s)),
336	after.map(\|s: &[u8]\| OsStr::from_encoded_bytes_unchecked(bytes:s)),
337	)
338	}
339	}
340	}
341
342	fn split_file_at_dot(file: &OsStr) -> (&OsStr, Option<&OsStr>) {
343	let slice: &[u8] = file.as_encoded_bytes();
344	if slice == b".." {
345	return (file, None);
346	}
347
348	// The unsafety here stems from converting between &OsStr and &[u8]
349	// and back. This is safe to do because (1) we only look at ASCII
350	// contents of the encoding and (2) new &OsStr values are produced
351	// only from ASCII-bounded slices of existing &OsStr values.
352	let i: usize = match slice[`1`..].iter().position(\|b: &u8\| *b == b'.') {
353	Some(i: usize) => i + `1`,
354	None => return (file, None),
355	};
356	let before: &[u8] = &slice[..i];
357	let after: &[u8] = &slice[i + `1`..];
358	unsafe {
359	(
360	OsStr::from_encoded_bytes_unchecked(bytes:before),
361	Some(OsStr::from_encoded_bytes_unchecked(bytes:after)),
362	)
363	}
364	}
365
366	////////////////////////////////////////////////////////////////////////////////
367	// The core iterators
368	////////////////////////////////////////////////////////////////////////////////
369
370	/// Component parsing works by a double-ended state machine; the cursors at the
371	/// front and back of the path each keep track of what parts of the path have
372	/// been consumed so far.
373	///
374	/// Going front to back, a path is made up of a prefix, a starting
375	/// directory component, and a body (of normal components)
376	#[derive(Copy, Clone, PartialEq, PartialOrd, Debug)]
377	enum State {
378	Prefix = `0`, // c:
379	StartDir = `1`, // / or . or nothing
380	Body = `2`, // foo/bar/baz
381	Done = `3`,
382	}
383
384	/// A structure wrapping a Windows path prefix as well as its unparsed string
385	/// representation.
386	///
387	/// In addition to the parsed [`Prefix`] information returned by [`kind`],
388	/// `PrefixComponent` also holds the raw and unparsed [`OsStr`] slice,
389	/// returned by [`as_os_str`].
390	///
391	/// Instances of this `struct` can be obtained by matching against the
392	/// [`Prefix` variant] on [`Component`].
393	///
394	/// Does not occur on Unix.
395	///
396	/// # Examples
397	///
398	/// ```
399	/// # if cfg!(windows) {
400	/// use std::path::{Component, Path, Prefix};
401	/// use std::ffi::OsStr;
402	///
403	/// let path = Path::new(r"c:\you\later\");
404	/// match path.components().next().unwrap() {
405	/// Component::Prefix(prefix_component) => {
406	/// assert_eq!(Prefix::Disk(b'C'), prefix_component.kind());
407	/// assert_eq!(OsStr::new("c:"), prefix_component.as_os_str());
408	/// }
409	/// _ => unreachable!(),
410	/// }
411	/// # }
412	/// ```
413	///
414	/// [`as_os_str`]: PrefixComponent::as_os_str
415	/// [`kind`]: PrefixComponent::kind
416	/// [`Prefix` variant]: Component::Prefix
417	#[stable(feature = "rust1", since = "1.0.0")]
418	#[derive(Copy, Clone, Eq, Debug)]
419	pub struct PrefixComponent<'a> {
420	/// The prefix as an unparsed `OsStr` slice.
421	raw: &'a OsStr,
422
423	/// The parsed prefix data.
424	parsed: Prefix<'a>,
425	}
426
427	impl<'a> PrefixComponent<'a> {
428	/// Returns the parsed prefix data.
429	///
430	/// See [`Prefix`]'s documentation for more information on the different
431	/// kinds of prefixes.
432	#[stable(feature = "rust1", since = "1.0.0")]
433	#[must_use]
434	#[inline]
435	pub fn kind(&self) -> Prefix<'a> {
436	self.parsed
437	}
438
439	/// Returns the raw [`OsStr`] slice for this prefix.
440	#[stable(feature = "rust1", since = "1.0.0")]
441	#[must_use]
442	#[inline]
443	pub fn as_os_str(&self) -> &'a OsStr {
444	self.raw
445	}
446	}
447
448	#[stable(feature = "rust1", since = "1.0.0")]
449	impl<'a> PartialEq for PrefixComponent<'a> {
450	#[inline]
451	fn eq(&self, other: &PrefixComponent<'a>) -> bool {
452	self.parsed == other.parsed
453	}
454	}
455
456	#[stable(feature = "rust1", since = "1.0.0")]
457	impl<'a> PartialOrd for PrefixComponent<'a> {
458	#[inline]
459	fn partial_cmp(&self, other: &PrefixComponent<'a>) -> Option<cmp::Ordering> {
460	PartialOrd::partial_cmp(&self.parsed, &other.parsed)
461	}
462	}
463
464	#[stable(feature = "rust1", since = "1.0.0")]
465	impl Ord for PrefixComponent<'_> {
466	#[inline]
467	fn cmp(&self, other: &Self) -> cmp::Ordering {
468	Ord::cmp(&self.parsed, &other.parsed)
469	}
470	}
471
472	#[stable(feature = "rust1", since = "1.0.0")]
473	impl Hash for PrefixComponent<'_> {
474	fn hash<H: Hasher>(&self, h: &mut H) {
475	self.parsed.hash(state:h);
476	}
477	}
478
479	/// A single component of a path.
480	///
481	/// A `Component` roughly corresponds to a substring between path separators
482	/// (`/` or `\`).
483	///
484	/// This `enum` is created by iterating over [`Components`], which in turn is
485	/// created by the [`components`](Path::components) method on [`Path`].
486	///
487	/// # Examples
488	///
489	/// ```rust
490	/// use std::path::{Component, Path};
491	///
492	/// let path = Path::new("/tmp/foo/bar.txt");
493	/// let components = path.components().collect::<Vec<_>>();
494	/// assert_eq!(&components, &[
495	/// Component::RootDir,
496	/// Component::Normal("tmp".as_ref()),
497	/// Component::Normal("foo".as_ref()),
498	/// Component::Normal("bar.txt".as_ref()),
499	/// ]);
500	/// ```
501	#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
502	#[stable(feature = "rust1", since = "1.0.0")]
503	pub enum Component<'a> {
504	/// A Windows path prefix, e.g., `C:` or `\\server\share`.
505	///
506	/// There is a large variety of prefix types, see [`Prefix`]'s documentation
507	/// for more.
508	///
509	/// Does not occur on Unix.
510	#[stable(feature = "rust1", since = "1.0.0")]
511	Prefix(#[stable(feature = "rust1", since = "1.0.0")] PrefixComponent<'a>),
512
513	/// The root directory component, appears after any prefix and before anything else.
514	///
515	/// It represents a separator that designates that a path starts from root.
516	#[stable(feature = "rust1", since = "1.0.0")]
517	RootDir,
518
519	/// A reference to the current directory, i.e., `.`.
520	#[stable(feature = "rust1", since = "1.0.0")]
521	CurDir,
522
523	/// A reference to the parent directory, i.e., `..`.
524	#[stable(feature = "rust1", since = "1.0.0")]
525	ParentDir,
526
527	/// A normal component, e.g., `a` and `b` in `a/b`.
528	///
529	/// This variant is the most common one, it represents references to files
530	/// or directories.
531	#[stable(feature = "rust1", since = "1.0.0")]
532	Normal(#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr),
533	}
534
535	impl<'a> Component<'a> {
536	/// Extracts the underlying [`OsStr`] slice.
537	///
538	/// # Examples
539	///
540	/// ```
541	/// use std::path::Path;
542	///
543	/// let path = Path::new("./tmp/foo/bar.txt");
544	/// let components: Vec<_> = path.components().map(\|comp\| comp.as_os_str()).collect();
545	/// assert_eq!(&components, &[".", "tmp", "foo", "bar.txt"]);
546	/// ```
547	#[must_use = "`self` will be dropped if the result is not used"]
548	#[stable(feature = "rust1", since = "1.0.0")]
549	pub fn as_os_str(self) -> &'a OsStr {
550	match self {
551	Component::Prefix(p: PrefixComponent<'_>) => p.as_os_str(),
552	Component::RootDir => OsStr::new(MAIN_SEP_STR),
553	Component::CurDir => OsStr::new("."),
554	Component::ParentDir => OsStr::new(".."),
555	Component::Normal(path: &OsStr) => path,
556	}
557	}
558	}
559
560	#[stable(feature = "rust1", since = "1.0.0")]
561	impl AsRef<OsStr> for Component<'_> {
562	#[inline]
563	fn as_ref(&self) -> &OsStr {
564	self.as_os_str()
565	}
566	}
567
568	#[stable(feature = "path_component_asref", since = "1.25.0")]
569	impl AsRef<Path> for Component<'_> {
570	#[inline]
571	fn as_ref(&self) -> &Path {
572	self.as_os_str().as_ref()
573	}
574	}
575
576	/// An iterator over the [`Component`]s of a [`Path`].
577	///
578	/// This `struct` is created by the [`components`] method on [`Path`].
579	/// See its documentation for more.
580	///
581	/// # Examples
582	///
583	/// ```
584	/// use std::path::Path;
585	///
586	/// let path = Path::new("/tmp/foo/bar.txt");
587	///
588	/// for component in path.components() {
589	/// println!("{component:?}");
590	/// }
591	/// ```
592	///
593	/// [`components`]: Path::components
594	#[derive(Clone)]
595	#[must_use = "iterators are lazy and do nothing unless consumed"]
596	#[stable(feature = "rust1", since = "1.0.0")]
597	pub struct Components<'a> {
598	// The path left to parse components from
599	path: &'a [u8],
600
601	// The prefix as it was originally parsed, if any
602	prefix: Option<Prefix<'a>>,
603
604	// true if path physically* has a root separator; for most Windows*
605	// prefixes, it may have a "logical" root separator for the purposes of
606	// normalization, e.g., \\server\share == \\server\share\.
607	has_physical_root: bool,
608
609	// The iterator is double-ended, and these two states keep track of what has
610	// been produced from either end
611	front: State,
612	back: State,
613	}
614
615	/// An iterator over the [`Component`]s of a [`Path`], as [`OsStr`] slices.
616	///
617	/// This `struct` is created by the [`iter`] method on [`Path`].
618	/// See its documentation for more.
619	///
620	/// [`iter`]: Path::iter
621	#[derive(Clone)]
622	#[must_use = "iterators are lazy and do nothing unless consumed"]
623	#[stable(feature = "rust1", since = "1.0.0")]
624	pub struct Iter<'a> {
625	inner: Components<'a>,
626	}
627
628	#[stable(feature = "path_components_debug", since = "1.13.0")]
629	impl fmt::Debug for Components<'_> {
630	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
631	struct DebugHelper<'a>(&'a Path);
632
633	impl fmt::Debug for DebugHelper<'_> {
634	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
635	f.debug_list().entries(self.0.components()).finish()
636	}
637	}
638
639	f.debug_tuple(name:"Components").field(&DebugHelper(self.as_path())).finish()
640	}
641	}
642
643	impl<'a> Components<'a> {
644	// how long is the prefix, if any?
645	#[inline]
646	fn prefix_len(&self) -> usize {
647	self.prefix.as_ref().map(Prefix::len).unwrap_or(`0`)
648	}
649
650	#[inline]
651	fn prefix_verbatim(&self) -> bool {
652	self.prefix.as_ref().map(Prefix::is_verbatim).unwrap_or(`false`)
653	}
654
655	/// how much of the prefix is left from the point of view of iteration?
656	#[inline]
657	fn prefix_remaining(&self) -> usize {
658	if self.front == State::Prefix { self.prefix_len() } else { `0` }
659	}
660
661	// Given the iteration so far, how much of the pre-State::Body path is left?
662	#[inline]
663	fn len_before_body(&self) -> usize {
664	let root = if self.front <= State::StartDir && self.has_physical_root { `1` } else { `0` };
665	let cur_dir = if self.front <= State::StartDir && self.include_cur_dir() { `1` } else { `0` };
666	self.prefix_remaining() + root + cur_dir
667	}
668
669	// is the iteration complete?
670	#[inline]
671	fn finished(&self) -> bool {
672	self.front == State::Done \|\| self.back == State::Done \|\| self.front > self.back
673	}
674
675	#[inline]
676	fn is_sep_byte(&self, b: u8) -> bool {
677	if self.prefix_verbatim() { is_verbatim_sep(b) } else { is_sep_byte(b) }
678	}
679
680	/// Extracts a slice corresponding to the portion of the path remaining for iteration.
681	///
682	/// # Examples
683	///
684	/// ```
685	/// use std::path::Path;
686	///
687	/// let mut components = Path::new("/tmp/foo/bar.txt").components();
688	/// components.next();
689	/// components.next();
690	///
691	/// assert_eq!(Path::new("foo/bar.txt"), components.as_path());
692	/// ```
693	#[must_use]
694	#[stable(feature = "rust1", since = "1.0.0")]
695	pub fn as_path(&self) -> &'a Path {
696	let mut comps = self.clone();
697	if comps.front == State::Body {
698	comps.trim_left();
699	}
700	if comps.back == State::Body {
701	comps.trim_right();
702	}
703	unsafe { Path::from_u8_slice(comps.path) }
704	}
705
706	/// Is the original* path rooted?*
707	fn has_root(&self) -> bool {
708	if self.has_physical_root {
709	return `true`;
710	}
711	if let Some(p) = self.prefix {
712	if p.has_implicit_root() {
713	return `true`;
714	}
715	}
716	`false`
717	}
718
719	/// Should the normalized path include a leading . ?
720	fn include_cur_dir(&self) -> bool {
721	if self.has_root() {
722	return `false`;
723	}
724	let mut iter = self.path[self.prefix_remaining()..].iter();
725	match (iter.next(), iter.next()) {
726	(Some(&b'.'), None) => `true`,
727	(Some(&b'.'), Some(&b)) => self.is_sep_byte(b),
728	_ => `false`,
729	}
730	}
731
732	// parse a given byte sequence following the OsStr encoding into the
733	// corresponding path component
734	unsafe fn parse_single_component<'b>(&self, comp: &'b [u8]) -> Option<Component<'b>> {
735	match comp {
736	b"." if self.prefix_verbatim() => Some(Component::CurDir),
737	b"." => None, // . components are normalized away, except at
738	// the beginning of a path, which is treated
739	// separately via `include_cur_dir`
740	b".." => Some(Component::ParentDir),
741	b"" => None,
742	_ => Some(Component::Normal(unsafe { OsStr::from_encoded_bytes_unchecked(comp) })),
743	}
744	}
745
746	// parse a component from the left, saying how many bytes to consume to
747	// remove the component
748	fn parse_next_component(&self) -> (usize, Option<Component<'a>>) {
749	debug_assert!(self.front == State::Body);
750	let (extra, comp) = match self.path.iter().position(\|b\| self.is_sep_byte(*b)) {
751	None => (`0`, self.path),
752	Some(i) => (`1`, &self.path[..i]),
753	};
754	// SAFETY: `comp` is a valid substring, since it is split on a separator.
755	(comp.len() + extra, unsafe { self.parse_single_component(comp) })
756	}
757
758	// parse a component from the right, saying how many bytes to consume to
759	// remove the component
760	fn parse_next_component_back(&self) -> (usize, Option<Component<'a>>) {
761	debug_assert!(self.back == State::Body);
762	let start = self.len_before_body();
763	let (extra, comp) = match self.path[start..].iter().rposition(\|b\| self.is_sep_byte(*b)) {
764	None => (`0`, &self.path[start..]),
765	Some(i) => (`1`, &self.path[start + i + `1`..]),
766	};
767	// SAFETY: `comp` is a valid substring, since it is split on a separator.
768	(comp.len() + extra, unsafe { self.parse_single_component(comp) })
769	}
770
771	// trim away repeated separators (i.e., empty components) on the left
772	fn trim_left(&mut self) {
773	while !self.path.is_empty() {
774	let (size, comp) = self.parse_next_component();
775	if comp.is_some() {
776	return;
777	} else {
778	self.path = &self.path[size..];
779	}
780	}
781	}
782
783	// trim away repeated separators (i.e., empty components) on the right
784	fn trim_right(&mut self) {
785	while self.path.len() > self.len_before_body() {
786	let (size, comp) = self.parse_next_component_back();
787	if comp.is_some() {
788	return;
789	} else {
790	self.path = &self.path[..self.path.len() - size];
791	}
792	}
793	}
794	}
795
796	#[stable(feature = "rust1", since = "1.0.0")]
797	impl AsRef<Path> for Components<'_> {
798	#[inline]
799	fn as_ref(&self) -> &Path {
800	self.as_path()
801	}
802	}
803
804	#[stable(feature = "rust1", since = "1.0.0")]
805	impl AsRef<OsStr> for Components<'_> {
806	#[inline]
807	fn as_ref(&self) -> &OsStr {
808	self.as_path().as_os_str()
809	}
810	}
811
812	#[stable(feature = "path_iter_debug", since = "1.13.0")]
813	impl fmt::Debug for Iter<'_> {
814	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
815	struct DebugHelper<'a>(&'a Path);
816
817	impl fmt::Debug for DebugHelper<'_> {
818	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
819	f.debug_list().entries(self.0.iter()).finish()
820	}
821	}
822
823	f.debug_tuple(name:"Iter").field(&DebugHelper(self.as_path())).finish()
824	}
825	}
826
827	impl<'a> Iter<'a> {
828	/// Extracts a slice corresponding to the portion of the path remaining for iteration.
829	///
830	/// # Examples
831	///
832	/// ```
833	/// use std::path::Path;
834	///
835	/// let mut iter = Path::new("/tmp/foo/bar.txt").iter();
836	/// iter.next();
837	/// iter.next();
838	///
839	/// assert_eq!(Path::new("foo/bar.txt"), iter.as_path());
840	/// ```
841	#[stable(feature = "rust1", since = "1.0.0")]
842	#[must_use]
843	#[inline]
844	pub fn as_path(&self) -> &'a Path {
845	self.inner.as_path()
846	}
847	}
848
849	#[stable(feature = "rust1", since = "1.0.0")]
850	impl AsRef<Path> for Iter<'_> {
851	#[inline]
852	fn as_ref(&self) -> &Path {
853	self.as_path()
854	}
855	}
856
857	#[stable(feature = "rust1", since = "1.0.0")]
858	impl AsRef<OsStr> for Iter<'_> {
859	#[inline]
860	fn as_ref(&self) -> &OsStr {
861	self.as_path().as_os_str()
862	}
863	}
864
865	#[stable(feature = "rust1", since = "1.0.0")]
866	impl<'a> Iterator for Iter<'a> {
867	type Item = &'a OsStr;
868
869	#[inline]
870	fn next(&mut self) -> Option<&'a OsStr> {
871	self.inner.next().map(Component::as_os_str)
872	}
873	}
874
875	#[stable(feature = "rust1", since = "1.0.0")]
876	impl<'a> DoubleEndedIterator for Iter<'a> {
877	#[inline]
878	fn next_back(&mut self) -> Option<&'a OsStr> {
879	self.inner.next_back().map(Component::as_os_str)
880	}
881	}
882
883	#[stable(feature = "fused", since = "1.26.0")]
884	impl FusedIterator for Iter<'_> {}
885
886	#[stable(feature = "rust1", since = "1.0.0")]
887	impl<'a> Iterator for Components<'a> {
888	type Item = Component<'a>;
889
890	fn next(&mut self) -> Option<Component<'a>> {
891	while !self.finished() {
892	match self.front {
893	State::Prefix if self.prefix_len() > `0` => {
894	self.front = State::StartDir;
895	debug_assert!(self.prefix_len() <= self.path.len());
896	let raw = &self.path[..self.prefix_len()];
897	self.path = &self.path[self.prefix_len()..];
898	return Some(Component::Prefix(PrefixComponent {
899	raw: unsafe { OsStr::from_encoded_bytes_unchecked(raw) },
900	parsed: self.prefix.unwrap(),
901	}));
902	}
903	State::Prefix => {
904	self.front = State::StartDir;
905	}
906	State::StartDir => {
907	self.front = State::Body;
908	if self.has_physical_root {
909	debug_assert!(!self.path.is_empty());
910	self.path = &self.path[`1`..];
911	return Some(Component::RootDir);
912	} else if let Some(p) = self.prefix {
913	if p.has_implicit_root() && !p.is_verbatim() {
914	return Some(Component::RootDir);
915	}
916	} else if self.include_cur_dir() {
917	debug_assert!(!self.path.is_empty());
918	self.path = &self.path[`1`..];
919	return Some(Component::CurDir);
920	}
921	}
922	State::Body if !self.path.is_empty() => {
923	let (size, comp) = self.parse_next_component();
924	self.path = &self.path[size..];
925	if comp.is_some() {
926	return comp;
927	}
928	}
929	State::Body => {
930	self.front = State::Done;
931	}
932	State::Done => unreachable!(),
933	}
934	}
935	None
936	}
937	}
938
939	#[stable(feature = "rust1", since = "1.0.0")]
940	impl<'a> DoubleEndedIterator for Components<'a> {
941	fn next_back(&mut self) -> Option<Component<'a>> {
942	while !self.finished() {
943	match self.back {
944	State::Body if self.path.len() > self.len_before_body() => {
945	let (size, comp) = self.parse_next_component_back();
946	self.path = &self.path[..self.path.len() - size];
947	if comp.is_some() {
948	return comp;
949	}
950	}
951	State::Body => {
952	self.back = State::StartDir;
953	}
954	State::StartDir => {
955	self.back = State::Prefix;
956	if self.has_physical_root {
957	self.path = &self.path[..self.path.len() - `1`];
958	return Some(Component::RootDir);
959	} else if let Some(p) = self.prefix {
960	if p.has_implicit_root() && !p.is_verbatim() {
961	return Some(Component::RootDir);
962	}
963	} else if self.include_cur_dir() {
964	self.path = &self.path[..self.path.len() - `1`];
965	return Some(Component::CurDir);
966	}
967	}
968	State::Prefix if self.prefix_len() > `0` => {
969	self.back = State::Done;
970	return Some(Component::Prefix(PrefixComponent {
971	raw: unsafe { OsStr::from_encoded_bytes_unchecked(self.path) },
972	parsed: self.prefix.unwrap(),
973	}));
974	}
975	State::Prefix => {
976	self.back = State::Done;
977	return None;
978	}
979	State::Done => unreachable!(),
980	}
981	}
982	None
983	}
984	}
985
986	#[stable(feature = "fused", since = "1.26.0")]
987	impl FusedIterator for Components<'_> {}
988
989	#[stable(feature = "rust1", since = "1.0.0")]
990	impl<'a> PartialEq for Components<'a> {
991	#[inline]
992	fn eq(&self, other: &Components<'a>) -> bool {
993	let Components { path: _, front: _, back: _, has_physical_root: _, prefix: _ } = self;
994
995	// Fast path for exact matches, e.g. for hashmap lookups.
996	// Don't explicitly compare the prefix or has_physical_root fields since they'll
997	// either be covered by the `path` buffer or are only relevant for `prefix_verbatim()`.
998	if self.path.len() == other.path.len()
999	&& self.front == other.front
1000	&& self.back == State::Body
1001	&& other.back == State::Body
1002	&& self.prefix_verbatim() == other.prefix_verbatim()
1003	{
1004	// possible future improvement: this could bail out earlier if there were a
1005	// reverse memcmp/bcmp comparing back to front
1006	if self.path == other.path {
1007	return `true`;
1008	}
1009	}
1010
1011	// compare back to front since absolute paths often share long prefixes
1012	Iterator::eq(self.clone().rev(), other.clone().rev())
1013	}
1014	}
1015
1016	#[stable(feature = "rust1", since = "1.0.0")]
1017	impl Eq for Components<'_> {}
1018
1019	#[stable(feature = "rust1", since = "1.0.0")]
1020	impl<'a> PartialOrd for Components<'a> {
1021	#[inline]
1022	fn partial_cmp(&self, other: &Components<'a>) -> Option<cmp::Ordering> {
1023	Some(compare_components(self.clone(), right:other.clone()))
1024	}
1025	}
1026
1027	#[stable(feature = "rust1", since = "1.0.0")]
1028	impl Ord for Components<'_> {
1029	#[inline]
1030	fn cmp(&self, other: &Self) -> cmp::Ordering {
1031	compare_components(self.clone(), right:other.clone())
1032	}
1033	}
1034
1035	fn compare_components(mut left: Components<'_>, mut right: Components<'_>) -> cmp::Ordering {
1036	// Fast path for long shared prefixes
1037	//
1038	// - compare raw bytes to find first mismatch
1039	// - backtrack to find separator before mismatch to avoid ambiguous parsings of '.' or '..' characters
1040	// - if found update state to only do a component-wise comparison on the remainder,
1041	// otherwise do it on the full path
1042	//
1043	// The fast path isn't taken for paths with a PrefixComponent to avoid backtracking into
1044	// the middle of one
1045	if left.prefix.is_none() && right.prefix.is_none() && left.front == right.front {
1046	// possible future improvement: a [u8]::first_mismatch simd implementation
1047	let first_difference = match left.path.iter().zip(right.path).position(\|(&a, &b)\| a != b) {
1048	None if left.path.len() == right.path.len() => return cmp::Ordering::Equal,
1049	None => left.path.len().min(right.path.len()),
1050	Some(diff) => diff,
1051	};
1052
1053	if let Some(previous_sep) =
1054	left.path[..first_difference].iter().rposition(\|&b\| left.is_sep_byte(b))
1055	{
1056	let mismatched_component_start = previous_sep + `1`;
1057	left.path = &left.path[mismatched_component_start..];
1058	left.front = State::Body;
1059	right.path = &right.path[mismatched_component_start..];
1060	right.front = State::Body;
1061	}
1062	}
1063
1064	Iterator::cmp(left, right)
1065	}
1066
1067	/// An iterator over [`Path`] and its ancestors.
1068	///
1069	/// This `struct` is created by the [`ancestors`] method on [`Path`].
1070	/// See its documentation for more.
1071	///
1072	/// # Examples
1073	///
1074	/// ```
1075	/// use std::path::Path;
1076	///
1077	/// let path = Path::new("/foo/bar");
1078	///
1079	/// for ancestor in path.ancestors() {
1080	/// println!("{}", ancestor.display());
1081	/// }
1082	/// ```
1083	///
1084	/// [`ancestors`]: Path::ancestors
1085	#[derive(Copy, Clone, Debug)]
1086	#[must_use = "iterators are lazy and do nothing unless consumed"]
1087	#[stable(feature = "path_ancestors", since = "1.28.0")]
1088	pub struct Ancestors<'a> {
1089	next: Option<&'a Path>,
1090	}
1091
1092	#[stable(feature = "path_ancestors", since = "1.28.0")]
1093	impl<'a> Iterator for Ancestors<'a> {
1094	type Item = &'a Path;
1095
1096	#[inline]
1097	fn next(&mut self) -> Option<Self::Item> {
1098	let next: Option<&Path> = self.next;
1099	self.next = next.and_then(Path::parent);
1100	next
1101	}
1102	}
1103
1104	#[stable(feature = "path_ancestors", since = "1.28.0")]
1105	impl FusedIterator for Ancestors<'_> {}
1106
1107	////////////////////////////////////////////////////////////////////////////////
1108	// Basic types and traits
1109	////////////////////////////////////////////////////////////////////////////////
1110
1111	/// An owned, mutable path (akin to [`String`]).
1112	///
1113	/// This type provides methods like [`push`] and [`set_extension`] that mutate
1114	/// the path in place. It also implements [`Deref`] to [`Path`], meaning that
1115	/// all methods on [`Path`] slices are available on `PathBuf` values as well.
1116	///
1117	/// [`push`]: PathBuf::push
1118	/// [`set_extension`]: PathBuf::set_extension
1119	///
1120	/// More details about the overall approach can be found in
1121	/// the [module documentation](self).
1122	///
1123	/// # Examples
1124	///
1125	/// You can use [`push`] to build up a `PathBuf` from
1126	/// components:
1127	///
1128	/// ```
1129	/// use std::path::PathBuf;
1130	///
1131	/// let mut path = PathBuf::new();
1132	///
1133	/// path.push(r"C:\");
1134	/// path.push("windows");
1135	/// path.push("system32");
1136	///
1137	/// path.set_extension("dll");
1138	/// ```
1139	///
1140	/// However, [`push`] is best used for dynamic situations. This is a better way
1141	/// to do this when you know all of the components ahead of time:
1142	///
1143	/// ```
1144	/// use std::path::PathBuf;
1145	///
1146	/// let path: PathBuf = [r"C:\", "windows", "system32.dll"].iter().collect();
1147	/// ```
1148	///
1149	/// We can still do better than this! Since these are all strings, we can use
1150	/// `From::from`:
1151	///
1152	/// ```
1153	/// use std::path::PathBuf;
1154	///
1155	/// let path = PathBuf::from(r"C:\windows\system32.dll");
1156	/// ```
1157	///
1158	/// Which method works best depends on what kind of situation you're in.
1159	#[cfg_attr(not(test), rustc_diagnostic_item = "PathBuf")]
1160	#[stable(feature = "rust1", since = "1.0.0")]
1161	// `PathBuf::as_mut_vec` current implementation relies
1162	// on `PathBuf` being layout-compatible with `Vec<u8>`.
1163	// However, `PathBuf` layout is considered an implementation detail and must not be relied upon. We
1164	// want `repr(transparent)` but we don't want it to show up in rustdoc, so we hide it under
1165	// `cfg(doc)`. This is an ad-hoc implementation of attribute privacy.
1166	#[cfg_attr(not(doc), repr(transparent))]
1167	pub struct PathBuf {
1168	inner: OsString,
1169	}
1170
1171	impl PathBuf {
1172	#[inline]
1173	fn as_mut_vec(&mut self) -> &mut Vec<u8> {
1174	unsafe { &mut (self as mut PathBuf as *mut Vec<u8>) }
1175	}
1176
1177	/// Allocates an empty `PathBuf`.
1178	///
1179	/// # Examples
1180	///
1181	/// ```
1182	/// use std::path::PathBuf;
1183	///
1184	/// let path = PathBuf::new();
1185	/// ```
1186	#[stable(feature = "rust1", since = "1.0.0")]
1187	#[must_use]
1188	#[inline]
1189	pub fn new() -> PathBuf {
1190	PathBuf { inner: OsString::new() }
1191	}
1192
1193	/// Creates a new `PathBuf` with a given capacity used to create the
1194	/// internal [`OsString`]. See [`with_capacity`] defined on [`OsString`].
1195	///
1196	/// # Examples
1197	///
1198	/// ```
1199	/// use std::path::PathBuf;
1200	///
1201	/// let mut path = PathBuf::with_capacity(`10`);
1202	/// let capacity = path.capacity();
1203	///
1204	/// // This push is done without reallocating
1205	/// path.push(r"C:\");
1206	///
1207	/// assert_eq!(capacity, path.capacity());
1208	/// ```
1209	///
1210	/// [`with_capacity`]: OsString::with_capacity
1211	#[stable(feature = "path_buf_capacity", since = "1.44.0")]
1212	#[must_use]
1213	#[inline]
1214	pub fn with_capacity(capacity: usize) -> PathBuf {
1215	PathBuf { inner: OsString::with_capacity(capacity) }
1216	}
1217
1218	/// Coerces to a [`Path`] slice.
1219	///
1220	/// # Examples
1221	///
1222	/// ```
1223	/// use std::path::{Path, PathBuf};
1224	///
1225	/// let p = PathBuf::from("/test");
1226	/// assert_eq!(Path::new("/test"), p.as_path());
1227	/// ```
1228	#[stable(feature = "rust1", since = "1.0.0")]
1229	#[must_use]
1230	#[inline]
1231	pub fn as_path(&self) -> &Path {
1232	self
1233	}
1234
1235	/// Extends `self` with `path`.
1236	///
1237	/// If `path` is absolute, it replaces the current path.
1238	///
1239	/// On Windows:
1240	///
1241	/// if `path` has a root but no prefix (e.g., `\windows`), it*
1242	/// replaces everything except for the prefix (if any) of `self`.
1243	/// if `path` has a prefix but no root, it replaces `self`.*
1244	/// if `self` has a verbatim prefix (e.g. `\\?\C:\windows`)*
1245	/// and `path` is not empty, the new path is normalized: all references
1246	/// to `.` and `..` are removed.
1247	///
1248	/// Consider using [`Path::join`] if you need a new `PathBuf` instead of
1249	/// using this function on a cloned `PathBuf`.
1250	///
1251	/// # Examples
1252	///
1253	/// Pushing a relative path extends the existing path:
1254	///
1255	/// ```
1256	/// use std::path::PathBuf;
1257	///
1258	/// let mut path = PathBuf::from("/tmp");
1259	/// path.push("file.bk");
1260	/// assert_eq!(path, PathBuf::from("/tmp/file.bk"));
1261	/// ```
1262	///
1263	/// Pushing an absolute path replaces the existing path:
1264	///
1265	/// ```
1266	/// use std::path::PathBuf;
1267	///
1268	/// let mut path = PathBuf::from("/tmp");
1269	/// path.push("/etc");
1270	/// assert_eq!(path, PathBuf::from("/etc"));
1271	/// ```
1272	#[stable(feature = "rust1", since = "1.0.0")]
1273	pub fn push<P: AsRef<Path>>(&mut self, path: P) {
1274	self._push(path.as_ref())
1275	}
1276
1277	fn _push(&mut self, path: &Path) {
1278	// in general, a separator is needed if the rightmost byte is not a separator
1279	let mut need_sep = self.as_mut_vec().last().map(\|c\| !is_sep_byte(*c)).unwrap_or(`false`);
1280
1281	// in the special case of `C:` on Windows, do not* add a separator*
1282	let comps = self.components();
1283
1284	if comps.prefix_len() > `0`
1285	&& comps.prefix_len() == comps.path.len()
1286	&& comps.prefix.unwrap().is_drive()
1287	{
1288	need_sep = `false`
1289	}
1290
1291	// absolute `path` replaces `self`
1292	if path.is_absolute() \|\| path.prefix().is_some() {
1293	self.as_mut_vec().truncate(`0`);
1294
1295	// verbatim paths need . and .. removed
1296	} else if comps.prefix_verbatim() && !path.inner.is_empty() {
1297	let mut buf: Vec<_> = comps.collect();
1298	for c in path.components() {
1299	match c {
1300	Component::RootDir => {
1301	buf.truncate(`1`);
1302	buf.push(c);
1303	}
1304	Component::CurDir => (),
1305	Component::ParentDir => {
1306	if let Some(Component::Normal(_)) = buf.last() {
1307	buf.pop();
1308	}
1309	}
1310	_ => buf.push(c),
1311	}
1312	}
1313
1314	let mut res = OsString::new();
1315	let mut need_sep = `false`;
1316
1317	for c in buf {
1318	if need_sep && c != Component::RootDir {
1319	res.push(MAIN_SEP_STR);
1320	}
1321	res.push(c.as_os_str());
1322
1323	need_sep = match c {
1324	Component::RootDir => `false`,
1325	Component::Prefix(prefix) => {
1326	!prefix.parsed.is_drive() && prefix.parsed.len() > `0`
1327	}
1328	_ => `true`,
1329	}
1330	}
1331
1332	self.inner = res;
1333	return;
1334
1335	// `path` has a root but no prefix, e.g., `\windows` (Windows only)
1336	} else if path.has_root() {
1337	let prefix_len = self.components().prefix_remaining();
1338	self.as_mut_vec().truncate(prefix_len);
1339
1340	// `path` is a pure relative path
1341	} else if need_sep {
1342	self.inner.push(MAIN_SEP_STR);
1343	}
1344
1345	self.inner.push(path);
1346	}
1347
1348	/// Truncates `self` to [`self.parent`].
1349	///
1350	/// Returns `false` and does nothing if [`self.parent`] is [`None`].
1351	/// Otherwise, returns `true`.
1352	///
1353	/// [`self.parent`]: Path::parent
1354	///
1355	/// # Examples
1356	///
1357	/// ```
1358	/// use std::path::{Path, PathBuf};
1359	///
1360	/// let mut p = PathBuf::from("/spirited/away.rs");
1361	///
1362	/// p.pop();
1363	/// assert_eq!(Path::new("/spirited"), p);
1364	/// p.pop();
1365	/// assert_eq!(Path::new("/"), p);
1366	/// ```
1367	#[stable(feature = "rust1", since = "1.0.0")]
1368	pub fn pop(&mut self) -> bool {
1369	match self.parent().map(\|p\| p.as_u8_slice().len()) {
1370	Some(len) => {
1371	self.as_mut_vec().truncate(len);
1372	`true`
1373	}
1374	None => `false`,
1375	}
1376	}
1377
1378	/// Updates [`self.file_name`] to `file_name`.
1379	///
1380	/// If [`self.file_name`] was [`None`], this is equivalent to pushing
1381	/// `file_name`.
1382	///
1383	/// Otherwise it is equivalent to calling [`pop`] and then pushing
1384	/// `file_name`. The new path will be a sibling of the original path.
1385	/// (That is, it will have the same parent.)
1386	///
1387	/// [`self.file_name`]: Path::file_name
1388	/// [`pop`]: PathBuf::pop
1389	///
1390	/// # Examples
1391	///
1392	/// ```
1393	/// use std::path::PathBuf;
1394	///
1395	/// let mut buf = PathBuf::from("/");
1396	/// assert!(buf.file_name() == None);
1397	///
1398	/// buf.set_file_name("foo.txt");
1399	/// assert!(buf == PathBuf::from("/foo.txt"));
1400	/// assert!(buf.file_name().is_some());
1401	///
1402	/// buf.set_file_name("bar.txt");
1403	/// assert!(buf == PathBuf::from("/bar.txt"));
1404	///
1405	/// buf.set_file_name("baz");
1406	/// assert!(buf == PathBuf::from("/baz"));
1407	/// ```
1408	#[stable(feature = "rust1", since = "1.0.0")]
1409	pub fn set_file_name<S: AsRef<OsStr>>(&mut self, file_name: S) {
1410	self._set_file_name(file_name.as_ref())
1411	}
1412
1413	fn _set_file_name(&mut self, file_name: &OsStr) {
1414	if self.file_name().is_some() {
1415	let popped = self.pop();
1416	debug_assert!(popped);
1417	}
1418	self.push(file_name);
1419	}
1420
1421	/// Updates [`self.extension`] to `Some(extension)` or to `None` if
1422	/// `extension` is empty.
1423	///
1424	/// Returns `false` and does nothing if [`self.file_name`] is [`None`],
1425	/// returns `true` and updates the extension otherwise.
1426	///
1427	/// If [`self.extension`] is [`None`], the extension is added; otherwise
1428	/// it is replaced.
1429	///
1430	/// If `extension` is the empty string, [`self.extension`] will be [`None`]
1431	/// afterwards, not `Some("")`.
1432	///
1433	/// # Caveats
1434	///
1435	/// The new `extension` may contain dots and will be used in its entirety,
1436	/// but only the part after the final dot will be reflected in
1437	/// [`self.extension`].
1438	///
1439	/// If the file stem contains internal dots and `extension` is empty, part
1440	/// of the old file stem will be considered the new [`self.extension`].
1441	///
1442	/// See the examples below.
1443	///
1444	/// [`self.file_name`]: Path::file_name
1445	/// [`self.extension`]: Path::extension
1446	///
1447	/// # Examples
1448	///
1449	/// ```
1450	/// use std::path::{Path, PathBuf};
1451	///
1452	/// let mut p = PathBuf::from("/feel/the");
1453	///
1454	/// p.set_extension("force");
1455	/// assert_eq!(Path::new("/feel/the.force"), p.as_path());
1456	///
1457	/// p.set_extension("dark.side");
1458	/// assert_eq!(Path::new("/feel/the.dark.side"), p.as_path());
1459	///
1460	/// p.set_extension("cookie");
1461	/// assert_eq!(Path::new("/feel/the.dark.cookie"), p.as_path());
1462	///
1463	/// p.set_extension("");
1464	/// assert_eq!(Path::new("/feel/the.dark"), p.as_path());
1465	///
1466	/// p.set_extension("");
1467	/// assert_eq!(Path::new("/feel/the"), p.as_path());
1468	///
1469	/// p.set_extension("");
1470	/// assert_eq!(Path::new("/feel/the"), p.as_path());
1471	/// ```
1472	#[stable(feature = "rust1", since = "1.0.0")]
1473	pub fn set_extension<S: AsRef<OsStr>>(&mut self, extension: S) -> bool {
1474	self._set_extension(extension.as_ref())
1475	}
1476
1477	fn _set_extension(&mut self, extension: &OsStr) -> bool {
1478	let file_stem = match self.file_stem() {
1479	None => return `false`,
1480	Some(f) => f.as_encoded_bytes(),
1481	};
1482
1483	// truncate until right after the file stem
1484	let end_file_stem = file_stem[file_stem.len()..].as_ptr().addr();
1485	let start = self.inner.as_encoded_bytes().as_ptr().addr();
1486	let v = self.as_mut_vec();
1487	v.truncate(end_file_stem.wrapping_sub(start));
1488
1489	// add the new extension, if any
1490	let new = extension.as_encoded_bytes();
1491	if !new.is_empty() {
1492	v.reserve_exact(new.len() + `1`);
1493	v.push(b'.');
1494	v.extend_from_slice(new);
1495	}
1496
1497	`true`
1498	}
1499
1500	/// Yields a mutable reference to the underlying [`OsString`] instance.
1501	///
1502	/// # Examples
1503	///
1504	/// ```
1505	/// use std::path::{Path, PathBuf};
1506	///
1507	/// let mut path = PathBuf::from("/foo");
1508	///
1509	/// path.push("bar");
1510	/// assert_eq!(path, Path::new("/foo/bar"));
1511	///
1512	/// // OsString's `push` does not add a separator.
1513	/// path.as_mut_os_string().push("baz");
1514	/// assert_eq!(path, Path::new("/foo/barbaz"));
1515	/// ```
1516	#[stable(feature = "path_as_mut_os_str", since = "1.70.0")]
1517	#[must_use]
1518	#[inline]
1519	pub fn as_mut_os_string(&mut self) -> &mut OsString {
1520	&mut self.inner
1521	}
1522
1523	/// Consumes the `PathBuf`, yielding its internal [`OsString`] storage.
1524	///
1525	/// # Examples
1526	///
1527	/// ```
1528	/// use std::path::PathBuf;
1529	///
1530	/// let p = PathBuf::from("/the/head");
1531	/// let os_str = p.into_os_string();
1532	/// ```
1533	#[stable(feature = "rust1", since = "1.0.0")]
1534	#[must_use = "`self` will be dropped if the result is not used"]
1535	#[inline]
1536	pub fn into_os_string(self) -> OsString {
1537	self.inner
1538	}
1539
1540	/// Converts this `PathBuf` into a [boxed](Box) [`Path`].
1541	#[stable(feature = "into_boxed_path", since = "1.20.0")]
1542	#[must_use = "`self` will be dropped if the result is not used"]
1543	#[inline]
1544	pub fn into_boxed_path(self) -> Box<Path> {
1545	let rw = Box::into_raw(self.inner.into_boxed_os_str()) as *mut Path;
1546	unsafe { Box::from_raw(rw) }
1547	}
1548
1549	/// Invokes [`capacity`] on the underlying instance of [`OsString`].
1550	///
1551	/// [`capacity`]: OsString::capacity
1552	#[stable(feature = "path_buf_capacity", since = "1.44.0")]
1553	#[must_use]
1554	#[inline]
1555	pub fn capacity(&self) -> usize {
1556	self.inner.capacity()
1557	}
1558
1559	/// Invokes [`clear`] on the underlying instance of [`OsString`].
1560	///
1561	/// [`clear`]: OsString::clear
1562	#[stable(feature = "path_buf_capacity", since = "1.44.0")]
1563	#[inline]
1564	pub fn clear(&mut self) {
1565	self.inner.clear()
1566	}
1567
1568	/// Invokes [`reserve`] on the underlying instance of [`OsString`].
1569	///
1570	/// [`reserve`]: OsString::reserve
1571	#[stable(feature = "path_buf_capacity", since = "1.44.0")]
1572	#[inline]
1573	pub fn reserve(&mut self, additional: usize) {
1574	self.inner.reserve(additional)
1575	}
1576
1577	/// Invokes [`try_reserve`] on the underlying instance of [`OsString`].
1578	///
1579	/// [`try_reserve`]: OsString::try_reserve
1580	#[stable(feature = "try_reserve_2", since = "1.63.0")]
1581	#[inline]
1582	pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> {
1583	self.inner.try_reserve(additional)
1584	}
1585
1586	/// Invokes [`reserve_exact`] on the underlying instance of [`OsString`].
1587	///
1588	/// [`reserve_exact`]: OsString::reserve_exact
1589	#[stable(feature = "path_buf_capacity", since = "1.44.0")]
1590	#[inline]
1591	pub fn reserve_exact(&mut self, additional: usize) {
1592	self.inner.reserve_exact(additional)
1593	}
1594
1595	/// Invokes [`try_reserve_exact`] on the underlying instance of [`OsString`].
1596	///
1597	/// [`try_reserve_exact`]: OsString::try_reserve_exact
1598	#[stable(feature = "try_reserve_2", since = "1.63.0")]
1599	#[inline]
1600	pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> {
1601	self.inner.try_reserve_exact(additional)
1602	}
1603
1604	/// Invokes [`shrink_to_fit`] on the underlying instance of [`OsString`].
1605	///
1606	/// [`shrink_to_fit`]: OsString::shrink_to_fit
1607	#[stable(feature = "path_buf_capacity", since = "1.44.0")]
1608	#[inline]
1609	pub fn shrink_to_fit(&mut self) {
1610	self.inner.shrink_to_fit()
1611	}
1612
1613	/// Invokes [`shrink_to`] on the underlying instance of [`OsString`].
1614	///
1615	/// [`shrink_to`]: OsString::shrink_to
1616	#[stable(feature = "shrink_to", since = "1.56.0")]
1617	#[inline]
1618	pub fn shrink_to(&mut self, min_capacity: usize) {
1619	self.inner.shrink_to(min_capacity)
1620	}
1621	}
1622
1623	#[stable(feature = "rust1", since = "1.0.0")]
1624	impl Clone for PathBuf {
1625	#[inline]
1626	fn clone(&self) -> Self {
1627	PathBuf { inner: self.inner.clone() }
1628	}
1629
1630	#[inline]
1631	fn clone_from(&mut self, source: &Self) {
1632	self.inner.clone_from(&source.inner)
1633	}
1634	}
1635
1636	#[stable(feature = "box_from_path", since = "1.17.0")]
1637	impl From<&Path> for Box<Path> {
1638	/// Creates a boxed [`Path`] from a reference.
1639	///
1640	/// This will allocate and clone `path` to it.
1641	fn from(path: &Path) -> Box<Path> {
1642	let boxed: Box<OsStr> = path.inner.into();
1643	let rw: mut Path = Box::into_raw(boxed) as mut Path;
1644	unsafe { Box::from_raw(rw) }
1645	}
1646	}
1647
1648	#[stable(feature = "box_from_cow", since = "1.45.0")]
1649	impl From<Cow<'_, Path>> for Box<Path> {
1650	/// Creates a boxed [`Path`] from a clone-on-write pointer.
1651	///
1652	/// Converting from a `Cow::Owned` does not clone or allocate.
1653	#[inline]
1654	fn from(cow: Cow<'_, Path>) -> Box<Path> {
1655	match cow {
1656	Cow::Borrowed(path: &Path) => Box::from(path),
1657	Cow::Owned(path: PathBuf) => Box::from(path),
1658	}
1659	}
1660	}
1661
1662	#[stable(feature = "path_buf_from_box", since = "1.18.0")]
1663	impl From<Box<Path>> for PathBuf {
1664	/// Converts a <code>[Box]<[Path]></code> into a [`PathBuf`].
1665	///
1666	/// This conversion does not allocate or copy memory.
1667	#[inline]
1668	fn from(boxed: Box<Path>) -> PathBuf {
1669	boxed.into_path_buf()
1670	}
1671	}
1672
1673	#[stable(feature = "box_from_path_buf", since = "1.20.0")]
1674	impl From<PathBuf> for Box<Path> {
1675	/// Converts a [`PathBuf`] into a <code>[Box]<[Path]></code>.
1676	///
1677	/// This conversion currently should not allocate memory,
1678	/// but this behavior is not guaranteed on all platforms or in all future versions.
1679	#[inline]
1680	fn from(p: PathBuf) -> Box<Path> {
1681	p.into_boxed_path()
1682	}
1683	}
1684
1685	#[stable(feature = "more_box_slice_clone", since = "1.29.0")]
1686	impl Clone for Box<Path> {
1687	#[inline]
1688	fn clone(&self) -> Self {
1689	self.to_path_buf().into_boxed_path()
1690	}
1691	}
1692
1693	#[stable(feature = "rust1", since = "1.0.0")]
1694	impl<T: ?Sized + AsRef<OsStr>> From<&T> for PathBuf {
1695	/// Converts a borrowed [`OsStr`] to a [`PathBuf`].
1696	///
1697	/// Allocates a [`PathBuf`] and copies the data into it.
1698	#[inline]
1699	fn from(s: &T) -> PathBuf {
1700	PathBuf::from(s.as_ref().to_os_string())
1701	}
1702	}
1703
1704	#[stable(feature = "rust1", since = "1.0.0")]
1705	impl From<OsString> for PathBuf {
1706	/// Converts an [`OsString`] into a [`PathBuf`]
1707	///
1708	/// This conversion does not allocate or copy memory.
1709	#[inline]
1710	fn from(s: OsString) -> PathBuf {
1711	PathBuf { inner: s }
1712	}
1713	}
1714
1715	#[stable(feature = "from_path_buf_for_os_string", since = "1.14.0")]
1716	impl From<PathBuf> for OsString {
1717	/// Converts a [`PathBuf`] into an [`OsString`]
1718	///
1719	/// This conversion does not allocate or copy memory.
1720	#[inline]
1721	fn from(path_buf: PathBuf) -> OsString {
1722	path_buf.inner
1723	}
1724	}
1725
1726	#[stable(feature = "rust1", since = "1.0.0")]
1727	impl From<String> for PathBuf {
1728	/// Converts a [`String`] into a [`PathBuf`]
1729	///
1730	/// This conversion does not allocate or copy memory.
1731	#[inline]
1732	fn from(s: String) -> PathBuf {
1733	PathBuf::from(OsString::from(s))
1734	}
1735	}
1736
1737	#[stable(feature = "path_from_str", since = "1.32.0")]
1738	impl FromStr for PathBuf {
1739	type Err = core::convert::Infallible;
1740
1741	#[inline]
1742	fn from_str(s: &str) -> Result<Self, Self::Err> {
1743	Ok(PathBuf::from(s))
1744	}
1745	}
1746
1747	#[stable(feature = "rust1", since = "1.0.0")]
1748	impl<P: AsRef<Path>> FromIterator<P> for PathBuf {
1749	fn from_iter<I: IntoIterator<Item = P>>(iter: I) -> PathBuf {
1750	let mut buf: PathBuf = PathBuf::new();
1751	buf.extend(iter);
1752	buf
1753	}
1754	}
1755
1756	#[stable(feature = "rust1", since = "1.0.0")]
1757	impl<P: AsRef<Path>> Extend<P> for PathBuf {
1758	fn extend<I: IntoIterator<Item = P>>(&mut self, iter: I) {
1759	iter.into_iter().for_each(move \|p: P\| self.push(path:p.as_ref()));
1760	}
1761
1762	#[inline]
1763	fn extend_one(&mut self, p: P) {
1764	self.push(path:p.as_ref());
1765	}
1766	}
1767
1768	#[stable(feature = "rust1", since = "1.0.0")]
1769	impl fmt::Debug for PathBuf {
1770	fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1771	fmt::Debug::fmt(&**self, f:formatter)
1772	}
1773	}
1774
1775	#[stable(feature = "rust1", since = "1.0.0")]
1776	impl ops::Deref for PathBuf {
1777	type Target = Path;
1778	#[inline]
1779	fn deref(&self) -> &Path {
1780	Path::new(&self.inner)
1781	}
1782	}
1783
1784	#[stable(feature = "path_buf_deref_mut", since = "1.68.0")]
1785	impl ops::DerefMut for PathBuf {
1786	#[inline]
1787	fn deref_mut(&mut self) -> &mut Path {
1788	Path::from_inner_mut(&mut self.inner)
1789	}
1790	}
1791
1792	#[stable(feature = "rust1", since = "1.0.0")]
1793	impl Borrow<Path> for PathBuf {
1794	#[inline]
1795	fn borrow(&self) -> &Path {
1796	self.deref()
1797	}
1798	}
1799
1800	#[stable(feature = "default_for_pathbuf", since = "1.17.0")]
1801	impl Default for PathBuf {
1802	#[inline]
1803	fn default() -> Self {
1804	PathBuf::new()
1805	}
1806	}
1807
1808	#[stable(feature = "cow_from_path", since = "1.6.0")]
1809	impl<'a> From<&'a Path> for Cow<'a, Path> {
1810	/// Creates a clone-on-write pointer from a reference to
1811	/// [`Path`].
1812	///
1813	/// This conversion does not clone or allocate.
1814	#[inline]
1815	fn from(s: &'a Path) -> Cow<'a, Path> {
1816	Cow::Borrowed(s)
1817	}
1818	}
1819
1820	#[stable(feature = "cow_from_path", since = "1.6.0")]
1821	impl<'a> From<PathBuf> for Cow<'a, Path> {
1822	/// Creates a clone-on-write pointer from an owned
1823	/// instance of [`PathBuf`].
1824	///
1825	/// This conversion does not clone or allocate.
1826	#[inline]
1827	fn from(s: PathBuf) -> Cow<'a, Path> {
1828	Cow::Owned(s)
1829	}
1830	}
1831
1832	#[stable(feature = "cow_from_pathbuf_ref", since = "1.28.0")]
1833	impl<'a> From<&'a PathBuf> for Cow<'a, Path> {
1834	/// Creates a clone-on-write pointer from a reference to
1835	/// [`PathBuf`].
1836	///
1837	/// This conversion does not clone or allocate.
1838	#[inline]
1839	fn from(p: &'a PathBuf) -> Cow<'a, Path> {
1840	Cow::Borrowed(p.as_path())
1841	}
1842	}
1843
1844	#[stable(feature = "pathbuf_from_cow_path", since = "1.28.0")]
1845	impl<'a> From<Cow<'a, Path>> for PathBuf {
1846	/// Converts a clone-on-write pointer to an owned path.
1847	///
1848	/// Converting from a `Cow::Owned` does not clone or allocate.
1849	#[inline]
1850	fn from(p: Cow<'a, Path>) -> Self {
1851	p.into_owned()
1852	}
1853	}
1854
1855	#[stable(feature = "shared_from_slice2", since = "1.24.0")]
1856	impl From<PathBuf> for Arc<Path> {
1857	/// Converts a [`PathBuf`] into an <code>[Arc]<[Path]></code> by moving the [`PathBuf`] data
1858	/// into a new [`Arc`] buffer.
1859	#[inline]
1860	fn from(s: PathBuf) -> Arc<Path> {
1861	let arc: Arc<OsStr> = Arc::from(s.into_os_string());
1862	unsafe { Arc::from_raw(ptr:Arc::into_raw(this:arc) as *const Path) }
1863	}
1864	}
1865
1866	#[stable(feature = "shared_from_slice2", since = "1.24.0")]
1867	impl From<&Path> for Arc<Path> {
1868	/// Converts a [`Path`] into an [`Arc`] by copying the [`Path`] data into a new [`Arc`] buffer.
1869	#[inline]
1870	fn from(s: &Path) -> Arc<Path> {
1871	let arc: Arc<OsStr> = Arc::from(s.as_os_str());
1872	unsafe { Arc::from_raw(ptr:Arc::into_raw(this:arc) as *const Path) }
1873	}
1874	}
1875
1876	#[stable(feature = "shared_from_slice2", since = "1.24.0")]
1877	impl From<PathBuf> for Rc<Path> {
1878	/// Converts a [`PathBuf`] into an <code>[Rc]<[Path]></code> by moving the [`PathBuf`] data into
1879	/// a new [`Rc`] buffer.
1880	#[inline]
1881	fn from(s: PathBuf) -> Rc<Path> {
1882	let rc: Rc<OsStr> = Rc::from(s.into_os_string());
1883	unsafe { Rc::from_raw(ptr:Rc::into_raw(this:rc) as *const Path) }
1884	}
1885	}
1886
1887	#[stable(feature = "shared_from_slice2", since = "1.24.0")]
1888	impl From<&Path> for Rc<Path> {
1889	/// Converts a [`Path`] into an [`Rc`] by copying the [`Path`] data into a new [`Rc`] buffer.
1890	#[inline]
1891	fn from(s: &Path) -> Rc<Path> {
1892	let rc: Rc<OsStr> = Rc::from(s.as_os_str());
1893	unsafe { Rc::from_raw(ptr:Rc::into_raw(this:rc) as *const Path) }
1894	}
1895	}
1896
1897	#[stable(feature = "rust1", since = "1.0.0")]
1898	impl ToOwned for Path {
1899	type Owned = PathBuf;
1900	#[inline]
1901	fn to_owned(&self) -> PathBuf {
1902	self.to_path_buf()
1903	}
1904	#[inline]
1905	fn clone_into(&self, target: &mut PathBuf) {
1906	self.inner.clone_into(&mut target.inner);
1907	}
1908	}
1909
1910	#[stable(feature = "rust1", since = "1.0.0")]
1911	impl PartialEq for PathBuf {
1912	#[inline]
1913	fn eq(&self, other: &PathBuf) -> bool {
1914	self.components() == other.components()
1915	}
1916	}
1917
1918	#[stable(feature = "rust1", since = "1.0.0")]
1919	impl Hash for PathBuf {
1920	fn hash<H: Hasher>(&self, h: &mut H) {
1921	self.as_path().hash(state:h)
1922	}
1923	}
1924
1925	#[stable(feature = "rust1", since = "1.0.0")]
1926	impl Eq for PathBuf {}
1927
1928	#[stable(feature = "rust1", since = "1.0.0")]
1929	impl PartialOrd for PathBuf {
1930	#[inline]
1931	fn partial_cmp(&self, other: &PathBuf) -> Option<cmp::Ordering> {
1932	Some(compare_components(self.components(), right:other.components()))
1933	}
1934	}
1935
1936	#[stable(feature = "rust1", since = "1.0.0")]
1937	impl Ord for PathBuf {
1938	#[inline]
1939	fn cmp(&self, other: &PathBuf) -> cmp::Ordering {
1940	compare_components(self.components(), right:other.components())
1941	}
1942	}
1943
1944	#[stable(feature = "rust1", since = "1.0.0")]
1945	impl AsRef<OsStr> for PathBuf {
1946	#[inline]
1947	fn as_ref(&self) -> &OsStr {
1948	&self.inner[..]
1949	}
1950	}
1951
1952	/// A slice of a path (akin to [`str`]).
1953	///
1954	/// This type supports a number of operations for inspecting a path, including
1955	/// breaking the path into its components (separated by `/` on Unix and by either
1956	/// `/` or `\` on Windows), extracting the file name, determining whether the path
1957	/// is absolute, and so on.
1958	///
1959	/// This is an unsized* type, meaning that it must always be used behind a*
1960	/// pointer like `&` or [`Box`]. For an owned version of this type,
1961	/// see [`PathBuf`].
1962	///
1963	/// More details about the overall approach can be found in
1964	/// the [module documentation](self).
1965	///
1966	/// # Examples
1967	///
1968	/// ```
1969	/// use std::path::Path;
1970	/// use std::ffi::OsStr;
1971	///
1972	/// // Note: this example does work on Windows
1973	/// let path = Path::new("./foo/bar.txt");
1974	///
1975	/// let parent = path.parent();
1976	/// assert_eq!(parent, Some(Path::new("./foo")));
1977	///
1978	/// let file_stem = path.file_stem();
1979	/// assert_eq!(file_stem, Some(OsStr::new("bar")));
1980	///
1981	/// let extension = path.extension();
1982	/// assert_eq!(extension, Some(OsStr::new("txt")));
1983	/// ```
1984	#[cfg_attr(not(test), rustc_diagnostic_item = "Path")]
1985	#[stable(feature = "rust1", since = "1.0.0")]
1986	// `Path::new` current implementation relies
1987	// on `Path` being layout-compatible with `OsStr`.
1988	// However, `Path` layout is considered an implementation detail and must not be relied upon. We
1989	// want `repr(transparent)` but we don't want it to show up in rustdoc, so we hide it under
1990	// `cfg(doc)`. This is an ad-hoc implementation of attribute privacy.
1991	#[cfg_attr(not(doc), repr(transparent))]
1992	pub struct Path {
1993	inner: OsStr,
1994	}
1995
1996	/// An error returned from [`Path::strip_prefix`] if the prefix was not found.
1997	///
1998	/// This `struct` is created by the [`strip_prefix`] method on [`Path`].
1999	/// See its documentation for more.
2000	///
2001	/// [`strip_prefix`]: Path::strip_prefix
2002	#[derive(Debug, Clone, PartialEq, Eq)]
2003	#[stable(since = "1.7.0", feature = "strip_prefix")]
2004	pub struct StripPrefixError(());
2005
2006	impl Path {
2007	// The following (private!) function allows construction of a path from a u8
2008	// slice, which is only safe when it is known to follow the OsStr encoding.
2009	unsafe fn from_u8_slice(s: &[u8]) -> &Path {
2010	unsafe { Path::new(OsStr::from_encoded_bytes_unchecked(s)) }
2011	}
2012	// The following (private!) function reveals the byte encoding used for OsStr.
2013	fn as_u8_slice(&self) -> &[u8] {
2014	self.inner.as_encoded_bytes()
2015	}
2016
2017	/// Directly wraps a string slice as a `Path` slice.
2018	///
2019	/// This is a cost-free conversion.
2020	///
2021	/// # Examples
2022	///
2023	/// ```
2024	/// use std::path::Path;
2025	///
2026	/// Path::new("foo.txt");
2027	/// ```
2028	///
2029	/// You can create `Path`s from `String`s, or even other `Path`s:
2030	///
2031	/// ```
2032	/// use std::path::Path;
2033	///
2034	/// let string = String::from("foo.txt");
2035	/// let from_string = Path::new(&string);
2036	/// let from_path = Path::new(&from_string);
2037	/// assert_eq!(from_string, from_path);
2038	/// ```
2039	#[stable(feature = "rust1", since = "1.0.0")]
2040	pub fn new<S: AsRef<OsStr> + ?Sized>(s: &S) -> &Path {
2041	unsafe { &(s.as_ref() as const OsStr as *const Path) }
2042	}
2043
2044	fn from_inner_mut(inner: &mut OsStr) -> &mut Path {
2045	// SAFETY: Path is just a wrapper around OsStr,
2046	// therefore converting &mut OsStr to &mut Path is safe.
2047	unsafe { &mut (inner as mut OsStr as *mut Path) }
2048	}
2049
2050	/// Yields the underlying [`OsStr`] slice.
2051	///
2052	/// # Examples
2053	///
2054	/// ```
2055	/// use std::path::Path;
2056	///
2057	/// let os_str = Path::new("foo.txt").as_os_str();
2058	/// assert_eq!(os_str, std::ffi::OsStr::new("foo.txt"));
2059	/// ```
2060	#[stable(feature = "rust1", since = "1.0.0")]
2061	#[must_use]
2062	#[inline]
2063	pub fn as_os_str(&self) -> &OsStr {
2064	&self.inner
2065	}
2066
2067	/// Yields a mutable reference to the underlying [`OsStr`] slice.
2068	///
2069	/// # Examples
2070	///
2071	/// ```
2072	/// use std::path::{Path, PathBuf};
2073	///
2074	/// let mut path = PathBuf::from("Foo.TXT");
2075	///
2076	/// assert_ne!(path, Path::new("foo.txt"));
2077	///
2078	/// path.as_mut_os_str().make_ascii_lowercase();
2079	/// assert_eq!(path, Path::new("foo.txt"));
2080	/// ```
2081	#[stable(feature = "path_as_mut_os_str", since = "1.70.0")]
2082	#[must_use]
2083	#[inline]
2084	pub fn as_mut_os_str(&mut self) -> &mut OsStr {
2085	&mut self.inner
2086	}
2087
2088	/// Yields a [`&str`] slice if the `Path` is valid unicode.
2089	///
2090	/// This conversion may entail doing a check for UTF-8 validity.
2091	/// Note that validation is performed because non-UTF-8 strings are
2092	/// perfectly valid for some OS.
2093	///
2094	/// [`&str`]: str
2095	///
2096	/// # Examples
2097	///
2098	/// ```
2099	/// use std::path::Path;
2100	///
2101	/// let path = Path::new("foo.txt");
2102	/// assert_eq!(path.to_str(), Some("foo.txt"));
2103	/// ```
2104	#[stable(feature = "rust1", since = "1.0.0")]
2105	#[must_use = "this returns the result of the operation, \
2106	without modifying the original"]
2107	#[inline]
2108	pub fn to_str(&self) -> Option<&str> {
2109	self.inner.to_str()
2110	}
2111
2112	/// Converts a `Path` to a [`Cow<str>`].
2113	///
2114	/// Any non-Unicode sequences are replaced with
2115	/// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD].
2116	///
2117	/// [U+FFFD]: super::char::REPLACEMENT_CHARACTER
2118	///
2119	/// # Examples
2120	///
2121	/// Calling `to_string_lossy` on a `Path` with valid unicode:
2122	///
2123	/// ```
2124	/// use std::path::Path;
2125	///
2126	/// let path = Path::new("foo.txt");
2127	/// assert_eq!(path.to_string_lossy(), "foo.txt");
2128	/// ```
2129	///
2130	/// Had `path` contained invalid unicode, the `to_string_lossy` call might
2131	/// have returned `"fo�.txt"`.
2132	#[stable(feature = "rust1", since = "1.0.0")]
2133	#[must_use = "this returns the result of the operation, \
2134	without modifying the original"]
2135	#[inline]
2136	pub fn to_string_lossy(&self) -> Cow<'_, str> {
2137	self.inner.to_string_lossy()
2138	}
2139
2140	/// Converts a `Path` to an owned [`PathBuf`].
2141	///
2142	/// # Examples
2143	///
2144	/// ```
2145	/// use std::path::Path;
2146	///
2147	/// let path_buf = Path::new("foo.txt").to_path_buf();
2148	/// assert_eq!(path_buf, std::path::PathBuf::from("foo.txt"));
2149	/// ```
2150	#[rustc_conversion_suggestion]
2151	#[must_use = "this returns the result of the operation, \
2152	without modifying the original"]
2153	#[stable(feature = "rust1", since = "1.0.0")]
2154	pub fn to_path_buf(&self) -> PathBuf {
2155	PathBuf::from(self.inner.to_os_string())
2156	}
2157
2158	/// Returns `true` if the `Path` is absolute, i.e., if it is independent of
2159	/// the current directory.
2160	///
2161	/// On Unix, a path is absolute if it starts with the root, so*
2162	/// `is_absolute` and [`has_root`] are equivalent.
2163	///
2164	/// On Windows, a path is absolute if it has a prefix and starts with the*
2165	/// root: `c:\windows` is absolute, while `c:temp` and `\temp` are not.
2166	///
2167	/// # Examples
2168	///
2169	/// ```
2170	/// use std::path::Path;
2171	///
2172	/// assert!(!Path::new("foo.txt").is_absolute());
2173	/// ```
2174	///
2175	/// [`has_root`]: Path::has_root
2176	#[stable(feature = "rust1", since = "1.0.0")]
2177	#[must_use]
2178	#[allow(deprecated)]
2179	pub fn is_absolute(&self) -> bool {
2180	if cfg!(target_os = "redox") {
2181	// FIXME: Allow Redox prefixes
2182	self.has_root() \|\| has_redox_scheme(self.as_u8_slice())
2183	} else {
2184	self.has_root() && (cfg!(any(unix, target_os = "wasi")) \|\| self.prefix().is_some())
2185	}
2186	}
2187
2188	/// Returns `true` if the `Path` is relative, i.e., not absolute.
2189	///
2190	/// See [`is_absolute`]'s documentation for more details.
2191	///
2192	/// # Examples
2193	///
2194	/// ```
2195	/// use std::path::Path;
2196	///
2197	/// assert!(Path::new("foo.txt").is_relative());
2198	/// ```
2199	///
2200	/// [`is_absolute`]: Path::is_absolute
2201	#[stable(feature = "rust1", since = "1.0.0")]
2202	#[must_use]
2203	#[inline]
2204	pub fn is_relative(&self) -> bool {
2205	!self.is_absolute()
2206	}
2207
2208	fn prefix(&self) -> Option<Prefix<'_>> {
2209	self.components().prefix
2210	}
2211
2212	/// Returns `true` if the `Path` has a root.
2213	///
2214	/// On Unix, a path has a root if it begins with `/`.*
2215	///
2216	/// On Windows, a path has a root if it:*
2217	/// has no prefix and begins with a separator, e.g., `\windows`*
2218	/// has a prefix followed by a separator, e.g., `c:\windows` but not `c:windows`*
2219	/// has any non-disk prefix, e.g., `\\server\share`*
2220	///
2221	/// # Examples
2222	///
2223	/// ```
2224	/// use std::path::Path;
2225	///
2226	/// assert!(Path::new("/etc/passwd").has_root());
2227	/// ```
2228	#[stable(feature = "rust1", since = "1.0.0")]
2229	#[must_use]
2230	#[inline]
2231	pub fn has_root(&self) -> bool {
2232	self.components().has_root()
2233	}
2234
2235	/// Returns the `Path` without its final component, if there is one.
2236	///
2237	/// This means it returns `Some("")` for relative paths with one component.
2238	///
2239	/// Returns [`None`] if the path terminates in a root or prefix, or if it's
2240	/// the empty string.
2241	///
2242	/// # Examples
2243	///
2244	/// ```
2245	/// use std::path::Path;
2246	///
2247	/// let path = Path::new("/foo/bar");
2248	/// let parent = path.parent().unwrap();
2249	/// assert_eq!(parent, Path::new("/foo"));
2250	///
2251	/// let grand_parent = parent.parent().unwrap();
2252	/// assert_eq!(grand_parent, Path::new("/"));
2253	/// assert_eq!(grand_parent.parent(), None);
2254	///
2255	/// let relative_path = Path::new("foo/bar");
2256	/// let parent = relative_path.parent();
2257	/// assert_eq!(parent, Some(Path::new("foo")));
2258	/// let grand_parent = parent.and_then(Path::parent);
2259	/// assert_eq!(grand_parent, Some(Path::new("")));
2260	/// let great_grand_parent = grand_parent.and_then(Path::parent);
2261	/// assert_eq!(great_grand_parent, None);
2262	/// ```
2263	#[stable(feature = "rust1", since = "1.0.0")]
2264	#[doc(alias = "dirname")]
2265	#[must_use]
2266	pub fn parent(&self) -> Option<&Path> {
2267	let mut comps = self.components();
2268	let comp = comps.next_back();
2269	comp.and_then(\|p\| match p {
2270	Component::Normal(_) \| Component::CurDir \| Component::ParentDir => {
2271	Some(comps.as_path())
2272	}
2273	_ => None,
2274	})
2275	}
2276
2277	/// Produces an iterator over `Path` and its ancestors.
2278	///
2279	/// The iterator will yield the `Path` that is returned if the [`parent`] method is used zero
2280	/// or more times. That means, the iterator will yield `&self`, `&self.parent().unwrap()`,
2281	/// `&self.parent().unwrap().parent().unwrap()` and so on. If the [`parent`] method returns
2282	/// [`None`], the iterator will do likewise. The iterator will always yield at least one value,
2283	/// namely `&self`.
2284	///
2285	/// # Examples
2286	///
2287	/// ```
2288	/// use std::path::Path;
2289	///
2290	/// let mut ancestors = Path::new("/foo/bar").ancestors();
2291	/// assert_eq!(ancestors.next(), Some(Path::new("/foo/bar")));
2292	/// assert_eq!(ancestors.next(), Some(Path::new("/foo")));
2293	/// assert_eq!(ancestors.next(), Some(Path::new("/")));
2294	/// assert_eq!(ancestors.next(), None);
2295	///
2296	/// let mut ancestors = Path::new("../foo/bar").ancestors();
2297	/// assert_eq!(ancestors.next(), Some(Path::new("../foo/bar")));
2298	/// assert_eq!(ancestors.next(), Some(Path::new("../foo")));
2299	/// assert_eq!(ancestors.next(), Some(Path::new("..")));
2300	/// assert_eq!(ancestors.next(), Some(Path::new("")));
2301	/// assert_eq!(ancestors.next(), None);
2302	/// ```
2303	///
2304	/// [`parent`]: Path::parent
2305	#[stable(feature = "path_ancestors", since = "1.28.0")]
2306	#[inline]
2307	pub fn ancestors(&self) -> Ancestors<'_> {
2308	Ancestors { next: Some(&self) }
2309	}
2310
2311	/// Returns the final component of the `Path`, if there is one.
2312	///
2313	/// If the path is a normal file, this is the file name. If it's the path of a directory, this
2314	/// is the directory name.
2315	///
2316	/// Returns [`None`] if the path terminates in `..`.
2317	///
2318	/// # Examples
2319	///
2320	/// ```
2321	/// use std::path::Path;
2322	/// use std::ffi::OsStr;
2323	///
2324	/// assert_eq!(Some(OsStr::new("bin")), Path::new("/usr/bin/").file_name());
2325	/// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("tmp/foo.txt").file_name());
2326	/// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("foo.txt/.").file_name());
2327	/// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("foo.txt/.//").file_name());
2328	/// assert_eq!(None, Path::new("foo.txt/..").file_name());
2329	/// assert_eq!(None, Path::new("/").file_name());
2330	/// ```
2331	#[stable(feature = "rust1", since = "1.0.0")]
2332	#[doc(alias = "basename")]
2333	#[must_use]
2334	pub fn file_name(&self) -> Option<&OsStr> {
2335	self.components().next_back().and_then(\|p\| match p {
2336	Component::Normal(p) => Some(p),
2337	_ => None,
2338	})
2339	}
2340
2341	/// Returns a path that, when joined onto `base`, yields `self`.
2342	///
2343	/// # Errors
2344	///
2345	/// If `base` is not a prefix of `self` (i.e., [`starts_with`]
2346	/// returns `false`), returns [`Err`].
2347	///
2348	/// [`starts_with`]: Path::starts_with
2349	///
2350	/// # Examples
2351	///
2352	/// ```
2353	/// use std::path::{Path, PathBuf};
2354	///
2355	/// let path = Path::new("/test/haha/foo.txt");
2356	///
2357	/// assert_eq!(path.strip_prefix("/"), Ok(Path::new("test/haha/foo.txt")));
2358	/// assert_eq!(path.strip_prefix("/test"), Ok(Path::new("haha/foo.txt")));
2359	/// assert_eq!(path.strip_prefix("/test/"), Ok(Path::new("haha/foo.txt")));
2360	/// assert_eq!(path.strip_prefix("/test/haha/foo.txt"), Ok(Path::new("")));
2361	/// assert_eq!(path.strip_prefix("/test/haha/foo.txt/"), Ok(Path::new("")));
2362	///
2363	/// assert!(path.strip_prefix("test").is_err());
2364	/// assert!(path.strip_prefix("/haha").is_err());
2365	///
2366	/// let prefix = PathBuf::from("/test/");
2367	/// assert_eq!(path.strip_prefix(prefix), Ok(Path::new("haha/foo.txt")));
2368	/// ```
2369	#[stable(since = "1.7.0", feature = "path_strip_prefix")]
2370	pub fn strip_prefix<P>(&self, base: P) -> Result<&Path, StripPrefixError>
2371	where
2372	P: AsRef<Path>,
2373	{
2374	self._strip_prefix(base.as_ref())
2375	}
2376
2377	fn _strip_prefix(&self, base: &Path) -> Result<&Path, StripPrefixError> {
2378	iter_after(self.components(), base.components())
2379	.map(\|c\| c.as_path())
2380	.ok_or(StripPrefixError(()))
2381	}
2382
2383	/// Determines whether `base` is a prefix of `self`.
2384	///
2385	/// Only considers whole path components to match.
2386	///
2387	/// # Examples
2388	///
2389	/// ```
2390	/// use std::path::Path;
2391	///
2392	/// let path = Path::new("/etc/passwd");
2393	///
2394	/// assert!(path.starts_with("/etc"));
2395	/// assert!(path.starts_with("/etc/"));
2396	/// assert!(path.starts_with("/etc/passwd"));
2397	/// assert!(path.starts_with("/etc/passwd/")); // extra slash is okay
2398	/// assert!(path.starts_with("/etc/passwd///")); // multiple extra slashes are okay
2399	///
2400	/// assert!(!path.starts_with("/e"));
2401	/// assert!(!path.starts_with("/etc/passwd.txt"));
2402	///
2403	/// assert!(!Path::new("/etc/foo.rs").starts_with("/etc/foo"));
2404	/// ```
2405	#[stable(feature = "rust1", since = "1.0.0")]
2406	#[must_use]
2407	pub fn starts_with<P: AsRef<Path>>(&self, base: P) -> bool {
2408	self._starts_with(base.as_ref())
2409	}
2410
2411	fn _starts_with(&self, base: &Path) -> bool {
2412	iter_after(self.components(), base.components()).is_some()
2413	}
2414
2415	/// Determines whether `child` is a suffix of `self`.
2416	///
2417	/// Only considers whole path components to match.
2418	///
2419	/// # Examples
2420	///
2421	/// ```
2422	/// use std::path::Path;
2423	///
2424	/// let path = Path::new("/etc/resolv.conf");
2425	///
2426	/// assert!(path.ends_with("resolv.conf"));
2427	/// assert!(path.ends_with("etc/resolv.conf"));
2428	/// assert!(path.ends_with("/etc/resolv.conf"));
2429	///
2430	/// assert!(!path.ends_with("/resolv.conf"));
2431	/// assert!(!path.ends_with("conf")); // use .extension() instead
2432	/// ```
2433	#[stable(feature = "rust1", since = "1.0.0")]
2434	#[must_use]
2435	pub fn ends_with<P: AsRef<Path>>(&self, child: P) -> bool {
2436	self._ends_with(child.as_ref())
2437	}
2438
2439	fn _ends_with(&self, child: &Path) -> bool {
2440	iter_after(self.components().rev(), child.components().rev()).is_some()
2441	}
2442
2443	/// Extracts the stem (non-extension) portion of [`self.file_name`].
2444	///
2445	/// [`self.file_name`]: Path::file_name
2446	///
2447	/// The stem is:
2448	///
2449	/// * [`None`], if there is no file name;
2450	/// The entire file name if there is no embedded `.`;*
2451	/// The entire file name if the file name begins with `.` and has no other `.`s within;*
2452	/// Otherwise, the portion of the file name before the final `.`*
2453	///
2454	/// # Examples
2455	///
2456	/// ```
2457	/// use std::path::Path;
2458	///
2459	/// assert_eq!("foo", Path::new("foo.rs").file_stem().unwrap());
2460	/// assert_eq!("foo.tar", Path::new("foo.tar.gz").file_stem().unwrap());
2461	/// ```
2462	///
2463	/// # See Also
2464	/// This method is similar to [`Path::file_prefix`], which extracts the portion of the file name
2465	/// before the first* `.`*
2466	///
2467	/// [`Path::file_prefix`]: Path::file_prefix
2468	///
2469	#[stable(feature = "rust1", since = "1.0.0")]
2470	#[must_use]
2471	pub fn file_stem(&self) -> Option<&OsStr> {
2472	self.file_name().map(rsplit_file_at_dot).and_then(\|(before, after)\| before.or(after))
2473	}
2474
2475	/// Extracts the prefix of [`self.file_name`].
2476	///
2477	/// The prefix is:
2478	///
2479	/// * [`None`], if there is no file name;
2480	/// The entire file name if there is no embedded `.`;*
2481	/// The portion of the file name before the first non-beginning `.`;*
2482	/// The entire file name if the file name begins with `.` and has no other `.`s within;*
2483	/// The portion of the file name before the second `.` if the file name begins with `.`*
2484	///
2485	/// [`self.file_name`]: Path::file_name
2486	///
2487	/// # Examples
2488	///
2489	/// ```
2490	/// # #![feature(path_file_prefix)]
2491	/// use std::path::Path;
2492	///
2493	/// assert_eq!("foo", Path::new("foo.rs").file_prefix().unwrap());
2494	/// assert_eq!("foo", Path::new("foo.tar.gz").file_prefix().unwrap());
2495	/// ```
2496	///
2497	/// # See Also
2498	/// This method is similar to [`Path::file_stem`], which extracts the portion of the file name
2499	/// before the last* `.`*
2500	///
2501	/// [`Path::file_stem`]: Path::file_stem
2502	///
2503	#[unstable(feature = "path_file_prefix", issue = "86319")]
2504	#[must_use]
2505	pub fn file_prefix(&self) -> Option<&OsStr> {
2506	self.file_name().map(split_file_at_dot).and_then(\|(before, _after)\| Some(before))
2507	}
2508
2509	/// Extracts the extension (without the leading dot) of [`self.file_name`], if possible.
2510	///
2511	/// The extension is:
2512	///
2513	/// * [`None`], if there is no file name;
2514	/// * [`None`], if there is no embedded `.`;
2515	/// * [`None`], if the file name begins with `.` and has no other `.`s within;
2516	/// Otherwise, the portion of the file name after the final `.`*
2517	///
2518	/// [`self.file_name`]: Path::file_name
2519	///
2520	/// # Examples
2521	///
2522	/// ```
2523	/// use std::path::Path;
2524	///
2525	/// assert_eq!("rs", Path::new("foo.rs").extension().unwrap());
2526	/// assert_eq!("gz", Path::new("foo.tar.gz").extension().unwrap());
2527	/// ```
2528	#[stable(feature = "rust1", since = "1.0.0")]
2529	#[must_use]
2530	pub fn extension(&self) -> Option<&OsStr> {
2531	self.file_name().map(rsplit_file_at_dot).and_then(\|(before, after)\| before.and(after))
2532	}
2533
2534	/// Creates an owned [`PathBuf`] with `path` adjoined to `self`.
2535	///
2536	/// If `path` is absolute, it replaces the current path.
2537	///
2538	/// See [`PathBuf::push`] for more details on what it means to adjoin a path.
2539	///
2540	/// # Examples
2541	///
2542	/// ```
2543	/// use std::path::{Path, PathBuf};
2544	///
2545	/// assert_eq!(Path::new("/etc").join("passwd"), PathBuf::from("/etc/passwd"));
2546	/// assert_eq!(Path::new("/etc").join("/bin/sh"), PathBuf::from("/bin/sh"));
2547	/// ```
2548	#[stable(feature = "rust1", since = "1.0.0")]
2549	#[must_use]
2550	pub fn join<P: AsRef<Path>>(&self, path: P) -> PathBuf {
2551	self._join(path.as_ref())
2552	}
2553
2554	fn _join(&self, path: &Path) -> PathBuf {
2555	let mut buf = self.to_path_buf();
2556	buf.push(path);
2557	buf
2558	}
2559
2560	/// Creates an owned [`PathBuf`] like `self` but with the given file name.
2561	///
2562	/// See [`PathBuf::set_file_name`] for more details.
2563	///
2564	/// # Examples
2565	///
2566	/// ```
2567	/// use std::path::{Path, PathBuf};
2568	///
2569	/// let path = Path::new("/tmp/foo.png");
2570	/// assert_eq!(path.with_file_name("bar"), PathBuf::from("/tmp/bar"));
2571	/// assert_eq!(path.with_file_name("bar.txt"), PathBuf::from("/tmp/bar.txt"));
2572	///
2573	/// let path = Path::new("/tmp");
2574	/// assert_eq!(path.with_file_name("var"), PathBuf::from("/var"));
2575	/// ```
2576	#[stable(feature = "rust1", since = "1.0.0")]
2577	#[must_use]
2578	pub fn with_file_name<S: AsRef<OsStr>>(&self, file_name: S) -> PathBuf {
2579	self._with_file_name(file_name.as_ref())
2580	}
2581
2582	fn _with_file_name(&self, file_name: &OsStr) -> PathBuf {
2583	let mut buf = self.to_path_buf();
2584	buf.set_file_name(file_name);
2585	buf
2586	}
2587
2588	/// Creates an owned [`PathBuf`] like `self` but with the given extension.
2589	///
2590	/// See [`PathBuf::set_extension`] for more details.
2591	///
2592	/// # Examples
2593	///
2594	/// ```
2595	/// use std::path::{Path, PathBuf};
2596	///
2597	/// let path = Path::new("foo.rs");
2598	/// assert_eq!(path.with_extension("txt"), PathBuf::from("foo.txt"));
2599	///
2600	/// let path = Path::new("foo.tar.gz");
2601	/// assert_eq!(path.with_extension(""), PathBuf::from("foo.tar"));
2602	/// assert_eq!(path.with_extension("xz"), PathBuf::from("foo.tar.xz"));
2603	/// assert_eq!(path.with_extension("").with_extension("txt"), PathBuf::from("foo.txt"));
2604	/// ```
2605	#[stable(feature = "rust1", since = "1.0.0")]
2606	pub fn with_extension<S: AsRef<OsStr>>(&self, extension: S) -> PathBuf {
2607	self._with_extension(extension.as_ref())
2608	}
2609
2610	fn _with_extension(&self, extension: &OsStr) -> PathBuf {
2611	let self_len = self.as_os_str().len();
2612	let self_bytes = self.as_os_str().as_encoded_bytes();
2613
2614	let (new_capacity, slice_to_copy) = match self.extension() {
2615	None => {
2616	// Enough capacity for the extension and the dot
2617	let capacity = self_len + extension.len() + `1`;
2618	let whole_path = self_bytes.iter();
2619	(capacity, whole_path)
2620	}
2621	Some(previous_extension) => {
2622	let capacity = self_len + extension.len() - previous_extension.len();
2623	let path_till_dot = self_bytes[..self_len - previous_extension.len()].iter();
2624	(capacity, path_till_dot)
2625	}
2626	};
2627
2628	let mut new_path = PathBuf::with_capacity(new_capacity);
2629	new_path.as_mut_vec().extend(slice_to_copy);
2630	new_path.set_extension(extension);
2631	new_path
2632	}
2633
2634	/// Produces an iterator over the [`Component`]s of the path.
2635	///
2636	/// When parsing the path, there is a small amount of normalization:
2637	///
2638	/// Repeated separators are ignored, so `a/b` and `a//b` both have*
2639	/// `a` and `b` as components.
2640	///
2641	/// Occurrences of `.` are normalized away, except if they are at the*
2642	/// beginning of the path. For example, `a/./b`, `a/b/`, `a/b/.` and
2643	/// `a/b` all have `a` and `b` as components, but `./a/b` starts with
2644	/// an additional [`CurDir`] component.
2645	///
2646	/// A trailing slash is normalized away, `/a/b` and `/a/b/` are equivalent.*
2647	///
2648	/// Note that no other normalization takes place; in particular, `a/c`
2649	/// and `a/b/../c` are distinct, to account for the possibility that `b`
2650	/// is a symbolic link (so its parent isn't `a`).
2651	///
2652	/// # Examples
2653	///
2654	/// ```
2655	/// use std::path::{Path, Component};
2656	/// use std::ffi::OsStr;
2657	///
2658	/// let mut components = Path::new("/tmp/foo.txt").components();
2659	///
2660	/// assert_eq!(components.next(), Some(Component::RootDir));
2661	/// assert_eq!(components.next(), Some(Component::Normal(OsStr::new("tmp"))));
2662	/// assert_eq!(components.next(), Some(Component::Normal(OsStr::new("foo.txt"))));
2663	/// assert_eq!(components.next(), None)
2664	/// ```
2665	///
2666	/// [`CurDir`]: Component::CurDir
2667	#[stable(feature = "rust1", since = "1.0.0")]
2668	pub fn components(&self) -> Components<'_> {
2669	let prefix = parse_prefix(self.as_os_str());
2670	Components {
2671	path: self.as_u8_slice(),
2672	prefix,
2673	has_physical_root: has_physical_root(self.as_u8_slice(), prefix)
2674	\|\| has_redox_scheme(self.as_u8_slice()),
2675	front: State::Prefix,
2676	back: State::Body,
2677	}
2678	}
2679
2680	/// Produces an iterator over the path's components viewed as [`OsStr`]
2681	/// slices.
2682	///
2683	/// For more information about the particulars of how the path is separated
2684	/// into components, see [`components`].
2685	///
2686	/// [`components`]: Path::components
2687	///
2688	/// # Examples
2689	///
2690	/// ```
2691	/// use std::path::{self, Path};
2692	/// use std::ffi::OsStr;
2693	///
2694	/// let mut it = Path::new("/tmp/foo.txt").iter();
2695	/// assert_eq!(it.next(), Some(OsStr::new(&path::MAIN_SEPARATOR.to_string())));
2696	/// assert_eq!(it.next(), Some(OsStr::new("tmp")));
2697	/// assert_eq!(it.next(), Some(OsStr::new("foo.txt")));
2698	/// assert_eq!(it.next(), None)
2699	/// ```
2700	#[stable(feature = "rust1", since = "1.0.0")]
2701	#[inline]
2702	pub fn iter(&self) -> Iter<'_> {
2703	Iter { inner: self.components() }
2704	}
2705
2706	/// Returns an object that implements [`Display`] for safely printing paths
2707	/// that may contain non-Unicode data. This may perform lossy conversion,
2708	/// depending on the platform. If you would like an implementation which
2709	/// escapes the path please use [`Debug`] instead.
2710	///
2711	/// [`Display`]: fmt::Display
2712	/// [`Debug`]: fmt::Debug
2713	///
2714	/// # Examples
2715	///
2716	/// ```
2717	/// use std::path::Path;
2718	///
2719	/// let path = Path::new("/tmp/foo.rs");
2720	///
2721	/// println!("{}", path.display());
2722	/// ```
2723	#[stable(feature = "rust1", since = "1.0.0")]
2724	#[must_use = "this does not display the path, \
2725	it returns an object that can be displayed"]
2726	#[inline]
2727	pub fn display(&self) -> Display<'_> {
2728	Display { path: self }
2729	}
2730
2731	/// Queries the file system to get information about a file, directory, etc.
2732	///
2733	/// This function will traverse symbolic links to query information about the
2734	/// destination file.
2735	///
2736	/// This is an alias to [`fs::metadata`].
2737	///
2738	/// # Examples
2739	///
2740	/// ```no_run
2741	/// use std::path::Path;
2742	///
2743	/// let path = Path::new("/Minas/tirith");
2744	/// let metadata = path.metadata().expect("metadata call failed");
2745	/// println!("{:?}", metadata.file_type());
2746	/// ```
2747	#[stable(feature = "path_ext", since = "1.5.0")]
2748	#[inline]
2749	pub fn metadata(&self) -> io::Result<fs::Metadata> {
2750	fs::metadata(self)
2751	}
2752
2753	/// Queries the metadata about a file without following symlinks.
2754	///
2755	/// This is an alias to [`fs::symlink_metadata`].
2756	///
2757	/// # Examples
2758	///
2759	/// ```no_run
2760	/// use std::path::Path;
2761	///
2762	/// let path = Path::new("/Minas/tirith");
2763	/// let metadata = path.symlink_metadata().expect("symlink_metadata call failed");
2764	/// println!("{:?}", metadata.file_type());
2765	/// ```
2766	#[stable(feature = "path_ext", since = "1.5.0")]
2767	#[inline]
2768	pub fn symlink_metadata(&self) -> io::Result<fs::Metadata> {
2769	fs::symlink_metadata(self)
2770	}
2771
2772	/// Returns the canonical, absolute form of the path with all intermediate
2773	/// components normalized and symbolic links resolved.
2774	///
2775	/// This is an alias to [`fs::canonicalize`].
2776	///
2777	/// # Examples
2778	///
2779	/// ```no_run
2780	/// use std::path::{Path, PathBuf};
2781	///
2782	/// let path = Path::new("/foo/test/../test/bar.rs");
2783	/// assert_eq!(path.canonicalize().unwrap(), PathBuf::from("/foo/test/bar.rs"));
2784	/// ```
2785	#[stable(feature = "path_ext", since = "1.5.0")]
2786	#[inline]
2787	pub fn canonicalize(&self) -> io::Result<PathBuf> {
2788	fs::canonicalize(self)
2789	}
2790
2791	/// Reads a symbolic link, returning the file that the link points to.
2792	///
2793	/// This is an alias to [`fs::read_link`].
2794	///
2795	/// # Examples
2796	///
2797	/// ```no_run
2798	/// use std::path::Path;
2799	///
2800	/// let path = Path::new("/laputa/sky_castle.rs");
2801	/// let path_link = path.read_link().expect("read_link call failed");
2802	/// ```
2803	#[stable(feature = "path_ext", since = "1.5.0")]
2804	#[inline]
2805	pub fn read_link(&self) -> io::Result<PathBuf> {
2806	fs::read_link(self)
2807	}
2808
2809	/// Returns an iterator over the entries within a directory.
2810	///
2811	/// The iterator will yield instances of <code>[io::Result]<[fs::DirEntry]></code>. New
2812	/// errors may be encountered after an iterator is initially constructed.
2813	///
2814	/// This is an alias to [`fs::read_dir`].
2815	///
2816	/// # Examples
2817	///
2818	/// ```no_run
2819	/// use std::path::Path;
2820	///
2821	/// let path = Path::new("/laputa");
2822	/// for entry in path.read_dir().expect("read_dir call failed") {
2823	/// if let Ok(entry) = entry {
2824	/// println!("{:?}", entry.path());
2825	/// }
2826	/// }
2827	/// ```
2828	#[stable(feature = "path_ext", since = "1.5.0")]
2829	#[inline]
2830	pub fn read_dir(&self) -> io::Result<fs::ReadDir> {
2831	fs::read_dir(self)
2832	}
2833
2834	/// Returns `true` if the path points at an existing entity.
2835	///
2836	/// Warning: this method may be error-prone, consider using [`try_exists()`] instead!
2837	/// It also has a risk of introducing time-of-check to time-of-use (TOCTOU) bugs.
2838	///
2839	/// This function will traverse symbolic links to query information about the
2840	/// destination file.
2841	///
2842	/// If you cannot access the metadata of the file, e.g. because of a
2843	/// permission error or broken symbolic links, this will return `false`.
2844	///
2845	/// # Examples
2846	///
2847	/// ```no_run
2848	/// use std::path::Path;
2849	/// assert!(!Path::new("does_not_exist.txt").exists());
2850	/// ```
2851	///
2852	/// # See Also
2853	///
2854	/// This is a convenience function that coerces errors to false. If you want to
2855	/// check errors, call [`Path::try_exists`].
2856	///
2857	/// [`try_exists()`]: Self::try_exists
2858	#[stable(feature = "path_ext", since = "1.5.0")]
2859	#[must_use]
2860	#[inline]
2861	pub fn exists(&self) -> bool {
2862	fs::metadata(self).is_ok()
2863	}
2864
2865	/// Returns `Ok(true)` if the path points at an existing entity.
2866	///
2867	/// This function will traverse symbolic links to query information about the
2868	/// destination file. In case of broken symbolic links this will return `Ok(false)`.
2869	///
2870	/// [`Path::exists()`] only checks whether or not a path was both found and readable. By
2871	/// contrast, `try_exists` will return `Ok(true)` or `Ok(false)`, respectively, if the path
2872	/// was _verified_ to exist or not exist. If its existence can neither be confirmed nor
2873	/// denied, it will propagate an `Err(_)` instead. This can be the case if e.g. listing
2874	/// permission is denied on one of the parent directories.
2875	///
2876	/// Note that while this avoids some pitfalls of the `exists()` method, it still can not
2877	/// prevent time-of-check to time-of-use (TOCTOU) bugs. You should only use it in scenarios
2878	/// where those bugs are not an issue.
2879	///
2880	/// # Examples
2881	///
2882	/// ```no_run
2883	/// use std::path::Path;
2884	/// assert!(!Path::new("does_not_exist.txt").try_exists().expect("Can't check existence of file does_not_exist.txt"));
2885	/// assert!(Path::new("/root/secret_file.txt").try_exists().is_err());
2886	/// ```
2887	///
2888	/// [`exists()`]: Self::exists
2889	#[stable(feature = "path_try_exists", since = "1.63.0")]
2890	#[inline]
2891	pub fn try_exists(&self) -> io::Result<bool> {
2892	fs::try_exists(self)
2893	}
2894
2895	/// Returns `true` if the path exists on disk and is pointing at a regular file.
2896	///
2897	/// This function will traverse symbolic links to query information about the
2898	/// destination file.
2899	///
2900	/// If you cannot access the metadata of the file, e.g. because of a
2901	/// permission error or broken symbolic links, this will return `false`.
2902	///
2903	/// # Examples
2904	///
2905	/// ```no_run
2906	/// use std::path::Path;
2907	/// assert_eq!(Path::new("./is_a_directory/").is_file(), `false`);
2908	/// assert_eq!(Path::new("a_file.txt").is_file(), `true`);
2909	/// ```
2910	///
2911	/// # See Also
2912	///
2913	/// This is a convenience function that coerces errors to false. If you want to
2914	/// check errors, call [`fs::metadata`] and handle its [`Result`]. Then call
2915	/// [`fs::Metadata::is_file`] if it was [`Ok`].
2916	///
2917	/// When the goal is simply to read from (or write to) the source, the most
2918	/// reliable way to test the source can be read (or written to) is to open
2919	/// it. Only using `is_file` can break workflows like `diff <( prog_a )` on
2920	/// a Unix-like system for example. See [`fs::File::open`] or
2921	/// [`fs::OpenOptions::open`] for more information.
2922	#[stable(feature = "path_ext", since = "1.5.0")]
2923	#[must_use]
2924	pub fn is_file(&self) -> bool {
2925	fs::metadata(self).map(\|m\| m.is_file()).unwrap_or(`false`)
2926	}
2927
2928	/// Returns `true` if the path exists on disk and is pointing at a directory.
2929	///
2930	/// This function will traverse symbolic links to query information about the
2931	/// destination file.
2932	///
2933	/// If you cannot access the metadata of the file, e.g. because of a
2934	/// permission error or broken symbolic links, this will return `false`.
2935	///
2936	/// # Examples
2937	///
2938	/// ```no_run
2939	/// use std::path::Path;
2940	/// assert_eq!(Path::new("./is_a_directory/").is_dir(), `true`);
2941	/// assert_eq!(Path::new("a_file.txt").is_dir(), `false`);
2942	/// ```
2943	///
2944	/// # See Also
2945	///
2946	/// This is a convenience function that coerces errors to false. If you want to
2947	/// check errors, call [`fs::metadata`] and handle its [`Result`]. Then call
2948	/// [`fs::Metadata::is_dir`] if it was [`Ok`].
2949	#[stable(feature = "path_ext", since = "1.5.0")]
2950	#[must_use]
2951	pub fn is_dir(&self) -> bool {
2952	fs::metadata(self).map(\|m\| m.is_dir()).unwrap_or(`false`)
2953	}
2954
2955	/// Returns `true` if the path exists on disk and is pointing at a symbolic link.
2956	///
2957	/// This function will not traverse symbolic links.
2958	/// In case of a broken symbolic link this will also return true.
2959	///
2960	/// If you cannot access the directory containing the file, e.g., because of a
2961	/// permission error, this will return false.
2962	///
2963	/// # Examples
2964	///
2965	#[cfg_attr(unix, doc = "```no_run")]
2966	#[cfg_attr(not(unix), doc = "```ignore")]
2967	/// use std::path::Path;
2968	/// use std::os::unix::fs::symlink;
2969	///
2970	/// let link_path = Path::new("link");
2971	/// symlink("/origin_does_not_exist/", link_path).unwrap();
2972	/// assert_eq!(link_path.is_symlink(), `true`);
2973	/// assert_eq!(link_path.exists(), `false`);
2974	/// ```
2975	///
2976	/// # See Also
2977	///
2978	/// This is a convenience function that coerces errors to false. If you want to
2979	/// check errors, call [`fs::symlink_metadata`] and handle its [`Result`]. Then call
2980	/// [`fs::Metadata::is_symlink`] if it was [`Ok`].
2981	#[must_use]
2982	#[stable(feature = "is_symlink", since = "1.58.0")]
2983	pub fn is_symlink(&self) -> bool {
2984	fs::symlink_metadata(self).map(\|m\| m.is_symlink()).unwrap_or(`false`)
2985	}
2986
2987	/// Converts a [`Box<Path>`](Box) into a [`PathBuf`] without copying or
2988	/// allocating.
2989	#[stable(feature = "into_boxed_path", since = "1.20.0")]
2990	#[must_use = "`self` will be dropped if the result is not used"]
2991	pub fn into_path_buf(self: Box<Path>) -> PathBuf {
2992	let rw = Box::into_raw(self) as *mut OsStr;
2993	let inner = unsafe { Box::from_raw(rw) };
2994	PathBuf { inner: OsString::from(inner) }
2995	}
2996	}
2997
2998	#[stable(feature = "rust1", since = "1.0.0")]
2999	impl AsRef<OsStr> for Path {
3000	#[inline]
3001	fn as_ref(&self) -> &OsStr {
3002	&self.inner
3003	}
3004	}
3005
3006	#[stable(feature = "rust1", since = "1.0.0")]
3007	impl fmt::Debug for Path {
3008	fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
3009	fmt::Debug::fmt(&self.inner, f:formatter)
3010	}
3011	}
3012
3013	/// Helper struct for safely printing paths with [`format!`] and `{}`.
3014	///
3015	/// A [`Path`] might contain non-Unicode data. This `struct` implements the
3016	/// [`Display`] trait in a way that mitigates that. It is created by the
3017	/// [`display`](Path::display) method on [`Path`]. This may perform lossy
3018	/// conversion, depending on the platform. If you would like an implementation
3019	/// which escapes the path please use [`Debug`] instead.
3020	///
3021	/// # Examples
3022	///
3023	/// ```
3024	/// use std::path::Path;
3025	///
3026	/// let path = Path::new("/tmp/foo.rs");
3027	///
3028	/// println!("{}", path.display());
3029	/// ```
3030	///
3031	/// [`Display`]: fmt::Display
3032	/// [`format!`]: crate::format
3033	#[stable(feature = "rust1", since = "1.0.0")]
3034	pub struct Display<'a> {
3035	path: &'a Path,
3036	}
3037
3038	#[stable(feature = "rust1", since = "1.0.0")]
3039	impl fmt::Debug for Display<'_> {
3040	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3041	fmt::Debug::fmt(&self.path, f)
3042	}
3043	}
3044
3045	#[stable(feature = "rust1", since = "1.0.0")]
3046	impl fmt::Display for Display<'_> {
3047	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3048	self.path.inner.display(formatter:f)
3049	}
3050	}
3051
3052	#[stable(feature = "rust1", since = "1.0.0")]
3053	impl PartialEq for Path {
3054	#[inline]
3055	fn eq(&self, other: &Path) -> bool {
3056	self.components() == other.components()
3057	}
3058	}
3059
3060	#[stable(feature = "rust1", since = "1.0.0")]
3061	impl Hash for Path {
3062	fn hash<H: Hasher>(&self, h: &mut H) {
3063	let bytes = self.as_u8_slice();
3064	let (prefix_len, verbatim) = match parse_prefix(&self.inner) {
3065	Some(prefix) => {
3066	prefix.hash(h);
3067	(prefix.len(), prefix.is_verbatim())
3068	}
3069	None => (`0`, `false`),
3070	};
3071	let bytes = &bytes[prefix_len..];
3072
3073	let mut component_start = `0`;
3074	let mut bytes_hashed = `0`;
3075
3076	for i in `0`..bytes.len() {
3077	let is_sep = if verbatim { is_verbatim_sep(bytes[i]) } else { is_sep_byte(bytes[i]) };
3078	if is_sep {
3079	if i > component_start {
3080	let to_hash = &bytes[component_start..i];
3081	h.write(to_hash);
3082	bytes_hashed += to_hash.len();
3083	}
3084
3085	// skip over separator and optionally a following CurDir item
3086	// since components() would normalize these away.
3087	component_start = i + `1`;
3088
3089	let tail = &bytes[component_start..];
3090
3091	if !verbatim {
3092	component_start += match tail {
3093	[b'.'] => `1`,
3094	[b'.', sep @ _, ..] if is_sep_byte(*sep) => `1`,
3095	_ => `0`,
3096	};
3097	}
3098	}
3099	}
3100
3101	if component_start < bytes.len() {
3102	let to_hash = &bytes[component_start..];
3103	h.write(to_hash);
3104	bytes_hashed += to_hash.len();
3105	}
3106
3107	h.write_usize(bytes_hashed);
3108	}
3109	}
3110
3111	#[stable(feature = "rust1", since = "1.0.0")]
3112	impl Eq for Path {}
3113
3114	#[stable(feature = "rust1", since = "1.0.0")]
3115	impl PartialOrd for Path {
3116	#[inline]
3117	fn partial_cmp(&self, other: &Path) -> Option<cmp::Ordering> {
3118	Some(compare_components(self.components(), right:other.components()))
3119	}
3120	}
3121
3122	#[stable(feature = "rust1", since = "1.0.0")]
3123	impl Ord for Path {
3124	#[inline]
3125	fn cmp(&self, other: &Path) -> cmp::Ordering {
3126	compare_components(self.components(), right:other.components())
3127	}
3128	}
3129
3130	#[stable(feature = "rust1", since = "1.0.0")]
3131	impl AsRef<Path> for Path {
3132	#[inline]
3133	fn as_ref(&self) -> &Path {
3134	self
3135	}
3136	}
3137
3138	#[stable(feature = "rust1", since = "1.0.0")]
3139	impl AsRef<Path> for OsStr {
3140	#[inline]
3141	fn as_ref(&self) -> &Path {
3142	Path::new(self)
3143	}
3144	}
3145
3146	#[stable(feature = "cow_os_str_as_ref_path", since = "1.8.0")]
3147	impl AsRef<Path> for Cow<'_, OsStr> {
3148	#[inline]
3149	fn as_ref(&self) -> &Path {
3150	Path::new(self)
3151	}
3152	}
3153
3154	#[stable(feature = "rust1", since = "1.0.0")]
3155	impl AsRef<Path> for OsString {
3156	#[inline]
3157	fn as_ref(&self) -> &Path {
3158	Path::new(self)
3159	}
3160	}
3161
3162	#[stable(feature = "rust1", since = "1.0.0")]
3163	impl AsRef<Path> for str {
3164	#[inline]
3165	fn as_ref(&self) -> &Path {
3166	Path::new(self)
3167	}
3168	}
3169
3170	#[stable(feature = "rust1", since = "1.0.0")]
3171	impl AsRef<Path> for String {
3172	#[inline]
3173	fn as_ref(&self) -> &Path {
3174	Path::new(self)
3175	}
3176	}
3177
3178	#[stable(feature = "rust1", since = "1.0.0")]
3179	impl AsRef<Path> for PathBuf {
3180	#[inline]
3181	fn as_ref(&self) -> &Path {
3182	self
3183	}
3184	}
3185
3186	#[stable(feature = "path_into_iter", since = "1.6.0")]
3187	impl<'a> IntoIterator for &'a PathBuf {
3188	type Item = &'a OsStr;
3189	type IntoIter = Iter<'a>;
3190	#[inline]
3191	fn into_iter(self) -> Iter<'a> {
3192	self.iter()
3193	}
3194	}
3195
3196	#[stable(feature = "path_into_iter", since = "1.6.0")]
3197	impl<'a> IntoIterator for &'a Path {
3198	type Item = &'a OsStr;
3199	type IntoIter = Iter<'a>;
3200	#[inline]
3201	fn into_iter(self) -> Iter<'a> {
3202	self.iter()
3203	}
3204	}
3205
3206	macro_rules! impl_cmp {
3207	(<$($life:lifetime),*> $lhs:ty, $rhs: ty) => {
3208	#[stable(feature = "partialeq_path", since = "1.6.0")]
3209	impl<$($life),> PartialEq<$rhs> for* $lhs {
3210	#[inline]
3211	fn eq(&self, other: &$rhs) -> bool {
3212	<Path as PartialEq>::eq(self, other)
3213	}
3214	}
3215
3216	#[stable(feature = "partialeq_path", since = "1.6.0")]
3217	impl<$($life),> PartialEq<$lhs> for* $rhs {
3218	#[inline]
3219	fn eq(&self, other: &$lhs) -> bool {
3220	<Path as PartialEq>::eq(self, other)
3221	}
3222	}
3223
3224	#[stable(feature = "cmp_path", since = "1.8.0")]
3225	impl<$($life),> PartialOrd<$rhs> for* $lhs {
3226	#[inline]
3227	fn partial_cmp(&self, other: &$rhs) -> Option<cmp::Ordering> {
3228	<Path as PartialOrd>::partial_cmp(self, other)
3229	}
3230	}
3231
3232	#[stable(feature = "cmp_path", since = "1.8.0")]
3233	impl<$($life),> PartialOrd<$lhs> for* $rhs {
3234	#[inline]
3235	fn partial_cmp(&self, other: &$lhs) -> Option<cmp::Ordering> {
3236	<Path as PartialOrd>::partial_cmp(self, other)
3237	}
3238	}
3239	};
3240	}
3241
3242	impl_cmp!(<> PathBuf, Path);
3243	impl_cmp!(<'a> PathBuf, &'a Path);
3244	impl_cmp!(<'a> Cow<'a, Path>, Path);
3245	impl_cmp!(<'a, 'b> Cow<'a, Path>, &'b Path);
3246	impl_cmp!(<'a> Cow<'a, Path>, PathBuf);
3247
3248	macro_rules! impl_cmp_os_str {
3249	(<$($life:lifetime),*> $lhs:ty, $rhs: ty) => {
3250	#[stable(feature = "cmp_path", since = "1.8.0")]
3251	impl<$($life),> PartialEq<$rhs> for* $lhs {
3252	#[inline]
3253	fn eq(&self, other: &$rhs) -> bool {
3254	<Path as PartialEq>::eq(self, other.as_ref())
3255	}
3256	}
3257
3258	#[stable(feature = "cmp_path", since = "1.8.0")]
3259	impl<$($life),> PartialEq<$lhs> for* $rhs {
3260	#[inline]
3261	fn eq(&self, other: &$lhs) -> bool {
3262	<Path as PartialEq>::eq(self.as_ref(), other)
3263	}
3264	}
3265
3266	#[stable(feature = "cmp_path", since = "1.8.0")]
3267	impl<$($life),> PartialOrd<$rhs> for* $lhs {
3268	#[inline]
3269	fn partial_cmp(&self, other: &$rhs) -> Option<cmp::Ordering> {
3270	<Path as PartialOrd>::partial_cmp(self, other.as_ref())
3271	}
3272	}
3273
3274	#[stable(feature = "cmp_path", since = "1.8.0")]
3275	impl<$($life),> PartialOrd<$lhs> for* $rhs {
3276	#[inline]
3277	fn partial_cmp(&self, other: &$lhs) -> Option<cmp::Ordering> {
3278	<Path as PartialOrd>::partial_cmp(self.as_ref(), other)
3279	}
3280	}
3281	};
3282	}
3283
3284	impl_cmp_os_str!(<> PathBuf, OsStr);
3285	impl_cmp_os_str!(<'a> PathBuf, &'a OsStr);
3286	impl_cmp_os_str!(<'a> PathBuf, Cow<'a, OsStr>);
3287	impl_cmp_os_str!(<> PathBuf, OsString);
3288	impl_cmp_os_str!(<> Path, OsStr);
3289	impl_cmp_os_str!(<'a> Path, &'a OsStr);
3290	impl_cmp_os_str!(<'a> Path, Cow<'a, OsStr>);
3291	impl_cmp_os_str!(<> Path, OsString);
3292	impl_cmp_os_str!(<'a> &'a Path, OsStr);
3293	impl_cmp_os_str!(<'a, 'b> &'a Path, Cow<'b, OsStr>);
3294	impl_cmp_os_str!(<'a> &'a Path, OsString);
3295	impl_cmp_os_str!(<'a> Cow<'a, Path>, OsStr);
3296	impl_cmp_os_str!(<'a, 'b> Cow<'a, Path>, &'b OsStr);
3297	impl_cmp_os_str!(<'a> Cow<'a, Path>, OsString);
3298
3299	#[stable(since = "1.7.0", feature = "strip_prefix")]
3300	impl fmt::Display for StripPrefixError {
3301	#[allow(deprecated, deprecated_in_future)]
3302	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3303	self.description().fmt(f)
3304	}
3305	}
3306
3307	#[stable(since = "1.7.0", feature = "strip_prefix")]
3308	impl Error for StripPrefixError {
3309	#[allow(deprecated)]
3310	fn description(&self) -> &str {
3311	"prefix not found"
3312	}
3313	}
3314
3315	/// Makes the path absolute without accessing the filesystem.
3316	///
3317	/// If the path is relative, the current directory is used as the base directory.
3318	/// All intermediate components will be resolved according to platforms-specific
3319	/// rules but unlike [`canonicalize`][crate::fs::canonicalize] this does not
3320	/// resolve symlinks and may succeed even if the path does not exist.
3321	///
3322	/// If the `path` is empty or getting the
3323	/// [current directory][crate::env::current_dir] fails then an error will be
3324	/// returned.
3325	///
3326	/// # Examples
3327	///
3328	/// ## Posix paths
3329	///
3330	/// ```
3331	/// #![feature(absolute_path)]
3332	/// # #[cfg(unix)]
3333	/// fn main() -> std::io::Result<()> {
3334	/// use std::path::{self, Path};
3335	///
3336	/// // Relative to absolute
3337	/// let absolute = path::absolute("foo/./bar")?;
3338	/// assert!(absolute.ends_with("foo/bar"));
3339	///
3340	/// // Absolute to absolute
3341	/// let absolute = path::absolute("/foo//test/.././bar.rs")?;
3342	/// assert_eq!(absolute, Path::new("/foo/test/../bar.rs"));
3343	/// Ok(())
3344	/// }
3345	/// # #[cfg(not(unix))]
3346	/// # fn main() {}
3347	/// ```
3348	///
3349	/// The path is resolved using [POSIX semantics][posix-semantics] except that
3350	/// it stops short of resolving symlinks. This means it will keep `..`
3351	/// components and trailing slashes.
3352	///
3353	/// ## Windows paths
3354	///
3355	/// ```
3356	/// #![feature(absolute_path)]
3357	/// # #[cfg(windows)]
3358	/// fn main() -> std::io::Result<()> {
3359	/// use std::path::{self, Path};
3360	///
3361	/// // Relative to absolute
3362	/// let absolute = path::absolute("foo/./bar")?;
3363	/// assert!(absolute.ends_with(r"foo\bar"));
3364	///
3365	/// // Absolute to absolute
3366	/// let absolute = path::absolute(r"C:\foo//test\..\./bar.rs")?;
3367	///
3368	/// assert_eq!(absolute, Path::new(r"C:\foo\bar.rs"));
3369	/// Ok(())
3370	/// }
3371	/// # #[cfg(not(windows))]
3372	/// # fn main() {}
3373	/// ```
3374	///
3375	/// For verbatim paths this will simply return the path as given. For other
3376	/// paths this is currently equivalent to calling [`GetFullPathNameW`][windows-path]
3377	/// This may change in the future.
3378	///
3379	/// [posix-semantics]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13
3380	/// [windows-path]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfullpathnamew
3381	#[unstable(feature = "absolute_path", issue = "92750")]
3382	pub fn absolute<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
3383	let path: &Path = path.as_ref();
3384	if path.as_os_str().is_empty() {
3385	Err(io::const_io_error!(io::ErrorKind::InvalidInput, "cannot make an empty path absolute",))
3386	} else {
3387	sys::path::absolute(path)
3388	}
3389	}
3390