SBTCVM's SSTNPL, Part 3: iterators
Tags: sbtcvm, ternary, sstnpl, tutorial
Published: 2018-10-22 19:07:23

---
title: SBTCVM's SSTNPL, Part 3: iterators
published: true
description: Part 3 of a tutorial series on SBTCVMs SSTNPL programming languages. Iterators.
tags: sbtcvm,ternary,sstnpl,tutorial
---

Welcome back to part 3 of my tutorial series on SSTNPL, a programming language for the 9-trit balanced ternary Virtual machine known as SBTCVM. In [part 1](https://dev.to/thomasthespacefox/sbtcvms-sstnpl-part-1-basics-3a7h), we discussed basic menus and did some basic variable setting. While in [part 2](https://dev.to/thomasthespacefox/sbtcvms-sstnpl-part-2-cards-on-the-table-f83) we looked at SSTNPL's 2D, array-like table system.

In this part, we will take a look at SSTNPL's iterators and how to use them to iterate over tables.

# Getting Started

like before, copy the tutorial_example_3.stnp file into your VMUSER directory located where you installed SBTCVM.



{% gist https://gist.github.com/ThomasTheSpaceFox/ff64aa13bf1f922111b34ce5b981c835 %}


# basic iterators
the basic iterators come in 2 variants, each with 4 arguments:

- **itval:** a variable name to be newly created. use this to get iterator 'state'
- **sub:** a subroutine label. You need to put the code you want to iterate with in a subroutine, and specify it here.
- **start:** The starting value of the iteration. Can be variable or literal 
- **end:** The ending value of the iteration. Can be variable or literal 

```
uiter itval,sub,start,end
diter itval,sub,start,end
```

So what does `uiter` and `diter` do? Well, `uiter` iterates **U**p from `start` to `end`, while `diter` iterates **D**own from `start` to `end`

# double iterators
Double iterators, are just that, 2 iterators in 1. For the sake of this tutorial, we'll call them the X iterator and the Y iterator. Whats the point of double iterators? Well, you will see later in this tutorial.
the double iterators also come in 2 variants, however, they have 7 arguments:

```
u2iter itvalx,itvaly,sub,startx,endx,starty,endy
d2iter itvalx,itvaly,sub,startx,endx,starty,endy
```

- **itvalx:** a variable name to be newly created. Use this to get the X iterator state.
- **itvaly:** a variable name to be newly created. Use this to get the Y iterator state.
- sub: a subroutine label. You need to put the code you want to iterate with in a subroutine, and specify it here.
- **startx:** starting value of the X iterator. Can be variable or literal 
- **starty:** starting value of the Y iterator. Can be variable or literal 
- **endx:** ending value of the X iterator. Can be variable or literal 
- **endy:** ending value of the Y iterator. Can be variable or literal 


**u2iter** counts from `startx` UP TO `endx` for each number of `starty` UP TO `endy`
and needs both ENDs to be GREATER than their respective STARTs

**d2iter** counts from `startx` DOWN TO `endx` for each number of `starty` DOWN TO `endy` and needs both ENDs to be LESS than their respective STARTs

Basically u2iter and d2iter run the X iterator for each iteration of the Y iterator.

# iterating over rows
Now that we know how to use SSTNPL's iterators in general, lets look how they apply to tables. For starters, lets iterate over the first row of our table 'sam'.

All we really need to do, is iterate over the X position argument of `tabr`, while having the y position argument pointing to the desired row.


```
uiter itval,getat1,@0,@2

label getat1
tabr sam,itval,@0
set cb
chardump cb
return
```

remember: table X and Y indexes start at 0, so our iterator range is 0-2

# iterating over columns
Exactly the same as rows, but we iterate over the Y position argument of `tabr` while the X position argument points to the desired column.


```
uiter itval,getat1B,@0,@2
#
label getat1B
tabr sam,@0,itval
set cb
chardump cb
return
```


# iterating over the whole thing
You see where this is going, don't you? Yes, all we need to do to iterate over the whole table is iterate over both the X and Y position arguments of `tabr`


```
u2iter itvalx,itvaly,getat2,@0,@2,@0,@2
#
label getat2
tabr sam,itvalx,itvaly
set cb
chardump cb
return
```


Simple eh? oh, and if you want to iterate over arbitrary sections of the table, say just columns 2 and 3:


```
u2iter itvalx,itvaly,getat2,@1,@2,@0,@2
#
label getat2
tabr sam,itvalx,itvaly
set cb
chardump cb
return
```


Now do you see the point of the double iterators? i sure hope so.

# Compiling & running

just as in part 1:

compile: ./stnpcom.py tutorial_example_3

run: /SBTCVM_G2_9.py tutorial_example_3

# Conclusion

Well, i hope you found these 3 tutorials helpful and informative. Just don't be surprised to see more SSTNPL tutorials in the future, as SSTNPL gains more features.