The iconv encode and decode functions can be used to encode/decode strings into/from a specified encoding type. These functions are essential when working with different character encodings and converting between them.

Supported Encoding Types:

• UTF-8
• UTF-16
• UTF-32

iconv.encode()

Description:

Encodes a string in the specified encoding format and returns that as a byte array.

Syntax:

iconv.encode(string, encodingType)

Parameters:

• string - The string to encode
• encodingType - The encoding format to use (UTF-8, UTF-16, or UTF-32)

Returns: A byte array representation of the encoded string in SnapLogic binary format

Examples:

iconv.encode($msg, "UTF-8")
// Where $msg = "Hello, World"
// Returns: {"_snaptype_binary_base64": "/v8ASABlAGwAbABvACwAIABXAG8AcgBsAGQ="}

iconv.encode("SnapLogic", "UTF-16")
// Returns: Byte array in UTF-16 encoding

iconv.encode($text, "UTF-32")
// Encodes text in UTF-32 format

iconv.decode()

Description:

Decodes an encoded byte array and returns a string in the specified encoding type.

Syntax:

iconv.decode(byteArray, encodingType)

Parameters:

• byteArray - The encoded byte array to decode
• encodingType - The encoding format to use for decoding (UTF-8, UTF-16, or UTF-32)

Returns: A decoded string

Examples:

iconv.decode($msg_encoded, "UTF-8")
// Where $msg_encoded contains an encoded byte array
// Returns: "Hello, World"

iconv.decode($binary_data, "UTF-16")
// Decodes UTF-16 encoded data

iconv.decode($utf32_bytes, "UTF-32")
// Decodes UTF-32 encoded data

Common Use Cases

Round-Trip Encoding/Decoding:

// Encode and then decode back to original string
iconv.decode(iconv.encode("Test String", "UTF-8"), "UTF-8")
// Returns: "Test String"

Working with Different Character Sets:

// Encode international characters
iconv.encode("Hëllö Wörld", "UTF-8")

// Decode to read international text
iconv.decode($encoded_international, "UTF-8")

File Content Encoding:

// Encode file content for transmission
{
  "filename": $fileName,
  "content": iconv.encode($fileContent, "UTF-8"),
  "encoding": "UTF-8"
}

API Data Transformation:

// Decode data received from API
{
  "originalEncoding": "UTF-16",
  "decodedContent": iconv.decode($apiResponse.data, "UTF-16")
}

Character Set Conversion:

// Convert from one encoding to another
// First decode from UTF-16, then encode to UTF-8
iconv.encode(
  iconv.decode($utf16_data, "UTF-16"),
  "UTF-8"
)

Encoding Types Comparison

Best Practices

• Encoding Selection: Use UTF-8 for most general purposes as it's widely supported and efficient for ASCII-compatible text.
• Consistency: Ensure the encoding type used for decode matches the type used for encode.
• International Characters: Always specify encoding explicitly when working with international or special characters.
• Binary Data: Remember that encoded strings are returned as binary byte arrays in SnapLogic format.
• Error Handling: Validate that data is properly encoded before attempting to decode to avoid corruption.
• Performance: UTF-8 is generally more efficient for Western languages; UTF-16 may be better for Asian languages.
• API Integration: Check API documentation for required encoding format before encoding/decoding data.
• Round-Trip Testing: Always test encode/decode operations to ensure data integrity.

Working with Binary Data

The iconv functions work with SnapLogic's binary data format, which uses the _snaptype_binary_base64 wrapper.

Binary Format Structure:

{
  "_snaptype_binary_base64": "Base64EncodedString"
}

Example Workflow:

// Step 1: Encode string to binary
$encoded = iconv.encode("Hello", "UTF-8")
// Result: {"_snaptype_binary_base64": "..."}

// Step 2: Pass binary data to another Snap

// Step 3: Decode binary back to string
$decoded = iconv.decode($encoded, "UTF-8")
// Result: "Hello"

Practical Examples

Encoding User Input:

// Ensure user input is properly encoded
{
  "userId": $userId,
  "comment": iconv.encode($userComment, "UTF-8"),
  "timestamp": Date.now()
}

Decoding API Response:

// Decode encoded content from API
{
  "id": $response.id,
  "title": iconv.decode($response.encoded_title, "UTF-8"),
  "body": iconv.decode($response.encoded_body, "UTF-8")
}

Character Set Migration:

// Migrate from UTF-16 to UTF-8
{
  "original": $data,
  "originalEncoding": "UTF-16",
  "newEncoding": "UTF-8",
  "converted": iconv.encode(
    iconv.decode($data, "UTF-16"),
    "UTF-8"
  )
}

Validating Encoding:

// Check if data round-trips correctly
$original = "Test String"
$encoded = iconv.encode($original, "UTF-8")
$decoded = iconv.decode($encoded, "UTF-8")
$isValid = $original == $decoded  // Should be true

Relationship with Base64 Functions

The iconv functions differ from Base64 functions in their purpose:

• iconv Functions: Convert between different character encodings (UTF-8, UTF-16, UTF-32)
• Base64 Functions: Convert binary data to/from Base64 text representation

These functions can be used together:

// Encode text to UTF-8, then Base64 encode for transmission
Base64.encode(iconv.encode($text, "UTF-8"))

// Decode Base64, then decode from UTF-8
iconv.decode(Base64.decode($base64data), "UTF-8")

Function Reference