mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add examples + documentation for std::path

Browse Source
This commit is contained in:
Steve Klabnik 2015-04-01 01:11:38 -04:00
parent d754722a04
commit 8ded156265
1 changed files with 213 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

213
src/libstd/path.rs
View File

@ -344,6 +344,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::*;
@ -540,6 +549,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> {
@ -610,6 +631,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();
@ -1207,12 +1238,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
@ -1221,6 +1268,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()
@ -1229,12 +1284,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())
@ -1248,6 +1319,14 @@ 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() &&
@ -1255,6 +1334,14 @@ impl Path {
}
/// 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()
@ -1278,6 +1365,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()
@ -1294,8 +1389,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);
/// ```
@ -1315,6 +1413,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 {
@ -1334,12 +1443,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()
@ -1353,6 +1482,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))
@ -1366,6 +1505,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))
@ -1374,6 +1523,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();
@ -1384,6 +1543,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();
@ -1394,6 +1563,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();
@ -1402,6 +1581,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());
@ -1415,6 +1606,18 @@ 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() }
@ -1422,6 +1625,16 @@ impl Path {
/// 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 }