diff --git a/docs/byref.md b/docs/byref.md new file mode 100644 index 000000000..ed0677714 --- /dev/null +++ b/docs/byref.md @@ -0,0 +1,75 @@ +#ByREF + +`ByRef` is a modifier used in function parameters to specify that the parameters is passed by reference (that is, +the original variable is passed to the [FUNCTION](function.md) or [SUB](sub.md)). + +##Syntax + +It's used in function parameter declaration as in this example: + +``` +FUNCTION plusOne(ByRef a As Ubyte) As UByte + LET a = a + 1 + RETURN a +END FUNCTION + +LET a = 0 +PRINT plusOne(a): REM prints 1 +PRINT a: REM prints 1; original value of A has been *modified* within the function +``` + +Here the variable `a` is being modified within the function, and this modification persist upon return. +Except for arrays, when `ByRef` or [ByVAL](byval.md) is not specified in [FUNCTION](function.md) or [SUB](sub.md) +parameters, [ByVAL](byval.md) will be used by default. On the other hand, if the parameter is an array, +and no access is specified, it's supposed to be `ByRef` (arrays cannot be passed by value). + +ByRef allows us to pass arrays to [FUNCTION](function.md) or [SUB](sub.md): + +``` +REM arrays passed to functions can be of *any dimensions*. Use LBOUND and UBOUND to detect dimensions! +FUNCTION maxValue(ByRef a() as Ubyte) As UByte + DIM i as UInteger + DIM result As UByte = 0 + FOR i = 0 TO 4 + IF a(i) > result THEN result = a(i) + NEXT i + RETURN result +END FUNCTION + +DIM myArray(4) As UByte = {4, 3, 1, 2, 5} +PRINT "Max value is "; maxValue(myArray) +``` + +In this example, is `ByRef` was omitted, it will be used by default, since the parameter was an array. +Arrays cannot be passed [ByVAL](byval.md). + +`ByRef` is also useful to return values in the parameters. [RETURN](return.md) allows to return a single value +from a [FUNCTION](function.md), but we can return several values by storing the result in those parameters. + +`ByRef` requires the parameter to be an _lvalue_, that is, a variable, an array or an array cell. You cannot use +`ByRef` with expressions (i.e. numbers) because you cannot store a value in them. + +Example of wrong usage: + +``` +FUNCTION plusOne(ByRef a As Ubyte) As UByte + LET a = a + 1 + RETURN a +END FUNCTION + + +DIM i as UByte = 7 +DIM myArray(5) as Ubyte + +PRINT plusOne(5): REM syntax error, 5 is not a variable or an array element. +PRINT plusOne(i): REM Ok. Will change i value to 8, and print 8) +PRINT plusOne(i + 1): REM syntax error, i + 1 is not a variable +PRINT plusOne(myArray(3)): REM Ok. Will increase myArray(3) by 1 and print the result +``` + +See also: + +* [FUNCTION](function.md) +* [RETURN](return.md) +* [SUB](sub.md) +* [ByVAL](byval.md) diff --git a/docs/byval.md b/docs/byval.md new file mode 100644 index 000000000..4de00c951 --- /dev/null +++ b/docs/byval.md @@ -0,0 +1,30 @@ +#ByVAL + +`ByVal` is a modifier used in function parameters to specify that the parameters is passed by value (that is, +a copy of the value is passed to the [FUNCTION](function.md) or [SUB](sub.md)). + +##Syntax + +It's used in function parameter declaration as in this example: + +``` +FUNCTION plusOne(ByVal a As Ubyte) As UByte + LET a = a + 1 + RETURN a +END FUNCTION + +LET a = 0 +PRINT plusOne(a): REM prints 1 +PRINT a: REM prints 0; original value of A is preserved +``` + +Here the variable `a` is being modified within the function, but the original value is preserved upon return. +Except for arrays, when [ByREF](byref.md) or `ByVal` is not specified in [FUNCTION](function.md) or [SUB](sub.md) +parameters, `ByVal` will be used by default. On the other hand, if the parameter is an array, and no access is +specified, it's supposed to be [ByREF](byref.md) (arrays cannot be passed by value). + +See also: + +* [FUNCTION](function.md) +* [SUB](sub.md) +* [ByREF](byref.md) diff --git a/docs/function.md b/docs/function.md index d2c25ff1d..2c78e2a77 100644 --- a/docs/function.md +++ b/docs/function.md @@ -73,3 +73,12 @@ END FUNCTION If you invoke zxbasic using `-O1` (or higher) optimization flag the compiler will detect and ignore unused functions (thus saving memory space). It will also issue a warning (perhaps you forgot to call it?), that can be ignored. + +##See Also + +* [SUB](sub.md) +* [ASM](asm.md) +* [END](end.md) +* [RETURN](return.md) +* [ByREF](byref.md) +* [ByVAL](byval.md) diff --git a/docs/lbound.md b/docs/lbound.md index 7e0fa4313..4dbe71128 100644 --- a/docs/lbound.md +++ b/docs/lbound.md @@ -10,18 +10,17 @@ LBound(, ) ##Description -Returns the array lower bound of the given . If the is not specified, it defaults to 1. +Returns the array lower bound of the given . If the is not specified, it defaults to 0. If the specified is 0, then total number of dimensions is returned. ##Examples ``` -DIM a(3 TO 5, 2 TO 8) -PRINT LBound(a, 2) : REM Prints 2 -PRINT Lbound(a) : REM Prints 3, because dimension defaults to 1 +DIM a(3 TO 5, 1 TO 8) +PRINT LBound(a, 2) : REM Prints 1 +PRINT Lbound(a) : REM Prints 2, the number of dimensions ``` - The result is always a 16bit integer value. If the is 0, then the number of dimension in the array is returned diff --git a/docs/ubound.md b/docs/ubound.md index aa726836f..e8f878b43 100644 --- a/docs/ubound.md +++ b/docs/ubound.md @@ -9,7 +9,7 @@ UBound(, ) ##Description -Returns the array upper bound of the given . If the is not specified, it defaults to 1. +Returns the array upper bound of the given . If the is not specified, it defaults to 0. If the specified is 0, then total number of dimensions is returned. ##Examples @@ -17,7 +17,7 @@ If the specified is 0, then total number of dimensions is returned. ``` DIM a(3 TO 5, 2 TO 8) PRINT UBound(a, 2) : REM Prints 8 -PRINT Ubound(a) : REM Prints 5, because dimension defaults to 1 +PRINT Ubound(a) : REM Prints 2, because it has 2 dimensions ```