loneElement and loneElementOption: extension methods for Iterable (#339)

Author: mpollmeier

core/src/main/scala/flatgraph/traversal/IterableOnceExtension.scala

@@ -0,0 +1,54 @@
+package flatgraph.traversal
+
+class IterableOnceExtension[A](val iterable: IterableOnce[A]) extends AnyVal {
+
+  /** @see {{{loneElement(hint)}}} */
+  def loneElement: A =
+    loneElement(hint = "")
+
+  /** @return
+    *   the one and only element from an Iterable
+    * @throws NoSuchElementException
+    *   if the Iterable is empty
+    * @throws AssertionError
+    *   if the Iterable has more than one element
+    */
+  def loneElement(hint: String): A = {
+    lazy val hintMaybe =
+      if (hint.isEmpty) ""
+      else s" Hint: $hint"
+
+    val iter = iterable.iterator
+    if (iter.isEmpty) {
+      throw new NoSuchElementException(s"Iterable was expected to have exactly one element, but it is empty.$hintMaybe")
+    } else {
+      val res = iter.next()
+      if (iter.hasNext) {
+        val collectionSizeHint = iterable.knownSize match {
+          case -1        => "it has more than one" // cannot be computed cheaply, i.e. without traversing the collection
+          case knownSize => s"it has $knownSize"
+        }
+        throw new AssertionError(s"Iterable was expected to have exactly one element, but $collectionSizeHint.$hintMaybe")
+      }
+      res
+    }
+  }
+
+  /** @return
+    *   {{{Some(element)}}} if the Iterable has exactly one element, or {{{None}}} if the Iterable has zero or more than 1 element. Note: if
+    *   the lone element is {{{null}}}, this will return {{{Some(null)}}}, which is in accordance with how {{{headOption}}} works.
+    */
+  def loneElementOption: Option[A] = {
+    val iter = iterable.iterator
+    if (iter.isEmpty) {
+      None
+    } else {
+      val result = iter.next()
+      if (iter.hasNext) {
+        None
+      } else {
+        Some(result)
+      }
+    }
+  }
+}

core/src/main/scala/flatgraph/traversal/Language.scala

@@ -28,6 +28,9 @@ trait language {
 
   implicit def iteratorToNumericSteps[A: Numeric](iter: IterableOnce[A]): NumericSteps[A] =
     new NumericSteps[A](iter)
+
+  implicit def iterableOnceExtension[A](iter: IterableOnce[A]): IterableOnceExtension[A] =
+    new IterableOnceExtension[A](iter)
 }
 
 @Traversal(elementType = classOf[AnyRef])

core/src/test/scala/flatgraph/traversal/IterableOnceExtensionTests.scala

@@ -0,0 +1,46 @@
+package flatgraph.traversal
+
+import flatgraph.traversal.language.*
+import org.scalatest.matchers.should.Matchers
+import org.scalatest.wordspec.AnyWordSpec
+
+import scala.collection.mutable.ArrayBuffer
+
+class IterableOnceExtensionTests extends AnyWordSpec with Matchers {
+
+  "loneElement returns the one and only element from an Iterable, and throws an exception otherwise" in {
+    Seq(1).loneElement shouldBe 1
+    Seq(1).loneElement("some context") shouldBe 1
+    Seq(null).loneElement shouldBe null
+
+    intercept[NoSuchElementException] {
+      Seq.empty.loneElement
+    }.getMessage should include("it is empty")
+
+    intercept[NoSuchElementException] {
+      Seq.empty.loneElement("some context")
+    }.getMessage should include("it is empty. Hint: some context")
+
+    intercept[AssertionError] {
+      Seq(1, 2).loneElement
+    }.getMessage should include("it has more than one")
+
+    intercept[AssertionError] {
+      ArrayBuffer(1, 2).loneElement
+    }.getMessage should include("it has 2") // ArrayBuffer can 'cheaply' compute their size, so we can have it in the exception message
+
+    intercept[AssertionError] {
+      Seq(1, 2).loneElement("some context")
+    }.getMessage should include("it has more than one. Hint: some context")
+  }
+
+  "loneElementOption returns an Option of the one and only element from an Iterable, or else None" in {
+    Seq(1).loneElementOption shouldBe Some(1)
+    Seq(null).loneElementOption shouldBe Some(null)
+
+    Seq.empty.loneElementOption shouldBe None
+
+    Seq(1, 2).loneElementOption shouldBe None
+  }
+
+}