Adobe ColdFusion 8

ToString

Description

Converts a value to a string.

Returns

A string.

Category

Conversion functions, String functions

Function syntax

ToString(value[, encoding])

See also

ToBase64, ToBinary, CharsetEncode; "Using XML and WDDX" in the ColdFusion Developer's Guide

History

ColdFusion MX:

  • Changed Unicode support: ColdFusion supports the Java UCS-2 representation of Unicode character values 0-65535. (ColdFusion 5 and earlier releases supported ASCII values 1-255.)
  • Added the encoding parameter.
  • Added ability to convert an XML document object to a string.

Parameters

Parameter

Description
value

Value to convert to a string; can be a simple value such as an integer, a binary object, or an XML document object.
encoding

The character encoding (character set) of the string. Optional for binary data, Generates an error if used for a simple value or XML document object.

The following list includes commonly used values:

  • utf-8
  • iso-8859-1
  • windows-1252
  • us-ascii
  • shift_jis
  • iso-2022-jp
  • euc-jp
  • euc-kr
  • big5
  • euc-cn
  • utf-16

For more information on character encoding, see: www.w3.org/International/O-charset.html.

The default value is the encoding of the page on which the function is called. See cfcontent.

Usage

This function can convert simple values and binary values that do not contain Byte zero. If this function cannot convert a value, it throws an exception. This function can also convert an XML document object to a string XML representation.

Adobe recommends that you use the CharsetEncode function to convert binary data to a string.

Example

<h3>ToString Example</h3>
<!---- Initialize data. ------>
<cfset charData = "">
<!----- Create string of ASCII characters (32-255) and concatenate them. ---->
<cfloop index = "data" from = "32" to = "255">
    <cfset ch = chr(data)>
    <cfset charData = charData & ch>
</cfloop>
<p>The following string is the concatenation of characters (32 to 255) 
    from the ASCII table.<br>
<cfoutput>#charData#</cfoutput></p>

<!------ Create a Base64 representation of this string. ---->
<cfset data64 = toBase64(#charData#)>
<p>
The following string is the Base64 representation of the string.<br>
<cfoutput>#data64#</cfoutput></p>
<!---- Create a binary representation of Base64 data. --->
<cfset dataBinary = toBinary(data64)>

<!---- Create the string representation of the binary data. ----->
<cfset dataString = ToString(dataBinary)>
<p>The following is the string representation of the binary data.<br>
<cfoutput>#dataString#</cfoutput></p>