<doc>
	<legacy_id>1135</legacy_id>
	<name>repeat</name>
	<type>control structure</type>

	<syntax>
		<example>repeat <i>loopForm statementList</i> end repeat</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary><glossary tag="execute">Executes</glossary> a set of <glossary tag="statement">statements</glossary> repeatedly.</summary>

	<examples>
<example><p>-- To create a numbered set of variables with similar names</p><p>-- eg myVar1, myVar2, ... myVar20, you can use a repeat loop</p><p>-- together with concatenation in the following form. Note that</p><p>-- this structure will only work with variable checking turned off.</p><p>-- If you prefer to declare your variables then an array is the</p><p>-- recommended way of doing this.</p><p>local tPrefix = "myVar"</p><p>local tVarCount = 20</p><p>repeat with tVarNum = 1 to 20</p><p>  put tPrefix  x into tVarName</p><p>  do "put empty into "  tVarNameend repeat</p></example>
<example>-- Loops with using 0 are validrepeat with tVarNum = 0 to 5 put tVarNum  comma after tTextend repeatput tTexttText = 0,1,2,3,4,5,</example>
<example><p>-- Loops can also make use of negative numbersrepeat with tVarNum = 3 down to -5 put tVarNum  comma after tTextend repeatput tTexttText = 3,2,1,0,-1,-2,-3,-4,-5,</p></example>
	</examples>

	<history>
		<introduced version="1.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="7.0">New chunk types added.</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>Writing LiveCode</category>
	</classification>

	<references>
		<command tag="wait">wait command</command>
		<keyword tag="while">while keyword</keyword>
		<keyword tag="for">for keyword</keyword>
		<keyword tag="until">until keyword</keyword>
		<keyword tag="forever">forever keyword</keyword>
		<keyword tag="element">element keyword</keyword>
		<keyword tag="end repeat">end repeat keyword</keyword>
		<keyword tag="each">each keyword</keyword>
		<control_st tag="next repeat">next repeat control_st</control_st>
	</references>

	<description>
	<overview>Use the <b>repeat</b> <glossary tag="control structure">control structure</glossary> to perform the same set of actions for each member of a set: for example, for each <keyword tag="card">card</keyword> in a <object tag="stack">stack</object>, or each <keyword tag="line">line</keyword> in a <glossary tag="variable">variable</glossary>.</overview>

		<parameters>
<parameter>
<name>loopForm</name>
<description>The loopForm is one of the following forms:</description> 
<options title="">
<option>
<item>forever</item>
<description></description>
</option>
<option>
<item>until condition</item>
<description></description>
</option>
<option>
<item>while condition</item>
<description></description>
</option>
<option>
<item>[for] number times</item>
<description></description>
</option>
<option>
<item>with counter = startValue [to | down to] endValue [step increment]</item>
<description></description>
</option>
<option>
<item>for each chunkType labelVariable in container</item>
<description></description>
</option>
<option>
<item> for each element labelVariable in array</item>
<description></description>
</option>
<option>
<item>for each key labelVariable in array</item>
<description></description>
</option>
</options>
<parameter>
<name>condition</name>
<description>Any expression that evaluates to true or false.</description> 
</parameter>
<parameter>
<name>number, startValue, endValue, and increment</name>
<description>Numbers or expressions that evaluate to numbers.</description> 
</parameter>
<parameter>
<name>counter or labelVariable</name>
<description>A legal variable name.</description> 
</parameter>
<parameter>
<name>chunkType</name>
<description>One of byte, codeunit, codepoint, character (or char), token, trueword, word (or segment), item, sentence, paragraph or line.</description> 
</parameter>
<parameter>
<name>container</name>
<description>Any existing container.</description> 
</parameter>
<parameter>
<name>array</name>
<description>Any existing container that contains an array of values.</description> 
</parameter>
<parameter>
<name>statementList</name>
<description>One or more LiveCode statements, and can also include if, switch, try, or repeat control structures.</description> 
</parameter>		</parameters>

	<value></value>
	<comments><b>Form:</b><p>The <b>repeat</b> <glossary tag="control structure">control structure</glossary> always begins with the word "repeat".</p><p>The last line of a <b>repeat</b> <glossary tag="control structure">control structure</glossary> is the <keyword tag="end repeat">end repeat</keyword> <glossary tag="keyword">keyword</glossary>.</p><p></p><p>How many times the <i>statementList</i> is <glossary tag="execute">executed</glossary> depends on the <i>loopForm</i> you use.</p><p></p><p><b>Forever</b></p><p>The forever form continues repeating the statements in the statementList until an exit, exit repeat, pass, or return statement is executed. Usually, one of these control structures is included in an if control structure within the statementList.</p><p></p><p>Use the forever form if you want to test a condition at the bottom of the loop, after the statementList is executed. In the following example, the go command is executed at least once, since the mouseClick is not checked until after the go command:</p><p></p><p>  repeat forever</p><p>    go next card</p><p>    if the mouseClick then exit repeat -- user clicked</p><p>  end repeat</p><p></p><p>If no loopForm is specified, the forever form is used.</p><p></p><p><b>Until</b></p><p>The until condition and while condition forms repeat the statementList as long as the condition is false or as long as it is true, respectively. LiveCode re-evaluates the condition before each iteration.</p><p></p><p>Use the until condition or while condition form if you want to test a condition at the top of the loop, before the statements are executed. This example scrolls through the cards until the user clicks the mouse:</p><p>  repeat until the mouseClick</p><p>    go next</p><p>    wait for 100 milliseconds</p><p>  end repeat</p><p></p><p><b>For number times</b></p><p>The for number times form repeats the statementList for the specified number of times.</p><p>The number is evaluated when the loop is first entered, and is not re-evaluated as a result of any actions performed in the statementList. For example, if the number is the number of cards, and the statementList contains a create card command, the loop is executed as many times as there were cards when the loop began, even though the current number of cards is changing with each iteration through the loop.</p><p></p><p>If the number is not an integer, it is rounded to the nearest integer, using the same rules as the round function.</p><p>Use the for number times form if you want to execute the statementList a fixed number of times. The following simple example beeps three times:</p><p></p><p>  repeat for 3 times</p><p>    beep</p><p>  end repeat</p><p></p><p><b>With counter</b></p><p>The with counter = startValue to endValue form and the with counter = startValue down to endValue form set the counter to the startValue at the beginning of the loop, and increase (or decrease, if you're using the down to form) the countVariable by 1 each time through the loop. When the counter is greater than or equal to the endValue, (less than or equal to, if you're using the down to form), the loop performs its final iteration and then ends.</p><p></p><p>If you specify an increment, the increment is added to the counter each time through the loop, rather than the counter being increased by 1. (The increment is not treated as an absolute value: if you're using the down to form, the increment must be negative.)</p><p></p><p>As with the for number times form described above, the startValue and endValue are evaluated when the loop is first entered, and are not re-evaluated as a result of any actions performed in the statementList.</p><p></p><p>Use one of these forms if you want to perform an action on each member of a set, and you need to refer to the member by number within the statementList. The following example loops through all the controls on the current card. The counter x is 1 during the first iteration, 2 during the second, and so on:</p><p></p><p>  repeat with x = 1 to the number of controls</p><p>    show control x</p><p>  end repeat</p><p></p><p>The following example loops backwards through a set of lines. The counter myLine is 20 during the first iteration, 18 during the second, and so on:</p><p></p><p>  repeat with myLine = 20 down to 1 step -2</p><p>    put myLine</p><p>  end repeat</p><p></p><p></p><note> It is possible to change the counter variable in a statement in the loop. However, doing this is not recommended, because it makes the loop logic difficult to follow:</note><p></p><p>  repeat with x = 1 to 20 -- this loop actually repeats ten times</p><p>    answer x</p><p>    add 1 to x -- not recommended</p><p>  end repeat</p><p></p><p><b>For each</b></p><p>The for each chunkType labelVariable in container form sets the labelVariable to the first chunk of the specified chunkType in the container at the beginning of the loop, then sets it to the next chunk for each iteration. For example, if the chunkType is word, the labelVariable is set to the next word in the container for each iteration of the loop.</p><p></p><p>Use the for each form if you want to perform an action on each chunk in a container. This form is much faster than the with countVariable = startValue to endValue form when looping through the chunks of a container. The following example changes a return-delimited list to a comma-delimited list:</p><p></p><p>  repeat for each line thisLine in myList</p><p>    put thisLine  comma after newList</p><p>  end repeat</p><p>  delete the last char of newList</p><p></p><p>The for each element labelVariable in array form sets the labelVariable to the first element in the array at the beginning of the loop, then sets it to the next element for each iteration.</p><p></p><p>Use the for each form if you want to perform an action on each element in an array. The following example gets only the multi-word entries in an array of phrases:</p><p></p><p>  repeat for each element thisIndexTerm in listOfTerms</p><p>    if the number of words in thisIndexTerm  1 then</p><p>      put thisIndexTerm  return after multiWordTerms</p><p>    end if</p><p>  end repeat</p><p></p><p></p><important>In any of the for each loops, you should not change the labelVariable or container in a statement inside the loop. Doing so will not cause a script error, but will almost certainly produce unexpected results.</important><p></p><p></p><note> The repeat control structure is implemented internally as a command and appears in the commandNames.</note><p></p><p></p><change><p>The ability to specify an increment for the repeat with counter = startValue to endValue form was added in version 2.0. In previous versions, this form of the repeat control structure always incremented or decremented the counter by 1 each time through the loop.</change><p></p><p>The ability to iterate through the keys of an array using repeat for each key was added in version 2.7.2</p></comments>
	</description>
</doc>