@@ -343,6 +343,15 @@ impl<'a> Prefix<'a> {
343
343
344
344
/// Determine whether the character is one of the permitted path
345
345
/// 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
+ /// ```
346
355
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
347
356
pub fn is_separator ( c : char ) -> bool {
348
357
use ascii:: * ;
@@ -539,6 +548,18 @@ impl<'a> AsRef<OsStr> for Component<'a> {
539
548
///
540
549
/// See the module documentation for an in-depth explanation of components and
541
550
/// 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
+ /// ```
542
563
#[ derive( Clone ) ]
543
564
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
544
565
pub struct Components < ' a > {
@@ -609,6 +630,16 @@ impl<'a> Components<'a> {
609
630
}
610
631
611
632
/// 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
+ /// ```
612
643
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
613
644
pub fn as_path ( & self ) -> & ' a Path {
614
645
let mut comps = self . clone ( ) ;
@@ -1210,12 +1241,28 @@ impl Path {
1210
1241
/// Directly wrap a string slice as a `Path` slice.
1211
1242
///
1212
1243
/// This is a cost-free conversion.
1244
+ ///
1245
+ /// # Examples
1246
+ ///
1247
+ /// ```
1248
+ /// use std::path::Path;
1249
+ ///
1250
+ /// Path::new("foo.txt");
1251
+ /// ```
1213
1252
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1214
1253
pub fn new < S : AsRef < OsStr > + ?Sized > ( s : & S ) -> & Path {
1215
1254
unsafe { mem:: transmute ( s. as_ref ( ) ) }
1216
1255
}
1217
1256
1218
1257
/// 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
+ /// ```
1219
1266
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1220
1267
pub fn as_os_str ( & self ) -> & OsStr {
1221
1268
& self . inner
@@ -1224,6 +1271,14 @@ impl Path {
1224
1271
/// Yield a `&str` slice if the `Path` is valid unicode.
1225
1272
///
1226
1273
/// 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
+ /// ```
1227
1282
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1228
1283
pub fn to_str ( & self ) -> Option < & str > {
1229
1284
self . inner . to_str ( )
@@ -1232,12 +1287,28 @@ impl Path {
1232
1287
/// Convert a `Path` to a `Cow<str>`.
1233
1288
///
1234
1289
/// 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
+ /// ```
1235
1298
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1236
1299
pub fn to_string_lossy ( & self ) -> Cow < str > {
1237
1300
self . inner . to_string_lossy ( )
1238
1301
}
1239
1302
1240
1303
/// 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
+ /// ```
1241
1312
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1242
1313
pub fn to_path_buf ( & self ) -> PathBuf {
1243
1314
PathBuf :: from ( self . inner . to_os_string ( ) )
@@ -1251,13 +1322,29 @@ impl Path {
1251
1322
/// * On Windows, a path is absolute if it has a prefix and starts with the
1252
1323
/// root: `c:\windows` is absolute, while `c:temp` and `\temp` are not. In
1253
1324
/// 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
+ /// ```
1254
1333
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1255
1334
pub fn is_absolute ( & self ) -> bool {
1256
1335
self . has_root ( ) &&
1257
1336
( cfg ! ( unix) || self . prefix ( ) . is_some ( ) )
1258
1337
}
1259
1338
1260
1339
/// 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
+ /// ```
1261
1348
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1262
1349
pub fn is_relative ( & self ) -> bool {
1263
1350
!self . is_absolute ( )
@@ -1281,6 +1368,14 @@ impl Path {
1281
1368
/// * has no prefix and begins with a separator, e.g. `\\windows`
1282
1369
/// * has a prefix followed by a separator, e.g. `c:\windows` but not `c:windows`
1283
1370
/// * 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
+ /// ```
1284
1379
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1285
1380
pub fn has_root ( & self ) -> bool {
1286
1381
self . components ( ) . has_root ( )
@@ -1297,8 +1392,11 @@ impl Path {
1297
1392
///
1298
1393
/// let path = Path::new("/foo/bar");
1299
1394
/// let foo = path.parent().unwrap();
1395
+ ///
1300
1396
/// assert!(foo == Path::new("/foo"));
1397
+ ///
1301
1398
/// let root = foo.parent().unwrap();
1399
+ ///
1302
1400
/// assert!(root == Path::new("/"));
1303
1401
/// assert!(root.parent() == None);
1304
1402
/// ```
@@ -1318,6 +1416,17 @@ impl Path {
1318
1416
///
1319
1417
/// If the path terminates in `.`, `..`, or consists solely or a root of
1320
1418
/// 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
+ /// ```
1321
1430
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1322
1431
pub fn file_name ( & self ) -> Option < & OsStr > {
1323
1432
self . components ( ) . next_back ( ) . and_then ( |p| match p {
@@ -1337,12 +1446,32 @@ impl Path {
1337
1446
}
1338
1447
1339
1448
/// 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
+ /// ```
1340
1459
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1341
1460
pub fn starts_with < P : AsRef < Path > > ( & self , base : P ) -> bool {
1342
1461
iter_after ( self . components ( ) , base. as_ref ( ) . components ( ) ) . is_some ( )
1343
1462
}
1344
1463
1345
1464
/// 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
+ /// ```
1346
1475
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1347
1476
pub fn ends_with < P : AsRef < Path > > ( & self , child : P ) -> bool {
1348
1477
iter_after ( self . components ( ) . rev ( ) , child. as_ref ( ) . components ( ) . rev ( ) ) . is_some ( )
@@ -1356,6 +1485,16 @@ impl Path {
1356
1485
/// * The entire file name if there is no embedded `.`;
1357
1486
/// * The entire file name if the file name begins with `.` and has no other `.`s within;
1358
1487
/// * 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
+ /// ```
1359
1498
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1360
1499
pub fn file_stem ( & self ) -> Option < & OsStr > {
1361
1500
self . file_name ( ) . map ( split_file_at_dot) . and_then ( |( before, after) | before. or ( after) )
@@ -1369,6 +1508,16 @@ impl Path {
1369
1508
/// * None, if there is no embedded `.`;
1370
1509
/// * None, if the file name begins with `.` and has no other `.`s within;
1371
1510
/// * 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
+ /// ```
1372
1521
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1373
1522
pub fn extension ( & self ) -> Option < & OsStr > {
1374
1523
self . file_name ( ) . map ( split_file_at_dot) . and_then ( |( before, after) | before. and ( after) )
@@ -1377,6 +1526,16 @@ impl Path {
1377
1526
/// Creates an owned `PathBuf` with `path` adjoined to `self`.
1378
1527
///
1379
1528
/// 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
+ /// ```
1380
1539
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1381
1540
pub fn join < P : AsRef < Path > > ( & self , path : P ) -> PathBuf {
1382
1541
let mut buf = self . to_path_buf ( ) ;
@@ -1387,6 +1546,16 @@ impl Path {
1387
1546
/// Creates an owned `PathBuf` like `self` but with the given file name.
1388
1547
///
1389
1548
/// 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
+ /// ```
1390
1559
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1391
1560
pub fn with_file_name < S : AsRef < OsStr > > ( & self , file_name : S ) -> PathBuf {
1392
1561
let mut buf = self . to_path_buf ( ) ;
@@ -1397,6 +1566,16 @@ impl Path {
1397
1566
/// Creates an owned `PathBuf` like `self` but with the given extension.
1398
1567
///
1399
1568
/// 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
+ /// ```
1400
1579
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1401
1580
pub fn with_extension < S : AsRef < OsStr > > ( & self , extension : S ) -> PathBuf {
1402
1581
let mut buf = self . to_path_buf ( ) ;
@@ -1405,6 +1584,18 @@ impl Path {
1405
1584
}
1406
1585
1407
1586
/// 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
+ /// ```
1408
1599
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1409
1600
pub fn components ( & self ) -> Components {
1410
1601
let prefix = parse_prefix ( self . as_os_str ( ) ) ;
@@ -1418,13 +1609,35 @@ impl Path {
1418
1609
}
1419
1610
1420
1611
/// 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
+ /// ```
1421
1624
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1422
1625
pub fn iter ( & self ) -> Iter {
1423
1626
Iter { inner : self . components ( ) }
1424
1627
}
1425
1628
1426
1629
/// Returns an object that implements `Display` for safely printing paths
1427
1630
/// 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
+ /// ```
1428
1641
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1429
1642
pub fn display ( & self ) -> Display {
1430
1643
Display { path : self }
0 commit comments