@@ -1379,27 +1379,159 @@ impl<'a> Formatter<'a> {
13791379 }
13801380 }
13811381
1382- /// Optionally specified integer width that the output should be
1382+ /// Optionally specified integer width that the output should be.
1383+ ///
1384+ /// # Examples
1385+ ///
1386+ /// ```
1387+ /// use std::fmt;
1388+ ///
1389+ /// struct Foo(i32);
1390+ ///
1391+ /// impl fmt::Display for Foo {
1392+ /// fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
1393+ /// if let Some(width) = formatter.width() {
1394+ /// // If we received a width, we use it
1395+ /// write!(formatter, "{:width$}", &format!("Foo({})", self.0), width = width)
1396+ /// } else {
1397+ /// // Otherwise we do nothing special
1398+ /// write!(formatter, "Foo({})", self.0)
1399+ /// }
1400+ /// }
1401+ /// }
1402+ ///
1403+ /// assert_eq!(&format!("{:10}", Foo(23)), "Foo(23) ");
1404+ /// assert_eq!(&format!("{}", Foo(23)), "Foo(23)");
1405+ /// ```
13831406#[ stable( feature = "fmt_flags" , since = "1.5.0" ) ]
13841407 pub fn width ( & self ) -> Option < usize > { self . width }
13851408
1386- /// Optionally specified precision for numeric types
1409+ /// Optionally specified precision for numeric types.
1410+ ///
1411+ /// # Examples
1412+ ///
1413+ /// ```
1414+ /// use std::fmt;
1415+ ///
1416+ /// struct Foo(f32);
1417+ ///
1418+ /// impl fmt::Display for Foo {
1419+ /// fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
1420+ /// if let Some(precision) = formatter.precision() {
1421+ /// // If we received a precision, we use it.
1422+ /// write!(formatter, "Foo({1:.*})", precision, self.0)
1423+ /// } else {
1424+ /// // Otherwise we default to 2.
1425+ /// write!(formatter, "Foo({:.2})", self.0)
1426+ /// }
1427+ /// }
1428+ /// }
1429+ ///
1430+ /// assert_eq!(&format!("{:.4}", Foo(23.2)), "Foo(23.2000)");
1431+ /// assert_eq!(&format!("{}", Foo(23.2)), "Foo(23.20)");
1432+ /// ```
13871433#[ stable( feature = "fmt_flags" , since = "1.5.0" ) ]
13881434 pub fn precision ( & self ) -> Option < usize > { self . precision }
13891435
13901436 /// Determines if the `+` flag was specified.
1437+ ///
1438+ /// # Examples
1439+ ///
1440+ /// ```
1441+ /// use std::fmt;
1442+ ///
1443+ /// struct Foo(i32);
1444+ ///
1445+ /// impl fmt::Display for Foo {
1446+ /// fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
1447+ /// if formatter.sign_plus() {
1448+ /// write!(formatter,
1449+ /// "Foo({}{})",
1450+ /// if self.0 < 0 { '-' } else { '+' },
1451+ /// self.0)
1452+ /// } else {
1453+ /// write!(formatter, "Foo({})", self.0)
1454+ /// }
1455+ /// }
1456+ /// }
1457+ ///
1458+ /// assert_eq!(&format!("{:+}", Foo(23)), "Foo(+23)");
1459+ /// assert_eq!(&format!("{}", Foo(23)), "Foo(23)");
1460+ /// ```
13911461#[ stable( feature = "fmt_flags" , since = "1.5.0" ) ]
13921462 pub fn sign_plus ( & self ) -> bool { self . flags & ( 1 << FlagV1 :: SignPlus as u32 ) != 0 }
13931463
13941464 /// Determines if the `-` flag was specified.
1465+ ///
1466+ /// # Examples
1467+ ///
1468+ /// ```
1469+ /// use std::fmt;
1470+ ///
1471+ /// struct Foo(i32);
1472+ ///
1473+ /// impl fmt::Display for Foo {
1474+ /// fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
1475+ /// if formatter.sign_minus() {
1476+ /// // You want a minus sign? Have one!
1477+ /// write!(formatter, "-Foo({})", self.0)
1478+ /// } else {
1479+ /// write!(formatter, "Foo({})", self.0)
1480+ /// }
1481+ /// }
1482+ /// }
1483+ ///
1484+ /// assert_eq!(&format!("{:-}", Foo(23)), "-Foo(23)");
1485+ /// assert_eq!(&format!("{}", Foo(23)), "Foo(23)");
1486+ /// ```
13951487#[ stable( feature = "fmt_flags" , since = "1.5.0" ) ]
13961488 pub fn sign_minus ( & self ) -> bool { self . flags & ( 1 << FlagV1 :: SignMinus as u32 ) != 0 }
13971489
13981490 /// Determines if the `#` flag was specified.
1491+ ///
1492+ /// # Examples
1493+ ///
1494+ /// ```
1495+ /// use std::fmt;
1496+ ///
1497+ /// struct Foo(i32);
1498+ ///
1499+ /// impl fmt::Display for Foo {
1500+ /// fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
1501+ /// if formatter.alternate() {
1502+ /// write!(formatter, "Foo({})", self.0)
1503+ /// } else {
1504+ /// write!(formatter, "{}", self.0)
1505+ /// }
1506+ /// }
1507+ /// }
1508+ ///
1509+ /// assert_eq!(&format!("{:#}", Foo(23)), "Foo(23)");
1510+ /// assert_eq!(&format!("{}", Foo(23)), "23");
1511+ /// ```
13991512#[ stable( feature = "fmt_flags" , since = "1.5.0" ) ]
14001513 pub fn alternate ( & self ) -> bool { self . flags & ( 1 << FlagV1 :: Alternate as u32 ) != 0 }
14011514
14021515 /// Determines if the `0` flag was specified.
1516+ ///
1517+ /// # Examples
1518+ ///
1519+ /// ```
1520+ /// use std::fmt;
1521+ ///
1522+ /// struct Foo(i32);
1523+ ///
1524+ /// impl fmt::Display for Foo {
1525+ /// fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
1526+ /// assert!(formatter.sign_aware_zero_pad());
1527+ /// assert_eq!(formatter.width(), Some(4));
1528+ /// // We ignore the formatter's options.
1529+ /// write!(formatter, "{}", self.0)
1530+ /// }
1531+ /// }
1532+ ///
1533+ /// assert_eq!(&format!("{:04}", Foo(23)), "23");
1534+ /// ```
14031535#[ stable( feature = "fmt_flags" , since = "1.5.0" ) ]
14041536 pub fn sign_aware_zero_pad ( & self ) -> bool {
14051537 self . flags & ( 1 << FlagV1 :: SignAwareZeroPad as u32 ) != 0
0 commit comments