A variable can be made a list variable anytime after it has been defined this is simply done by declaring it with an index. The following line of code would create a integer list with 10 elements
Data[10] = 99
Any existing data will still be in the list, new elements will be initialized to zero and element 10 will be set to 99.
The size of the list can be increased by simply writing to a new list index, however since this means recreating the list each time which can be slow it is recommended that if the maximum size of the list is known then the list is set to this size when it is first used.
Lists can have multiple values assigned to them using braces
Data = { 1 2 3 4 }
will create a list with with four items with the values 1, 2, 3 and 4.
If you want to reduce the size of a list the lst_resize command can be used, this takes two arguments the first is the list to resize and the second is the number of elements in the new list, resizing the list will not effect the data in the remaining list. The following line of code would change the size of the list defined above to 9 elements.
lst_resize Data 9
The number of elements in a list can be found with the lst_size command, this takes two arguments the first is the variable to return the size in and the second is the variable to get the list size from. So to get the number of elements in the Data list created above.
lst_size NumberOfElements Data
If a variable is assigned to another and it is a list then the entire list will be copied.
Lists are passed into blocks in the same way as a normal variable as an alias the example below demonstrates using lists.
//---------------------------------------
// File: VariableLists.e
//---------------------------------------
//---------------------------------------
// Block: go
//---------------------------------------
block Go
//create two variables
A = 1
B = 0
outl A " " B
B = A
outl A " " B
I = 0
//add some elements to create a list
while I < 10
A[I] = I
++ I
_while
//display the list
outlst A ", "
new_line
//make B equal to A
B = A
//get the size of the B list
lst_size BSize B
I = 0
//display the list
outlst B ", "
new_line
//resize B
lst_resize B 5
//get the size of the B list
lst_size BSize B
//display the list
outlst B ", "
new_line
lst_delelement B[3]
//display the list
outlst B ", "
new_line
//assign some new values to A
A = { 100 101 102 103 }
//display the new list
outlst A ", "
new_line
_block
Its often necessary to extract different types of data from a buffer or add them to a buffer the lst_extract and lst_set commands allow this to be done. The following code shows how four variable Var0, Var1, Var2 and Var3 can be extracted from the byte list ByteList. The evolve constants define how the data is extracted so Var0 will contain a int type containing the first 8 bytes from the list array, Var2 will be a byte variable containing the ninth byte in the list
lst_extract Var0 #INT64 Var1 #BYTE Var2 #INT16 Var3 #INT32 ByteList
There are 2 possible types of strings that can be extracted either fixed length or null terminated. The following example shows how a null terminated string is extracted. When the code is run Var1 will be “abcd”.
ByteList = { 'a' 'b' 'c' 'd' 0x00 'h' }
lst_extract Var1 #STRNULL ByteList
The following code shows how a fixed length string is extracted if the #STR constant is used then it must be followed by a number which is the number of bytes to read. When the code is run Var1 will contain “abc”.
ByteList = { 'a' 'b' 'c' 'd' 0x00 'h' }
lst_extract Var1 #STR 3 ByteList
The following code shows lst_extract in use.
//---------------------------------------
// File: ListExtraction.e
//---------------------------------------
//---------------------------------------
// Block: Test0
//---------------------------------------
block Test0
ByteList = { 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88 0x99 0xaa 0xbb }
lst_extract Var0 #LINT64 Var1 #BYTE Var2 #LINT16 Var3 #LINT32 ByteList
outl Var1
outl Var2
outl Var3
outl Var0
_block
//---------------------------------------
// Block: Test1
//---------------------------------------
block Test1
ByteList = { 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88 0x99 0xaa 0xbb }
lst_extract Var0 #INT64 Var1 #BYTE Var2 #INT16 Var3 #INT32 ByteList
outl Var1
outl Var2
outl Var3
outl Var0
_block
//---------------------------------------
// Block: Test2
//---------------------------------------
block Test2
ByteList = { 'a' 'b' 'c' 'd' 0x00 }
lst_extract Var1 #STRNULL ByteList
outl Var1
_block
//---------------------------------------
// Block: Test3
//---------------------------------------
block Test3
ByteList = { 'a' 'b' 'c' 'd' 'e' 'f' 'g' }
lst_extract Var1 #STR 5 ByteList
outl Var1
_block
//---------------------------------------
// Block: Go
//---------------------------------------
block Go
out_ibase #HEX
Test0
new_line
Test1
new_line
Test2
new_line
Test3
_block
//---------------------------------------
// File: ListSet.e
//---------------------------------------------------------
The opposite of lst_extract is lst_set this allows you to put data into a buffer the following code shows this.
//---------------------------------------
// Block: Go
//---------------------------------------
block Go
Var1 = "Test"
Var2 = 0x1234
Var3 = 0x22
//create the byte list
lst_set ByteList Var1 #STRNULL Var2 #INT16 Var3 #BYTE
//print the byte list
outlst ByteList ", "
new_line
_block
If you want to swap some elements from one list to another this can be done using the lst_masklst command. This allows you to define the required elements to be copied in a bit mask. The following code shows how this works.
//---------------------------------------
// File: ListMaskList.e
//---------------------------------------
//---------------------------------------
// Block: Go
//---------------------------------------
block Go
Var = { "Local" "Local Stop" "Remote" "Local Open" "Local Close" "Local Inhand" }
I = 1
while I < 64
lst_masklst Dest Var I
outlst Dest ", "
new_line
++ I
_while
_block
In every loop the code creates a mask with the variable I this mask defines which elements from Var to copy to the new list Des.
Lists can easily be sorted in either ascending or descending order using the lst_sort command as shown below.
//---------------------------------------
// File: ListSort.e
//---------------------------------------
//---------------------------------------
// Block: Go
//---------------------------------------
block Go
Var = { 596.44 5.6 8.7 45.26 359.6 359.8 526.235 0.22 }
lst_sort Var #ASCEND
outlst Var ", "
new_line
lst_sort Var #DESCEND
outlst Var ", "
new_line
VarStr = { "Mark" "John" "Martin" "Paul" "Kate" "Ali" "Jane" "Kate" }
lst_sort VarStr #ASCEND
outlst VarStr ", "
new_line
lst_sort VarStr #DESCEND
outlst VarStr ", "
new_line
_block
Lists can be searched with the lst_find command this takes four arguments a variable to return the index of the found value or -1 if it wasn't found. The list to search, the value to search for and the starting index to start the search from.
The following example shows how to use lst_find.
//---------------------------------------
// File: ListFind.e
//---------------------------------------
//---------------------------------------
// Block: Go
//---------------------------------------
block Go
Var = { 2.6 3.25 5.5 78.576 6559.75 456.5 4564.125 546.65 }
lst_find Position Var 4564.125 0
outlst Var ", "
new_line
outl "Position of 4564.125 is " Position
//check what happens if out of range
lst_find Position Var 4564.125 200
outl "Position of 4564.125 is " Position
new_line
//try a string list
Var1 = { "Mark" "John" "Martin" "Paul" "Kate" "Ali" "Jane" "Kate" }
outlst Var1 ", "
new_line
Position = 0
//loop while found a match
while Position != -1
lst_find Position Var1 "Kate" Position
//if found a match then print it
if Position != -1
outl "Position of Kate is " Position
++ Position
_if
_while
_block
Containers allow you to group variables together, a container variable has two parts the container name and the variable name so in the following example the container name is Record1 and the variable names are FirstName and SecondName.
Record1.FirstName = "John"
Record1.SecondName = "Brown"
Containers can be assigned to each other and also passed into blocks by using the ampersand.
@Record2 = @Record1
The following example shows how they can be used.
//---------------------------------------
// File: Container.e
//---------------------------------------
//---------------------------------------
// Block: Display
//---------------------------------------
// Variables:
// @DispTime
//---------------------------------------
block Display @DispTime
outl DispTime.Hour ":" DispTime.Minute ":" DispTime.Second
//update the time
++ DispTime.Hour
++ DispTime.Minute
++ DispTime.Second
_block
//---------------------------------------
// Block: Go
//---------------------------------------
block Go
Time.Hour = 1
Time.Minute = 2
Time.Second = 3
//display the time
Display @Time
//create a new container
@NewTime = @Time
//update the new time
++ NewTime.Hour
++ NewTime.Minute
++ NewTime.Second
//display the 2 times
outl Time.Hour ":" Time.Minute ":" Time.Second
outl NewTime.Hour ":" NewTime.Minute ":" NewTime.Second
_block
Enums are a simple way to create constants the value assigned to each variable gets implemented by 1 with the first variable being given the value of zero
enum <enum name> <var name0> <var name2> <...>
For example the following command would create would create 2 constants STATE_OFF = 0 and STATE_ON = 1
enum STATE OFF ON
The variable names must consist of upper case letters, numbers and under scores only to be valid.