truncate()

truncate()

Version: 1.0 build 20040415
Requires: Adobe ColdFusion 5.0 or greater
Total size: 2.09 KB
Download time: 0.37 seconds at 56kbps
Edition: Freeware

Description

This function takes a string and truncates it to a maximum length, where the length is specified in characters, words or sentences. If the string is trucated, ellipsis is added to the end of the string. You may change the ellipsis value any way you like, e.g. " . . . ", " etc.", or simply use an empty string.

As this function may truncate a string at any point, you should strip any HTML from the string before truncating it.

Returns

A string.

Category

String

Parameters


Parameter Type Required? Default Description
str string Yes The string
maxLength integer Yes Maximum length of string
units string No
  • "sentences": Measure the string length in sentences
  • "words": Measure the string length in words
  • "[all other values]": Measure the string length in characters (default)
ellipsis string No String to append to a truncated string. Default: '...'.

UDF source


 
<cfscript>
  /**
  * Truncate a string to a specified maximum number of characters, words, or
  * sentences. Optionally, add ellipsis to truncated strings.
  * 
  * @param str              The string (Required)
  * @param maxLength        Integer (Required)
  * @param units            Units of measurement: "Characters" (default),
  *                         "words", or "sentences" (Optional)
  * @param ellipsis         String to append to truncated string. Default: "..."
  * @return string
  * @author Matthew Walker, WWW.eswsoftware.com
  * @version 1, 2004-04-15
  */
  
  function truncate(str, maxLength) {
    var result = str;
    var units = "characters";
    var ellipsis = "...";
    var stringLength = 0;
    var temp = "";
   
    if ( not structKeyExists(request, "eswsoftware") )
      request.eswsoftware = structNew();
    if ( not structKeyExists(request.eswsoftware, "truncate") )
      request.eswsoftware.truncate = structNew();  
    request.eswsoftware.truncate.version = 1;
	    
    if ( arrayLen(arguments) gte 3 )
      units = arguments[3];  
      
    if ( arrayLen(arguments) gte 4 )
      ellipsis = arguments[4];    
    
    switch(units) {
    
      case "sentences": {
        stringLength = listLen(str, ".");
        if(stringLength gt maxLength) {
          temp = listToArray(str, ".");
          arraySet(temp, maxLength + 1, arrayLen(temp), "");
          result = arrayToList(temp, ".");
        }
        break;
      }
      
      case "words": {
        stringLength = listLen(str, " ");
        if(stringLength gt maxLength) {
          temp = listToArray(str, " ");
          arraySet(temp, maxLength + 1, arrayLen(temp), "");
          result = arrayToList(temp, " ");
        }
        break;
      }
      
      default: {
        stringLength = len(str);
        if(stringLength gt maxLength) {
          result = left(str, max(maxlength - len(ellipsis), 1));
        }
      }
    
    }
    
    if(stringLength gt maxLength) {
      result = result & ellipsis;
    }

    return result;
  }
</cfscript>
World Wide Web
HyperText Markup Language
The coding language used to create hypertext documents for use on the World Wide Web.