@@ -344,6 +344,15 @@ impl<'a> Prefix<'a> {
344
344
345
345
/// Determine whether the character is one of the permitted path
346
346
/// 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
+ /// ```
347
356
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
348
357
pub fn is_separator ( c : char ) -> bool {
349
358
use ascii:: * ;
@@ -540,6 +549,18 @@ impl<'a> AsRef<OsStr> for Component<'a> {
540
549
///
541
550
/// See the module documentation for an in-depth explanation of components and
542
551
/// 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
+ /// ```
543
564
#[ derive( Clone ) ]
544
565
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
545
566
pub struct Components < ' a > {
@@ -610,6 +631,16 @@ impl<'a> Components<'a> {
610
631
}
611
632
612
633
/// 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
+ /// ```
613
644
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
614
645
pub fn as_path ( & self ) -> & ' a Path {
615
646
let mut comps = self . clone ( ) ;
@@ -1207,12 +1238,28 @@ impl Path {
1207
1238
/// Directly wrap a string slice as a `Path` slice.
1208
1239
///
1209
1240
/// This is a cost-free conversion.
1241
+ ///
1242
+ /// # Examples
1243
+ ///
1244
+ /// ```
1245
+ /// use std::path::Path;
1246
+ ///
1247
+ /// Path::new("foo.txt");
1248
+ /// ```
1210
1249
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1211
1250
pub fn new < S : AsRef < OsStr > + ?Sized > ( s : & S ) -> & Path {
1212
1251
unsafe { mem:: transmute ( s. as_ref ( ) ) }
1213
1252
}
1214
1253
1215
1254
/// 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
+ /// ```
1216
1263
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1217
1264
pub fn as_os_str ( & self ) -> & OsStr {
1218
1265
& self . inner
@@ -1221,6 +1268,14 @@ impl Path {
1221
1268
/// Yield a `&str` slice if the `Path` is valid unicode.
1222
1269
///
1223
1270
/// 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
+ /// ```
1224
1279
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1225
1280
pub fn to_str ( & self ) -> Option < & str > {
1226
1281
self . inner . to_str ( )
@@ -1229,12 +1284,28 @@ impl Path {
1229
1284
/// Convert a `Path` to a `Cow<str>`.
1230
1285
///
1231
1286
/// 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
+ /// ```
1232
1295
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1233
1296
pub fn to_string_lossy ( & self ) -> Cow < str > {
1234
1297
self . inner . to_string_lossy ( )
1235
1298
}
1236
1299
1237
1300
/// 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
+ /// ```
1238
1309
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1239
1310
pub fn to_path_buf ( & self ) -> PathBuf {
1240
1311
PathBuf :: from ( self . inner . to_os_string ( ) )
@@ -1248,13 +1319,29 @@ impl Path {
1248
1319
/// * On Windows, a path is absolute if it has a prefix and starts with the
1249
1320
/// root: `c:\windows` is absolute, while `c:temp` and `\temp` are not. In
1250
1321
/// 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
+ /// ```
1251
1330
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1252
1331
pub fn is_absolute ( & self ) -> bool {
1253
1332
self . has_root ( ) &&
1254
1333
( cfg ! ( unix) || self . prefix ( ) . is_some ( ) )
1255
1334
}
1256
1335
1257
1336
/// 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
+ /// ```
1258
1345
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1259
1346
pub fn is_relative ( & self ) -> bool {
1260
1347
!self . is_absolute ( )
@@ -1278,6 +1365,14 @@ impl Path {
1278
1365
/// * has no prefix and begins with a separator, e.g. `\\windows`
1279
1366
/// * has a prefix followed by a separator, e.g. `c:\windows` but not `c:windows`
1280
1367
/// * 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
+ /// ```
1281
1376
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1282
1377
pub fn has_root ( & self ) -> bool {
1283
1378
self . components ( ) . has_root ( )
@@ -1294,8 +1389,11 @@ impl Path {
1294
1389
///
1295
1390
/// let path = Path::new("/foo/bar");
1296
1391
/// let foo = path.parent().unwrap();
1392
+ ///
1297
1393
/// assert!(foo == Path::new("/foo"));
1394
+ ///
1298
1395
/// let root = foo.parent().unwrap();
1396
+ ///
1299
1397
/// assert!(root == Path::new("/"));
1300
1398
/// assert!(root.parent() == None);
1301
1399
/// ```
@@ -1315,6 +1413,17 @@ impl Path {
1315
1413
///
1316
1414
/// If the path terminates in `.`, `..`, or consists solely or a root of
1317
1415
/// 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
+ /// ```
1318
1427
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1319
1428
pub fn file_name ( & self ) -> Option < & OsStr > {
1320
1429
self . components ( ) . next_back ( ) . and_then ( |p| match p {
@@ -1334,12 +1443,32 @@ impl Path {
1334
1443
}
1335
1444
1336
1445
/// 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
+ /// ```
1337
1456
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1338
1457
pub fn starts_with < P : AsRef < Path > > ( & self , base : P ) -> bool {
1339
1458
iter_after ( self . components ( ) , base. as_ref ( ) . components ( ) ) . is_some ( )
1340
1459
}
1341
1460
1342
1461
/// 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
+ /// ```
1343
1472
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1344
1473
pub fn ends_with < P : AsRef < Path > > ( & self , child : P ) -> bool {
1345
1474
iter_after ( self . components ( ) . rev ( ) , child. as_ref ( ) . components ( ) . rev ( ) ) . is_some ( )
@@ -1353,6 +1482,16 @@ impl Path {
1353
1482
/// * The entire file name if there is no embedded `.`;
1354
1483
/// * The entire file name if the file name begins with `.` and has no other `.`s within;
1355
1484
/// * 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
+ /// ```
1356
1495
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1357
1496
pub fn file_stem ( & self ) -> Option < & OsStr > {
1358
1497
self . file_name ( ) . map ( split_file_at_dot) . and_then ( |( before, after) | before. or ( after) )
@@ -1366,6 +1505,16 @@ impl Path {
1366
1505
/// * None, if there is no embedded `.`;
1367
1506
/// * None, if the file name begins with `.` and has no other `.`s within;
1368
1507
/// * 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
+ /// ```
1369
1518
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1370
1519
pub fn extension ( & self ) -> Option < & OsStr > {
1371
1520
self . file_name ( ) . map ( split_file_at_dot) . and_then ( |( before, after) | before. and ( after) )
@@ -1374,6 +1523,16 @@ impl Path {
1374
1523
/// Creates an owned `PathBuf` with `path` adjoined to `self`.
1375
1524
///
1376
1525
/// 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
+ /// ```
1377
1536
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1378
1537
pub fn join < P : AsRef < Path > > ( & self , path : P ) -> PathBuf {
1379
1538
let mut buf = self . to_path_buf ( ) ;
@@ -1384,6 +1543,16 @@ impl Path {
1384
1543
/// Creates an owned `PathBuf` like `self` but with the given file name.
1385
1544
///
1386
1545
/// 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
+ /// ```
1387
1556
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1388
1557
pub fn with_file_name < S : AsRef < OsStr > > ( & self , file_name : S ) -> PathBuf {
1389
1558
let mut buf = self . to_path_buf ( ) ;
@@ -1394,6 +1563,16 @@ impl Path {
1394
1563
/// Creates an owned `PathBuf` like `self` but with the given extension.
1395
1564
///
1396
1565
/// 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
+ /// ```
1397
1576
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1398
1577
pub fn with_extension < S : AsRef < OsStr > > ( & self , extension : S ) -> PathBuf {
1399
1578
let mut buf = self . to_path_buf ( ) ;
@@ -1402,6 +1581,18 @@ impl Path {
1402
1581
}
1403
1582
1404
1583
/// 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
+ /// ```
1405
1596
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1406
1597
pub fn components ( & self ) -> Components {
1407
1598
let prefix = parse_prefix ( self . as_os_str ( ) ) ;
@@ -1415,13 +1606,35 @@ impl Path {
1415
1606
}
1416
1607
1417
1608
/// 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
+ /// ```
1418
1621
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1419
1622
pub fn iter ( & self ) -> Iter {
1420
1623
Iter { inner : self . components ( ) }
1421
1624
}
1422
1625
1423
1626
/// Returns an object that implements `Display` for safely printing paths
1424
1627
/// 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
+ /// ```
1425
1638
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1426
1639
pub fn display ( & self ) -> Display {
1427
1640
Display { path : self }
0 commit comments