If we're going to introduce this, I wonder if there's any value in passing the left over input as well?  We should probably also use this everywhere, in enumerators for example - that's beyond the scope of this PR though.  For now I think we should have some scaladoc to say what it is.