while(condition){}

---

The operator while(condition){…} performs an action repeatedly until the condition expression evaluates as false. Put another way, the code in the curly brackets will continue to be run again and again, until condition expression evaluates as false. This operator addresses the scenario where:

- it is known a task needs to be done multiple times but,

_ the exact number of times to repeat the task is not known

Using while() it is possible to define the a test (condition) to ascertain when the task is done and the repeating/looping action can stop.

For those less used to coding, consider a generalised analogy—the task of filling a bucket with water filling a bucket. Before adding anything to the bucket we might sensibly ask if the bucket is full and only if it is not, do we add another scoop of water. But if the bucket is full, we stop adding water. It can be summarised thus:

• Is the bucket full?
  • No? We add another scoop of water and start over with the original check (i.e. continue the loop).
  • Yes? We're done—exit and finish.

Examples

Consider the case where it is desired to process a note's $Text, of unknown size, one sentence at a time. Thus (code commenting is for explanation only, and is not needed in actual code):

	// make a variable holding $Text, so $Text itself is not affected
	var:str vText = $Text;
	// start the loop using vText
	while(vText!=""){
		// get the first sentence in vText
		var:string vStr = $Text.sentence(0);
		// pass that sentence to function fProcessText() to do whatever task with it ...
		fProcessText(vStr);
		// remove the sentence vStr from vText *before* the loop runs again
		// so that vStr is different in the next loop, i.e. each sentence is used only once
		vText = vText.substr(vStr.size).trim();
	};

This will read $Text and process it to call the user-defined function fProcessText() passing it one sentence at a time. Each loop removes the just-processed sentence, so the text considered in the next loop is one sentence shorter, until eventually vText is empty at which point the while() operator completes and the next action after it, if any, is read.

A programmer might write the same as above more tersely:

var vt=$Text;while(vt){var:string s=vt.sentence;vt=vt.substr(s.size).trim(); process(s);} 

But, importantly, both do the same thing and the different code has no effect on Tinderbox performance. As long as the code is valid, users are free to choose their style.

Prior to this, it would be necessary to first count the number of discrete sentences and store that in a variable, then make a list of discrete sentences, then iterate this list using a loop counter and checking in each loop to see if the counter figure was below the stored count before taking any per-item action; while() wraps all that up into a simple operator.

Preventing against infinite loops

An infinite loop occurs when condition always remains false and thus the code loop never stops running. To guard against this unintended scenario while() loops are limited to 10,000 iterations, i.e. if the loop has run 10,000 time it automatically stops regardless of the state of condition.