[ANSI-Smalltalk] #peekFor:

[Richard O'Keefe]

In the Smalltalk standard, we read

5.9.2.8 Message: peekFor: anObject
   Synopsis
     Peeks at the next object in the stream
     and returns true if it matches the argument,
     and false if not.
   Definition: <gettableStream>
     Returns the result of sending #= to the first object
     in the receiver’s future sequence values with anObject
     as the argument.  Returns false if the receiver has
     no future sequence values.
   Parameters
     anObject <Object> uncaptured
   Return Value
     <boolean> unspecified
   Errors
     none

There is no faintest suggestion here that the state of the
stream changes in any way.  In particular, there is no
suggestion that a successful match will result in the stream
being advanced.

However, the Blue Book says on page 199

	Determine the response to the message [#]peek.
	If it is the same as the argument, anObject,
	THEN INCREMENT THE POSITION REFERENCE and
	answer true.  Otherwise answer false and do
	not change the position reference.

The comment in VisualWorks says

	Answer false and do not move the position
	if self next ~= anObject or if the receiver
	is at the end.  Answer true and
	INCREMENT POSITION if self next = anObject.

The comment in Squeak says

	Answer false and do not move over the next element
	if it is not equal to the argument, anObject, or
	if the receiver is at the end.  Answer true and
	INCREMENT THE POSITION for accessing elements,
	if the next element is equal to anObject.

When I wrote my stream classes, I took the standard text literally,
and my #peekFor: never advanced the stream position.  Whoops!
I propose the following replacement for the definition:

   Definition: <gettableStream>
     If the receiver has no future sequence values,
     returns false.  Otherwise, determines the result of
     sending #= to the first object in the receiver's
     future sequence values with anObject as the argument.
     If that is false, return false with no change to the
     receiver's state.  If #= answers true, the first
     object is removed from the receiver's future sequence
     values and appended to the end of the receiver's past
     sequence values, then true is returned.