manual:chapter5:basics

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
manual:chapter5:basics [2017/05/05 07:47]
pier4r
manual:chapter5:basics [2021/09/15 10:32]
claudio
Line 8: Line 8:
 A typical sequence of a program is to place some objects on the stack, do one or more operations and leave the result in the stack. For example: A typical sequence of a program is to place some objects on the stack, do one or more operations and leave the result in the stack. For example:
  
-<code>« 1 2 + »</code>+<code> 
 +« 
 +  1 2 + 
 +»</code>
  
 Let's analyze the program above: Let's analyze the program above:
Line 18: Line 21:
 And that's the most basic RPL program. Operators and functions always take some values from the stack and leave some results on it. A program may include multiple operations: And that's the most basic RPL program. Operators and functions always take some values from the stack and leave some results on it. A program may include multiple operations:
  
-<code>« 1 2 + 2 / »</code>+<code>« 
 +  1 2 + 
 +  2 / 
 +»</code>
  
 The program above starts identical to the previous example, and after the + operator is executed, the resulting number 3 is left on the stack. As the program continues, the number 2 is put on level 1, relegating the number 3 to level 2. The division operator takes 2 numbers and performs the division of the number in level 2 divided by the number in level 1. In this case, level 2 had a 3 and level 1 had a 2, therefore the number 1.5 will be left on the stack as a result. The program above starts identical to the previous example, and after the + operator is executed, the resulting number 3 is left on the stack. As the program continues, the number 2 is put on level 1, relegating the number 3 to level 2. The division operator takes 2 numbers and performs the division of the number in level 2 divided by the number in level 1. In this case, level 2 had a 3 and level 1 had a 2, therefore the number 1.5 will be left on the stack as a result.
Line 24: Line 30:
 ---- ----
  
-==== Operators and Commands ====+==== Operators, Functions and Commands ==== 
 + 
 +In the examples above we showed how + and / would take some objects from the stack, operate on them and place the result in the stack. This is the basic operation of all operators and commands in RPL. All commands, functions and operators take some (or none) arguments from the stack, and leave some (or none) results in it. There are hundreds of RPL keywords, all based on the same principle of taking and leaving objects on the stack. Future chapters will describe each keyword in depth, for now only a few ones will be introduced that define the basic core of the RPL language.  
 + 
 +Fundamentally all the keywords can be divided into 4 classes: commands, operators, functions and analytic functions. Difference between classes isn't in the effect they have on the stack (as said above, almost any keyword manipulates the stack) rather in behavior and scope. 
 + 
 +=== Commands === 
 + 
 +Commands perform actions. They are used to control program flow (''IF'', ''WHILE'', ''FOR''), manipulate objects (''PUT'', ''HEAD'') or variables (''STO+'', ''QUOTEID'') and setting the system (''SETLOCALE'', ''ASNKEYS''). 
 + 
 +=== Operators === 
 + 
 +Operators manipulate objects, returning results. Usually these objects are [[manual:chapter3:reals|real numbers]], but they can also be [[manual:chapter3:angles|angles]], [[manual:chapter3:matrix|matrices]] or [[manual:chapter3:symbolic|symbolic expressions]]. 
 + 
 +Most operators are //binary// i.e. they need two arguments and when used within symbolic expressions are distinguished by the fact that they adopt the //infix// notation. There also are a few //unary// operators adopting the //prefix// notation in symbolics (unary ''+'' and ''-'') and also one operator adopting //postfix// notation (''!'', the factorial operator). 
 + 
 +The basic arithmetic operators work as expected (''+'' and ''/'' were already introduced), taking objects from the stack and leaving the result of the operation. Test operators (''>'', ''<'', ''≤'', ''≥'', ''=='' ) take two objects from the stack, perform a comparison and leave a 1 on the stack if the test was true, and a 0 if the test failed. The true condition is always represented with the number 1, while the false condition is always represented with the number 0. 
 + 
 +=== Functions === 
 + 
 +Functions, like operators, manipulate objects and return results. They can be inserted into symbolic expressions, adopting a //functional// notation (i.e. their name is followed by a list of parameters enclosed by parentheses) but differ from analytic functions by the fact that they cannot be differentiated or integrated, either because they returns non numerical objects (''PHERMITE'', ''PMUL'') or because they are not continuous and/or differentiable (''ISPRIME?'', ''RAND'', ''MIN'').
  
-In the examples above we showed how + and / would take some objects from the stack, operate on them and place the result in the stack. This is the basic operation of all operators and commands in RPL. All commands and operators take some (or none) arguments from the stack, and leave some (or none) results in it. There are hundreds of RPL commands, all based on the same principle of taking and leaving objects on the stack. Future chapters will describe each command in depth, for now only a few commands will be introduced that define the basic core of the RPL language. The basic arithmetic operators work as expected (+ and / were already introduced), taking objects from the stack and leaving the result of the operation. Test operators (>, <, ≤, ≥, == ) take two objects from the stack, perform a comparison and leave a 1 on the stack if the test was true, and a 0 if the test failed. The true condition is always represented with the number 1, while the false condition is always represented with the number 0.+=== Analytic Functions ===
  
 +Analytic functions are a subset of the functions that conform to the layman's concept of mathematical function: they take one or more numerical arguments and return one. Usually are continuous and/or differentiable and include trigonometric (''SIN'', ''ACOS'') and hyperbolic (''LN'', ''TANH'') functions.
 ---- ----
  
Line 46: Line 73:
 Programs may take values from the stack, just like any RPL operator or command. To use values from the stack, a program simply needs to assume they are there and operate on them. Our previous example could be rewritten as: Programs may take values from the stack, just like any RPL operator or command. To use values from the stack, a program simply needs to assume they are there and operate on them. Our previous example could be rewritten as:
  
-<code>« + 2 / »</code>+<code>« 
 +  + 
 +  2 / 
 +»</code>
  
 This short program runs the operator + as its first command. Previously, we had included in the program the numbers 1 and 2, which were put on the stack. This version now expects the user to leave two numbers on the stack before running this program. The program will then add them together, and later divide the result by two (computing the average). This short program runs the operator + as its first command. Previously, we had included in the program the numbers 1 and 2, which were put on the stack. This version now expects the user to leave two numbers on the stack before running this program. The program will then add them together, and later divide the result by two (computing the average).
Line 61: Line 91:
 Variables are created with the comand ''STO'' (store) which stores an object into a named variable. Variables are created with the comand ''STO'' (store) which stores an object into a named variable.
  
-<code>« 4 'X' STO »</code>+<code>« 
 +  4 'X' STO 
 +»</code>
 The program above stores the number 4 in a variable named ''X''. Notice the name of a variable must be enclosed in single quotes when it refers to the name itself, and without quotes when it refers to the content of a variable. In this case, we want the name ''%%'X'%%'' The program above stores the number 4 in a variable named ''X''. Notice the name of a variable must be enclosed in single quotes when it refers to the name itself, and without quotes when it refers to the content of a variable. In this case, we want the name ''%%'X'%%''
  to be put on the stack, to be used by the ''STO'' command.  to be put on the stack, to be used by the ''STO'' command.
Line 91: Line 123:
 To make it even more useful, variables appear in the soft menus, so instead of typing the word ''AVERAGE'' every time, simply using the corresponding key will also run the program and compute the average. To make it even more useful, variables appear in the soft menus, so instead of typing the word ''AVERAGE'' every time, simply using the corresponding key will also run the program and compute the average.
  
-''3'' ''5'' ''APPS(G)'' +''3'' ''5'' (press the key **G**
-will do the same, assuming there were no other variables, so that ''AVERAGE'' was shown on the first spot of the second soft menu, activated with the ''G'' key.+will do the same, assuming there were no other variables, so that ''AVERAGE'' was shown on the first spot of the second soft menu, activated with the **G** key.
  
 ---- ----
Line 204: Line 236:
 The syntax for this construct is: The syntax for this construct is:
 <code> <code>
-IF expression THEN statements END+IF test_clause THEN statements END
 </code> </code>
 or with the ''ELSE'' part. or with the ''ELSE'' part.
 <code> <code>
-IF expression THEN statements ELSE statements END+IF test_clause THEN statements ELSE statements END
 </code> </code>
  
-The syntax is IF (something is true) THEN (do this) ELSE (do that) END. Anything between IF and THEN is a test clause, and has to leave a true/false result on the stack. If the result is true, anything between the THEN and ELSE will be executed, and if it's false, anything between ELSE and END will be executed instead.+The syntax is ''IF'' (something is true) ''THEN'' (do this) ''ELSE'' (do that) ''END''. Anything between ''IF'' and ''THEN'' is a //test clause//, and has to leave a true/false result on the stack. If the result is true, anything between the ''THEN'' and ''ELSE'' will be executed, and if it's false, anything between ''ELSE'' and ''END'' will be executed instead.
  
-The ELSE part is optional: IF (something is true) THEN (do this) END is a valid construct, which will execute anything between THEN and END if the condition is true, and simply do nothing if it;s false.+The ''ELSE'' part is optional: ''IF'' (something is true) ''THEN'' (do this) ''END'' is a valid construct, which will execute anything between ''THEN'' and ''END'' if the condition is true, and simply do nothing if it;s false.
  
 For example, the following program: For example, the following program:
  
-<1 'X' STO 2 'X' LSTO IF X 2 == THEN "YES" ELSE "NO" END >+<file> 
-It begins by storing the number 1 in a global variable X, and the number 2 in a local variable. Now let's focus on the conditional statement. The test clause in this case is X 2 ==, which is true if X equals 2. Since we have just created a local X with the number 2, the condition is true and execution will continue after the THEN statement, leaving the string "YES" on the stack. Anything after the ELSE is skipped (because the test was true) and execution continues after the END statement. Now let's modify the example by reversing the order of the STO operations:+« 1 'X' STO 2 'X' LSTO IF X 2 == THEN "YES" ELSE "NO" END » 
 +</file
 +It begins by storing the number ''1'' in a global variable ''X'', and the number 2 in a local variable. Now let's focus on the conditional statement. The test clause in this case is ''X 2 =='', which is true if ''X'' equals ''2''. Since we have just created a local ''X'' with the number ''2'', the condition is true and execution will continue after the ''THEN'' statement, leaving the string ''"YES"'' on the stack. Anything after the ''ELSE'' is skipped (because the test was true) and execution continues after the ''END'' statement. Now let's modify the example by reversing the order of the ''STO'' operations:
  
-<2 'X' LSTO 1 'X' STO IF X 2 == THEN "YES" ELSE "NO" END >+<file> 
- In this case, the first LSTO creates a local variable X with the number 2, but the STO operation changes its value to 1. When the test clause is executed, X 2 == is now false (X=1), therefore anything after the THEN is skipped and execution continues after the ELSE word, leaving the string "NO" in the stack.+« 2 'X' LSTO 1 'X' STO IF X 2 == THEN "YES" ELSE "NO" END » 
 +</file
 +In this case, the first ''LSTO'' creates a local variable ''X'' with the number ''2'', but the ''STO'' operation changes its value to ''1''. When the test clause is executed, ''X 2 =='' is now false (indeed ''X'' is ''1''), therefore anything after the ''THEN'' is skipped and execution continues after the ''ELSE'' word, leaving the string ''"NO"'' in the stack.
  
-Notice that the test result is a true/false value taken from the stack, and doesn't necessarily have to be put on the stack between the IF and THEN statements. For example the following is perfectly valid:+Notice that the test result is a true/false value taken from the stack, and doesn't necessarily have to be put on the stack between the ''IF'' and ''THEN'' statements. For example the following is perfectly valid:
  
-<X 2 == IF THEN "YES" END >+<file> 
-The test clause is outside the construct, which makes it difficult to understand for a human, but the effect is exactly the same as long as a true/false value is on the stack when the IF/THEN statement is executed. This is also valid for loops, where the test clause might be empty.Since putting the test clause in the right place makes for a much easier to read program, it's consider good practice to put the test clause between IF and THEN.+« X 2 == IF THEN "YES" END » 
 +</file
 +The test clause is outside the construct, which makes it difficult to understand for a human, but the effect is exactly the same as long as a true/false value is on the stack when the ''IF''/''THEN'' statement is executed. This is also valid for loops, where the test clause might be empty.Since putting the test clause in the right place makes for a much easier to read program, it's consider good practice to put the test clause between ''IF'' and ''THEN''.
  
 === Conditionals: IFT/IFTE === === Conditionals: IFT/IFTE ===
  
 The syntax for this construct is: The syntax for this construct is:
-... ... IFT+<file> 
 +test_clause command IFT 
 +</file> 
 +or 
 +<file> 
 +test_clause commad_if_true command_if_false IFTE 
 +</file>
  
-... ... ... IFTE+These are simple commands, as opposed to a construct formed by various wordsThe ''IFT'' (IF True) takes 2 arguments from the stackThe argument in level 2 of the stack is a true/false condition, while in level 1, it expects an object to evaluate only if the condition in level2 is true, otherwise it does nothing.
  
-These are simple commands, as opposed to a construct formed by various words. The IFT (IF True) takes 2 arguments from the stack. The argument in level 2 of the stack is a true/false conditionwhile in level 1, it expects an object to evaluate only if the condition in level2 is true, otherwise it does nothing.+<file> 
 +« 1 'X' STO X 1 == "Yes" IFT » 
 +</file> 
 +The example above stores ''1'' in variable ''X'', then ''X 1 =='' compares ''X'' and ''1'', leaving true in the stack if they are equal (in this case yes). It then puts on the stack the object to evaluate, in this case the string ''"Yes"'' (usually it's a program, but any type of object can be used). The ''IFT'' will take the two arguments, and since the condition is true, will evaluate the ''"Yes"'' string, leaving it on the stack.
  
-<<'XSTO X 1 == "Yes" IFT >> +''IFTE'' is similar but takes 3 arguments from the stack. Level 3 has the test condition, level 2 the object to execute if true, and level 1 the object to execute if false. The behavior is similar to IF/THEN/ELSE, where the object in level 1 will only be executed if the condition is false, the object in level 2 only if the condition is true. ''IFT'' and ''IFTE'' are reverse polish equivalents of IF/THEN/END and IF/THEN/ELSE/END.
-The example above stores 1 in variable X, then X 1 == compares X and 1, leaving true in the stack if they are equal (in this case yes). It then puts on the stack the object to evaluate, in this case the string "Yes" (usually it's a program, but any type of object can be used). The IFT will take the two arguments, and since the condition is true, will evaluate the "Yes" string, leaving it on the stack. +
- +
-IFTE is similar but takes 3 arguments from the stack. Level 3 has the test condition, level 2 the object to execute if true, and level 1 the object to execute if false. The behavior is similar to IF/THEN/ELSE, where the object in level 1 will only be executed if the condition is false, the object in level 2 only if the condition is true. IFT and IFTE are reverse polish equivalents of IF/THEN/END and IF/THEN/ELSE/END.+
  
 === Conditionals: CASE/END === === Conditionals: CASE/END ===
- 
 The syntax for this construct is: The syntax for this construct is:
-CASE ... END +<file> 
- +CASE  
-CASE (this test is true) THEN (do this) END (this other test is trueTHEN (do that) END ... [as many tests as needed with their corresponding THEN and END] ... (do this since none of the above were trueEND+statements  
 +  @default 'case' clause, there is no test 
 +END 
 +</file> 
 +or 
 +<file> 
 +CASE  
 +test_clause1 THEN statements END  
 +@do the statements only if the test_clause1 is true and then 
 +@quit the case block 
 +test_clause2 THEN statements END  
 +@do the statements only if the test_clause2 is true and then 
 +@quit the case block 
 +... @as many tests as needed with their corresponding THEN and END  
 +statements @do this since none of the above test clauses were true 
 +  @this is the default clause 
 +END 
 +</file>
  
-Similar to the IF statement, there is a series of test clauses with THEN ... END. The first test clause is evaluated, and if it's true, anything between the following THEN and END statements will be executed, otherwise it will be skipped and execution will continue at the next test clause. In this way, test clauses will be executed until one of them is true. When this happens, the action specified for that test will be executed (immediately after the THEN), and when the END word is reached, execution will skip all other clauses until the end of the CASE statement. If none of the test clauses is true, execution falls trough to the default clause, finished with an END statement.+Similar to the ''IF'' statement, there is a series of test clauses with ''THEN statements END'' structure. The first test clause is evaluated, and if it's true, anything between the following ''THEN'' and ''END'' statements will be executed, otherwise it will be skipped and execution will continue at the next test clause. In this way, test clauses will be executed until one of them is true. When this happens, the action specified for that test will be executed (the action is specified immediately after the ''THEN''), and when the ''END'' word is reached, execution will skip all other clauses until the ''END'' of the ''CASE'' statement. If none of the test clauses is true, execution falls trough to the default clause, finished with an ''END'' statement.
  
 For example: For example:
  
-<CASE +<file> 
 +« CASE  
 +  X 1 == THEN "ONE" END 
 +  X 2 == THEN "TWO" END 
 +  "OTHER" 
 +  END  
 +» 
 +</file>
  
-X 1 == THEN "ONE" END+If the variable ''X'' contains the value ''1'', the first test clause will be true, the string ''"ONE"'' will be put on the stack and that's the end of the ''CASE'' statement.
  
-X 2 == THEN "TWO" END+If the variable ''X'' contains the value ''2'', the first clause will be false, execution will continue to the second test clause, which is true in this case, leaving the string ''"TWO"'' in the stack and ending the ''CASE''.
  
-"OTHER"+If the variable ''X'' contains ''0'', the first and second test clauses will fail, execution will continue at the default clause, leaving ''"OTHER"'' in the stack.
  
-END >> +=== START loops === 
-If the variable X contains the value 1, the first test clause will be true, the string "ONE" will be put on the stack and that's the end of the CASE statement.+The syntax for this construct is: 
 +<code> 
 +startIndex endIndex START codeStatements NEXT 
 +</code
 +or 
 +<code> 
 +startIndex endIndex START codeStatements incrementValue STEP 
 +</code>
  
-If the variable X contains the value 2the first clause will be false, execution will continue to the second test clause, which is true in this case, leaving the string "TWO" in the stack and ending the CASE.+Where ''startIndex'' ''endIndex'' are integers. 
 +''incrementValue'' is a positive or a negative integer.
  
-If the variable X contains 0, the first and second test clauses will failexecution will continue at the default clauseleaving "OTHER" in the stack.+''START'' loops execute the ''codeStatements'' a number of times equal to the difference between ''startIndex'' and ''endIndex'' . If one wants to execute with stepsfor example from 1 to 100 with steps of 2, therefore doing 1 3 5 7 and so on 
 + 
 +This loops takes 2 arguments from the stack: a start and and end count. It repeats the ''codeStatements'' between ''START'' and either ''NEXT'' or ''STEP'' using a counter that goes from the first argument (start) to the second argument (end). For example: 
 + 
 +<file> 
 +« 1 10 START "HELLO" NEXT » 
 +</file> 
 +Will count from 1 to 10and therefore repeat 10 times whatever is inside the loop delimiters (''START'' and ''NEXT'' in this case). As a result, the above program will leave the word ''"HELLO"'' 10 times on the stack. 
 + 
 +When using the ''NEXT'' keyword to end the loopthe counter is increased by one. This can be overridden by using the ''STEP'' keyword, which takes the increment from the stack and adds it to the counter: 
 + 
 +<file> 
 +« 10 1 START "HELLO-1 STEP » 
 +</file> 
 +This is equivalent to the previous example, except it counts from 10 to 1, adding -1 at each increment. 
 + 
 +The counter in a ''START'' loop cannot be accessed from inside the loop.
  
 === FOR loops === === FOR loops ===
Line 278: Line 369:
 </code> </code>
  
-A FOR loop is almost identical to a START loop, except the counter is made available to the program inside the loop as a local variable. For example:+''FOR'' loop is almost identical to a ''START'' loop, except the counter is made available to the program inside the loop as a local variable. For example
 + 
 +<file> 
 +« 1 10 FOR J "HELLO" NEXT » 
 +</file> 
 +This example is the same as the ''START'' example, except that after the ''FOR'' statement, we are required to provide the name of a local variable that will become the index counter for the loop. In this case we used the name ''J'' (arbitrarily). The example doesn't use ''J'', so it could've been written using a ''START'' loop as we previously did. However, the following:
  
-<1 10 FOR J "HELLO" NEXT >+<file> 
-This example is the same as the START example, except that after the FOR statement, we are required to provide the name of a local variable that will become the index counter for the loop. In this case we used the name J (arbitrarily). The example doesn't use J, so it could've been written using a START loop as we previously did. However, the following:+« 1 10 FOR J NEXT » 
 +</file>
  
-<< 1 10 FOR J J NEXT >> +will count from ''1'' to ''10'', on a variable named ''J'', and will repeat whatever is after the variable name and the ''NEXT'' statement. At the end of the program, the numbers ''1'' through ''10'' will be left on the stack, since the second ''J'' in the program refers to the counter and will be repeated 10 times with the value of ''J'' changing from ''1'' through ''10''.
-will count from 1 to 10, on a variable named 'J', and will repeat whatever is after the variable name and the NEXT statement. At the end of the program, the numbers 1 through 10 will be left on the stack, since the second J in the program refers to the counter and will be repeated 10 times with the value of J changing from 1 through 10.+
  
-Similar to the START loop, the increment when using NEXT is one, and it can be replaced with the keyword STEP, which takes the increment from the stack:+Similar to the ''START'' loop, the increment when using ''NEXT'' is one, and it can be replaced with the keyword ''STEP'', which takes the increment from the stack:
  
-<1 10 FOR J J 2 STEP >>+<file> 
 +« 1 10 FOR J J 2 STEP » 
 +</file>
 will leave the numbers 1,3,5,7,9 on the stack. will leave the numbers 1,3,5,7,9 on the stack.
  
-=== START loops === 
-The syntax for this construct is: 
-<code> 
-startIndex endIndex START codeStatements NEXT 
-</code> 
-or 
-<code> 
-startIndex endIndex START codeStatements incrementValue STEP 
-</code> 
  
-Where ''startIndex'' , ''endIndex'' are integers+The behavior of the ''NEXT'' statement is different from the ''STEP'' statement: 
-''incrementValue'' is a positive or a negative integer.+  * ''NEXT'' always increments the counter by 1while ''STEP'' could go either direction or leave the same value
 +  * ''NEXT'' always checks if the counter is ≤ end value to continue the loop. ''STEP'' checks if the counter is ≤ or ≥ end value depending on the direction of the loop.
  
-''START'' loops execute the ''codeStatements'' a number of times equal to the difference between ''startIndex'' and ''endIndex'' . If one wants to execute with stepsfor example from 1 to 100 with steps of 2therefore doing 1 3 5 7 and so on+When using ''STEP''the direction of a loop is determined by the initial start and end values. If the end value is higher than the start value (therefore counting up)the loop will continue while the variable is less than or equal to the end value. On the contraryif the end value is lower than the start value, the loop will continue as long as the variable is greater than or equal to the end value.
  
-This loops takes 2 arguments from the stack: a start and and end count. It repeats anything between START and either NEXT or STEP using a counter that goes from the first argument (start) to the second argument (end). For example:+When ''STEP'' is used, the magnitude and direction of the step do not affect the condition to end the loop. For example:
  
-<< 1 10 START "HELLO" NEXT >+<file
-Will count from to 10, and therefore repeat 10 times whatever is inside the loop delimiters (START/NEXT in this case). As a result, the above program will leave the word "HELLO" 10 times on the stack.+« 1 'S' STO  
 +    1 10 FOR J  
 +        J  
 +        IF J 4 == THEN -1 'S' STO END 
 +        IF J 1 == THEN 2 'S' STO END 
 +    S STEP 
 +» 
 +</file>
  
-When using the NEXT keyword to end the loop, the counter is increased by oneThis can be overriden by using the STEP keywordwhich takes the increment from the stack and adds it to the counter:+In the above example ''J'' will count from 1 to 10 (therefore this is a loop counting up) with a step ''S''. The loop begins with a step of 1being stored in ''S''The loop will run leaving the values of J in the stack, initially 1,2,3,4 then the condition in the ''IF'' statement becomes true and the step changes to -1. 
 +The loop will now begin counting down 3,2,1 and the second ''IF'' statement becomes true, changing the step to 2. The loop will continue running 3,5,7,9, and then the loop will exit when the counter is >10. The complete sequence generated by the code above is then 1,2,3,4,3,2,1,3,5,7,9.
  
-<10 1 START "HELLO" -1 STEP >> +When ''NEXT'' is used, the direction is always assumed to be up regardless of start and end values, therefore the following loop: 
-This is equivalent to the previous exampleexcept it counts from 10 to 1, adding -1 at each increment.+ 
 +<file> 
 +« A 10 FOR J J NEXT » 
 +</file> 
 + 
 +Will produce the following outputs, depending on the value of ''A'': 
 + 
 +  * ''A=1'' will produce 1,2,3,4,5,6,7,8,9,10 
 +  * ''A=10'' it will produce 10 
 +  * ''A=11'' it will produce 11 
 + 
 +Notice that despite the starting value being higher than the end value and the loop using ''NEXT'' (therefore it's a assumed to be a loop counting up), the loop executed at least once. This is because the decision to exit the loop is made when ''NEXT'' is reached. 
 + 
 +Now let's review a loop using ''STEP'' with a positive step: 
 + 
 +<file> 
 +« A 10 FOR J J 1 STEP » 
 +</file
 + 
 +Will produce the following outputs, depending on the value of ''A'': 
 + 
 +  * ''A=1'' will produce 1,2,3,4,5,6,7,8,9,10 
 +  * ''A=10'' it will produce 10 
 +  * ''A=11'' it will produce 11,12,13,14,15,... infinite loop 
 + 
 +Notice that while the loop appears to count up by looking at the code, the condition A>10 causes the loop to be counting down because the start value is larger than the end valueand therefore it will only end when J<10, regardless of the magnitude and direction of the step. Since the step increases the counter, the loop never ends. 
 + 
 +In some situations it is desirable to keep the direction of the loop fixed regardless of the start/end values. The ''FORUP'' and ''FORDN'' commands can be used in lieu of ''FOR''. These two variants have two advantages: 
 +  * The direction of the loop is fixed and known, regardless of the values the limits might have at run time. 
 +  * The loop has one additional check when the word ''FORUP'' or ''FORDN'' is executed. This allows for early exit without being forced to execute the loop clause. 
 + 
 +Back to the example used above for ''NEXT'' but in this case using FORUP: 
 + 
 +<file> 
 +« A 10 FORUP J J NEXT » 
 +</file> 
 + 
 +Will produce the following outputs, depending on the value of ''A'': 
 + 
 +  * ''A=1'' will produce 1,2,3,4,5,6,7,8,9,10 
 +  * ''A=10'' it will produce 10 
 +  * ''A=11'' it will not produce any output 
 + 
 +It differs from using ''FOR'' in the last case: the clause between ''FORUP'' and ''NEXT'' is never executed because the starting value was already larger than the end limit. 
 + 
 +On the other end: 
 +<file> 
 +« A 10 FORDN J J -1 STEP » 
 +</file> 
 + 
 +  * ''A=1'' will produce no output 
 +  * ''A=10'' it will produce 10 
 +  * ''A=11'' will produce 11,10 
 + 
 +Note that ''NEXT'' always considers the loop direction going up, therefore ''NEXT'' is not compatible with ''FORDN'' which contradicts that assumption. 
 + 
 +Summarizing, the main differences between all the ''FOR'' constructs: 
 + 
 +     * ''FOR'' may count up or down, and may be used with both ''NEXT'' and ''STEP''. The loop clause is always executed at least once. 
 +     * ''FORUP'' always counts up, may be used with ''NEXT'' or ''STEP''. The loop clause is not executed if the starting value is greater than the end value. 
 +     * ''FORDN'' always counts down, can only be used with ''STEP''. The loop clause is not executed if the starting value is less than the end value.
  
-The counter in a START loop cannot be accessed from inside the loop. 
  
 + 
 === DO loops === === DO loops ===
 The syntax for this construct is: The syntax for this construct is:
-DO .... UNTIL ... END+<file> 
 +DO .... UNTIL testClause END 
 +</file>
  
-Unlinke FOR and START, this loop has no counter. It repeats everything between DO and END, as many times as needed until the test clause (which is everything between UNTIL and END) becomes true.+Unlike ''FOR'' and ''START'', this loop has no counter. It repeats everything between ''DO'' and ''END'', as many times as needed until the ''testClause'' (which is everything between UNTIL and END) becomes true.
  
-Normally, the test clause will contain some test that leaves a true/false result on the stack. When the word END is executed, it will take one argument from the stack and will verify if it's true or false. If it's true, it will not repeat the loop, if it's false, it will start repeating everything after the DO keyword.+Normally, the ''testClause'' will contain some test that leaves a true/false result on the stack. When the word ''END'' is executed, it will take one argument from the stack and will verify if it's true or false. If it's true, it will not repeat the loop, if it's false, it will start repeating everything after the ''DO'' keyword.
  
-In newRPL, a condition is said to be false if it's the number zero. Anything else will be considered true, including things similar to the number zero, like a (0,0) complex number, or a zero vector [0 0]. Both of them will be considered true.+In newRPL, **a condition is said to be false if it's the number zero**. Anything else will be considered true, including things similar to the number zero, like a (0,0) complex number, or a zero vector [0 0]. Both of them will be considered true.
  
-<10 'X' LSTO DO X X 2 / 'X' STO UNTIL X 2 <= END >+<file> 
-The example above creates a local variable X and then starts a DO loop. In the loop the value of X is left on the stack (the first X) , then halved (by X 2 /) and stored back. This is repeated until the condition X<=2 is met. At the end of the program, the numbers 10, 5, and 2.5 will be left on the stack. FOR and START are more adequate when there is a counter that is added or subtracted a quantity every cycle. In this example, while X could be seen as a counter of some sort, it is halved on each cycle, so the FOR and START loops can't be used.+« 10 'X' LSTO DO X X 2 / 'X' STO UNTIL X 2 ≤ END » 
 +</file
 +The example above creates a local variable ''X'' and then starts a ''DO'' loop. In the loop the value of ''X'' is left on the stack (the first ''X'') , then halved (by ''X 2 /'') and stored back. This is repeated until the condition ''X 2 ≤''  is met. At the end of the program, the numbers 10, 5, and 2.5 will be left on the stack.  
 + 
 +''FOR'' and ''START'' are more adequate when there is a counter that is added or subtracted a quantity every cycle. In this example, while ''X'' could be seen as a counter of some sort, it is halved on each cycle, so the ''FOR'' and ''START'' loops can't be used.
  
 === WHILE loops === === WHILE loops ===
 The syntax for this construct is: The syntax for this construct is:
 +<file>
 WHILE ... REPEAT ... END WHILE ... REPEAT ... END
 +</file>
  
-The syntax for these loops is WHILE (something is true) REPEAT (this) END. Anything between the WHILE and REPEAT is a test clause, and has to leave a true/false result on the stack. If the result is true, anything between REPEAT and END will be executed, otherwise the loop ends and the program continues at the END statement.+The syntax for these loops is ''WHILE'' (something is true) ''REPEAT'' (this) ''END''. Anything between the ''WHILE'' and ''REPEAT'' is a test clause, and has to leave a true/false result on the stack. If the result is true, anything between ''REPEAT'' and ''END'' will be executed, otherwise the loop ends and the program continues at the ''END'' statement.
  
 Same as before, a condition is said to be false if it's the number zero. Anything else will be considered true. Same as before, a condition is said to be false if it's the number zero. Anything else will be considered true.
  
-These loops are similar to the DO loops with some important differences:+These loops are similar to the ''DO'' loops with some important differences
 + 
 +''WHILE'' loops have the test clause at the beginning of the loop, and if the result is false, the loop will not execute at all. ''DO'' loops, on the contrary, do one full loop execution before reaching the ''UNTIL'' test clause, so even if it results false, the loop was executed at least once. 
 +''WHILE'' loops cycle when the clause is true. ''DO'' loops cycle when the clause is false. 
 +Let's write the previous example using a ''WHILE'' loop:
  
-WHILE loops have the test clause at the beginning of the loop, and if the result is false, the loop will not execute at all. DO loops, on the contrary, do one full loop execution before reaching the UNTIL test clause, so even if it results false, the loop was executed at least once. +<file> 
-WHILE loops cycle when the clause is true. DO loops cycle when the clause is false. +« 10 'X' LSTO WHILE X 2 > REPEAT X X 2 / 'X' STO END » 
-Let's write the previous example using a WHILE loop:+</file>
  
-<< 10 'X' LSTO WHILE X 2 > REPEAT X X 2 / 'X' STO END >> +Again, the result will be the numbers 10, 5 and 2.5 left on the stack. Notice that now the loop will execute when ''X 2 >''. Before, the loop would run until ''X 2 ≤'' which is a different way of stating the exact same thing.
-Again, the result will be the numbers 10, 5 and 2.5 left on the stack. Notice that now the loop will execute when X>2. Before, the loop would run until X<=2 which is a different way of stating the exact same thing.+
  
 ==== Additional sources ==== ==== Additional sources ====
 Since the newRPL is based on the userRPL designed for HP calculator, the basic syntax is shared between those two languages so many examples can be found checking the resources shared by the HP calculator community (in particular for calculators of the series HP 48, 49, 50 ). Since the newRPL is based on the userRPL designed for HP calculator, the basic syntax is shared between those two languages so many examples can be found checking the resources shared by the HP calculator community (in particular for calculators of the series HP 48, 49, 50 ).
  
-=== Links === +Please see the [[manual:appendix:links|Useful resources]] page.
-[[http://www.wiki4hp.com/doku.php?id=resources:start|List of HP calculator resources online]] +
-* [[http://www.hpcalc.org/|Online repository of files related to HP calculators, interesting to look in the programming section for manuals]]+
  • manual/chapter5/basics.txt
  • Last modified: 2021/09/15 10:32
  • by claudio