<doc>
	<legacy_id>2499</legacy_id>
	<name>uniEncode</name>
	<type>function</type>

	<syntax>
		<example>the uniEncode of <i>stringToEncode</i></example>
		<example>uniEncode(<i>stringToEncode</i>[,<i>language</i>])</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Converts a <keyword tag="string">string</keyword> from single-byte text to <glossary tag="Unicode">Unicode</glossary>.</summary>

	<examples>
<example>uniEncode("AB") <i>-- returns "A",null,"B",null (on Intel)</i></example>
<example>uniEncode("AB") <i>-- returns null,"A",null,"B" (on PPC)</i></example>
<example><p>uniEncode(inputText,"Japanese") <i>-- converts Shift-JIS to Unicode</i></p></example>
	</examples>

	<history>
		<introduced version="1.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="7.0">7.0</changed>
<changed version="2.1.1">2.1.1</changed>
		<experimental version=""></experimental>
		<nonexperimental version=""></nonexperimental>
	</history>

	<objects>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<desktop/>
		<server/>
		<web/>
		<mobile/>
	</classes>

	<security>
	</security>


	<classification>
	</classification>

	<references>
		<function tag="uniDecode">uniDecode function</function>
		<property tag="unicodeTitle">unicodeTitle Property</property>
	</references>

	<description>
	<overview>Use the <b>uniEncode</b> <control_st tag="function">function</control_st> to convert single-byte characters to double-byte characters.</overview>

		<parameters>
  <parameter>
    <name>stringToDecode</name>
    <description> any string, or expression that evaluates to a string.</description>
  </parameter>
  <parameter>
    <name>language</name>
    <description>one of the following</description>
    <options title="">
      <option>
        <item>ANSI(synonym for "English"</item>
        <description/>
      </option>
      <option>
        <item>Arabic</item>
        <description/>
      </option>
      <option>
        <item>Bulgarian</item>
        <description/>
      </option>
      <option>
        <item>Chinese</item>
        <description/>
      </option>
      <option>
        <item>English</item>
        <description/>
      </option>
      <option>
        <item>Greek</item>
        <description/>
      </option>
      <option>
        <item>Hebrew</item>
        <description/>
      </option>
      <option>
        <item>Japanese (Shift-JIS)</item>
        <description/>
      </option>
      <option>
        <item>Korean</item>
        <description/>
      </option>
      <option>
        <item>Polish</item>
        <description/>
      </option>
      <option>
        <item>Roman</item>
        <description/>
      </option>
      <option>
        <item>Russian (Cyrillic)</item>
        <description/>
      </option>
      <option>
        <item>Thai</item>
        <description/>
      </option>
      <option>
        <item>Turkish</item>
        <description/>
      </option>
      <option>
        <item>SimplifiedChinese</item>
        <description/>
      </option>
      <option>
        <item>Unicode (UTF-16)</item>
        <description/>
      </option>
      <option>
        <item>UTF8</item>
        <description/>
      </option>
      <option>
        <item>w (synonym for "Unicode"</item>
        <description/>
      </option>
    </options>
  </parameter>		</parameters>

	<value>The <b>uniEncode</b> <control_st tag="function">function</control_st> <glossary tag="return">returns</glossary> a <glossary tag="Unicode">Unicode</glossary> <keyword tag="string">string</keyword>.<p></p><p>If you don't specify a <i>language</i>, the <keyword tag="string">string</keyword> has each <keyword tag="character">character</keyword> of <i>stringToEncode</i> either followed or led (depending on <function tag="platform">platform</function>) by a <constant tag="null">null</constant> <keyword tag="character">character</keyword>.</p><p></p><p>If a <i>language</i> is specified, the <b>uniEncode</b> <control_st tag="function">function</control_st> returns the <glossary tag="Unicode">Unicode</glossary> equivalent of the <i>stringToEncode</i>, assuming the appropriate single-byte encoding for the specified <i>language</i>.</p></value>
	<comments><important><p>As of LiveCode 7.0 the uniEncode function has been deprecated. It will continue to work as in previous versions but shoud 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 uniDecode function and unicodeText field property.</important><p></p><p>The <b>uniEncode</b> <control_st tag="function">function</control_st> is the <keyword tag="inverse">inverse</keyword> of the <function tag="uniDecode">uniDecode</function> <control_st tag="function">function</control_st> and inserts <constant tag="null">null</constant> bytes for <glossary tag="Unicode">Unicode</glossary> compatibility. In other words, it turns single-byte characters into their double-byte equivalent.</p><p></p><p></p><p></p><note> You can use the UTF8 encoding only with the <function tag="uniDecode">uniDecode</function> and <b>uniEncode</b> <glossary tag="function">functions</glossary>. You cannot set an <glossary tag="object">object's</glossary> <property tag="textFont">textFont</property> <glossary tag="property">property</glossary> to use UTF-8. To display Unicode text in an <glossary tag="object">object</glossary>, use either "Unicode" or a language name as the second item of the <glossary tag="object">object's</glossary> <property tag="textFont">textFont</property>.</note><p></p><p></p><p></p><important>The <function tag="format">format</function> produced by the <b>uniEncode</b> <control_st tag="function">function</control_st> is processor-dependent. On "big-endian" processors, where the first <glossary tag="byte">byte</glossary> is least significant (such as Intel and Alpha processors), the <b>uniEncode</b> <control_st tag="function">function</control_st> adds the <constant tag="null">null</constant> <glossary tag="byte">byte</glossary> after each <keyword tag="character">character</keyword>. On "little-endian" processors, where the last <glossary tag="byte">byte</glossary> is least significant (such as PowerPC processors), the <b>uniEncode</b> <control_st tag="function">function</control_st> adds the <constant tag="null">null</constant> <glossary tag="byte">byte</glossary> before each <keyword tag="character">character</keyword>.</important><p></p><p></p><p></p><change><p>The ability to encode text in Polish was added in version 2.1.1.</change><p></p><p>The ability to handle double-byte characters on "little-endian" processors was added in version 2.0. In previous versions, the <b>uniEncode</b> <control_st tag="function">function</control_st> always added the <constant tag="null">null</constant> <glossary tag="byte">byte</glossary> after the character, regardless of <function tag="platform">platform</function>.</p><p></p><p>The ability to convert language-specific encodings into Unicode text was added in version 2.0. In previous versions, the <b>uniEncode</b> <control_st tag="function">function</control_st> simply added a <constant tag="null">null</constant> <glossary tag="byte">byte</glossary>.</p></comments>
	</description>
</doc>