[String] add $lastGlue argument to join() methods

Author: nicolas-grekas

AbstractString.php

@@ -387,7 +387,7 @@ public function isEmpty(): bool
     /**
      * @return static
      */
-    abstract public function join(array $strings): self;
+    abstract public function join(array $strings, string $lastGlue = null): self;
 
     public function jsonSerialize(): string
     {

AbstractUnicodeString.php

@@ -180,10 +180,12 @@ public function folded(bool $compat = true): parent
         return $str;
     }
 
-    public function join(array $strings): parent
+    public function join(array $strings, string $lastGlue = null): parent
     {
         $str = clone $this;
-        $str->string = implode($this->string, $strings);
+
+        $tail = null !== $lastGlue && 1 < \count($strings) ? $lastGlue.array_pop($strings) : '';
+        $str->string = implode($this->string, $strings).$tail;
 
         if (!preg_match('//u', $str->string)) {
             throw new InvalidArgumentException('Invalid UTF-8 string.');

ByteString.php

@@ -168,10 +168,12 @@ public function isUtf8(): bool
         return '' === $this->string || preg_match('//u', $this->string);
     }
 
-    public function join(array $strings): parent
+    public function join(array $strings, string $lastGlue = null): parent
     {
         $str = clone $this;
-        $str->string = implode($str->string, $strings);
+
+        $tail = null !== $lastGlue && 1 < \count($strings) ? $lastGlue.array_pop($strings) : '';
+        $str->string = implode($this->string, $strings).$tail;
 
         return $str;
     }

Tests/AbstractAsciiTestCase.php

@@ -1160,6 +1160,11 @@ public function testJoin(string $expected, string $origin, array $join)
         $this->assertEquals(static::createFromString($expected), $instance);
     }
 
+    public function testJoinWithLastGlue()
+    {
+        $this->assertSame('foo, bar and baz', (string) static::createFromString(', ')->join(['foo', 'bar', 'baz'], ' and '));
+    }
+
     public static function provideJoin()
     {
         return [

UnicodeString.php

@@ -178,9 +178,9 @@ public function indexOfLast($needle, int $offset = 0): ?int
         return false === $i ? null : $i;
     }
 
-    public function join(array $strings): AbstractString
+    public function join(array $strings, string $lastGlue = null): AbstractString
     {
-        $str = parent::join($strings);
+        $str = parent::join($strings, $lastGlue);
         normalizer_is_normalized($str->string) ?: $str->string = normalizer_normalize($str->string);
 
         return $str;