Whatever message this page gives is out now! Go check it out!

BinaryEncode

Last update:
May 18, 2026

Description

Converts binary data to a string.

Returns

An encoded string representing the binary data.

Category

Conversion functions, String functions

Function syntax

BinaryEncode(binarydata, encoding)

See also

BinaryDecode, CharsetEncode, CharsetDecode

History

ColdFusion (2021 release): Introduced encoding base64Url
ColdFusion MX 7: Added this function.

Parameters

Parameter
Description
binarydata
A variable containing the binary data to encode.
encoding
A string that specifies the encoding method to use to represent the data; one of the following:
  • Hex: use the characters 0-9 and A-F to represent the hexadecimal value of each byte; for example, 3A.
  • UU: use the UNIX UUencode algorithm to convert the data.
  • Base64: use the Base64 algorithm to convert the data, as specified by IETF RFC 2045, at www.ietf.org/rfc/rfc2045.txt.
  • Base64Url: modification of the main Base64 standard, which uses the encoding result as filename or URL address.

Usage

Binary objects and, in some cases, 8-bit characters, cannot be transported over many Internet protocols, such as HTTP and SMTP, and might not be supported by some database systems. By Binary encoding the data, you convert the data into a format that you can transfer over any Internet protocol or store in a database as character data. To convert the data back to a binary format, use the BinaryDecode function. Adobe recommends that you use the BinaryEncode function, and not the ToBase64(binarydata) function, to convert binary data to Base64 data in all new applications.This function provides a superset of the functionality of the ToBase64(binarydata) function.See the following pages for additional information on handling binary data:
  • cffile for loading and reading binary data
  • cfwddx for serializing and deserializing binary data
  • IsBinary for checking variables for binary format
  • Len for determining the length of a binary object

Example

<cfscript>

function base64ToHex( String base64Value ){
        var binaryValue = binaryDecode( base64Value, "base64" );
        var hexValue = binaryEncode( binaryValue, "hex" );
        return( lcase( hexValue ) );
    }
    function base64ToString( String base64Value ){
        var binaryValue = binaryDecode( base64Value, "base64" );
        var stringValue = toString( binaryValue );
        return( stringValue );
    }
    function hexToBase64( String hexValue ){
        var binaryValue = binaryDecode( hexValue, "hex" );
        var base64Value = binaryEncode( binaryValue, "base64" );
        return( base64Value );
    }
    function hexToString( String hexValue ){
        var binaryValue = binaryDecode( hexValue, "hex" );
        var stringValue = toString( binaryValue );
        return( stringValue );
    }
    function stringToBase64( String stringValue ){
        var binaryValue = stringToBinary( stringValue );
        var base64Value = binaryEncode( binaryValue, "base64" );
        return( base64Value );
    }
    function stringToBinary( String stringValue ){
        var base64Value = toBase64( stringValue );
        var binaryValue = toBinary( base64Value );
        return( binaryValue );
    }
    function stringToHex( String stringValue ){
        var binaryValue = stringToBinary( stringValue );
        var hexValue = binaryEncode( binaryValue, "hex" );
        return( lcase( hexValue ) );
    }
    // ------------------------------------------------------ //
    // ------------------------------------------------------ //
    // ------------------------------------------------------ //
    // ------------------------------------------------------ //
    // Let's create a string value to test with.
    message = "GoodMorning! What's Up?";
    writeOutput( "Original :: " & message );
    writeOutput( "<br />" );
    // Now, let's check to the String-to-XXX conversions.
    writeOutput( "<br />" );
    messageAsHex = stringToHex( message );
    writeOutput( "Hex :: " & messageAsHex );
    writeOutput( "<br />" );
    messageAsBase64 = stringToBase64( message );
    writeOutput( "Base64 :: " & messageAsBase64 );
    writeOutput( "<br />" );
    messageAsBinary = stringToBinary( message );
    writeOutput( "Binary :: B" & arrayLen( messageAsBinary ) );
    writeOutput( "<br />" );
    
</cfscript>
Output
Original :: GoodMorning! What's Up?

Hex :: 476f6f644d6f726e696e6721205768617427732055703f

Base64 :: R29vZE1vcm5pbmchIFdoYXQncyBVcD8=

Binary :: B23

Example 2

<cfscript> 
    longString = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890`~!@##$%^&*()_+=-{}[]|\:;""'<>?,./"; 
    binaryString = toBinary(toBase64(longString)); 
    //encode binary data 
    encodedBinaryData = binaryEncode(binaryString, "Base64Url");        
    writedump(encodedBinaryData); 
    //decode the encoded binary data 
    decodedBinaryData = binaryDecode(encodedBinaryData, "Base64Url");   
    //verify if the decoded binary data is the same as the source binary data 
    writeOutput("<br/>") 
    if(toString(binaryString) eq toString(decodedBinaryData)) 
    { 
        writeoutput("binaryEncode/binaryDecode of a long string is OK"); 
    } 
    else 
    { 
        writeoutput("binaryEncode/binaryDecode of a long string is NOT OK"); 
    } 
</cfscript>

Output

YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWjEyMzQ1Njc4OTBgfiFAIyQlXiYqKClfKz0te31bXXxcOjsiJzw-PywuLw

binaryEncode/binaryDecode of a long string is OK

Share this page

Was this page helpful?
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Thank you for your feedback. Your response will help improve this page.

On this page