Implemented insertBefore() method

README.md

@@ -1916,6 +1916,34 @@ Map::from( ['foo', 'bar'] )->insertAfter( null, 'baz' );
 ```
 
 
+### insertBefore()
+
+Inserts the value or values before the given element.
+
+```php
+public function insertBefore( $element, $value ) : self
+```
+
+* @param mixed `$element` Element before the value is inserted
+* @param mixed `$value` Element or list of elements to insert
+* @return self Updated map for fluid interface
+
+Numerical array indexes are not preserved.
+
+**Examples:**
+
+```php
+Map::from( ['a' => 'foo', 'b' => 'bar'] )->insertBefore( 'bar', 'baz' );
+// ['a' => 'foo', 0 => 'baz', 'b' => 'bar']
+
+Map::from( ['foo', 'bar'] )->insertBefore( 'bar', ['baz', 'boo'] );
+// ['foo', 'baz', 'boo', 'bar']
+
+Map::from( ['foo', 'bar'] )->insertBefore( null, 'baz' );
+// ['foo', 'bar', 'baz']
+```
+
+
 ### intersect()
 
 Returns all values in a new map that are available in both, the map and the given elements.

src/Map.php

@@ -1532,6 +1532,34 @@ public function insertAfter( $element, $value ) : self
 	}
 
 
+	/**
+	 * Inserts the value or values before the given element.
+	 *
+	 * Examples:
+	 *  Map::from( ['a' => 'foo', 'b' => 'bar'] )->insertBefore( 'bar', 'baz' );
+	 *  Map::from( ['foo', 'bar'] )->insertBefore( 'bar', ['baz', 'boo'] );
+	 *  Map::from( ['foo', 'bar'] )->insertBefore( null, 'baz' );
+	 *
+	 * Results:
+	 *  ['a' => 'foo', 0 => 'baz', 'b' => 'bar']
+	 *  ['foo', 'baz', 'boo', 'bar']
+	 *  ['foo', 'bar', 'baz']
+	 *
+	 * Numerical array indexes are not preserved.
+	 *
+	 * @param mixed $element Element before the value is inserted
+	 * @param mixed $value Element or list of elements to insert
+	 * @return self Updated map for fluid interface
+	 */
+	public function insertBefore( $element, $value ) : self
+	{
+		$pos = ( $element !== null ? $this->pos( $element ) : count( $this->list ) );
+		array_splice( $this->list, $pos, 0, $this->getArray( $value ) );
+
+		return $this;
+	}
+
+
 	/**
 	 * Returns all values in a new map that are available in both, the map and the given elements.
 	 *

tests/MapTest.php

@@ -1212,6 +1212,33 @@ public function testInsertAfterEnd()
 	}
 
 
+	public function testInsertBefore()
+	{
+		$r = Map::from( ['a' => 'foo', 'b' => 'bar'] )->insertBefore( 'bar', 'baz' );
+
+		$this->assertInstanceOf( Map::class, $r );
+		$this->assertEquals( ['a' => 'foo', 0 => 'baz', 'b' => 'bar'], $r->toArray() );
+	}
+
+
+	public function testInsertBeforeArray()
+	{
+		$r = Map::from( ['foo', 'bar'] )->insertBefore( 'bar', ['baz', 'boo'] );
+
+		$this->assertInstanceOf( Map::class, $r );
+		$this->assertEquals( ['foo', 'baz', 'boo', 'bar'], $r->toArray() );
+	}
+
+
+	public function testInsertBeforeEnd()
+	{
+		$r = Map::from( ['foo', 'bar'] )->insertBefore( null, 'baz' );
+
+		$this->assertInstanceOf( Map::class, $r );
+		$this->assertEquals( ['foo', 'bar', 'baz'], $r->toArray() );
+	}
+
+
 	public function testIntersect()
 	{
 		$m = new Map( ['id' => 1, 'first_word' => 'Hello'] );