Add head function

src/iter.php

@@ -735,6 +735,21 @@ function dropWhile(callable $predicate, iterable $iterable): \Iterator {
     }
 }
 
+/**
+ * Takes a non-empty iterable and returns the first element.
+ *
+ * @param iterable $iterable
+ * @return mixed
+ * @throws \InvalidArgumentException if argument is empty
+ */
+function head(iterable $iterable) {
+    foreach ($iterable as $value) {
+        return $value;
+    }
+
+    throw new \InvalidArgumentException('Argument must be non-empty');
+}
+
 /**
  * Takes an iterable containing any amount of nested iterables and returns
  * a flat iterable with just the values.

test/iterTest.php

@@ -272,6 +272,21 @@ public function testTakeOrDropWhile() {
         );
     }
 
+    public function testHead()
+    {
+        $this->assertSame(1, head([1,2,3]));
+        $this->assertSame(4, head(range(4,8)));
+    }
+
+    /**
+     * @expectedException \InvalidArgumentException
+     * @expectedExceptionMessage Argument must be non-empty
+     */
+    public function testHeadOnEmptyArgumentError()
+    {
+        head([]);
+    }
+
     public function testFlatten() {
         $this->assertSame(
             [1, 2, 3, 4, 5],