Skip to content

Commit ec6c2c3

Browse files
committed
Rollup merge of #23932 - steveklabnik:doc_std_path, r=flaper87
2 parents 77112bb + 8ded156 commit ec6c2c3

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
@@ -343,6 +343,15 @@ impl<'a> Prefix<'a> {
343343

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

611632
/// Extract a slice corresponding to the portion of the path remaining for iteration.
633+
///
634+
/// # Examples
635+
///
636+
/// ```
637+
/// use std::path::Path;
638+
///
639+
/// let path = Path::new("/tmp/foo/bar.txt");
640+
///
641+
/// println!("{:?}", path.components().as_path());
642+
/// ```
612643
#[stable(feature = "rust1", since = "1.0.0")]
613644
pub fn as_path(&self) -> &'a Path {
614645
let mut comps = self.clone();
@@ -1210,12 +1241,28 @@ impl Path {
12101241
/// Directly wrap a string slice as a `Path` slice.
12111242
///
12121243
/// This is a cost-free conversion.
1244+
///
1245+
/// # Examples
1246+
///
1247+
/// ```
1248+
/// use std::path::Path;
1249+
///
1250+
/// Path::new("foo.txt");
1251+
/// ```
12131252
#[stable(feature = "rust1", since = "1.0.0")]
12141253
pub fn new<S: AsRef<OsStr> + ?Sized>(s: &S) -> &Path {
12151254
unsafe { mem::transmute(s.as_ref()) }
12161255
}
12171256

12181257
/// Yield the underlying `OsStr` slice.
1258+
///
1259+
/// # Examples
1260+
///
1261+
/// ```
1262+
/// use std::path::Path;
1263+
///
1264+
/// let os_str = Path::new("foo.txt").as_os_str();
1265+
/// ```
12191266
#[stable(feature = "rust1", since = "1.0.0")]
12201267
pub fn as_os_str(&self) -> &OsStr {
12211268
&self.inner
@@ -1224,6 +1271,14 @@ impl Path {
12241271
/// Yield a `&str` slice if the `Path` is valid unicode.
12251272
///
12261273
/// This conversion may entail doing a check for UTF-8 validity.
1274+
///
1275+
/// # Examples
1276+
///
1277+
/// ```
1278+
/// use std::path::Path;
1279+
///
1280+
/// let path_str = Path::new("foo.txt").to_str();
1281+
/// ```
12271282
#[stable(feature = "rust1", since = "1.0.0")]
12281283
pub fn to_str(&self) -> Option<&str> {
12291284
self.inner.to_str()
@@ -1232,12 +1287,28 @@ impl Path {
12321287
/// Convert a `Path` to a `Cow<str>`.
12331288
///
12341289
/// Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.
1290+
///
1291+
/// # Examples
1292+
///
1293+
/// ```
1294+
/// use std::path::Path;
1295+
///
1296+
/// let path_str = Path::new("foo.txt").to_string_lossy();
1297+
/// ```
12351298
#[stable(feature = "rust1", since = "1.0.0")]
12361299
pub fn to_string_lossy(&self) -> Cow<str> {
12371300
self.inner.to_string_lossy()
12381301
}
12391302

12401303
/// Convert a `Path` to an owned `PathBuf`.
1304+
///
1305+
/// # Examples
1306+
///
1307+
/// ```
1308+
/// use std::path::Path;
1309+
///
1310+
/// let path_str = Path::new("foo.txt").to_path_buf();
1311+
/// ```
12411312
#[stable(feature = "rust1", since = "1.0.0")]
12421313
pub fn to_path_buf(&self) -> PathBuf {
12431314
PathBuf::from(self.inner.to_os_string())
@@ -1251,13 +1322,29 @@ impl Path {
12511322
/// * On Windows, a path is absolute if it has a prefix and starts with the
12521323
/// root: `c:\windows` is absolute, while `c:temp` and `\temp` are not. In
12531324
/// other words, `path.is_absolute() == path.prefix().is_some() && path.has_root()`.
1325+
///
1326+
/// # Examples
1327+
///
1328+
/// ```
1329+
/// use std::path::Path;
1330+
///
1331+
/// assert_eq!(false, Path::new("foo.txt").is_absolute());
1332+
/// ```
12541333
#[stable(feature = "rust1", since = "1.0.0")]
12551334
pub fn is_absolute(&self) -> bool {
12561335
self.has_root() &&
12571336
(cfg!(unix) || self.prefix().is_some())
12581337
}
12591338

12601339
/// A path is *relative* if it is not absolute.
1340+
///
1341+
/// # Examples
1342+
///
1343+
/// ```
1344+
/// use std::path::Path;
1345+
///
1346+
/// assert!(Path::new("foo.txt").is_relative());
1347+
/// ```
12611348
#[stable(feature = "rust1", since = "1.0.0")]
12621349
pub fn is_relative(&self) -> bool {
12631350
!self.is_absolute()
@@ -1281,6 +1368,14 @@ impl Path {
12811368
/// * has no prefix and begins with a separator, e.g. `\\windows`
12821369
/// * has a prefix followed by a separator, e.g. `c:\windows` but not `c:windows`
12831370
/// * has any non-disk prefix, e.g. `\\server\share`
1371+
///
1372+
/// # Examples
1373+
///
1374+
/// ```
1375+
/// use std::path::Path;
1376+
///
1377+
/// assert!(Path::new("/etc/passwd").has_root());
1378+
/// ```
12841379
#[stable(feature = "rust1", since = "1.0.0")]
12851380
pub fn has_root(&self) -> bool {
12861381
self.components().has_root()
@@ -1297,8 +1392,11 @@ impl Path {
12971392
///
12981393
/// let path = Path::new("/foo/bar");
12991394
/// let foo = path.parent().unwrap();
1395+
///
13001396
/// assert!(foo == Path::new("/foo"));
1397+
///
13011398
/// let root = foo.parent().unwrap();
1399+
///
13021400
/// assert!(root == Path::new("/"));
13031401
/// assert!(root.parent() == None);
13041402
/// ```
@@ -1318,6 +1416,17 @@ impl Path {
13181416
///
13191417
/// If the path terminates in `.`, `..`, or consists solely or a root of
13201418
/// prefix, `file_name` will return `None`.
1419+
///
1420+
/// # Examples
1421+
///
1422+
/// ```
1423+
/// use std::path::Path;
1424+
///
1425+
/// let path = Path::new("hello_world.rs");
1426+
/// let filename = "hello_world.rs";
1427+
///
1428+
/// assert_eq!(filename, path.file_name().unwrap());
1429+
/// ```
13211430
#[stable(feature = "rust1", since = "1.0.0")]
13221431
pub fn file_name(&self) -> Option<&OsStr> {
13231432
self.components().next_back().and_then(|p| match p {
@@ -1337,12 +1446,32 @@ impl Path {
13371446
}
13381447

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

13451464
/// Determines whether `child` is a suffix of `self`.
1465+
///
1466+
/// # Examples
1467+
///
1468+
/// ```
1469+
/// use std::path::Path;
1470+
///
1471+
/// let path = Path::new("/etc/passwd");
1472+
///
1473+
/// assert!(path.ends_with("passwd"));
1474+
/// ```
13461475
#[stable(feature = "rust1", since = "1.0.0")]
13471476
pub fn ends_with<P: AsRef<Path>>(&self, child: P) -> bool {
13481477
iter_after(self.components().rev(), child.as_ref().components().rev()).is_some()
@@ -1356,6 +1485,16 @@ impl Path {
13561485
/// * The entire file name if there is no embedded `.`;
13571486
/// * The entire file name if the file name begins with `.` and has no other `.`s within;
13581487
/// * Otherwise, the portion of the file name before the final `.`
1488+
///
1489+
/// # Examples
1490+
///
1491+
/// ```
1492+
/// use std::path::Path;
1493+
///
1494+
/// let path = Path::new("foo.rs");
1495+
///
1496+
/// assert_eq!("foo", path.file_stem().unwrap());
1497+
/// ```
13591498
#[stable(feature = "rust1", since = "1.0.0")]
13601499
pub fn file_stem(&self) -> Option<&OsStr> {
13611500
self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.or(after))
@@ -1369,6 +1508,16 @@ impl Path {
13691508
/// * None, if there is no embedded `.`;
13701509
/// * None, if the file name begins with `.` and has no other `.`s within;
13711510
/// * Otherwise, the portion of the file name after the final `.`
1511+
///
1512+
/// # Examples
1513+
///
1514+
/// ```
1515+
/// use std::path::Path;
1516+
///
1517+
/// let path = Path::new("foo.rs");
1518+
///
1519+
/// assert_eq!("rs", path.extension().unwrap());
1520+
/// ```
13721521
#[stable(feature = "rust1", since = "1.0.0")]
13731522
pub fn extension(&self) -> Option<&OsStr> {
13741523
self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.and(after))
@@ -1377,6 +1526,16 @@ impl Path {
13771526
/// Creates an owned `PathBuf` with `path` adjoined to `self`.
13781527
///
13791528
/// See `PathBuf::push` for more details on what it means to adjoin a path.
1529+
///
1530+
/// # Examples
1531+
///
1532+
/// ```
1533+
/// use std::path::Path;
1534+
///
1535+
/// let path = Path::new("/tmp");
1536+
///
1537+
/// let new_path = path.join("foo");
1538+
/// ```
13801539
#[stable(feature = "rust1", since = "1.0.0")]
13811540
pub fn join<P: AsRef<Path>>(&self, path: P) -> PathBuf {
13821541
let mut buf = self.to_path_buf();
@@ -1387,6 +1546,16 @@ impl Path {
13871546
/// Creates an owned `PathBuf` like `self` but with the given file name.
13881547
///
13891548
/// See `PathBuf::set_file_name` for more details.
1549+
///
1550+
/// # Examples
1551+
///
1552+
/// ```
1553+
/// use std::path::Path;
1554+
///
1555+
/// let path = Path::new("/tmp/foo.rs");
1556+
///
1557+
/// let new_path = path.with_file_name("bar.rs");
1558+
/// ```
13901559
#[stable(feature = "rust1", since = "1.0.0")]
13911560
pub fn with_file_name<S: AsRef<OsStr>>(&self, file_name: S) -> PathBuf {
13921561
let mut buf = self.to_path_buf();
@@ -1397,6 +1566,16 @@ impl Path {
13971566
/// Creates an owned `PathBuf` like `self` but with the given extension.
13981567
///
13991568
/// See `PathBuf::set_extension` for more details.
1569+
///
1570+
/// # Examples
1571+
///
1572+
/// ```
1573+
/// use std::path::Path;
1574+
///
1575+
/// let path = Path::new("/tmp/foo.rs");
1576+
///
1577+
/// let new_path = path.with_extension("foo.txt");
1578+
/// ```
14001579
#[stable(feature = "rust1", since = "1.0.0")]
14011580
pub fn with_extension<S: AsRef<OsStr>>(&self, extension: S) -> PathBuf {
14021581
let mut buf = self.to_path_buf();
@@ -1405,6 +1584,18 @@ impl Path {
14051584
}
14061585

14071586
/// Produce an iterator over the components of the path.
1587+
///
1588+
/// # Examples
1589+
///
1590+
/// ```
1591+
/// use std::path::Path;
1592+
///
1593+
/// let path = Path::new("/tmp/foo.rs");
1594+
///
1595+
/// for component in path.components() {
1596+
/// println!("{:?}", component);
1597+
/// }
1598+
/// ```
14081599
#[stable(feature = "rust1", since = "1.0.0")]
14091600
pub fn components(&self) -> Components {
14101601
let prefix = parse_prefix(self.as_os_str());
@@ -1418,13 +1609,35 @@ impl Path {
14181609
}
14191610

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

14261629
/// Returns an object that implements `Display` for safely printing paths
14271630
/// that may contain non-Unicode data.
1631+
///
1632+
/// # Examples
1633+
///
1634+
/// ```
1635+
/// use std::path::Path;
1636+
///
1637+
/// let path = Path::new("/tmp/foo.rs");
1638+
///
1639+
/// println!("{}", path.display());
1640+
/// ```
14281641
#[stable(feature = "rust1", since = "1.0.0")]
14291642
pub fn display(&self) -> Display {
14301643
Display { path: self }

0 commit comments

Comments
 (0)