Issue #10534 has been updated by Bart Mesuere.

Subject changed from Enumerator methods other than "next" do not respect "peek" to Enumerator methods other than "next" do not always respect "peek"

I don't agree that a documentation would fix this. This issue results in unpredictable behaviour:
~~~
$ ruby -e "e=['a','b','c'].each;puts e.peek;puts e.next"
a
a
$ ruby -e "e=['a','b','c'].each;puts e.peek;e.each{|l| puts l}"
a
a
b
c
~~~

~~~
$ echo -e "a\nb\nc" | ruby -e "e=STDIN.each_line;puts e.peek;puts e.next"
a
a
$ echo -e "a\nb\nc" | ruby -e "e=STDIN.each_line;puts e.peek;e.each{|l| puts l}"
a
b
c
~~~

There's no way to know if the underlying iteration method has "side effects" except from trying it.

----------------------------------------
Bug #10534: Enumerator methods other than "next" do not always respect "peek"
https://bugs.ruby-lang.org/issues/10534#change-52814

* Author: Jonas Nicklas
* Status: Open
* Priority: Normal
* Assignee: 
* ruby -v: ruby 2.1.5p273 (2014-11-13 revision 48405) [x86_64-darwin14.0]
* Backport: 2.0.0: UNKNOWN, 2.1: UNKNOWN
----------------------------------------
It seems like using "peek" and then calling other methods on the Enumerator consumes the value that was peeked at. While `next` correctly returns the peeked-at value the next time it is called, other Enumerator methods such as `to_a` and `each` do not.

~~~
>> enum = StringIO.new("foo").each
=> #<Enumerator: #<StringIO:0x007ff3313d8688>:each>
>> enum.peek
=> "foo"
>> enum.to_a
=> []
~~~

Here the final call to `enum.to_a` should have returned `["foo"]`, since we have not consumed anything from the enumerator yet. The peeked-at value is not included in the returned Array.

Taking a glance at the code, it seems that these methods do not call `next` under the hood, but instead have some other mechanism of iterating over the Enumerator, this seems very counter-intuitive to me.



-- 
https://bugs.ruby-lang.org/