Same name in other branches

1. 8.9.x core/lib/Drupal/Component/Utility/Unicode.php \Drupal\Component\Utility\Unicode::truncate()
2. 10 core/lib/Drupal/Component/Utility/Unicode.php \Drupal\Component\Utility\Unicode::truncate()
3. 11.x core/lib/Drupal/Component/Utility/Unicode.php \Drupal\Component\Utility\Unicode::truncate()

Truncates a UTF-8-encoded string safely to a number of characters.

Parameters

string $string: The string to truncate.

int $max_length: An upper limit on the returned string length, including trailing ellipsis if $add_ellipsis is TRUE.

bool $wordsafe: If TRUE, attempt to truncate on a word boundary. Word boundaries are spaces, punctuation, and Unicode characters used as word boundaries in non-Latin languages; see Unicode::PREG_CLASS_WORD_BOUNDARY for more information. If a word boundary cannot be found that would make the length of the returned string fall within length guidelines (see parameters $max_length and $min_wordsafe_length), word boundaries are ignored.

bool $add_ellipsis: If TRUE, add '...' to the end of the truncated string (defaults to FALSE). The string length will still fall within $max_length.

int $min_wordsafe_length: If $wordsafe is TRUE, the minimum acceptable length for truncation (before adding an ellipsis, if $add_ellipsis is TRUE). Has no effect if $wordsafe is FALSE. This can be used to prevent having a very short resulting string that will not be understandable. For instance, if you are truncating the string "See myverylongurlexample.com for more information" to a word-safe return length of 20, the only available word boundary within 20 characters is after the word "See", which wouldn't leave a very informative string. If you had set $min_wordsafe_length to 10, though, the function would realise that "See" alone is too short, and would then just truncate ignoring word boundaries, giving you "See myverylongurl..." (assuming you had set $add_ellipses to TRUE).

Return value

string The truncated string.

27 calls to Unicode::truncate()

BookManager::recurseTableOfContents in core/modules/book/src/BookManager.php

Recursively processes and formats book links for getTableOfContents().

CommentAdminOverview::buildForm in core/modules/comment/src/Form/CommentAdminOverview.php

Form constructor for the comment overview administration form.

CommentAdminTest::testApprovalAdminInterface in core/modules/comment/tests/src/Functional/Views/CommentAdminTest.php

Tests comment approval functionality through admin/content/comment.

CommentForm::buildEntity in core/modules/comment/src/CommentForm.php

Builds an updated entity object based upon the submitted form values.

CommentPermalinkFormatter::getEntityUrl in core/modules/comment/src/Plugin/Field/FieldFormatter/CommentPermalinkFormatter.php

Gets the URI elements of the entity.

... See full list

File

core/lib/Drupal/Component/Utility/Unicode.php, line 308

Class

Unicode

Provides Unicode-related conversions and operations.

Namespace

Drupal\Component\Utility

Code

public static function truncate($string, $max_length, $wordsafe = FALSE, $add_ellipsis = FALSE, $min_wordsafe_length = 1) {
    $ellipsis = '';
    $max_length = max($max_length, 0);
    $min_wordsafe_length = max($min_wordsafe_length, 0);
    if (mb_strlen($string) <= $max_length) {
        // No truncation needed, so don't add ellipsis, just return.
        return $string;
    }
    if ($add_ellipsis) {
        // Truncate ellipsis in case $max_length is small.
        $ellipsis = mb_substr('…', 0, $max_length);
        $max_length -= mb_strlen($ellipsis);
        $max_length = max($max_length, 0);
    }
    if ($max_length <= $min_wordsafe_length) {
        // Do not attempt word-safe if lengths are bad.
        $wordsafe = FALSE;
    }
    if ($wordsafe) {
        $matches = [];
        // Find the last word boundary, if there is one within $min_wordsafe_length
        // to $max_length characters. preg_match() is always greedy, so it will
        // find the longest string possible.
        $found = preg_match('/^(.{' . $min_wordsafe_length . ',' . $max_length . '})[' . Unicode::PREG_CLASS_WORD_BOUNDARY . ']/us', $string, $matches);
        if ($found) {
            $string = $matches[1];
        }
        else {
            $string = mb_substr($string, 0, $max_length);
        }
    }
    else {
        $string = mb_substr($string, 0, $max_length);
    }
    if ($add_ellipsis) {
        // If we're adding an ellipsis, remove any trailing periods.
        $string = rtrim($string, '.');
        $string .= $ellipsis;
    }
    return $string;
}

---