Skip to content

Commit 8ded156

Browse files
committed
Add examples + documentation for std::path
1 parent d754722 commit 8ded156

File tree

1 file changed

+213
-0
lines changed

1 file changed

+213
-0
lines changed

src/libstd/path.rs

+213
Original file line numberDiff line numberDiff line change
@@ -344,6 +344,15 @@ impl<'a> Prefix<'a> {
344344

345345
/// Determine whether the character is one of the permitted path
346346
/// separators for the current platform.
347+
///
348+
/// # Examples
349+
///
350+
/// ```
351+
/// use std::path;
352+
///
353+
/// assert!(path::is_separator('/'));
354+
/// assert!(!path::is_separator('❤'));
355+
/// ```
347356
#[stable(feature = "rust1", since = "1.0.0")]
348357
pub fn is_separator(c: char) -> bool {
349358
use ascii::*;
@@ -540,6 +549,18 @@ impl<'a> AsRef<OsStr> for Component<'a> {
540549
///
541550
/// See the module documentation for an in-depth explanation of components and
542551
/// their role in the API.
552+
///
553+
/// # Examples
554+
///
555+
/// ```
556+
/// use std::path::Path;
557+
///
558+
/// let path = Path::new("/tmp/foo/bar.txt");
559+
///
560+
/// for component in path.components() {
561+
/// println!("{:?}", component);
562+
/// }
563+
/// ```
543564
#[derive(Clone)]
544565
#[stable(feature = "rust1", since = "1.0.0")]
545566
pub struct Components<'a> {
@@ -610,6 +631,16 @@ impl<'a> Components<'a> {
610631
}
611632

612633
/// Extract a slice corresponding to the portion of the path remaining for iteration.
634+
///
635+
/// # Examples
636+
///
637+
/// ```
638+
/// use std::path::Path;
639+
///
640+
/// let path = Path::new("/tmp/foo/bar.txt");
641+
///
642+
/// println!("{:?}", path.components().as_path());
643+
/// ```
613644
#[stable(feature = "rust1", since = "1.0.0")]
614645
pub fn as_path(&self) -> &'a Path {
615646
let mut comps = self.clone();
@@ -1207,12 +1238,28 @@ impl Path {
12071238
/// Directly wrap a string slice as a `Path` slice.
12081239
///
12091240
/// This is a cost-free conversion.
1241+
///
1242+
/// # Examples
1243+
///
1244+
/// ```
1245+
/// use std::path::Path;
1246+
///
1247+
/// Path::new("foo.txt");
1248+
/// ```
12101249
#[stable(feature = "rust1", since = "1.0.0")]
12111250
pub fn new<S: AsRef<OsStr> + ?Sized>(s: &S) -> &Path {
12121251
unsafe { mem::transmute(s.as_ref()) }
12131252
}
12141253

12151254
/// Yield the underlying `OsStr` slice.
1255+
///
1256+
/// # Examples
1257+
///
1258+
/// ```
1259+
/// use std::path::Path;
1260+
///
1261+
/// let os_str = Path::new("foo.txt").as_os_str();
1262+
/// ```
12161263
#[stable(feature = "rust1", since = "1.0.0")]
12171264
pub fn as_os_str(&self) -> &OsStr {
12181265
&self.inner
@@ -1221,6 +1268,14 @@ impl Path {
12211268
/// Yield a `&str` slice if the `Path` is valid unicode.
12221269
///
12231270
/// This conversion may entail doing a check for UTF-8 validity.
1271+
///
1272+
/// # Examples
1273+
///
1274+
/// ```
1275+
/// use std::path::Path;
1276+
///
1277+
/// let path_str = Path::new("foo.txt").to_str();
1278+
/// ```
12241279
#[stable(feature = "rust1", since = "1.0.0")]
12251280
pub fn to_str(&self) -> Option<&str> {
12261281
self.inner.to_str()
@@ -1229,12 +1284,28 @@ impl Path {
12291284
/// Convert a `Path` to a `Cow<str>`.
12301285
///
12311286
/// Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.
1287+
///
1288+
/// # Examples
1289+
///
1290+
/// ```
1291+
/// use std::path::Path;
1292+
///
1293+
/// let path_str = Path::new("foo.txt").to_string_lossy();
1294+
/// ```
12321295
#[stable(feature = "rust1", since = "1.0.0")]
12331296
pub fn to_string_lossy(&self) -> Cow<str> {
12341297
self.inner.to_string_lossy()
12351298
}
12361299

12371300
/// Convert a `Path` to an owned `PathBuf`.
1301+
///
1302+
/// # Examples
1303+
///
1304+
/// ```
1305+
/// use std::path::Path;
1306+
///
1307+
/// let path_str = Path::new("foo.txt").to_path_buf();
1308+
/// ```
12381309
#[stable(feature = "rust1", since = "1.0.0")]
12391310
pub fn to_path_buf(&self) -> PathBuf {
12401311
PathBuf::from(self.inner.to_os_string())
@@ -1248,13 +1319,29 @@ impl Path {
12481319
/// * On Windows, a path is absolute if it has a prefix and starts with the
12491320
/// root: `c:\windows` is absolute, while `c:temp` and `\temp` are not. In
12501321
/// other words, `path.is_absolute() == path.prefix().is_some() && path.has_root()`.
1322+
///
1323+
/// # Examples
1324+
///
1325+
/// ```
1326+
/// use std::path::Path;
1327+
///
1328+
/// assert_eq!(false, Path::new("foo.txt").is_absolute());
1329+
/// ```
12511330
#[stable(feature = "rust1", since = "1.0.0")]
12521331
pub fn is_absolute(&self) -> bool {
12531332
self.has_root() &&
12541333
(cfg!(unix) || self.prefix().is_some())
12551334
}
12561335

12571336
/// A path is *relative* if it is not absolute.
1337+
///
1338+
/// # Examples
1339+
///
1340+
/// ```
1341+
/// use std::path::Path;
1342+
///
1343+
/// assert!(Path::new("foo.txt").is_relative());
1344+
/// ```
12581345
#[stable(feature = "rust1", since = "1.0.0")]
12591346
pub fn is_relative(&self) -> bool {
12601347
!self.is_absolute()
@@ -1278,6 +1365,14 @@ impl Path {
12781365
/// * has no prefix and begins with a separator, e.g. `\\windows`
12791366
/// * has a prefix followed by a separator, e.g. `c:\windows` but not `c:windows`
12801367
/// * has any non-disk prefix, e.g. `\\server\share`
1368+
///
1369+
/// # Examples
1370+
///
1371+
/// ```
1372+
/// use std::path::Path;
1373+
///
1374+
/// assert!(Path::new("/etc/passwd").has_root());
1375+
/// ```
12811376
#[stable(feature = "rust1", since = "1.0.0")]
12821377
pub fn has_root(&self) -> bool {
12831378
self.components().has_root()
@@ -1294,8 +1389,11 @@ impl Path {
12941389
///
12951390
/// let path = Path::new("/foo/bar");
12961391
/// let foo = path.parent().unwrap();
1392+
///
12971393
/// assert!(foo == Path::new("/foo"));
1394+
///
12981395
/// let root = foo.parent().unwrap();
1396+
///
12991397
/// assert!(root == Path::new("/"));
13001398
/// assert!(root.parent() == None);
13011399
/// ```
@@ -1315,6 +1413,17 @@ impl Path {
13151413
///
13161414
/// If the path terminates in `.`, `..`, or consists solely or a root of
13171415
/// prefix, `file_name` will return `None`.
1416+
///
1417+
/// # Examples
1418+
///
1419+
/// ```
1420+
/// use std::path::Path;
1421+
///
1422+
/// let path = Path::new("hello_world.rs");
1423+
/// let filename = "hello_world.rs";
1424+
///
1425+
/// assert_eq!(filename, path.file_name().unwrap());
1426+
/// ```
13181427
#[stable(feature = "rust1", since = "1.0.0")]
13191428
pub fn file_name(&self) -> Option<&OsStr> {
13201429
self.components().next_back().and_then(|p| match p {
@@ -1334,12 +1443,32 @@ impl Path {
13341443
}
13351444

13361445
/// Determines whether `base` is a prefix of `self`.
1446+
///
1447+
/// # Examples
1448+
///
1449+
/// ```
1450+
/// use std::path::Path;
1451+
///
1452+
/// let path = Path::new("/etc/passwd");
1453+
///
1454+
/// assert!(path.starts_with("/etc"));
1455+
/// ```
13371456
#[stable(feature = "rust1", since = "1.0.0")]
13381457
pub fn starts_with<P: AsRef<Path>>(&self, base: P) -> bool {
13391458
iter_after(self.components(), base.as_ref().components()).is_some()
13401459
}
13411460

13421461
/// Determines whether `child` is a suffix of `self`.
1462+
///
1463+
/// # Examples
1464+
///
1465+
/// ```
1466+
/// use std::path::Path;
1467+
///
1468+
/// let path = Path::new("/etc/passwd");
1469+
///
1470+
/// assert!(path.ends_with("passwd"));
1471+
/// ```
13431472
#[stable(feature = "rust1", since = "1.0.0")]
13441473
pub fn ends_with<P: AsRef<Path>>(&self, child: P) -> bool {
13451474
iter_after(self.components().rev(), child.as_ref().components().rev()).is_some()
@@ -1353,6 +1482,16 @@ impl Path {
13531482
/// * The entire file name if there is no embedded `.`;
13541483
/// * The entire file name if the file name begins with `.` and has no other `.`s within;
13551484
/// * Otherwise, the portion of the file name before the final `.`
1485+
///
1486+
/// # Examples
1487+
///
1488+
/// ```
1489+
/// use std::path::Path;
1490+
///
1491+
/// let path = Path::new("foo.rs");
1492+
///
1493+
/// assert_eq!("foo", path.file_stem().unwrap());
1494+
/// ```
13561495
#[stable(feature = "rust1", since = "1.0.0")]
13571496
pub fn file_stem(&self) -> Option<&OsStr> {
13581497
self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.or(after))
@@ -1366,6 +1505,16 @@ impl Path {
13661505
/// * None, if there is no embedded `.`;
13671506
/// * None, if the file name begins with `.` and has no other `.`s within;
13681507
/// * Otherwise, the portion of the file name after the final `.`
1508+
///
1509+
/// # Examples
1510+
///
1511+
/// ```
1512+
/// use std::path::Path;
1513+
///
1514+
/// let path = Path::new("foo.rs");
1515+
///
1516+
/// assert_eq!("rs", path.extension().unwrap());
1517+
/// ```
13691518
#[stable(feature = "rust1", since = "1.0.0")]
13701519
pub fn extension(&self) -> Option<&OsStr> {
13711520
self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.and(after))
@@ -1374,6 +1523,16 @@ impl Path {
13741523
/// Creates an owned `PathBuf` with `path` adjoined to `self`.
13751524
///
13761525
/// See `PathBuf::push` for more details on what it means to adjoin a path.
1526+
///
1527+
/// # Examples
1528+
///
1529+
/// ```
1530+
/// use std::path::Path;
1531+
///
1532+
/// let path = Path::new("/tmp");
1533+
///
1534+
/// let new_path = path.join("foo");
1535+
/// ```
13771536
#[stable(feature = "rust1", since = "1.0.0")]
13781537
pub fn join<P: AsRef<Path>>(&self, path: P) -> PathBuf {
13791538
let mut buf = self.to_path_buf();
@@ -1384,6 +1543,16 @@ impl Path {
13841543
/// Creates an owned `PathBuf` like `self` but with the given file name.
13851544
///
13861545
/// See `PathBuf::set_file_name` for more details.
1546+
///
1547+
/// # Examples
1548+
///
1549+
/// ```
1550+
/// use std::path::Path;
1551+
///
1552+
/// let path = Path::new("/tmp/foo.rs");
1553+
///
1554+
/// let new_path = path.with_file_name("bar.rs");
1555+
/// ```
13871556
#[stable(feature = "rust1", since = "1.0.0")]
13881557
pub fn with_file_name<S: AsRef<OsStr>>(&self, file_name: S) -> PathBuf {
13891558
let mut buf = self.to_path_buf();
@@ -1394,6 +1563,16 @@ impl Path {
13941563
/// Creates an owned `PathBuf` like `self` but with the given extension.
13951564
///
13961565
/// See `PathBuf::set_extension` for more details.
1566+
///
1567+
/// # Examples
1568+
///
1569+
/// ```
1570+
/// use std::path::Path;
1571+
///
1572+
/// let path = Path::new("/tmp/foo.rs");
1573+
///
1574+
/// let new_path = path.with_extension("foo.txt");
1575+
/// ```
13971576
#[stable(feature = "rust1", since = "1.0.0")]
13981577
pub fn with_extension<S: AsRef<OsStr>>(&self, extension: S) -> PathBuf {
13991578
let mut buf = self.to_path_buf();
@@ -1402,6 +1581,18 @@ impl Path {
14021581
}
14031582

14041583
/// Produce an iterator over the components of the path.
1584+
///
1585+
/// # Examples
1586+
///
1587+
/// ```
1588+
/// use std::path::Path;
1589+
///
1590+
/// let path = Path::new("/tmp/foo.rs");
1591+
///
1592+
/// for component in path.components() {
1593+
/// println!("{:?}", component);
1594+
/// }
1595+
/// ```
14051596
#[stable(feature = "rust1", since = "1.0.0")]
14061597
pub fn components(&self) -> Components {
14071598
let prefix = parse_prefix(self.as_os_str());
@@ -1415,13 +1606,35 @@ impl Path {
14151606
}
14161607

14171608
/// Produce an iterator over the path's components viewed as `OsStr` slices.
1609+
///
1610+
/// # Examples
1611+
///
1612+
/// ```
1613+
/// use std::path::Path;
1614+
///
1615+
/// let path = Path::new("/tmp/foo.rs");
1616+
///
1617+
/// for component in path.iter() {
1618+
/// println!("{:?}", component);
1619+
/// }
1620+
/// ```
14181621
#[stable(feature = "rust1", since = "1.0.0")]
14191622
pub fn iter(&self) -> Iter {
14201623
Iter { inner: self.components() }
14211624
}
14221625

14231626
/// Returns an object that implements `Display` for safely printing paths
14241627
/// that may contain non-Unicode data.
1628+
///
1629+
/// # Examples
1630+
///
1631+
/// ```
1632+
/// use std::path::Path;
1633+
///
1634+
/// let path = Path::new("/tmp/foo.rs");
1635+
///
1636+
/// println!("{}", path.display());
1637+
/// ```
14251638
#[stable(feature = "rust1", since = "1.0.0")]
14261639
pub fn display(&self) -> Display {
14271640
Display { path: self }

0 commit comments

Comments
 (0)