Creating and using Arrays
The Positron16 compiler supports multi part Byte, Word, Dword, SByte, SWord, SDword and Float variable arrays. An array is a group of variables of the same size (8-bits, 16-bits or 32-bits wide), sharing a single name, but split into numbered cells, called elements.
An array is defined using the following syntax: -
Dim Name[length] as Byte
Dim Name[length] as Word
Dim Name[length] as Dword
Dim Name[length] as SByte
Dim Name[length] as SWord
Dim Name[length] as SDword
Dim Name[length] as Floatwhere Name is the variable's given name, and the new argument, [ length ], informs the compiler how many elements you want the array to contain. For example: -
Dim bMyArray[10] as Byte
' Create a 10 element unsigned byte array.
Dim wMyArray[10] as Word
' Create a 10 element unsigned word array.
Dim dMyArray[10] as Dword ' Create a 10 element unsigned dword array.
Dim sbMyArray[10] as SByte ' Create a 10 element signed byte array.
Dim swMyArray[10] as SWord ' Create a 10 element signed word array.
Dim sdMyArray[10] as SDword ' Create a 10 element signed dword array.
Dim fMyArray[10] as Float ' Create a 10 element floating point array.Arrays may have up to 65535 elements.
Once an array is created, its elements may be accessed numerically. Numbering starts at 0 and ends at n-1. For example: -
MyArray[3] = 57
Hrsout "MyArray[3] = ", Dec MyArray[3], 13The above example will access the fourth element in the Byte array and display "MyArray[3] = 57" on the serial terminal. The true flexibility of arrays is that the index value itself may be a variable. For example: -
Device = 24FJ64GA002
' Select the device to compile for
Declare Xtal = 16
' Tell the compiler the device will be operating at 16MHz
Declare Hserial_Baud = 9600 ' USART1 Baud rate
Declare Hrsout1_Pin = PORTB.14 ' Select the pin for TX with USART1
Dim bMyArray[10] as Byte
' Create a 10 element byte array.
Dim bIndex as Byte
' Create a Byte variable.
RPOR7 = 3
' Make PPS Pin RP14 U1TX
For bIndex = 0 to 9
' Repeat with bIndex= 0,1,2...9
bMyArray[bIndex] = bIndex * 10 ' Write to each element of the array.
Next
For bIndex = 0 to 9
' Repeat with bIndex= 0,1,2...9
HrsoutLn Dec bMyArray[bIndex] ' Show the contents of each element.
DelayMs 500
' Wait long enough to view the values
NextIf the previous program is run, 10 values will be displayed, counting from 0 to 90 i.e. Index * 10.
A word of caution regarding arrays: If you're familiar with interpreted BASICs and have used their arrays, you may have run into the "subscript out of range" error. Subscript is simply another term for the index value. It is considered "out-of range" when it exceeds the maximum value for the size of the array.
For example, in the previous example, MyArray is a 10-element array. Allowable index values are 0 through 9. If your program exceeds this range, the compiler will not respond with an error message. Instead, it will access the next RAM location past the end of the array.
If you are not careful about this, it can cause all sorts of subtle anomalies, as previously loaded variables are overwritten. It's up to the programmer (you!) to prevent this from happening.
Even more flexibility is allowed with arrays because the index value may also be an expression.
Device = 24FJ64GA002
' Select the device to compile for
Declare Xtal = 16
' Tell the compiler the device will be operating at 16MHz
Declare Hserial_Baud = 9600
' USART1 Baud rate
Declare Hrsout1_Pin = PORTB.14
' Select the pin for TX with USART1
Dim bMyArray[10] as Byte
' Create a 10 element byte array.
Dim bIndex as Byte
' Create a Byte variable
RPOR7 = 3
' Make PPS Pin RP14 U1TX
For bIndex = 0 to 8
' Repeat with Index= 0,1,2...8
bMyArray[Index + 1] = bIndex * 10 ' Write to each element of array
Next
For bIndex = 0 to 8
' Repeat with Index= 0,1,2...8
Hrsout Dec bMyArray[bIndex + 1], 13 ' Show the contents of elements
DelayMs 500
' Wait long enough to view the values
NextThe expression within the square braces should be kept simple, and arrays are not allowed as part of the expression.
Using Arrays in Expressions.
Of course, arrays are allowed within expressions themselves. For example: -
Dim bMyArray[10] as Byte
' Create a 10 element byte array
Dim bIndex as Byte
' Create a Byte variable
Dim MyByte as Byte
' Create another Byte variable
Dim MyResult as Byte
' Create a variable to hold result of expression
bIndex = 5
' bIndex now holds the value 5
MyByte = 10
' Variable MyByte now holds the value 10
MyArray[bIndex] = 20
' Load the 6th element of bMyArray with value 20
MyResult = (MyByte * bMyArray[bIndex]) / 20 ' Do a simple expression
Hrsout Dec MyResult, 13
' Display result of expressionThe previous example will display 10 on the LCD, because the expression reads as: -
(10 * 20) / 20
MyByte holds a value of 10, MyArray[Index] holds a value of 20, these two variables are multiplied together which will yield 200, then they're divided by the constant 20 to produce a result of 10.
Byte Arrays as Strings
Byte arrays may also be used as simple strings in certain commands, because after all, a string is simply a byte array used to store text.
For this, the Str modifier is used.
Some of the commands that support the Str modifier are: -
Busout - Busin
Hbusout - Hbusin
Hbusout2 – Hbusin2
Hrsout - Hrsin
Owrite - Oread
Rsout - Rsin
Serout - Serin
Shout - Shin
The Str modifier works in two ways, it outputs data from a pre-declared array in commands that send data i.e. Rsout, Print etc, and loads data into an array, in commands that input information i.e. Rsin, Serin etc. The following examples illustrate the Str modifier in each compatible command.
Using Str with the Busin and Busout commands.
Refer to the sections explaining the Busin and Busout commands.
Using Str with the Hbusin and Hbusout commands.
Refer to the sections explaining the Hbusin, Hbusout, Hbusin2 and Hbusout2 commands.
Using Str with the Rsin command.
Dim Array1[10] as Byte
' Create a 10 element byte array named Array1
Rsin Str Array1
' Load 10 bytes of data directly into Array1Using Str with the Rsout command.
Dim Array1[10] as Byte
' Create a 10 element byte array named Array1
Rsout Str Array1
' Send 10 bytes of data directly from Array1Using Str with the Hrsin and Hrsout commands.
Refer to the sections explaining the Hrsout and Hrsin commands. Using Str with the Shout command.
Symbol Data_Pin = PORTA.0
' Alias the two lines for the Shout command
Symbol Clock_Pin = PORTA.1
Dim bArray1[10] as Byte
' Create a 10 element byte array named bArray1
' Send 10 bytes of data from bArray1
Shout Data_Pin, Clock_Pin, MsbFirst, [Str bArray1]Using Str with the Shin command.
Symbol Data_Pin = PORTA.0
' Alias the two lines for the Shin command
Symbol Clock_Pin = PORTA.1
Dim bArray1[10] as Byte
' Create a 10 element byte array named bArray1
' Load 10 bytes of data directly into bArray1
Shin Data_Pin, Clock_Pin, MsbPre, [Str bArray1]Using Str with the Print command.
Dim bArray1[10] as Byte
' Create a 10 element byte array named bArray1
Print Str bArray1
' Send 10 bytes of data directly from bArray1Using Str with the Serout and Serin commands.
Refer to the sections explaining the Serin and Serout commands.
Using Str with the Oread and Owrite commands.
Refer to the sections explaining the Oread and Owrite commands.
The Str modifier has two forms for variable-width and fixed-width data, shown below: -
Str ByteArray ASCII string from ByteArray until byte = 0 (null terminated).
Or array length is reached.
Str ByteArray\n ASCII string consisting of n bytes from ByteArray.
Null terminated means that a zero (null) is placed at the end of the string of ASCII characters to signal that the string has finished.
The example below is the variable-width form of the Str modifier: -
Dim bMyArray[5] as Byte
' Create a 5 element Byte array
bMyArray[0] = "A"
' Fill the array with ASCII
bMyArray[1] = "B"
bMyArray[2] = "C"
bMyArray[3] = "D"
bMyArray[4] = 0
' Add the null Terminator
Print Str bMyArray
' Display the stringThe code above displays "ABCD" on the LCD. In this form, the Str formatter displays each character contained in the byte array until it finds a character that is equal to 0 (value 0, not ASCII "0"). Note: If the byte array does not end with 0 (null), the compiler will read and output all RAM register contents until it cycles through all RAM locations for the declared length of the byte array.
For example, the same code as before without a null terminator is: -
Dim bMyArray[4] as Byte
' Create a 4 element Byte array
bMyArray[0] = "A"
' Fill the array with ASCII
bMyArray[1] = "B"
bMyArray[2] = "C"
bMyArray[3] = "D"
Print Str bMyArray
' Display the stringThe code above will display the whole of the array, because the array was declared with only four elements, and each element was filled with an ASCII character i.e. "ABCD".
To specify a fixed-width format for the Str modifier, use the form Str MyArray\n; where MyArray is the byte array and n is the number of characters to display, or transmit. Changing the Print line in the examples above to: -
Print Str bMyArray \ 2would display "AB" on the LCD.
Str is not only used as a modifier, it is also a command, and is used for initially filling an array with data. The above examples may be re-written as: -
Dim bMyArray[5] as Byte
' Create a 5 element array
Str bMyArray = "ABCD", 0
' Fill array with ASCII, and null terminate it
Print Str bMyArray
' Display the stringStrings may also be copied into other strings: -
Dim String1[5] as Byte
' Create a 5 element array
Dim String2[5] as Byte
' Create another 5 element array
Str String1 = "ABCD", 0
' Fill array with ASCII, and null terminate it
Str String2 = "EFGH", 0
' Fill other array with ASCII, null terminate it
Str String1 = Str String2
' Copy String2 into String1
Print Str String1
' Display the stringThe above example will display "EFGH", because String1 has been overwritten by String2.
Using the Str command with Busout, Hbusout, Shout, and Owrite differs from using it with commands Serout, Print, Hrsout, and Rsout in that, the latter commands are used more for dealing with text, or ASCII data, therefore these are null terminated.
The Hbusout, Busout, Shout, and Owrite commands are not commonly used for sending ASCII data, and are more inclined to send standard 8-bit bytes. Thus, a null terminator would cut short a string of byte data, if one of the values happened to be a 0. So these commands will output data until the length of the array is reached, or a fixed length terminator is used i.e. MyArray\n.