Expand {Path,OsStr}::{to_str,to_string_lossy} doc examples.

diff --git a/src/libstd/ffi/os_str.rs b/src/libstd/ffi/os_str.rs
index 84b50f04463fe7dc8ccef469b5f02e1df007a67b..175fe30db661ce149445780742a63725765d757f 100644 (file)
--- a/src/libstd/ffi/os_str.rs
+++ b/src/libstd/ffi/os_str.rs
@@ -259,6 +259,15 @@ fn from_inner(inner: &Slice) -> &OsStr {
     /// Yields a `&str` slice if the `OsStr` is valid Unicode.
     ///
     /// This conversion may entail doing a check for UTF-8 validity.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::ffi::OsStr;
+    ///
+    /// let os_str = OsStr::new("foo");
+    /// assert_eq!(os_str.to_str(), Some("foo"));
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn to_str(&self) -> Option<&str> {
         self.inner.to_str()
@@ -267,6 +276,20 @@ pub fn to_str(&self) -> Option<&str> {
     /// Converts an `OsStr` to a `Cow<str>`.
     ///
     /// Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.
+    ///
+    /// # Examples
+    ///
+    /// Calling `to_string_lossy` on an `OsStr` with valid unicode:
+    ///
+    /// ```
+    /// use std::ffi::OsStr;
+    ///
+    /// let os_str = OsStr::new("foo");
+    /// assert_eq!(os_str.to_string_lossy(), "foo");
+    /// ```
+    ///
+    /// Had `os_str` contained invalid unicode, the `to_string_lossy` call might
+    /// have returned `"fo�"`.
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn to_string_lossy(&self) -> Cow<str> {
         self.inner.to_string_lossy()

diff --git a/src/libstd/path.rs b/src/libstd/path.rs
index d13baea40a9ff8069744f6a278548ac468ddee8d..3f9bf70adde22557cadf3f7fb5e16d6d51479d86 100644 (file)
--- a/src/libstd/path.rs
+++ b/src/libstd/path.rs
@@ -1428,8 +1428,8 @@ pub fn as_os_str(&self) -> &OsStr {
     /// ```
     /// use std::path::Path;
     ///
-    /// let path_str = Path::new("foo.txt").to_str();
-    /// assert_eq!(path_str, Some("foo.txt"));
+    /// let path = Path::new("foo.txt");
+    /// assert_eq!(path.to_str(), Some("foo.txt"));
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn to_str(&self) -> Option<&str> {
@@ -1444,12 +1444,17 @@ pub fn to_str(&self) -> Option<&str> {
     ///
     /// # Examples
     ///
+    /// Calling `to_string_lossy` on a `Path` with valid unicode:
+    ///
     /// ```
     /// use std::path::Path;
     ///
-    /// let path_str = Path::new("foo.txt").to_string_lossy();
-    /// assert_eq!(path_str, "foo.txt");
+    /// let path = Path::new("foo.txt");
+    /// assert_eq!(path.to_string_lossy(), "foo.txt");
     /// ```
+    ///
+    /// Had `os_str` contained invalid unicode, the `to_string_lossy` call might
+    /// have returned `"fo�.txt"`.
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn to_string_lossy(&self) -> Cow<str> {
         self.inner.to_string_lossy()