SI-9691 BufferedIterator should expose a headOption

This exposes a new API to the BufferedIterator trait. It will return the next element of an iterator as an Option.  The return will be  Some(value) if there is a next value, and None if there is not a next element.

2 files changed, 34 insertions, 0 deletions

diff --git a/src/library/scala/collection/BufferedIterator.scala b/src/library/scala/collection/BufferedIterator.scala
index e6e97d584c..1424ef2fd0 100644
--- a/src/library/scala/collection/BufferedIterator.scala
+++ b/src/library/scala/collection/BufferedIterator.scala
@@ -24,5 +24,11 @@ trait BufferedIterator[+A] extends Iterator[A] {
    */
   def head: A
 
+  /** Returns an option of the next element of an iterator without advancing beyond it.
+    * @return  the next element of this iterator if it has a next element
+    *           `None` if it does not
+    */
+  def headOption : Option[A] = if (hasNext) Some(head) else None
+
   override def buffered: this.type = this
 }
diff --git a/test/junit/scala/collection/IteratorTest.scala b/test/junit/scala/collection/IteratorTest.scala
index 4df29e36c0..09061a3b29 100644
--- a/test/junit/scala/collection/IteratorTest.scala
+++ b/test/junit/scala/collection/IteratorTest.scala
@@ -214,4 +214,32 @@ class IteratorTest {
     assertSameElements(exp, res)
     assertEquals(8, counter) // was 14
   }
+  // SI-9691
+  @Test def bufferedHeadOptionReturnsValueWithHeadOrNone(): Unit = {
+    // Checks BufferedIterator returns Some(value) when there is a value
+    val validHeadOption = List(1,2,3).iterator.buffered.headOption
+    assertEquals(Some(1), validHeadOption)
+    // Checks BufferedIterator returns None when there is no value
+    val invalidHeadOption = List(1,2,3).iterator.drop(10).buffered.headOption
+    assertEquals(None: Option[Int], invalidHeadOption)
+    // Checks BufferedIterator returns Some(value) in the last position with a value
+    val validHeadOptionAtTail = List(1,2,3).iterator.drop(2).buffered.headOption
+    assertEquals(Some(3), validHeadOptionAtTail)
+    // Checks BufferedIterator returns None at the first position without a value
+    val invalidHeadOptionOnePastTail = List(1,2,3).iterator.drop(3).buffered.headOption
+    assertEquals(None, invalidHeadOptionOnePastTail)
+    // Checks BufferedIterator returns Some(null) if the next value is null.
+    val nullHandingList = List(null, "yellow").iterator.buffered.headOption
+    assertEquals(Some(null), nullHandingList)
+    // Checks that BufferedIterator is idempotent. That the head is not
+    // changed by its invocation, nor the headOption by the next call to head.
+    val it = List(1,2,3).iterator.buffered
+    val v1 = it.head
+    val v2 = it.headOption
+    val v3 = it.head
+    val v4 = it.headOption
+    assertEquals(v1, v3)
+    assertEquals(v2, v4)
+    assertEquals(Some(v1), v2)
+  }
 }