<doc>
	<legacy_id>1764</legacy_id>
	<name>split</name>
	<type>command</type>

	<syntax>
		<example>split <i>variable</i> {by | using | with} <i>primaryDelimiter</i> [and <i>secondaryDelimiter</i>]</example>
		<example>split <i>variable</i> {by | using | with} <i>primaryDelimiter</i> as set</example>
		<example>split <i>variable</i> {by | using | with} {row | column}</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Transforms a list into an <glossary tag="array">array</glossary>. </summary>

	<examples>
<example><p>put "one,two,three" into tData</p><p>split tData by comma</p><p>// RESULT</p><p>// tData[1] = "one"</p><p>// tData[2] = "two"</p><p>// tData[3] = "three"</p></example>
<example><p>put "one,two,three" into line 1 of tData</p><p>put "ben,fraser,elanor" into line 2 of tData</p><p>put "apple,orange,grape" into line 3 of tData</p><p>set the rowdel to comma</p><p>split tData by column</p><p>// RESULT</p><p>// tData[1] = </p><p>// one</p><p>// two</p><p>// three</p><p>// tData[2] = </p><p>// ben</p><p>// fraser</p><p>// elanor</p><p>// tData[3] = </p><p>// apple</p><p>// orange</p><p>// grape</p></example>
	</examples>

	<history>
		<introduced version="1.1">Added. </introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="2.8.1">2.8.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>
		<category>Values &amp; Properties</category>
	</classification>

	<references>
		<function tag="extents">extents Function</function>
		<function tag="keys">keys Function</function>
		<command tag="combine">combine Command</command>
		<command tag="intersect">intersect Command</command>
		<property tag="columnDelimiter">columnDelimiter Property</property>
		<property tag="rowDelimiter">rowDelimiter Property</property>
		<keyword tag="[]">[] Keyword</keyword>
		<keyword tag="using">using Keyword</keyword>
	</references>

	<description>
	<overview>Use the <b>split</b> command to place a list in an array so you can easily address each part of the list.</overview>

		<parameters>
			<parameter>
			<name>variable</name>
			<description>Any variable that is not an array</description>
			</parameter>  
			
			<parameter>
			<name>primaryDelimiter</name>
			<description>A character or an expression that evaluates to a character.</description>
			</parameter>  
			
			<parameter>
			<name>secondaryDelimiter</name>
			<description>A character or an expression that evaluates to a character.</description>
			</parameter>  
		</parameters>

	<value></value>
	<comments>
		<p>The <b>split</b> command separates the parts of the variable into elements of an array. After the command is finished executing, the variable specified is an array.</p>
		<p></p>
		<p>If the first form of the <b>split</b> command is used, the parts that become elements are defined by the <i>primaryDelimiter</i>. For example, if the <i>primaryDelimiter</i> is <constant tag="return">return</constant>, each line of the variable becomes an element in the resulting array.</p>
		<p></p>
		<p>If you don't specify a <i>secondaryDelimiter</i>, then a simple numeric array is created, with each key being a number, starting with 1.</p>
		<p></p>
		<p>If you specify a <i>secondaryDelimiter</i>, the key for each element is the first portion of each part of the variable, separated from the element's content by the <i>secondaryDelimiter</i>. For example, if the <i>primaryDelimiter</i> is <constant tag="return">return</constant> and the <i>secondaryDelimiter</i> is <constant tag="space">space</constant>, the remainder of each line of the variable is placed in an array element whose key is the first word of the line.</p>
		<p></p>
		<p>If you use the as set form the <b>split</b> command converts the passed variable to an array with the keys being equal to the original list and the values being true.</p>
		<p></p>
		<p>For example, the following statements create an array:</p>
		<p></p>
		<p>put "A apple,B bottle,C cradle" into myVariable</p>
		<p>split myVariable by comma and space</p>
		<p></p>
		<p>The resulting array looks like this:</p>
		<p></p>
		<p>KEY	VALUE</p>
		<p>	A	apple</p>
		<p>	B	bottle</p>
		<p>	C	cradle</p>
		<p></p>
		<important>Using the <b>split</b> command can discard data if any of the keys in the original variable are duplicated. If more than one part of the variable delimited by the <i>primaryDelimiter</i> has the same first portion delimited by the <i>secondaryDelimiter</i>, only the element corresponding to the first part is created. (For example, if you are splitting a variable by <constant tag="return">return</constant> and <constant tag="space">space</constant>, and two lines happen to have the same first word, only one of the lines is retained in the array.) Only one element is created for each unique key.</important>
		<p></p>
		<p>If the second form of the <b>split</b> command is used, the string is split into elements of an array where each element using the <property tag="rowDelimiter">rowDelimiter</property> or <property tag="columnDelimiter">columnDelimiter</property>, where each element of the resulting array is a row or column of the string respectively.</p>
		<p></p>
		<p>Splitting a string by row converts the string into an array where each element of the array corresponds to a row in the string separated by the <property tag="rowDelimiter">rowDelimiter</property>.</p>
		<p></p>
		<p>Splitting a string by column converts the string into an array where each element of the array corresponds to a column in the string separated by the <property tag="columnDelimiter">columnDelimiter</property>.</p>
		</comments>
	</description>
</doc>