Adding get_input() to types that already have public as_str() 🏷️ (#890)

* Added merge and get_input for Span.

* Corrected examples in doc-comments.
Reexporting merge_spans.

* Run cargo fmt and replaced std with core.

* Added get_input  for Span, Pairs and Pair. 🏷️

* Run cargo fmt.

pest/src/iterators/pair.rs

@@ -125,6 +125,38 @@ impl<'i, R: RuleType> Pair<'i, R> {
         &self.input[start..end]
     }
 
+    /// Returns the input string of the `Pair`.
+    ///
+    /// This function returns the input string of the `Pair` as a `&str`. This is the source string
+    /// from which the `Pair` was created. The returned `&str` can be used to examine the contents of
+    /// the `Pair` or to perform further processing on the string.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use std::rc::Rc;
+    /// # use pest;
+    /// # #[allow(non_camel_case_types)]
+    /// # #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+    /// enum Rule {
+    ///     ab
+    /// }
+    ///
+    /// // Example: Get input string from a Pair
+    ///
+    /// let input = "ab";
+    /// let pair = pest::state(input, |state| {
+    ///     // generating Token pair with Rule::ab ...
+    /// #     state.rule(Rule::ab, |s| s.match_string("ab"))
+    /// }).unwrap().next().unwrap();
+    ///
+    /// assert_eq!(pair.as_str(), "ab");
+    /// assert_eq!(input, pair.get_input());
+    /// ```
+    pub fn get_input(&self) -> &'i str {
+        self.input
+    }
+
     /// Returns the `Span` defined by the `Pair`, consuming it.
     ///
     /// # Examples
@@ -426,4 +458,12 @@ mod tests {
 
         assert_eq!(2, pairs.tokens().count());
     }
+
+    #[test]
+    fn get_input_of_pair() {
+        let input = "abcde";
+        let pair = AbcParser::parse(Rule::a, input).unwrap().next().unwrap();
+
+        assert_eq!(input, pair.get_input());
+    }
 }

pest/src/iterators/pairs.rs

@@ -114,6 +114,40 @@ impl<'i, R: RuleType> Pairs<'i, R> {
         }
     }
 
+    /// Returns the input string of `Pairs`.
+    ///
+    /// This function returns the input string of `Pairs` as a `&str`. This is the source string
+    /// from which `Pairs` was created. The returned `&str` can be used to examine the contents of
+    /// `Pairs` or to perform further processing on the string.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use std::rc::Rc;
+    /// # use pest;
+    /// # #[allow(non_camel_case_types)]
+    /// # #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+    /// enum Rule {
+    ///     a,
+    ///     b
+    /// }
+    ///
+    /// // Example: Get input string from Pairs
+    ///
+    /// let input = "a b";
+    /// let pairs = pest::state(input, |state| {
+    ///     // generating Token pairs with Rule::a and Rule::b ...
+    /// #     state.rule(Rule::a, |s| s.match_string("a")).and_then(|s| s.skip(1))
+    /// #         .and_then(|s| s.rule(Rule::b, |s| s.match_string("b")))
+    /// }).unwrap();
+    ///
+    /// assert_eq!(pairs.as_str(), "a b");
+    /// assert_eq!(input, pairs.get_input());
+    /// ```
+    pub fn get_input(&self) -> &'i str {
+        self.input
+    }
+
     /// Captures inner token `Pair`s and concatenates resulting `&str`s. This does not capture
     /// the input between token `Pair`s.
     ///
@@ -527,6 +561,14 @@ mod tests {
         assert_eq!(pairs.as_str(), "abcde");
     }
 
+    #[test]
+    fn get_input_of_pairs() {
+        let input = "abcde";
+        let pairs = AbcParser::parse(Rule::a, input).unwrap();
+
+        assert_eq!(pairs.get_input(), input);
+    }
+
     #[test]
     fn as_str_empty() {
         let mut pairs = AbcParser::parse(Rule::a, "abcde").unwrap();

pest/src/span.rs

@@ -525,9 +525,10 @@ mod tests {
     }
 
     #[test]
-    fn get_input() {
+    fn get_input_of_span() {
         let input = "abc\ndef\nghi";
         let span = Span::new(input, 1, 7).unwrap();
+
         assert_eq!(span.get_input(), input);
     }
 
@@ -537,6 +538,7 @@ mod tests {
         let span1 = Span::new(input, 1, 7).unwrap();
         let span2 = Span::new(input, 7, 11).unwrap();
         let merged = merge_spans(&span1, &span2).unwrap();
+
         assert_eq!(merged, Span::new(input, 1, 11).unwrap());
     }
 
@@ -546,6 +548,7 @@ mod tests {
         let span1 = Span::new(input, 1, 7).unwrap();
         let span2 = Span::new(input, 5, 11).unwrap();
         let merged = merge_spans(&span1, &span2).unwrap();
+
         assert_eq!(merged, Span::new(input, 1, 11).unwrap());
     }
 
@@ -555,6 +558,7 @@ mod tests {
         let span1 = Span::new(input, 1, 7).unwrap();
         let span2 = Span::new(input, 8, 11).unwrap();
         let merged = merge_spans(&span1, &span2);
+
         assert!(merged.is_none());
     }
 }