String Functions

CFML comes with a wealth of functions that make string manipulation simple. In fact, CFML string functions comprise one of the largest classes of CFML functions. The following list summarizes some of the more commonly used string functions:

• Asc(string)— Returns the ASCII numeric value of the first character of string. For example:

  The ASCII value of "a" is <cfoutput>#Asc("a")#</cfoutput>. 
  

• Chr(value)— Returns the character with the ASCII value equal to value. value must therefore be an integer between 0 and 255. The following example shows how to use the Chr() function to generate a carriage return-line feed character:

  <!--- 
        Carriage Return has ASCII value 13.
        Line Feed has ASCII value 10.
  --->
  <cfset CRLF = Chr(13) & Chr(10)>
  

• CJustify(string,length)— Centers string in a field of length length. For example:

  <cfset centeredString = CJustify("Hello!",12)> 
  

• Compare(string1,string2)— Does a case-sensitive comparison of string1 and string2, returning -1 if string1 is less than string2, 0 if the strings are equal, and 1 if string1 is greater than string2. In the following example, ColdFusion would output "abc" is less than "ABC".:

  <cfswitch expression="#Compare("abc","ABC")#"> 
  <cfcase value="1">
     "abc" is greater than "ABC".
  </cfcase>
  <cfcase value="0">
     "abc" and "ABC" are equal.
  </cfcase>
  <cfcase value="-1">
     "abc" is less than "ABC".
  </cfcase>
  </cfswitch>
  

• CompareNoCase(string1,string2)— Does a non-case-sensitive comparison of string1 and string2, returning -1 if string1 is less than string2, 0 if the strings are equal, and 1 if string1 is greater than string2. In the following example, ColdFusion would output "abc" and "ABC" are equal.:

  <cfswitch expression="#CompareNoCase("abc","ABC")#"> 
  <cfcase value="1">
     "abc" is greater than "ABC".
  </cfcase>
  <cfcase value="0">
     "abc" and "ABC" are equal.
  </cfcase>
  <cfcase value="-1">
     "abc" is less than "ABC".
  </cfcase>
  </cfswitch>
  						

• Find(string1,string2,start)— Returns the position in string2 where there is an occurrence of string1. The case-sensitive search begins at the first character unless you specify a different value with the start parameter. The function returns 0 if no occurrence of string1 is found. Otherwise, it returns the position of string1 within string2. In the following example, ColdFusion would output a value of 4:

  <cfoutput>#Find("dog","DogdogDog")#</cfoutput> 
  

• FindNoCase(string1,string2,start)— Returns the position in string2 where there is an occurrence of string1. The non-case-sensitive search begins at the first character unless you specify a different value with the start parameter. The function returns 0 if no occurrence of string1 is found. Otherwise, it returns the position of string1 within string2. In the following example, ColdFusion would output a value of 1:

  <cfoutput>#FindNoCase("cat","CatcatCat")#</cfoutput> 
  

• Insert(string1,string2,pos)— Inserts string1 into string2 at position pos. If pos is 0, the function concatenates string1 and string2. The output from the following example would be ColdFusion:

  <cfoutput>#Insert("old","CFusion",2)#</cfoutput>
  						

• LCase(string)— Converts string to lowercase. For example:

  <cfset emailName = LCase(Form.firstName & Form.lastName)>
  						

• Left(string,pos)— Returns the leftmost pos characters from string. In the following example, the area code would be printed out as 202:

  <cfset phoneNumber = "2025551234"> 
  Your Area Code is <cfoutput>#Left(phoneNumber,3)#</cfoutput>
  						

• Len(string)— Returns the number of characters in string. For example:

  Your name is <cfoutput>#Len(Form.name)#</cfoutput> characters long.
  						

• LTrim(string)— Removes any leading spaces from string. For example:

  <!--- 
      Remove all white space characters from the front of myVariable
  --->
  <cfset myVariable = LTrim(myVariable)>
  						

• Mid(string,start,num_chars)— Extracts num_chars characters from string, starting at position start. The output from the following example would be 555:

  <cfset phoneNumber = "2025551234"> 
  The middle part of your phone number is
  <cfoutput>Mid(phoneNumber,4,3)#</cfoutput>
  

• Replace(string1,string2,string3,scope)— Replaces occurrences of string2 in string1 with string3. scope controls how many replacements should be made ("one" or "all"). For example:

  <!--- 
     Replace each instance of a user-specified keyword
     With the keyword in boldface text.
  --->
  <cfset passage = Replace(passage,Form.keyword,
  "<b>" & Form.keyword & "</b>", "all")>
  

• Reverse(string)— Reverses the order of the characters in string. For example:

  Your name spelled backwards is <cfoutput>#Reverse(Form.name)#</cfoutput>.
  						

• Right(string,pos)— Returns the rightmost pos characters from string. In the following example, the output from the function would be 1234:

  <cfset phoneNumber = "2025551234"> 
  The last four digits of your phone number are
  <cfoutput>Right(phoneNumber,4)#</cfoutput>
  

• RJustify(string,length)— Right-justifies string in a field of length length. For example:

  <cfset rightJustifiedString = RJustify("Hello!",10)>
  						

• RTrim(string)— Removes trailing spaces from string. For example:

  <!--- 
      Remove all white space characters from the end of myVariable
  --->
  <cfset myVariable = RTrim(myVariable)>
  						

• Trim(string)— Removes all whitespace characters from either end of string. For example:

  <!--- 
      Remove all white space characters from both ends of myVariable
  --->
  <cfset myVariable = Trim(myVariable)>
  

• UCase(string)— Converts string to uppercase. For example:

  <cfset stateAbbreviation = Ucase(stateAbbreviation)> 
  

• Val(string)— Converts string into a numerical value, if possible. The function returns a value of 0 if conversion is not possible. Val() is useful in trapping potentially harmful SQL commands that hackers may attempt to append to a query string. In this situation, Val() preserves the numerical value being passed (typically a primary key value) and throws out the deleterious SQL command. For example:

  <cfquery datasource="customers" name="qGetCustomerInfo"> 
  SELECT *
  FROM Customers
  WHERE CustomerID = #Val(URL.CustomerID)#
  </cfquery>