{{fbdoc item="title" value="Operator Step (Iteration)"}}----
Increments the iterator of a ##[[KeyPgFornext|For...Next]]## loop

{{fbdoc item="syntax"}}##
	{ [[KeyPgType|Type]] | [[KeyPgClass|Class]] | [[KeyPgUnion|Union]] } //typename//
		[[KeyPgDeclare|declare]] [[KeyPgOperator|operator]] **Step** ()
		[[KeyPgDeclare|declare]] [[KeyPgOperator|operator]] **Step** ( [ [[KeyPgByref|byref]] | [[KeyPgByval|byval]] ] //stp// [[KeyPgAs|as]] //typename// )
		//...//
	End { [[KeyPgType|Type]] | [[KeyPgClass|Class]] | [[KeyPgUnion|Union]] }
##
{{fbdoc item="usage"}}##
	[[KeyPgFornext|For]] //iterator// [ As //typename// ] = //start_value// To //end_value// [ [[KeyPgFornext|Step]] //step_value// ]
		[// ...statements... //]
	[[KeyPgFornext|Next]]
##
{{fbdoc item="param"}}
**##(including arguments)##**
	##//typename//##
		name of the ##[[KeyPgType|Type]]##, ##[[KeyPgClass|Class]]##, or ##[[KeyPgUnion|Union]]##
	##//stp//##, ##//step_value//##
		a ##//typename//## object used as an incremental value
	##//iterator//##
		a ##//typename//## object used as an iterator
	##//end_value//##
		a ##//typename//## object used as a loop-terminating value
	##//start_value//##
		a ##//typename//## object used to copy construct or assign to the iterator initially

{{fbdoc item="desc"}}
	##[[KeyPgOpFor|Operator For]]##, ##[[KeyPgOpNext|Operator Next]]## and ##**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 Step**## is called to increment the iterator object immediately after all statements in the ##[[KeyPgFornext|For...Next]]## body are executed, if any.
	
	The first version of ##**Operator Step**## 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 to increment the iterator object.
	
	__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//##.

{{fbdoc item="ex"}}
	{{fbdoc item="filename" value="examples/manual/udt/step.bas"}}%%(freebasic)
'' Example Type
Type T
  '' value is set by the constructor
  value As Double
  Declare Constructor( ByVal x As Double = 0 )

  Declare Operator For( ByRef stp As T )
  Declare Operator Step( ByRef stp As T )
  Declare Operator Next( ByRef cond As T, ByRef stp As T ) As Integer
End Type

Constructor T ( ByVal x As Double )
  print "T iterator constructed with value " & x
  value = x
End Constructor

Operator T.for( ByRef stp As T )
End Operator

Operator T.step( ByRef stp As T )
  print " incremented by " & stp.value & " in step."
  value += stp.value
End Operator

Operator T.next( ByRef cond As T, ByRef stp As T ) As Integer
  '' iterator's moving from a high value to a low value (step >= 0)
  If( stp.value < 0 ) Then
	return( value >= cond.value )
  Else
  '' iterator's moving from a low value to a high value (step < 0)
	return( value <= cond.value )
  End If
End Operator

'' Example Usage. It looks like we are working with numbers, but the iterators
'' have overloaded constructors. The 10, 1, and -1 are all of type T.
For i As T = 10 To 1 Step -1
  Print i.value;
Next i
	%%
	A more practical example demonstrating file iteration based on [[http://www.freebasic.net/forum/viewtopic.php?p=83564|cha0s' file iteration class]]:
	{{fbdoc item="filename" value="examples/manual/udt/stepFileIteration.bas"}}%%(freebasic)
'' a class which iterates through files
type FileIter
	as string pathName, fileName
	declare constructor( byref pathName as string )

	declare operator for()
	declare operator step()
	declare operator next( byref endCond as FileIter) as integer
end type

Constructor FileIter( Byref pathName As String )   
	this.pathName = pathName
End Constructor

Operator FileIter.for( )   
	fileName = dir(pathName & "/*.*")   
End Operator

Operator FileIter.step( )   
	fileName = dir("")
End Operator

Operator FileIter.next( Byref endCond As FileIter ) As Integer
	Return(fileName <> endCond.pathName)   
	'' the c'tor sets the path name and so we check against that
End Operator

'' example code
'' change it to any directory
For i As FileIter = "./" To ""
	print i.fileName
Next
	%%
	Another example working with strings:
	{{fbdoc item="filename" value="examples/manual/udt/step-char-iterator.bas"}}%%(freebasic)
type CharIterator
	'' used to build a step var
	declare constructor( byval r as zstring ptr )
	
	'' implicit step versions
	declare operator for ( )
	declare operator step( )
	declare operator next( byref end_cond as CharIterator ) as integer
	
	'' explicit step versions
	declare operator for ( byref step_var as CharIterator )
	declare operator step( byref step_var as CharIterator )
	declare operator next( byref end_cond as CharIterator, byref step_var as CharIterator ) as integer
	
	'' give the current "value"    
	declare operator cast( ) as string
	
	private:	
		'' data
		value as string
		
		'' This member isn't necessary - we could use
		'' the step variable on each iteration - 
		'' but we choose this method, since we have
		'' to compare strings otherwise. See below.
		is_up as integer
end type

constructor CharIterator( byval r as zstring ptr )
	value = *r
end constructor

operator CharIterator.cast( ) as string
	operator = value
end operator

'' implicit step versions
'' 
'' In this example, we interpret implicit step
'' to always mean 'up'
operator CharIterator.for( )
	print "implicit step"
end operator

operator CharIterator.step( )
	value[0] += 1
end operator 

operator CharIterator.next( byref end_cond as CharIterator ) as integer
	return this.value <= end_cond.value
end operator

'' explicit step versions
'' 
'' In this example, we calculate the direction
'' at FOR, but since the step var is passed to
'' each operator, we have the choice to also calculate
'' it "on-the-fly". For strings such as this, repeated comparison
'' may penalize, but if you're working with simpler types,
'' then you may prefer to avoid the overhead of 
'' an 'is_up' variable.
operator CharIterator.for( byref step_var as CharIterator )
	print "explicit step"
	is_up = (step_var.value = "up")
end operator

operator CharIterator.step( byref step_var as CharIterator )
	if( is_up ) then
		value[0] += 1
	else
		value[0] -= 1
	end if
end operator 

operator CharIterator.next( byref end_cond as CharIterator, byref step_var as CharIterator ) as integer
	if( this.is_up ) then
		return this.value <= end_cond.value
	else
		return this.value >= end_cond.value
	end if
end operator

for i as CharIterator = "a" to "z"
	print i; " ";
next
print "done"

for i as CharIterator = "a" to "z" step "up"
	print i; " ";
next
print "done"

for i as CharIterator = "z" to "a" step "down"
	print i; " ";
next
print "done"

for i as CharIterator = "z" to "a" step "up"
	print i; " ";
next
print "done"
	%%
	Iterating with fractions:
	{{fbdoc item="filename" value="examples/manual/udt/step-fraction-iterator.bas"}}%%(freebasic)
Type fraction
	'' Used to build a step var
	Declare Constructor( ByVal n As Integer, ByVal d As Integer )

	'' Implicit step versions
	Declare Operator For ( )
	Declare Operator Step( )
	Declare Operator Next( ByRef end_cond As fraction ) As Integer

	'' Explicit step versions
	Declare Operator For ( ByRef step_var As fraction )
	Declare Operator Step( ByRef step_var As fraction )
	Declare Operator Next( ByRef end_cond As fraction, ByRef step_var As fraction ) As Integer

	'' Give the current "value"    
	Declare Operator Cast( ) As Double
	Declare Operator Cast( ) As String

	Private:
		As Integer num, den
End Type

Constructor fraction( ByVal n As Integer, ByVal d As Integer )
	This.num = n : This.den = d
End Constructor

Operator fraction.Cast( ) As Double
	Operator = num / den
End Operator

Operator fraction.Cast( ) As String
	Operator = num & "/" & den
End Operator

'' Some fraction functions
Function gcd( ByVal n As Integer, ByVal m As Integer ) As Integer
	Dim As Integer t
		While m <> 0
			t = m
			m = n Mod m
			n = t
		Wend
	Return n
End Function

Function lcd( ByVal n As Integer, ByVal m As Integer ) As Integer
	Return (n * m) / gcd( n, m )
End Function

''
'' Implicit step versions
''
'' In this example, we interpret implicit step
'' to mean 1
''
Operator fraction.For( )
	Print "implicit step"
End Operator

Operator fraction.Step( )
	Dim As Integer lowest = lcd( This.den, 1 )
	Dim As Double mult_factor = This.den / lowest
	Dim As fraction step_temp = fraction( 1, 1 )
   
	This.num *= mult_factor
	This.den *= mult_factor
   
	step_temp.num *= lowest
	step_temp.den *= lowest
   
	This.num += step_temp.num
End Operator

Operator fraction.Next( ByRef end_cond As fraction ) As Integer
	Return This <= end_cond
End Operator

''
'' Explicit step versions
''
Operator fraction.For( ByRef step_var As fraction )
	Print "explicit step"
End Operator

Operator fraction.Step( ByRef step_var As fraction )
	Dim As Integer lowest = lcd( This.den, step_var.den )
	Dim As Double mult_factor = This.den / lowest
	Dim As fraction step_temp = step_var

	This.num *= mult_factor
	This.den *= mult_factor

	mult_factor = step_temp.den / lowest

	step_temp.num *= mult_factor
	step_temp.den *= mult_factor

	This.num += step_temp.num
End Operator

Operator fraction.Next( ByRef end_cond As fraction, ByRef step_var As fraction ) As Integer
	If(( step_var.num < 0 ) Or ( step_var.den < 0 ) ) Then
		Return This >= end_cond
	Else
		Return This <= end_cond
	End If
End Operator

For i As fraction = fraction(1,1) To fraction(4,1)
	Print i; " ";
Next
Print "done"

For i As fraction = fraction(1,4) To fraction(1,1) Step fraction(1,4)
	Print i; " ";
Next
Print "done"

For i As fraction = fraction(4,4) To fraction(1,4) Step fraction(-1,4)
	Print i; " ";
Next
Print "done"

For i As fraction = fraction(4,4) To fraction(1,4)
	Print i; " ";
Next
Print "done"
	%%
{{fbdoc item="lang"}}
	- Only available in the //[[CompilerOptlang|-lang fb]]// dialect.

{{fbdoc item="see"}}
	- ##[[KeyPgOpFor|Operator For]]##
	- ##[[KeyPgOpNext|Operator Next]]##
	- ##[[KeyPgFornext|For...Next]]##

{{fbdoc item="back" value="CatPgOpIterating|Iterating Operators"}}{{fbdoc item="back" value="CatPgOperators|Operators"}}