Merge pull request #190 from quodlibetor/document-parse-from-str

Add a note and example to DateTime::parse_from_str

src/datetime.rs

@@ -211,6 +211,20 @@ impl DateTime<FixedOffset> {
     /// on the supported escape sequences.
     ///
     /// See also `Offset::datetime_from_str` which gives a local `DateTime` on specific time zone.
+    ///
+    /// Note that this method *requires a timezone* in the string. See
+    /// [`NaiveDateTime::parse_from_str`](./naive/struct.NaiveDateTime.html#method.parse_from_str)
+    /// for a version that does not require a timezone in the to-be-parsed str.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use chrono::{DateTime, FixedOffset, TimeZone};
+    ///
+    /// let dt = DateTime::parse_from_str(
+    ///     "1983 Apr 13 12:09:14.274 +0000", "%Y %b %d %H:%M:%S%.3f %z");
+    /// assert_eq!(dt, Ok(FixedOffset::east(0).ymd(1983, 4, 13).and_hms_milli(12, 9, 14, 274)));
+    /// ```
     pub fn parse_from_str(s: &str, fmt: &str) -> ParseResult<DateTime<FixedOffset>> {
         let mut parsed = Parsed::new();
         try!(parse(&mut parsed, s, StrftimeItems::new(fmt)));

src/format/strftime.rs

@@ -54,7 +54,7 @@ Spec. | Example       | Description
 `%M`  | `34`          | Minute number (00--59), zero-padded to 2 digits.
 `%S`  | `60`          | Second number (00--60), zero-padded to 2 digits. [5]
 `%f`  | `026490000`   | The fractional seconds (in nanoseconds) since last whole second. [8]
-`%.f` | `.026490`     | Similar to `.%f` but left-aligned. [8]
+`%.f` | `.026490`     | Similar to `.%f` but left-aligned. These all consume the leading dot. [8]
 `%.3f`| `.026`        | Similar to `.%f` but left-aligned but fixed to a length of 3. [8]
 `%.6f`| `.026490`     | Similar to `.%f` but left-aligned but fixed to a length of 6. [8]
 `%.9f`| `.026490000`  | Similar to `.%f` but left-aligned but fixed to a length of 9. [8]