[String] Add WORD_STRICT mode to truncate method

Korbeil · Korbeil · commit a2ec8743eb94 · 2024-06-25T18:01:35.000+02:00
diff --git a/src/Symfony/Component/String/AbstractString.php b/src/Symfony/Component/String/AbstractString.php
@@ -605,8 +605,12 @@ public function trimSuffix($suffix): static
         return $str;
     }
 
-    public function truncate(int $length, string $ellipsis = '', bool $cut = true): static
+    public function truncate(int $length, string $ellipsis = '', bool|TruncateCut $cut = TruncateCut::Char): static
     {
+        if (\is_bool($cut)) {
+            $cut = $cut ? TruncateCut::Char : TruncateCut::WordAfterWord;
+        }
+
         $stringLength = $this->length();
 
         if ($stringLength <= $length) {
@@ -619,7 +623,8 @@ public function truncate(int $length, string $ellipsis = '', bool $cut = true):
             $ellipsisLength = 0;
         }
 
-        if (!$cut) {
+        $desiredLength = $length;
+        if (TruncateCut::WordAfterWord === $cut || TruncateCut::Word === $cut) {
             if (null === $length = $this->indexOf([' ', "\r", "\n", "\t"], ($length ?: 1) - 1)) {
                 return clone $this;
             }
@@ -629,6 +634,14 @@ public function truncate(int $length, string $ellipsis = '', bool $cut = true):
 
         $str = $this->slice(0, $length - $ellipsisLength);
 
+        if (TruncateCut::Word === $cut) {
+            if (0 === $ellipsisLength && $desiredLength === $this->indexOf([' ', "\r", "\n", "\t"], $length)) {
+                return $str;
+            }
+
+            $str = $str->beforeLast([' ', "\r", "\n", "\t"]);
+        }
+
         return $ellipsisLength ? $str->trimEnd()->append($ellipsis) : $str;
     }
 
diff --git a/src/Symfony/Component/String/CHANGELOG.md b/src/Symfony/Component/String/CHANGELOG.md
@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+7.2
+---
+
+ *  Add `TruncateCut::Word` mode to truncate method
+
 7.1
 ---
 
diff --git a/src/Symfony/Component/String/Tests/AbstractAsciiTestCase.php b/src/Symfony/Component/String/Tests/AbstractAsciiTestCase.php
@@ -16,6 +16,7 @@
 use Symfony\Component\String\ByteString;
 use Symfony\Component\String\CodePointString;
 use Symfony\Component\String\Exception\InvalidArgumentException;
+use Symfony\Component\String\TruncateCut;
 use Symfony\Component\String\UnicodeString;
 
 abstract class AbstractAsciiTestCase extends TestCase
@@ -1498,30 +1499,34 @@ public static function providePadStart()
     /**
      * @dataProvider provideTruncate
      */
-    public function testTruncate(string $expected, string $origin, int $length, string $ellipsis, bool $cut = true)
+    public function testTruncate(string $expected, string $origin, int $length, string $ellipsis, TruncateCut $cut = TruncateCut::Char)
     {
         $instance = static::createFromString($origin)->truncate($length, $ellipsis, $cut);
 
         $this->assertEquals(static::createFromString($expected), $instance);
     }
 
-    public static function provideTruncate()
+    public static function provideTruncate(): array
     {
         return [
             ['', '', 3, ''],
             ['', 'foo', 0, '...'],
-            ['foo', 'foo', 0, '...', false],
+            ['foo', 'foo', 0, '...', TruncateCut::WordAfterWord],
             ['fo', 'foobar', 2, ''],
             ['foobar', 'foobar', 10, ''],
-            ['foobar', 'foobar', 10, '...', false],
+            ['foobar', 'foobar', 10, '...', TruncateCut::WordAfterWord],
             ['foo', 'foo', 3, '...'],
             ['fo', 'foobar', 2, '...'],
             ['...', 'foobar', 3, '...'],
             ['fo...', 'foobar', 5, '...'],
-            ['foobar...', 'foobar foo', 6, '...', false],
-            ['foobar...', 'foobar foo', 7, '...', false],
-            ['foobar foo...', 'foobar foo a', 10, '...', false],
-            ['foobar foo aar', 'foobar foo aar', 12, '...', false],
+            ['foobar...', 'foobar foo', 6, '...', TruncateCut::WordAfterWord],
+            ['foobar...', 'foobar foo', 7, '...', TruncateCut::WordAfterWord],
+            ['foobar foo...', 'foobar foo a', 10, '...', TruncateCut::WordAfterWord],
+            ['foobar foo aar', 'foobar foo aar', 12, '...', TruncateCut::WordAfterWord],
+            ['foobar foo', 'foobar foo aar', 10, '', TruncateCut::Word],
+            ['foobar...', 'foobar foo aar', 10, '...', TruncateCut::Word],
+            ['Lorem ipsum', 'Lorem ipsum dolor sit amet', 14, '', TruncateCut::Word],
+            ['Lorem...', 'Lorem ipsum dolor sit amet', 10, '...', TruncateCut::Word],
         ];
     }
 
diff --git a/src/Symfony/Component/String/TruncateCut.php b/src/Symfony/Component/String/TruncateCut.php
@@ -0,0 +1,42 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\String;
+
+enum TruncateCut
+{
+    /**
+     * Will cut exactly at given length.
+     *
+     * Length: 14
+     * Source: Lorem ipsum dolor sit amet
+     * Output: Lorem ipsum do
+     */
+    case Char;
+
+    /**
+     * Will cut at given length, if length is onto a word, will cut before it.
+     *
+     * Length: 14
+     * Source: Lorem ipsum dolor sit amet
+     * Output: Lorem ipsum
+     */
+    case Word;
+
+    /**
+     * Will cut at given length until the end of the current word if length is onto a word.
+     *
+     * Length: 14
+     * Source: Lorem ipsum dolor sit amet
+     * Output: Lorem ipsum dolor
+     */
+    case WordAfterWord;
+}
