From a282b08b886fd981144b9e67f9fae5a9831774db Mon Sep 17 00:00:00 2001 From: nham Date: Wed, 30 Jul 2014 11:35:20 -0400 Subject: [PATCH 1/3] Add examples for GenericPath methods. --- src/libstd/path/mod.rs | 233 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) diff --git a/src/libstd/path/mod.rs b/src/libstd/path/mod.rs index 1e9ec32d75943..25367dd53f4cd 100644 --- a/src/libstd/path/mod.rs +++ b/src/libstd/path/mod.rs @@ -142,6 +142,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// Creates a new Path from a byte vector or string. /// The resulting Path will always be normalized. /// + /// # Example + /// + /// ``` + /// let path = Path::new("foo/bar"); + /// ``` + /// /// # Failure /// /// Fails the task if the path contains a NUL. @@ -155,6 +161,13 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// Creates a new Path from a byte vector or string, if possible. /// The resulting Path will always be normalized. + /// + /// # Example + /// + /// ``` + /// let x: &[u8] = ['f' as u8, 'o' as u8, 'o' as u8, 0]; + /// assert!(Path::new_opt(x).is_none()); + /// ``` #[inline] fn new_opt(path: T) -> Option { if contains_nul(&path) { @@ -166,18 +179,47 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// Returns the path as a string, if possible. /// If the path is not representable in utf-8, this returns None. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("/abc/def"); + /// assert_eq!(p.as_str(), Some("/abc/def")); + /// ``` #[inline] fn as_str<'a>(&'a self) -> Option<&'a str> { str::from_utf8(self.as_vec()) } /// Returns the path as a byte vector + /// + /// # Example + /// + /// ``` + /// let p = Path::new("abc/def"); + /// assert_eq!(p.as_vec(), &[97, 98, 99, 47, 100, 101, 102]); + /// ``` fn as_vec<'a>(&'a self) -> &'a [u8]; /// Converts the Path into an owned byte vector + /// + /// # Example + /// + /// ``` + /// let p = Path::new("abc/def"); + /// assert_eq!(p.into_vec(), vec!(97, 98, 99, 47, 100, 101, 102)); + /// // attempting to use p now results in "error: use of moved value" + /// ``` fn into_vec(self) -> Vec; /// Returns an object that implements `Show` for printing paths + /// + /// # Example + /// + /// ``` + /// let p = Path::new("abc/def"); + /// println!("{}", p.display()); // prints "abc/def" + /// ``` fn display<'a>(&'a self) -> Display<'a, Self> { Display{ path: self, filename: false } } @@ -185,32 +227,78 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// Returns an object that implements `Show` for printing filenames /// /// If there is no filename, nothing will be printed. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("abc/def"); + /// println!("{}", p.filename_display()); // prints "def" + /// ``` fn filename_display<'a>(&'a self) -> Display<'a, Self> { Display{ path: self, filename: true } } /// Returns the directory component of `self`, as a byte vector (with no trailing separator). /// If `self` has no directory component, returns ['.']. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("abc/def/ghi"); + /// assert_eq!(p.dirname(), &[97, 98, 99, 47, 100, 101, 102]); + /// ``` fn dirname<'a>(&'a self) -> &'a [u8]; + /// Returns the directory component of `self`, as a string, if possible. /// See `dirname` for details. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("abc/def/ghi"); + /// assert_eq!(p.dirname_str(), Some("abc/def")); + /// ``` #[inline] fn dirname_str<'a>(&'a self) -> Option<&'a str> { str::from_utf8(self.dirname()) } + /// Returns the file component of `self`, as a byte vector. /// If `self` represents the root of the file hierarchy, returns None. /// If `self` is "." or "..", returns None. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("abc/def/ghi"); + /// assert_eq!(p.filename(), Some(&[103, 104, 105])); + /// ``` fn filename<'a>(&'a self) -> Option<&'a [u8]>; + /// Returns the file component of `self`, as a string, if possible. /// See `filename` for details. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("abc/def/ghi"); + /// assert_eq!(p.filename_str(), Some("ghi")); + /// ``` #[inline] fn filename_str<'a>(&'a self) -> Option<&'a str> { self.filename().and_then(str::from_utf8) } + /// Returns the stem of the filename of `self`, as a byte vector. /// The stem is the portion of the filename just before the last '.'. /// If there is no '.', the entire filename is returned. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("/abc/def.txt"); + /// assert_eq!(p.filestem(), Some(&[100, 101, 102])); + /// ``` fn filestem<'a>(&'a self) -> Option<&'a [u8]> { match self.filename() { None => None, @@ -224,16 +312,32 @@ pub trait GenericPath: Clone + GenericPathUnsafe { }) } } + /// Returns the stem of the filename of `self`, as a string, if possible. /// See `filestem` for details. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("/abc/def.txt"); + /// assert_eq!(p.filestem_str(), Some("def")); + /// ``` #[inline] fn filestem_str<'a>(&'a self) -> Option<&'a str> { self.filestem().and_then(str::from_utf8) } + /// Returns the extension of the filename of `self`, as an optional byte vector. /// The extension is the portion of the filename just after the last '.'. /// If there is no extension, None is returned. /// If the filename ends in '.', the empty vector is returned. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("abc/def.txt"); + /// assert_eq!(p.extension(), Some(&[116, 120, 116])); + /// ``` fn extension<'a>(&'a self) -> Option<&'a [u8]> { match self.filename() { None => None, @@ -247,8 +351,16 @@ pub trait GenericPath: Clone + GenericPathUnsafe { } } } + /// Returns the extension of the filename of `self`, as a string, if possible. /// See `extension` for details. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("abc/def.txt"); + /// assert_eq!(p.extension_str(), Some("txt")); + /// ``` #[inline] fn extension_str<'a>(&'a self) -> Option<&'a str> { self.extension().and_then(str::from_utf8) @@ -257,6 +369,14 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// Replaces the filename portion of the path with the given byte vector or string. /// If the replacement name is [], this is equivalent to popping the path. /// + /// # Example + /// + /// ``` + /// let mut p = Path::new("abc/def.txt"); + /// p.set_filename("foo.dat"); + /// assert!(p == Path::new("abc/foo.dat")); + /// ``` + /// /// # Failure /// /// Fails the task if the filename contains a NUL. @@ -265,11 +385,20 @@ pub trait GenericPath: Clone + GenericPathUnsafe { assert!(!contains_nul(&filename)); unsafe { self.set_filename_unchecked(filename) } } + /// Replaces the extension with the given byte vector or string. /// If there is no extension in `self`, this adds one. /// If the argument is [] or "", this removes the extension. /// If `self` has no filename, this is a no-op. /// + /// # Example + /// + /// ``` + /// let mut p = Path::new("abc/def.txt"); + /// p.set_extension("csv"); + /// assert!(p == Path::new("abc/def.csv")); + /// ``` + /// /// # Failure /// /// Fails the task if the extension contains a NUL. @@ -308,6 +437,13 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// byte vector or string. /// See `set_filename` for details. /// + /// # Example + /// + /// ``` + /// let mut p = Path::new("abc/def.txt"); + /// assert!(p.with_filename("foo.dat") == Path::new("abc/foo.dat")); + /// ``` + /// /// # Failure /// /// Fails the task if the filename contains a NUL. @@ -317,6 +453,7 @@ pub trait GenericPath: Clone + GenericPathUnsafe { p.set_filename(filename); p } + /// Returns a new Path constructed by setting the extension to the given /// byte vector or string. /// See `set_extension` for details. @@ -333,6 +470,13 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// Returns the directory component of `self`, as a Path. /// If `self` represents the root of the filesystem hierarchy, returns `self`. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("abc/def/ghi"); + /// assert!(p.dir_path() == Path::new("abc/def")); + /// ``` fn dir_path(&self) -> Self { // self.dirname() returns a NUL-free vector unsafe { GenericPathUnsafe::new_unchecked(self.dirname()) } @@ -341,11 +485,26 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// Returns a Path that represents the filesystem root that `self` is rooted in. /// /// If `self` is not absolute, or vol/cwd-relative in the case of Windows, this returns None. + /// + /// # Example + /// + /// ``` + /// assert!(Path::new("abc/def").root_path() == None); + /// assert!(Path::new("/abc/def").root_path() == Some(Path::new("/"))); + /// ``` fn root_path(&self) -> Option; /// Pushes a path (as a byte vector or string) onto `self`. /// If the argument represents an absolute path, it replaces `self`. /// + /// # Example + /// + /// ``` + /// let mut p = Path::new("foo/bar"); + /// p.push("baz.txt"); + /// assert!(p == Path::new("foo/bar/baz.txt")); + /// ``` + /// /// # Failure /// /// Fails the task if the path contains a NUL. @@ -354,8 +513,17 @@ pub trait GenericPath: Clone + GenericPathUnsafe { assert!(!contains_nul(&path)); unsafe { self.push_unchecked(path) } } + /// Pushes multiple paths (as byte vectors or strings) onto `self`. /// See `push` for details. + /// + /// # Example + /// + /// ``` + /// let mut p = Path::new("foo"); + /// p.push_many(&["bar", "baz.txt"]); + /// assert!(p == Path::new("foo/bar/baz.txt")); + /// ``` #[inline] fn push_many(&mut self, paths: &[T]) { let t: Option = None; @@ -369,15 +537,31 @@ pub trait GenericPath: Clone + GenericPathUnsafe { } } } + /// Removes the last path component from the receiver. /// Returns `true` if the receiver was modified, or `false` if it already /// represented the root of the file hierarchy. + /// + /// # Example + /// + /// ``` + /// let mut p = Path::new("foo/bar/baz.txt"); + /// p.pop(); + /// assert!(p == Path::new("foo/bar")); + /// ``` fn pop(&mut self) -> bool; /// Returns a new Path constructed by joining `self` with the given path /// (as a byte vector or string). /// If the given path is absolute, the new Path will represent just that. /// + /// # Example + /// + /// ``` + /// let p = Path::new("/foo"); + /// assert!(p.join("bar.txt") == Path::new("/foo/bar.txt")); + /// ``` + /// /// # Failure /// /// Fails the task if the path contains a NUL. @@ -387,9 +571,18 @@ pub trait GenericPath: Clone + GenericPathUnsafe { p.push(path); p } + /// Returns a new Path constructed by joining `self` with the given paths /// (as byte vectors or strings). /// See `join` for details. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("foo"); + /// let fbbq = Path::new("foo/bar/baz/quux.txt"); + /// assert!(p.join_many(&["bar", "baz", "quux.txt"]) == fbbq); + /// ``` #[inline] fn join_many(&self, paths: &[T]) -> Self { let mut p = self.clone(); @@ -400,12 +593,26 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// Returns whether `self` represents an absolute path. /// An absolute path is defined as one that, when joined to another path, will /// yield back the same absolute path. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("/abc/def"); + /// assert!(p.is_absolute()); + /// ``` fn is_absolute(&self) -> bool; /// Returns whether `self` represents a relative path. /// Typically this is the inverse of `is_absolute`. /// But for Windows paths, it also means the path is not volume-relative or /// relative to the current working directory. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("abc/def"); + /// assert!(p.is_relative()); + /// ``` fn is_relative(&self) -> bool { !self.is_absolute() } @@ -413,15 +620,41 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// Returns whether `self` is equal to, or is an ancestor of, the given path. /// If both paths are relative, they are compared as though they are relative /// to the same parent path. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("foo/bar/baz/quux.txt"); + /// let fb = Path::new("foo/bar"); + /// let bq = Path::new("baz/quux.txt"); + /// assert!(fb.is_ancestor_of(&p)); + /// ``` fn is_ancestor_of(&self, other: &Self) -> bool; /// Returns the Path that, were it joined to `base`, would yield `self`. /// If no such path exists, None is returned. /// If `self` is absolute and `base` is relative, or on Windows if both /// paths refer to separate drives, an absolute path is returned. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("foo/bar/baz/quux.txt"); + /// let fb = Path::new("foo/bar"); + /// let bq = Path::new("baz/quux.txt"); + /// assert!(p.path_relative_from(&fb) == Some(bq)); + /// ``` fn path_relative_from(&self, base: &Self) -> Option; /// Returns whether the relative path `child` is a suffix of `self`. + /// + /// # Example + /// + /// ``` + /// let p = Path::new("foo/bar/baz/quux.txt"); + /// let bq = Path::new("baz/quux.txt"); + /// assert!(p.ends_with_path(&bq)); + /// ``` fn ends_with_path(&self, child: &Self) -> bool; } From cefd09d5dbfaf03692a704b7b9526049e7166491 Mon Sep 17 00:00:00 2001 From: nham Date: Wed, 30 Jul 2014 14:19:47 -0400 Subject: [PATCH 2/3] Use byte strings throughout examples. Add an example that was missed in the last commit. --- src/libstd/path/mod.rs | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/src/libstd/path/mod.rs b/src/libstd/path/mod.rs index 25367dd53f4cd..7ce6e9b70494d 100644 --- a/src/libstd/path/mod.rs +++ b/src/libstd/path/mod.rs @@ -165,7 +165,7 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` - /// let x: &[u8] = ['f' as u8, 'o' as u8, 'o' as u8, 0]; + /// let x: &[u8] = b"foo\0"; /// assert!(Path::new_opt(x).is_none()); /// ``` #[inline] @@ -197,7 +197,7 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// /// ``` /// let p = Path::new("abc/def"); - /// assert_eq!(p.as_vec(), &[97, 98, 99, 47, 100, 101, 102]); + /// assert_eq!(p.as_vec(), b"abc/def"); /// ``` fn as_vec<'a>(&'a self) -> &'a [u8]; @@ -207,7 +207,7 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// /// ``` /// let p = Path::new("abc/def"); - /// assert_eq!(p.into_vec(), vec!(97, 98, 99, 47, 100, 101, 102)); + /// assert_eq!(p.into_vec(), b"abc/def".to_vec()); /// // attempting to use p now results in "error: use of moved value" /// ``` fn into_vec(self) -> Vec; @@ -245,7 +245,7 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// /// ``` /// let p = Path::new("abc/def/ghi"); - /// assert_eq!(p.dirname(), &[97, 98, 99, 47, 100, 101, 102]); + /// assert_eq!(p.dirname(), b"abc/def"); /// ``` fn dirname<'a>(&'a self) -> &'a [u8]; @@ -271,7 +271,7 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// /// ``` /// let p = Path::new("abc/def/ghi"); - /// assert_eq!(p.filename(), Some(&[103, 104, 105])); + /// assert_eq!(p.filename(), Some(b"ghi")); /// ``` fn filename<'a>(&'a self) -> Option<&'a [u8]>; @@ -297,7 +297,7 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// /// ``` /// let p = Path::new("/abc/def.txt"); - /// assert_eq!(p.filestem(), Some(&[100, 101, 102])); + /// assert_eq!(p.filestem(), Some(b"def")); /// ``` fn filestem<'a>(&'a self) -> Option<&'a [u8]> { match self.filename() { @@ -336,7 +336,7 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// /// ``` /// let p = Path::new("abc/def.txt"); - /// assert_eq!(p.extension(), Some(&[116, 120, 116])); + /// assert_eq!(p.extension(), Some(b"txt")); /// ``` fn extension<'a>(&'a self) -> Option<&'a [u8]> { match self.filename() { @@ -458,6 +458,13 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// byte vector or string. /// See `set_extension` for details. /// + /// # Example + /// + /// ``` + /// let mut p = Path::new("abc/def.txt"); + /// assert!(p.with_extension("csv") == Path::new("abc/def.csv")); + /// ``` + /// /// # Failure /// /// Fails the task if the extension contains a NUL. From 49a9c8ebfe48bd255b10ec3d8c4b2e972be43952 Mon Sep 17 00:00:00 2001 From: nham Date: Wed, 30 Jul 2014 15:21:55 -0400 Subject: [PATCH 3/3] Add logic to skip the doc tests on windows since these examples are unix-specific --- src/libstd/path/mod.rs | 124 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) diff --git a/src/libstd/path/mod.rs b/src/libstd/path/mod.rs index 7ce6e9b70494d..a22db7292fa08 100644 --- a/src/libstd/path/mod.rs +++ b/src/libstd/path/mod.rs @@ -145,7 +145,11 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let path = Path::new("foo/bar"); + /// # } /// ``` /// /// # Failure @@ -165,8 +169,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let x: &[u8] = b"foo\0"; /// assert!(Path::new_opt(x).is_none()); + /// # } /// ``` #[inline] fn new_opt(path: T) -> Option { @@ -183,8 +191,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("/abc/def"); /// assert_eq!(p.as_str(), Some("/abc/def")); + /// # } /// ``` #[inline] fn as_str<'a>(&'a self) -> Option<&'a str> { @@ -196,8 +208,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("abc/def"); /// assert_eq!(p.as_vec(), b"abc/def"); + /// # } /// ``` fn as_vec<'a>(&'a self) -> &'a [u8]; @@ -206,9 +222,13 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("abc/def"); /// assert_eq!(p.into_vec(), b"abc/def".to_vec()); /// // attempting to use p now results in "error: use of moved value" + /// # } /// ``` fn into_vec(self) -> Vec; @@ -217,8 +237,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("abc/def"); /// println!("{}", p.display()); // prints "abc/def" + /// # } /// ``` fn display<'a>(&'a self) -> Display<'a, Self> { Display{ path: self, filename: false } @@ -231,8 +255,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("abc/def"); /// println!("{}", p.filename_display()); // prints "def" + /// # } /// ``` fn filename_display<'a>(&'a self) -> Display<'a, Self> { Display{ path: self, filename: true } @@ -244,8 +272,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("abc/def/ghi"); /// assert_eq!(p.dirname(), b"abc/def"); + /// # } /// ``` fn dirname<'a>(&'a self) -> &'a [u8]; @@ -255,8 +287,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("abc/def/ghi"); /// assert_eq!(p.dirname_str(), Some("abc/def")); + /// # } /// ``` #[inline] fn dirname_str<'a>(&'a self) -> Option<&'a str> { @@ -270,8 +306,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("abc/def/ghi"); /// assert_eq!(p.filename(), Some(b"ghi")); + /// # } /// ``` fn filename<'a>(&'a self) -> Option<&'a [u8]>; @@ -281,8 +321,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("abc/def/ghi"); /// assert_eq!(p.filename_str(), Some("ghi")); + /// # } /// ``` #[inline] fn filename_str<'a>(&'a self) -> Option<&'a str> { @@ -296,8 +340,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("/abc/def.txt"); /// assert_eq!(p.filestem(), Some(b"def")); + /// # } /// ``` fn filestem<'a>(&'a self) -> Option<&'a [u8]> { match self.filename() { @@ -319,8 +367,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("/abc/def.txt"); /// assert_eq!(p.filestem_str(), Some("def")); + /// # } /// ``` #[inline] fn filestem_str<'a>(&'a self) -> Option<&'a str> { @@ -335,8 +387,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("abc/def.txt"); /// assert_eq!(p.extension(), Some(b"txt")); + /// # } /// ``` fn extension<'a>(&'a self) -> Option<&'a [u8]> { match self.filename() { @@ -358,8 +414,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("abc/def.txt"); /// assert_eq!(p.extension_str(), Some("txt")); + /// # } /// ``` #[inline] fn extension_str<'a>(&'a self) -> Option<&'a str> { @@ -372,9 +432,13 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let mut p = Path::new("abc/def.txt"); /// p.set_filename("foo.dat"); /// assert!(p == Path::new("abc/foo.dat")); + /// # } /// ``` /// /// # Failure @@ -394,9 +458,13 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let mut p = Path::new("abc/def.txt"); /// p.set_extension("csv"); /// assert!(p == Path::new("abc/def.csv")); + /// # } /// ``` /// /// # Failure @@ -440,8 +508,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let mut p = Path::new("abc/def.txt"); /// assert!(p.with_filename("foo.dat") == Path::new("abc/foo.dat")); + /// # } /// ``` /// /// # Failure @@ -461,8 +533,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let mut p = Path::new("abc/def.txt"); /// assert!(p.with_extension("csv") == Path::new("abc/def.csv")); + /// # } /// ``` /// /// # Failure @@ -481,8 +557,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("abc/def/ghi"); /// assert!(p.dir_path() == Path::new("abc/def")); + /// # } /// ``` fn dir_path(&self) -> Self { // self.dirname() returns a NUL-free vector @@ -496,8 +576,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// assert!(Path::new("abc/def").root_path() == None); /// assert!(Path::new("/abc/def").root_path() == Some(Path::new("/"))); + /// # } /// ``` fn root_path(&self) -> Option; @@ -507,9 +591,13 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let mut p = Path::new("foo/bar"); /// p.push("baz.txt"); /// assert!(p == Path::new("foo/bar/baz.txt")); + /// # } /// ``` /// /// # Failure @@ -527,9 +615,13 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let mut p = Path::new("foo"); /// p.push_many(&["bar", "baz.txt"]); /// assert!(p == Path::new("foo/bar/baz.txt")); + /// # } /// ``` #[inline] fn push_many(&mut self, paths: &[T]) { @@ -552,9 +644,13 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let mut p = Path::new("foo/bar/baz.txt"); /// p.pop(); /// assert!(p == Path::new("foo/bar")); + /// # } /// ``` fn pop(&mut self) -> bool; @@ -565,8 +661,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("/foo"); /// assert!(p.join("bar.txt") == Path::new("/foo/bar.txt")); + /// # } /// ``` /// /// # Failure @@ -586,9 +686,13 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("foo"); /// let fbbq = Path::new("foo/bar/baz/quux.txt"); /// assert!(p.join_many(&["bar", "baz", "quux.txt"]) == fbbq); + /// # } /// ``` #[inline] fn join_many(&self, paths: &[T]) -> Self { @@ -604,8 +708,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("/abc/def"); /// assert!(p.is_absolute()); + /// # } /// ``` fn is_absolute(&self) -> bool; @@ -617,8 +725,12 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("abc/def"); /// assert!(p.is_relative()); + /// # } /// ``` fn is_relative(&self) -> bool { !self.is_absolute() @@ -631,10 +743,14 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("foo/bar/baz/quux.txt"); /// let fb = Path::new("foo/bar"); /// let bq = Path::new("baz/quux.txt"); /// assert!(fb.is_ancestor_of(&p)); + /// # } /// ``` fn is_ancestor_of(&self, other: &Self) -> bool; @@ -646,10 +762,14 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("foo/bar/baz/quux.txt"); /// let fb = Path::new("foo/bar"); /// let bq = Path::new("baz/quux.txt"); /// assert!(p.path_relative_from(&fb) == Some(bq)); + /// # } /// ``` fn path_relative_from(&self, base: &Self) -> Option; @@ -658,9 +778,13 @@ pub trait GenericPath: Clone + GenericPathUnsafe { /// # Example /// /// ``` + /// # foo(); + /// # #[cfg(windows)] fn foo() {} + /// # #[cfg(unix)] fn foo() { /// let p = Path::new("foo/bar/baz/quux.txt"); /// let bq = Path::new("baz/quux.txt"); /// assert!(p.ends_with_path(&bq)); + /// # } /// ``` fn ends_with_path(&self, child: &Self) -> bool; }