Name: uniDecode

Type: function

Syntax: the uniDecode of <stringToDecode> 

Syntax: uniDecode(<stringToDecode> [, <language>])

Summary: Converts a string from <Unicode> to single-byte text.

Introduced: 1.0

OS: mac,windows,linux,ios,android

Platforms: desktop,server,web,mobile

Example:
uniDecode("A" & numToChar(zero)) -- returns "A" (on PPC)

Example:
uniDecode("ABCDE") -- returns "BD" (on Intel)

Example:
uniDecode(field "JIS Input","Japanese") -- converts to JIS

Parameters:
stringToDecode (string): any string, or expression that evaluates to a string.
language (enum): one of the following
- "ANSI" (synonym for "English"
- "Arabic"
- "Bulgarian"
- "Chinese"
- "English"
- "Greek"
- "Hebrew"
- "Japanese" (Shift-JIS)
- "Korean"
- "Polish"
- "Roman"
- "Russian" (Cyrillic)
- "Thai"
- "Turkish"
- "SimplifiedChinese"
- "Unicode" (UTF-16)
- "UTF8"
- "w" (synonym for "Unicode"

The result: As of LiveCode 7.0 the uniDecode function has been deprecated. It will continue to work as in previous versions but should not be used in new code as the existing behaviour is incompatible with the new, transparent Unicode handling (the resulting value will be treated as binary data rather than text). This functions is only useful in combination with the also-deprecated uniEncode function and unicodeText field property.

Returns:
If you don't specify a <language>, the <uniDecode> <function> <return|returns> the <stringToDecode>, with every second <byte> removed.
If a <language> is specified, the <uniDecode> <function> encodes the <stringToDecode> into single-byte text, using the appropriate method for the specified <language>.

Description:
Use the <uniDecode> <function(control_st)> to convert double-byte characters to single-byte characters.

>*Important:* 

The <uniDecode> function is the <inverse> of the <uniEncode> function and removes the <null> <byte|bytes> inserted for <Unicode> compatibility. In other words, it turns double-byte <characters> into their closest single-byte equivalent.

If the <stringToDecode> contains an odd number of <byte|bytes>, the last <byte> is ignored.

>*Note:* You can use the UTF8 encoding only with the <uniDecode> and <uniEncode> <function(glossary)|functions>. You cannot set an <object|object's> <textFont> <property> to use UTF-8. To display Unicode text in an <object>, use either "Unicode" or a language name as the second item of the <object|object's> <textFont>.

>*Important:* The <format> expected by the <uniDecode> <function(control_st)> is processor-dependent. On "little-endian" processors, where the first <byte> is least significant (such as Intel and Alpha processors), the <uniDecode> <function(control_st)> removes the second byte of each <character>. On "big-endian" processors, where the last <byte> is least significant (such as PowerPC processors), the <uniDecode> <function(control_st)> removes the first <byte> of each <character>.

The ability to handle double-byte characters on "little-endian" processors was added in version 2.0. In previous versions, the <uniDecode> <function(control_st)> always removed the second <byte> of each pair of <byte|bytes>, regardless of <platform>.

The ability to convert Unicode text into language-specific encodings was added in version 2.0. In previous versions, the <uniDecode> <function(control_st)> simply removed every other <byte>.

Changes:
The ability to encode text in Polish was added in version 2.1.1.

References: textFont (property), unicodeText (property), object (object), inverse (keyword), characters (keyword), character (keyword), null (constant), format (function), uniEncode (function), uniDecode (function), platform (function), property (glossary), Unicode (glossary), function (glossary), byte (glossary), return (glossary), function (control_st)

Tags: text processing
