// Windows Prefixes
////////////////////////////////////////////////////////////////////////////////
-/// Windows path prefixes, e.g. `C:` or `\\server\share`.
+/// Windows path prefixes, e.g., `C:` or `\\server\share`.
///
/// Windows uses a variety of path prefix styles, including references to drive
/// volumes (like `C:`), network shared folders (like `\\server\share`), and
-/// others. In addition, some path prefixes are "verbatim" (i.e. prefixed with
+/// others. In addition, some path prefixes are "verbatim" (i.e., prefixed with
/// `\\?\`), in which case `/` is *not* treated as a separator and essentially
/// no normalization is performed.
///
#[derive(Copy, Clone, Debug, Hash, PartialOrd, Ord, PartialEq, Eq)]
#[stable(feature = "rust1", since = "1.0.0")]
pub enum Prefix<'a> {
- /// Verbatim prefix, e.g. `\\?\cat_pics`.
+ /// Verbatim prefix, e.g., `\\?\cat_pics`.
///
/// Verbatim prefixes consist of `\\?\` immediately followed by the given
/// component.
Verbatim(#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr),
/// Verbatim prefix using Windows' _**U**niform **N**aming **C**onvention_,
- /// e.g. `\\?\UNC\server\share`.
+ /// e.g., `\\?\UNC\server\share`.
///
/// Verbatim UNC prefixes consist of `\\?\UNC\` immediately followed by the
/// server's hostname and a share name.
#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr,
),
- /// Verbatim disk prefix, e.g. `\\?\C:\`.
+ /// Verbatim disk prefix, e.g., `\\?\C:\`.
///
/// Verbatim disk prefixes consist of `\\?\` immediately followed by the
/// drive letter and `:\`.
#[stable(feature = "rust1", since = "1.0.0")]
VerbatimDisk(#[stable(feature = "rust1", since = "1.0.0")] u8),
- /// Device namespace prefix, e.g. `\\.\COM42`.
+ /// Device namespace prefix, e.g., `\\.\COM42`.
///
/// Device namespace prefixes consist of `\\.\` immediately followed by the
/// device name.
}
- /// Determines if the prefix is verbatim, i.e. begins with `\\?\`.
+ /// Determines if the prefix is verbatim, i.e., begins with `\\?\`.
///
/// # Examples
///
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub enum Component<'a> {
- /// A Windows path prefix, e.g. `C:` or `\\server\share`.
+ /// A Windows path prefix, e.g., `C:` or `\\server\share`.
///
/// There is a large variety of prefix types, see [`Prefix`]'s documentation
/// for more.
#[stable(feature = "rust1", since = "1.0.0")]
RootDir,
- /// A reference to the current directory, i.e. `.`.
+ /// A reference to the current directory, i.e., `.`.
#[stable(feature = "rust1", since = "1.0.0")]
CurDir,
- /// A reference to the parent directory, i.e. `..`.
+ /// A reference to the parent directory, i.e., `..`.
#[stable(feature = "rust1", since = "1.0.0")]
ParentDir,
- /// A normal component, e.g. `a` and `b` in `a/b`.
+ /// A normal component, e.g., `a` and `b` in `a/b`.
///
/// This variant is the most common one, it represents references to files
/// or directories.
// true if path *physically* has a root separator; for most Windows
// prefixes, it may have a "logical" rootseparator for the purposes of
- // normalization, e.g. \\server\share == \\server\share\.
+ // normalization, e.g., \\server\share == \\server\share\.
has_physical_root: bool,
// The iterator is double-ended, and these two states keep track of what has
(comp.len() + extra, self.parse_single_component(comp))
}
- // trim away repeated separators (i.e. empty components) on the left
+ // trim away repeated separators (i.e., empty components) on the left
fn trim_left(&mut self) {
while !self.path.is_empty() {
let (size, comp) = self.parse_next_component();
}
}
- // trim away repeated separators (i.e. empty components) on the right
+ // trim away repeated separators (i.e., empty components) on the right
fn trim_right(&mut self) {
while self.path.len() > self.len_before_body() {
let (size, comp) = self.parse_next_component_back();
///
/// On Windows:
///
- /// * if `path` has a root but no prefix (e.g. `\windows`), it
+ /// * if `path` has a root but no prefix (e.g., `\windows`), it
/// replaces everything except for the prefix (if any) of `self`.
/// * if `path` has a prefix but no root, it replaces `self`.
///
if path.is_absolute() || path.prefix().is_some() {
self.as_mut_vec().truncate(0);
- // `path` has a root but no prefix, e.g. `\windows` (Windows only)
+ // `path` has a root but no prefix, e.g., `\windows` (Windows only)
} else if path.has_root() {
let prefix_len = self.components().prefix_remaining();
self.as_mut_vec().truncate(prefix_len);
#[stable(feature = "path_buf_from_box", since = "1.18.0")]
impl From<Box<Path>> for PathBuf {
- /// Converts a `Box<Path>` into a `PathBuf`.
- /// This conversion does not allocate memory
+ /// Converts a `Box<Path>` into a `PathBuf`
+ ///
+ /// This conversion does not allocate or copy memory.
fn from(boxed: Box<Path>) -> PathBuf {
boxed.into_path_buf()
}
#[stable(feature = "box_from_path_buf", since = "1.20.0")]
impl From<PathBuf> for Box<Path> {
- /// Converts a `PathBuf` into a `Box<Path>`.
- /// This conversion does not allocate memory
+ /// Converts a `PathBuf` into a `Box<Path>`
+ ///
+ /// This conversion currently should not allocate memory,
+ /// but this behavior is not guaranteed on all platforms or in all future versions.
fn from(p: PathBuf) -> Box<Path> {
p.into_boxed_path()
}
#[stable(feature = "rust1", since = "1.0.0")]
impl From<OsString> for PathBuf {
- /// Converts a `OsString` into a `PathBuf`.
- /// This conversion does not allocate memory
+ /// Converts a `OsString` into a `PathBuf`
+ ///
+ /// This conversion does not allocate or copy memory.
fn from(s: OsString) -> PathBuf {
PathBuf { inner: s }
}
#[stable(feature = "from_path_buf_for_os_string", since = "1.14.0")]
impl From<PathBuf> for OsString {
- /// Converts a `PathBuf` into a `OsString`.
- /// This conversion does not allocate memory
+ /// Converts a `PathBuf` into a `OsString`
+ ///
+ /// This conversion does not allocate or copy memory.
fn from(path_buf : PathBuf) -> OsString {
path_buf.inner
}
#[stable(feature = "rust1", since = "1.0.0")]
impl From<String> for PathBuf {
- /// Converts a `String` into a `PathBuf`.
- /// This conversion does not allocate memory
+ /// Converts a `String` into a `PathBuf`
+ ///
+ /// This conversion does not allocate or copy memory.
fn from(s: String) -> PathBuf {
PathBuf::from(OsString::from(s))
}
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<PathBuf> for Arc<Path> {
- /// Converts a `PathBuf` into a `Arc<Path>`.
- /// This conversion happens in place.
- /// This conversion does not allocate memory.
+ /// Converts a Path into a Rc by copying the Path data into a new Rc buffer.
#[inline]
fn from(s: PathBuf) -> Arc<Path> {
let arc: Arc<OsStr> = Arc::from(s.into_os_string());
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl<'a> From<&'a Path> for Arc<Path> {
- /// Converts a `PathBuf` into a `Arc<Path>`.
- /// This conversion happens in place.
- /// This conversion does not allocate memory.
+ /// Converts a Path into a Rc by copying the Path data into a new Rc buffer.
#[inline]
fn from(s: &Path) -> Arc<Path> {
let arc: Arc<OsStr> = Arc::from(s.as_os_str());
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<PathBuf> for Rc<Path> {
- /// Converts a `PathBuf` into a `Rc<Path>`.
- /// This conversion happens in place.
- /// This conversion does not allocate memory.
+ /// Converts a Path into a Rc by copying the Path data into a new Rc buffer.
#[inline]
fn from(s: PathBuf) -> Rc<Path> {
let rc: Rc<OsStr> = Rc::from(s.into_os_string());
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl<'a> From<&'a Path> for Rc<Path> {
+ /// Converts a Path into a Rc by copying the Path data into a new Rc buffer.
#[inline]
fn from(s: &Path) -> Rc<Path> {
let rc: Rc<OsStr> = Rc::from(s.as_os_str());
PathBuf::from(self.inner.to_os_string())
}
- /// Returns `true` if the `Path` is absolute, i.e. if it is independent of
+ /// Returns `true` if the `Path` is absolute, i.e., if it is independent of
/// the current directory.
///
/// * On Unix, a path is absolute if it starts with the root, so
}
}
- /// Returns `true` if the `Path` is relative, i.e. not absolute.
+ /// Returns `true` if the `Path` is relative, i.e., not absolute.
///
/// See [`is_absolute`]'s documentation for more details.
///
/// * On Unix, a path has a root if it begins with `/`.
///
/// * On Windows, a path has a root if it:
- /// * has no prefix and begins with a separator, e.g. `\windows`
- /// * has a prefix followed by a separator, e.g. `c:\windows` but not `c:windows`
- /// * has any non-disk prefix, e.g. `\\server\share`
+ /// * has no prefix and begins with a separator, e.g., `\windows`
+ /// * has a prefix followed by a separator, e.g., `c:\windows` but not `c:windows`
+ /// * has any non-disk prefix, e.g., `\\server\share`
///
/// # Examples
///
///
/// # Errors
///
- /// If `base` is not a prefix of `self` (i.e. [`starts_with`]
+ /// If `base` is not a prefix of `self` (i.e., [`starts_with`]
/// returns `false`), returns [`Err`].
///
/// [`starts_with`]: #method.starts_with
/// This function will traverse symbolic links to query information about the
/// destination file. In case of broken symbolic links this will return `false`.
///
- /// If you cannot access the directory containing the file, e.g. because of a
+ /// If you cannot access the directory containing the file, e.g., because of a
/// permission error, this will return `false`.
///
/// # Examples
/// This function will traverse symbolic links to query information about the
/// destination file. In case of broken symbolic links this will return `false`.
///
- /// If you cannot access the directory containing the file, e.g. because of a
+ /// If you cannot access the directory containing the file, e.g., because of a
/// permission error, this will return `false`.
///
/// # Examples
/// This function will traverse symbolic links to query information about the
/// destination file. In case of broken symbolic links this will return `false`.
///
- /// If you cannot access the directory containing the file, e.g. because of a
+ /// If you cannot access the directory containing the file, e.g., because of a
/// permission error, this will return `false`.
///
/// # Examples
projects / rust.git / blobdiff