charsetEncode

Description

Uses the specified encoding to convert binary data to a string.

History

ColdFusion MX 7: Added this function.

Syntax

CharsetEncode(binaryobject, encoding)

Attributes

Attribute	Description	Required	Default
binaryobject	A variable containing binary data to decode into text.
encoding	The character encoding that was used to encode the string into binary format. It must be a character encoding name recognized by the Java runtime. 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 a complete list of character encoding names supported by Sun Java runtimes, see http://java.sun.com/javase/6/docs/technotes/guides/intl/encoding.doc.html.

Returns

A string representation of the binary object.

Usage

Adobe recommends that you use this function, and not the ToString function, to convert binary data to strings in all new applications.

Example

The following example uses the CharsetDecode function to convert a string from a form to a binary object, and uses the CharsetEncode function to convert it back to the original value. You can change the character encoding that ColdFusion uses for the conversion. If you select the Asian language encodings, characters that are not in the specified character set are successfully converted.

<h3>Character Encoding Conversion Example</h3> 
<!--- Do the following if the form has been submitted. ---> 
<cfif IsDefined("Form.myString")> 
 
    <!--- Do the conversions. ---> 
    <cfscript> 
        chardecode=CharsetDecode(Form.myString, Form.charEncoding); 
        charencode=CharsetEncode(chardecode, Form.charEncoding); 
    </cfscript> 
 
    <!--- Display the input values and results. ---> 
    <cfoutput> 
        <h3>Parameter Settings</h3> 
        <b>The string:</b><br> 
             #Form.myString#</p> 
        <b>The character encoding:</b> #Form.charEncoding#</p> 
         
        <h3>Results of the operations:</h3> 
        <b>Dump of the string converted to a binary object by CharsetDecode:  
            </b><br> 
            <cfdump var="#chardecode#"></p> 
        <b>The binary object converted back to a string by CharsetEncode:  
            </b><br> 
        #charencode#</p> 
    </cfoutput> 
</cfif> 
 
<!--- The input form. ---> 
<form action="#CGI.SCRIPT_NAME#" method="post"> 
    <b>Select the character encoding</b><br> 
    <!--- This is a subset, additional encodings are available. ---> 
    <select size="1" name="charEncoding" > 
        <option selected>UTF-8</option> 
        <option>ASCII</option> 
        <option>ISO8859_1</option> 
        <option>CP1252</option> 
        <option>SJIS</option> 
        <option>MS932</option> 
        <option>EUC_CN</option> 
        <option>Big5</option> 
    </select><br> 
    <br> 
    <b>Enter a string</b><br> 
    <textArea name = "myString" cols = "40" rows = "5" WRAP = "VIRTUAL"> 
    The following four characters are not in all character encodings: ½àç÷ 
    </textArea><br> 
    <br> 
    <input type = "Submit" value = "convert my data"> 
</form>

cfmldocs