Skip to content

Commit

Permalink
Rollup merge of #23932 - steveklabnik:doc_std_path, r=flaper87
Browse files Browse the repository at this point in the history
  • Loading branch information
@Manishearth
Manishearth committed Apr 1, 2015
2 parents 77112bb + 8ded156 commit ec6c2c3
Showing 1 changed file with 213 additions and 0 deletions.
213 changes: 213 additions & 0 deletions src/libstd/path.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -343,6 +343,15 @@ impl<'a> Prefix<'a> {

/// Determine whether the character is one of the permitted path
/// separators for the current platform.
///
/// # Examples
///
/// ```
/// use std::path;
///
/// assert!(path::is_separator('/'));
/// assert!(!path::is_separator('❤'));
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn is_separator(c: char) -> bool {
use ascii::*;
Expand Down Expand Up @@ -539,6 +548,18 @@ impl<'a> AsRef<OsStr> for Component<'a> {
///
/// See the module documentation for an in-depth explanation of components and
/// their role in the API.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("/tmp/foo/bar.txt");
///
/// for component in path.components() {
/// println!("{:?}", component);
/// }
/// ```
#[derive(Clone)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Components<'a> {
Expand Down Expand Up @@ -609,6 +630,16 @@ impl<'a> Components<'a> {
}

/// Extract a slice corresponding to the portion of the path remaining for iteration.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("/tmp/foo/bar.txt");
///
/// println!("{:?}", path.components().as_path());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn as_path(&self) -> &'a Path {
let mut comps = self.clone();
Expand Down Expand Up @@ -1210,12 +1241,28 @@ impl Path {
/// Directly wrap a string slice as a `Path` slice.
///
/// This is a cost-free conversion.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// Path::new("foo.txt");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn new<S: AsRef<OsStr> + ?Sized>(s: &S) -> &Path {
unsafe { mem::transmute(s.as_ref()) }
}

/// Yield the underlying `OsStr` slice.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let os_str = Path::new("foo.txt").as_os_str();
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn as_os_str(&self) -> &OsStr {
&self.inner
Expand All @@ -1224,6 +1271,14 @@ impl Path {
/// Yield a `&str` slice if the `Path` is valid unicode.
///
/// This conversion may entail doing a check for UTF-8 validity.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path_str = Path::new("foo.txt").to_str();
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn to_str(&self) -> Option<&str> {
self.inner.to_str()
Expand All @@ -1232,12 +1287,28 @@ impl Path {
/// Convert a `Path` to a `Cow<str>`.
///
/// Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path_str = Path::new("foo.txt").to_string_lossy();
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn to_string_lossy(&self) -> Cow<str> {
self.inner.to_string_lossy()
}

/// Convert a `Path` to an owned `PathBuf`.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path_str = Path::new("foo.txt").to_path_buf();
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn to_path_buf(&self) -> PathBuf {
PathBuf::from(self.inner.to_os_string())
Expand All @@ -1251,13 +1322,29 @@ impl Path {
/// * On Windows, a path is absolute if it has a prefix and starts with the
/// root: `c:\windows` is absolute, while `c:temp` and `\temp` are not. In
/// other words, `path.is_absolute() == path.prefix().is_some() && path.has_root()`.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// assert_eq!(false, Path::new("foo.txt").is_absolute());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn is_absolute(&self) -> bool {
self.has_root() &&
(cfg!(unix) || self.prefix().is_some())
}

/// A path is *relative* if it is not absolute.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// assert!(Path::new("foo.txt").is_relative());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn is_relative(&self) -> bool {
!self.is_absolute()
Expand All @@ -1281,6 +1368,14 @@ impl Path {
/// * 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
///
/// ```
/// use std::path::Path;
///
/// assert!(Path::new("/etc/passwd").has_root());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn has_root(&self) -> bool {
self.components().has_root()
Expand All @@ -1297,8 +1392,11 @@ impl Path {
///
/// let path = Path::new("/foo/bar");
/// let foo = path.parent().unwrap();
///
/// assert!(foo == Path::new("/foo"));
///
/// let root = foo.parent().unwrap();
///
/// assert!(root == Path::new("/"));
/// assert!(root.parent() == None);
/// ```
Expand All @@ -1318,6 +1416,17 @@ impl Path {
///
/// If the path terminates in `.`, `..`, or consists solely or a root of
/// prefix, `file_name` will return `None`.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("hello_world.rs");
/// let filename = "hello_world.rs";
///
/// assert_eq!(filename, path.file_name().unwrap());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn file_name(&self) -> Option<&OsStr> {
self.components().next_back().and_then(|p| match p {
Expand All @@ -1337,12 +1446,32 @@ impl Path {
}

/// Determines whether `base` is a prefix of `self`.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("/etc/passwd");
///
/// assert!(path.starts_with("/etc"));
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn starts_with<P: AsRef<Path>>(&self, base: P) -> bool {
iter_after(self.components(), base.as_ref().components()).is_some()
}

/// Determines whether `child` is a suffix of `self`.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("/etc/passwd");
///
/// assert!(path.ends_with("passwd"));
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn ends_with<P: AsRef<Path>>(&self, child: P) -> bool {
iter_after(self.components().rev(), child.as_ref().components().rev()).is_some()
Expand All @@ -1356,6 +1485,16 @@ impl Path {
/// * The entire file name if there is no embedded `.`;
/// * The entire file name if the file name begins with `.` and has no other `.`s within;
/// * Otherwise, the portion of the file name before the final `.`
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("foo.rs");
///
/// assert_eq!("foo", path.file_stem().unwrap());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn file_stem(&self) -> Option<&OsStr> {
self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.or(after))
Expand All @@ -1369,6 +1508,16 @@ impl Path {
/// * None, if there is no embedded `.`;
/// * None, if the file name begins with `.` and has no other `.`s within;
/// * Otherwise, the portion of the file name after the final `.`
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("foo.rs");
///
/// assert_eq!("rs", path.extension().unwrap());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn extension(&self) -> Option<&OsStr> {
self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.and(after))
Expand All @@ -1377,6 +1526,16 @@ impl Path {
/// Creates an owned `PathBuf` with `path` adjoined to `self`.
///
/// See `PathBuf::push` for more details on what it means to adjoin a path.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("/tmp");
///
/// let new_path = path.join("foo");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn join<P: AsRef<Path>>(&self, path: P) -> PathBuf {
let mut buf = self.to_path_buf();
Expand All @@ -1387,6 +1546,16 @@ impl Path {
/// Creates an owned `PathBuf` like `self` but with the given file name.
///
/// See `PathBuf::set_file_name` for more details.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("/tmp/foo.rs");
///
/// let new_path = path.with_file_name("bar.rs");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn with_file_name<S: AsRef<OsStr>>(&self, file_name: S) -> PathBuf {
let mut buf = self.to_path_buf();
Expand All @@ -1397,6 +1566,16 @@ impl Path {
/// Creates an owned `PathBuf` like `self` but with the given extension.
///
/// See `PathBuf::set_extension` for more details.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("/tmp/foo.rs");
///
/// let new_path = path.with_extension("foo.txt");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn with_extension<S: AsRef<OsStr>>(&self, extension: S) -> PathBuf {
let mut buf = self.to_path_buf();
Expand All @@ -1405,6 +1584,18 @@ impl Path {
}

/// Produce an iterator over the components of the path.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("/tmp/foo.rs");
///
/// for component in path.components() {
/// println!("{:?}", component);
/// }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn components(&self) -> Components {
let prefix = parse_prefix(self.as_os_str());
Expand All @@ -1418,13 +1609,35 @@ impl Path {
}

/// Produce an iterator over the path's components viewed as `OsStr` slices.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("/tmp/foo.rs");
///
/// for component in path.iter() {
/// println!("{:?}", component);
/// }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn iter(&self) -> Iter {
Iter { inner: self.components() }
}

/// Returns an object that implements `Display` for safely printing paths
/// that may contain non-Unicode data.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// let path = Path::new("/tmp/foo.rs");
///
/// println!("{}", path.display());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn display(&self) -> Display {
Display { path: self }
Expand Down

0 comments on commit ec6c2c3

Please sign in to comment.