Document/explain Positioner for parsing third-party types about combine HOT 6 CLOSED

/// Trait for updating the position for types which can be yielded from a `Stream`.
pub trait Positioner: PartialEq {
    type Item;
    /// The type which keeps track of the position
    type Position: Clone + Ord;
    /// Creates a start position
    fn start() -> Self::Position;
    /// Updates the position given that `self` has been taken from the stream
    fn update(&self, item: &Self::Item, position: &mut Self::Position);
}

/// The `State2<I>` struct keeps track of the current position in the stream `I` using the
/// `Positioner` trait to update the position.
#[derive(Clone, PartialEq)]
pub struct State2<I, X, P>
    where I: Stream<Position=P>,
          X: Positioner<Position=P>,
          P: Clone + Ord
{
    /// The input stream used when items are requested
    pub input: I,
    /// The positioner used to update the current position
    pub positioner: X,
    /// The current position
    pub position: P,
}

impl<I, X, P> fmt::Debug for State2<I, X, P>
    where I: Stream<Position=P> + fmt::Debug,
          X: Positioner<Position=P>,
          P: Clone + Ord + fmt::Debug
{
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f,
               "State2 {{ position: {:?}, input: {:?} }}",
               self.position,
               self.input)
    }
}

impl<I, X, P> State2<I, X, P>
    where I: Stream<Position=P>,
          X: Positioner<Position=P>,
          P: Clone + Ord
{
    /// Creates a new `State2<I, X, P>` from an input stream and a positioner. Initializes the position to
    /// `X::start()`
    pub fn new(input: I, positioner: X) -> State2<I, X, P> {
        State2::new_with_position(input, positioner, X::start())
    }

    /// Creates a new `State2<I, X, P>` from an input stream and a positioner, and sets the initial position.
    pub fn new_with_position(input: I, positioner: X, position: P) -> State2<I, X, P> {
        State2 {
            input: input,
            positioner: positioner,
            position: position,
        }
    }
}

impl<I, X, P> combine::StreamOnce for State2<I, X, P>
    where I: Stream<Position=P>,
          X: Positioner<Item=I::Item, Position=P>,
          P: Clone + Ord
{
    type Item = I::Item;
    type Range = I::Range;
    type Position = P;

    #[inline]
    fn uncons(&mut self) -> Result<I::Item, combine::primitives::Error<I::Item, I::Range>> {
        match self.input.uncons() {
            Ok(c) => {
                self.positioner.update(&c, &mut self.position);
                Ok(c)
            }
            Err(err) => Err(err),
        }
    }

    #[inline(always)]
    fn position(&self) -> Self::Position {
        self.position.clone()
    }
}

#[derive(Clone, PartialEq)]
struct ValuePositioner;

impl Positioner for ValuePositioner {
    type Item = Value;
    type Position = usize;
    fn start() -> usize {
        0
    }
    fn update(&self, item: &Value, position: &mut usize) {
        match *item {
            Value::Integer(ref x) => *position += (*x as usize),
            _ => *position += 1
        }
    }
}

#[test]
fn test_() {
    let input = [Value::Integer(2), Value::Integer(3)];
    let mut parser = many(any());
    let result = parser.parse(State2::new(&input[..], ValuePositioner));
    assert_eq!(result,
               Ok((vec![Value::Integer(2)], State2::new_with_position(&[Value::Integer(3)][..], ValuePositioner, 1))));
}