Add doc examples for most untrusted::Input methods.

src/untrusted.rs

@@ -93,6 +93,14 @@ pub struct Input<'a> {
 
 impl<'a> Input<'a> {
     /// Construct a new `Input` for the given input `bytes`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use untrusted::Input;
+    ///
+    /// let input = Input::from(b"foo");
+    /// ```
     pub fn from(bytes: &'a [u8]) -> Input<'a> {
         // This limit is important for avoiding integer overflow. In particular,
         // `Reader` assumes that an `i + 1 > i` if `input.value.get(i)` does
@@ -104,17 +112,68 @@ impl<'a> Input<'a> {
     }
 
     /// Returns `true` if the input is empty and false otherwise.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use untrusted::Input;
+    ///
+    /// let input = Input::from(b"");
+    /// println!("{:?}", input.is_empty()); // prints true
+    ///
+    /// let input = Input::from(b"foo");
+    /// println!("{:?}", input.is_empty()); // prints false
+    /// ```
     #[inline]
     pub fn is_empty(&self) -> bool { self.value.len() == 0 }
 
     /// Returns the length of the `Input`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use untrusted::Input;
+    ///
+    /// let input = Input::from(b"foo");
+    /// println!("{:?}", input.len()); // prints 3
+    /// ```
     #[inline]
     pub fn len(&self) -> usize { self.value.len() }
 
 
     /// Calls `read` with the given input as a `Reader`, ensuring that `read`
     /// consumed the entire input. If `read` does not consume the entire input,
     /// `incomplete_read` is returned.
+    ///
+    /// # Examples
+    ///
+    /// `read` consumes entire input:
+    ///
+    /// ```
+    /// use untrusted::Input;
+    ///
+    /// let input = Input::from(b"foo");
+    /// let result = input.read_all((), |input| {
+    ///     let _ = try!(input.read_byte());
+    ///     let _ = try!(input.read_byte());
+    ///     let _ = try!(input.read_byte());
+    ///     Ok(())
+    /// });
+    /// println!("{:?}", result.is_ok()); // prints true
+    /// ```
+    ///
+    /// `read` does *not* consume entire input:
+    ///
+    /// ```
+    /// use untrusted::Input;
+    ///
+    /// let input = Input::from(b"foo");
+    /// let result = input.read_all((), |input| {
+    ///     let _ = try!(input.read_byte());
+    ///     Ok(())
+    /// });
+    /// println!("{:?}", result.is_err()); // prints true
+    /// ```
     pub fn read_all<F, R, E>(&self, incomplete_read: E, read: F)
                              -> Result<R, E>
                              where F: FnOnce(&mut Reader<'a>) -> Result<R, E> {
@@ -143,6 +202,16 @@ impl<'a> Input<'a> {
 
     /// Access the input as a slice so it can be processed by functions that
     /// are not written using the Input/Reader framework.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use untrusted::Input;
+    ///
+    /// let input = Input::from(b"foo");
+    /// let slice = input.as_slice_less_safe();
+    /// println!("{:?}", slice == b"foo"); // prints true
+    /// ```
     #[inline]
     pub fn as_slice_less_safe(&self) -> &'a [u8] {
         self.value.as_slice_less_safe()