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