Operator Next (Iteration)

Determines if a KeyPgFornextFor...Next loop should be terminated

Syntax
	{ KeyPgTypeType | KeyPgClassClass | KeyPgUnionUnion } typename
		KeyPgDeclareDeclare KeyPgOperatorOperator Next ( [ KeyPgByrefByRef | KeyPgByvalByVal ] cond KeyPgAsAs typename ) KeyPgAsAs 
		KeyPgIntegerInteger
		KeyPgDeclareDeclare KeyPgOperatorOperator Next ( [ KeyPgByrefByRef | KeyPgByvalByVal ] cond KeyPgAsAs typename, [ KeyPgByrefByRef | 
		KeyPgByvalByVal ] stp KeyPgAsAs typename ) KeyPgAsAs KeyPgIntegerInteger
		...
	End { KeyPgTypeType | KeyPgClassClass | KeyPgUnionUnion }

Usage
	KeyPgFornextFor iterator [ As typename ] = start_value To end_value [ KeyPgFornextStep 
	step_value ]
		[ ...statements... ]
	KeyPgFornextNext

Parameters
(including arguments)
	typename
		name of the KeyPgTypeType, KeyPgClassClass, or KeyPgUnionUnion
	cond, end_value
		a typename object used as a loop-terminating value
	stp, step_value
		a typename object used as an incremental value
	iterator
		a typename object used as an iterator
	start_value
		a typename object used to copy construct or assign to the iterator 
		initially

Description
	KeyPgOpForOperator For, Operator Next and KeyPgOpStepOperator Step can be overloaded in 
	user-defined type definitions to allow objects of that type to be used 
	as iterators and step values in KeyPgFornextFor...Next loops.
	As all non-static member procedures, they have passed a hidden KeyPgThisThis 
	parameter that allows to access by reference to the iterator object in 
	the code body of the 3 operators.

	Operator Next is called every time the iterator object needs to be 
	checked against the end value. This happens immediately after the call 
	to its KeyPgOpForOperator For, and immediately after any calls to its KeyPgOpStepOperator Step
	. Operator Next should return zero (0) if the loop should be terminated, 
	or non-zero if the loop should continue iterating. The first time 
	Operator Next is called, no statements in the KeyPgFornextFor...Next body, if any, 
	have been executed yet.

	The first version of Operator Next is used if no step value is given in 
	the KeyPgFornextFor...Next statement. If a step value is given, the second version 
	is used and is passed the step value because testing for iterating end 
	may depend on it.

	Advanced usage
		The above description seems to imply that the 3 arguments start_value
		, end_value, and step_value must be of the same type as the iterator 
		(this is the more obvious use), but it is not quite true:
			- The start_value, end_value, and step_value arguments can be of 
			any type (of different types among themselves and also of 
			different types from the one of the iterator).
			- The only constraint is that the iterator could be constructed 
			(in case of local iterator) or assigned (in case of global 
			iterator) from the start_value argument (because the iterator is 
			implicitly constructed or assigned under the hood).
			- Similarly the other parameters end_value, and step_value must be 
			able to be converted into objects of the same type as the iterator
			.

Example
	See the KeyPgOpStepOperator Step examples.

Dialect Differences
	* Only available in the CompilerOptlang-lang fb dialect.

See also
	* KeyPgOpForOperator For
	* KeyPgOpStepOperator Step
	* KeyPgFornextFor...Next

