feature symfony#57243 [String] Add TruncateMode mode to truncate methods (Korbeil)

This PR was merged into the 7.2 branch.

Discussion
----------

[String] Add `TruncateMode` mode to `truncate` methods

| Q             | A
| ------------- | ---
| Branch?       | 7.2
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        |
| License       | MIT

When using truncate we had two behaviors:
```php
u("Lorem ipsum dolor sit amet")->truncate(14, cut: true); // outputs: Lorem ipsum do
u("Lorem ipsum dolor sit amet")->truncate(14, cut: false); // outputs: Lorem ipsum dolor
```

But sometimes, I want the truncate to fit within 14 chars while keeping all complete words, so I changed truncate method to have a new mode "WordBefore" and switch the `cut` parameter to use a new enum so we can choose which mode is better.

Now:
```php
u("Lorem ipsum dolor sit amet")->truncate(14, cut: TruncateMode::Char); // outputs: Lorem ipsum do
u("Lorem ipsum dolor sit amet")->truncate(14, cut: TruncateMode::WordAfter); // outputs: Lorem ipsum dolor
u("Lorem ipsum dolor sit amet")->truncate(14, cut: TruncateMode::WordBefore); // outputs: Lorem ipsum
```

Commits
-------

c3136a0 [String] Add WORD_STRICT mode to truncate method

Author: fabpot

UPGRADE-7.2.md

@@ -17,3 +17,11 @@ Yaml
 ----
 
  * Deprecate parsing duplicate mapping keys whose value is `null`
+
+String
+------
+
+ * `truncate` method now also accept `TruncateMode` enum instead of a boolean:
+   * `TruncateMode::Char` is equivalent to `true` value ;
+   * `TruncateMode::WordAfter` is equivalent to `true` value ;
+   * `TruncateMode::Word` is a new mode that will cut the sentence on the last word before the limit is reached.

src/Symfony/Component/String/AbstractString.php

@@ -605,7 +605,7 @@ 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|TruncateMode $cut = TruncateMode::Char): static
     {
         $stringLength = $this->length();
 
@@ -619,7 +619,8 @@ public function truncate(int $length, string $ellipsis = '', bool $cut = true):
             $ellipsisLength = 0;
         }
 
-        if (!$cut) {
+        $desiredLength = $length;
+        if (TruncateMode::WordAfter === $cut || TruncateMode::WordBefore === $cut || !$cut) {
             if (null === $length = $this->indexOf([' ', "\r", "\n", "\t"], ($length ?: 1) - 1)) {
                 return clone $this;
             }
@@ -629,6 +630,14 @@ public function truncate(int $length, string $ellipsis = '', bool $cut = true):
 
         $str = $this->slice(0, $length - $ellipsisLength);
 
+        if (TruncateMode::WordBefore === $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;
     }
 

src/Symfony/Component/String/CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+7.2
+---
+
+ * Add `TruncateMode` enum to handle more truncate methods
+
 7.1
 ---
 

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\TruncateMode;
 use Symfony\Component\String\UnicodeString;
 
 abstract class AbstractAsciiTestCase extends TestCase
@@ -1505,22 +1506,24 @@ 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, bool|TruncateMode $cut = TruncateMode::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, '...', TruncateMode::WordAfter],
             ['fo', 'foobar', 2, ''],
             ['foobar', 'foobar', 10, ''],
             ['foobar', 'foobar', 10, '...', false],
+            ['foobar', 'foobar', 10, '...', TruncateMode::WordAfter],
             ['foo', 'foo', 3, '...'],
             ['fo', 'foobar', 2, '...'],
             ['...', 'foobar', 3, '...'],
@@ -1529,6 +1532,14 @@ public static function provideTruncate()
             ['foobar...', 'foobar foo', 7, '...', false],
             ['foobar foo...', 'foobar foo a', 10, '...', false],
             ['foobar foo aar', 'foobar foo aar', 12, '...', false],
+            ['foobar...', 'foobar foo', 6, '...', TruncateMode::WordAfter],
+            ['foobar...', 'foobar foo', 7, '...', TruncateMode::WordAfter],
+            ['foobar foo...', 'foobar foo a', 10, '...', TruncateMode::WordAfter],
+            ['foobar foo aar', 'foobar foo aar', 12, '...', TruncateMode::WordAfter],
+            ['foobar foo', 'foobar foo aar', 10, '', TruncateMode::WordBefore],
+            ['foobar...', 'foobar foo aar', 10, '...', TruncateMode::WordBefore],
+            ['Lorem ipsum', 'Lorem ipsum dolor sit amet', 14, '', TruncateMode::WordBefore],
+            ['Lorem...', 'Lorem ipsum dolor sit amet', 10, '...', TruncateMode::WordBefore],
         ];
     }
 

src/Symfony/Component/String/TruncateMode.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 TruncateMode
+{
+    /**
+     * Will cut exactly at given length.
+     *
+     * Length: 14
+     * Source: Lorem ipsum dolor sit amet
+     * Output: Lorem ipsum do
+     */
+    case Char;
+
+    /**
+     * Returns the string up to the last complete word containing the specified length.
+     *
+     * Length: 14
+     * Source: Lorem ipsum dolor sit amet
+     * Output: Lorem ipsum
+     */
+    case WordBefore;
+
+    /**
+     * Returns the string up to the complete word after or at the given length.
+     *
+     * Length: 14
+     * Source: Lorem ipsum dolor sit amet
+     * Output: Lorem ipsum dolor
+     */
+    case WordAfter;
+}