truncate_utf8

  1. drupal
    1. 5
    2. 8
    3. 6
    4. 7
Versions
5 truncate_utf8($string, $len, $wordsafe = FALSE, $dots = FALSE)
7 – 8 truncate_utf8($string, $max_length, $wordsafe = FALSE, $add_ellipsis = FALSE, $min_wordsafe_length = 1)
6 truncate_utf8($string, $len, $wordsafe = FALSE, $dots = FALSE)

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

Parameters

$string The string to truncate.

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

$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 PREG_CLASS_UNICODE_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.

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

$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

The truncated string.

▾ 17 functions call truncate_utf8()

aggregator_aggregator_process in modules/aggregator/aggregator.processor.inc
Implements hook_aggregator_process().
aggregator_parse_feed in modules/aggregator/aggregator.parser.inc
Parse a feed and store its items.
comment_admin_overview in modules/comment/comment.admin.inc
Form builder for the comment overview administration form.
comment_submit in modules/comment/comment.module
Prepare a comment for submission.
DatabaseSchema_mysql::prepareComment in includes/database/mysql/schema.inc
Prepare a table or column comment for database query.
DBLogTestCase::assertLogMessage in modules/dblog/dblog.test
Assert messages appear on the log overview screen.
DBLogTestCase::doUser in modules/dblog/dblog.test
Generate and verify user events.
field_ui_existing_field_options in modules/field_ui/field_ui.admin.inc
Return an array of existing field to be added to a bundle.
search_excerpt in modules/search/search.module
Returns snippets from a piece of text, with certain keywords highlighted. Used for formatting search results.
text_summary in modules/field/modules/text/text.module
Generate a trimmed, formatted version of a text field value.
theme_dblog_message in modules/dblog/dblog.admin.inc
Returns HTML for a log message.
UnicodeUnitTest::runTruncateTests in modules/simpletest/tests/unicode.test
Runs test cases for helperTestTruncate().
_book_toc_recurse in modules/book/book.module
Recursively processes and formats menu items for book_toc().
_locale_translate_seek in includes/locale.inc
Perform a string search and display results in a table
_menu_parents_recurse in modules/menu/menu.module
Recursive helper function for menu_parent_options().
_search_index_truncate in modules/search/search.module
Helper function for array_walk in search_index_split.
_statistics_link in modules/statistics/statistics.module
It is possible to adjust the width of columns generated by the statistics module.

Code

includes/unicode.inc, line 312

<?php
function truncate_utf8($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 (drupal_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 = drupal_substr(t('...'), 0, $max_length);
    $max_length -= drupal_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 = array();
    // 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 . '})[' . PREG_CLASS_UNICODE_WORD_BOUNDARY . ']/u', $string, $matches);
    if ($found) {
      $string = $matches[1];
    }
    else {
      $string = drupal_substr($string, 0, $max_length);
    }
  }
  else {
    $string = drupal_substr($string, 0, $max_length);
  }

  if ($add_ellipsis) {
    $string .= $ellipsis;
  }

  return $string;
}
?>