Arrays: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
m (Removed protection from "Arrays")
No edit summary
 
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
__NOEDITSECTION__
{| align="right" style="max-width:30%;"
{|align="right"
| __TOC__
|__TOC__
|}
|}
 
=== What are Arrays? ===
===What are Arrays?===


Arrays are simply variables with a number of elements that can each hold data in memory. To designate a certain element, integers denote the value's position in memory. Don't let talk about memory scare you! Basic does all of the work for you just by using the simple commands in this tutorial. Besides that, you have already been using memory since you created your first variable!
Arrays are simply variables with a number of elements that can each hold data in memory. To designate a certain element, integers denote the value's position in memory. Don't let talk about memory scare you! Basic does all of the work for you just by using the simple commands in this tutorial. Besides that, you have already been using memory since you created your first variable!




Arrays can store element bytes of information like any other variable depending on the type of the variable. The total memory bytes used by an array type can be determined using the table below multiplied by the number of array elements:  
Arrays can store element bytes of information like any other variable depending on the type of the variable. The total memory bytes used by an array type can be determined using the table below multiplied by the number of array elements:


;Standard QBasic/QuickBASIC types
;Standard QBasic/QuickBASIC types
:*[[STRING]] = 1 byte per character
:*[[STRING]] = 1 byte per character
:*[[INTEGER]] = 2 bytes (signed Integer values from -32768 to 32767)  
:*[[INTEGER]] = 2 bytes (signed Integer values from -32768 to 32767)
:*[[LONG]] = 4 bytes (signed Integer values from -2147483648 to 2147483647)
:*[[LONG]] = 4 bytes (signed Integer values from -2147483648 to 2147483647)
:*[[SINGLE]] = 4 bytes (up to 7 digit floating decimal point values)
:*[[SINGLE]] = 4 bytes (up to 7 digit floating decimal point values)
Line 25: Line 23:




While QBasic uses signed values '''QB64''' can use signed or [[_UNSIGNED]] values for [[_BIT]], [[_BYTE]], [[INTEGER]], [[LONG]] or [[_INTEGER64]] variable type values.  
While QBasic uses signed values '''QB64''' can use signed or [[_UNSIGNED]] values for [[_BIT]], [[_BYTE]], [[INTEGER]], [[LONG]] or [[_INTEGER64]] variable type values.


The array's variable type must be determined when the array is created. If no type is used, the default type is [[SINGLE]].
The array's variable type must be determined when the array is created. If no type is used, the default type is [[SINGLE]].
Line 32: Line 30:
<center>[[#toc|Return to Top]]</center>
<center>[[#toc|Return to Top]]</center>


===When do I need an Array?===
=== When do I need an Array? ===


'''When you find yourself creating several variables with numbers in their names.''' This may seem simplistic, but normally programmers tend to use similar names to denote similar value types. This makes arrays perfect in many cases. You can get several values of the same type simply by referring to the element positions in an array. Plus you can have thousands of possibilities when needed.  
'''When you find yourself creating several variables with numbers in their names.''' This may seem simplistic, but normally programmers tend to use similar names to denote similar value types. This makes arrays perfect in many cases. You can get several values of the same type simply by referring to the element positions in an array. Plus you can have thousands of possibilities when needed.


Arrays can be created to hold values until they are needed. They can hold image or file data too! There are many possible uses!  
Arrays can be created to hold values until they are needed. They can hold image or file data too! There are many possible uses!


The only drawback is that the data is lost when the program ends, but array data can be permanently stored in files when you want to save the data. All that you need is a simple loop to transfer the data sequencially or save the entire array to a [[BINARY]] file using '''QB64''' with a simple [[PUT]] statement. You also can retrieve the array data using one [[GET]].
The only drawback is that the data is lost when the program ends, but array data can be permanently stored in files when you want to save the data. All that you need is a simple loop to transfer the data sequencially or save the entire array to a [[BINARY]] file using '''QB64''' with a simple [[PUT]] statement. You also can retrieve the array data using one [[GET]].
Line 43: Line 41:
<center>[[#toc|Return to Top]]</center>
<center>[[#toc|Return to Top]]</center>


===Creating Array Variables===
=== Creating Array Variables ===


First we need to create a place in memory for the array. To do that we have to tell Basic the array's name, type of values it will hold and how many values we need to access. This is called dimensioning an array.  
First we need to create a place in memory for the array. To do that we have to tell Basic the array's name, type of values it will hold and how many values we need to access. This is called dimensioning an array.


How good are you at counting from zero? This might seem like a simple question, but think about this. How many elements would we have if they were numbered 0 through 10? If you said 11, then you were correct. Some people have problems counting when 0 is involved so Basic has an option to allow all arrays to start at 1.  
How good are you at counting from zero? This might seem like a simple question, but think about this. How many elements would we have if they were numbered 0 through 10? If you said 11, then you were correct. Some people have problems counting when 0 is involved so Basic has an option to allow all arrays to start at 1.




Line 57: Line 55:




{{KW|DIM}} reserves the array's name, variable type and number of elements in memory before the array is used. DIM reserves a {{KW|STATIC}} (unchangeable) array unless the {{KW|$DYNAMIC}} (changeable) metacommand is used at the program's start or {{KW|REDIM}} was used to dimension the array originally.
[[DIM]] reserves the array's name, variable type and number of elements in memory before the array is used. DIM reserves a [[STATIC]] (unchangeable) array unless the [[$DYNAMIC]] (changeable) metacommand is used at the program's start or [[REDIM]] was used to dimension the array originally.




Line 63: Line 61:


{{CodeStart}}
{{CodeStart}}
 
{{Cl|DIM}} Array({{Text|100|#F580B1}}) {{Cl|AS}} {{Cl|INTEGER}}
{{Cl|DIM}} Array(100) AS {{Cl|INTEGER}}
 
{{CodeEnd}}
{{CodeEnd}}


An array starts at element 0 unless changed by {{KW|OPTION BASE}} 1 (which can set the start at 1), you can also define the start and end area by [[DIM]]ensioning within a range.
An array starts at element 0 unless changed by [[OPTION BASE]] 1 (which can set the start at 1), you can also define the start and end area by [[DIM]]ensioning within a range.




[[DIM]]ensioning with a range is possible also by using TO between the minimum and  highest elements. Arrays can start and end at any element(index) value up to 32767. '''QB64''' allows larger array sizes!  
[[DIM]]ensioning with a range is possible also by using TO between the minimum and  highest elements. Arrays can start and end at any element(index) value up to 32767. '''QB64''' allows larger array sizes!


''Example 2:'' dimensions an Integer array that can hold 100 values in indices 1 to 100.
''Example 2:'' dimensions an Integer array that can hold 100 values in indices 1 to 100.


{{CodeStart}}
{{CodeStart}}
 
{{Cl|DIM}} Array%({{Text|1|#F580B1}} {{Cl|TO}} {{Text|100|#F580B1}})
{{Cl|DIM}} Array%(1 TO 100)
 
{{CodeEnd}}
{{CodeEnd}}


Line 84: Line 78:




{{KW|REDIM}} can be used to redimension a dynamic array. Any information contained in the array before the REDIM will be lost...however. In order to use {{KW|REDIM}}, the variable must have originally been dimensioned using {{KW|REDIM}}, or a {{KW|$DYNAMIC}} metacommand must be placed at the top of the program.
[[REDIM]] can be used to redimension a dynamic array. Any information contained in the array before the REDIM will be lost...however. In order to use [[REDIM]], the variable must have originally been dimensioned using [[REDIM]], or a [[$DYNAMIC]] metacommand must be placed at the top of the program.


''Example 3:''
''Example 3:''


{{CodeStart}}
{{CodeStart}}
{{Cl|OPTION BASE}} {{Text|1|#F580B1}} {{Text|<nowiki>' placed before any arrays are dimensioned</nowiki>|#919191}}
{{Cl|OPTION BASE}} 1         ' placed before any arrays are dimensioned  
{{Cl|REDIM}} Array$({{Text|1000|#F580B1}}) {{Text|<nowiki>' REDIM creates a dynamic array</nowiki>|#919191}}
{{Cl|REDIM}} Array$(1000)     ' REDIM creates a dynamic array
 
{{CodeEnd}}
{{CodeEnd}}




'''QB64''' has a REDIM {{KW|_PRESERVE}} action which can be used in a REDIM statement in order to preserve the data information in the array.  
'''QB64''' has a REDIM [[_PRESERVE]] action which can be used in a REDIM statement in order to preserve the data information in the array.




Line 102: Line 94:


{{CodeStart}}
{{CodeStart}}
 
{{Cl|REM}}{{Text|<nowiki> </nowiki>|#919191}}{{Cm|$DYNAMIC}}
{{Cl|REM}} {{Cl|$DYNAMIC}}
{{Cl|DIM}} array({{Text|20|#F580B1}})
{{Cl|DIM}} array(20)
array({{Text|10|#F580B1}}) = {{Text|24|#F580B1}}
array(10) = 24
{{Cl|PRINT}} array({{Text|10|#F580B1}})
{{Cl|PRINT}} array(10)
{{Cl|REDIM}} {{Cl|_PRESERVE}} array({{Text|30|#F580B1}})
{{Cl|REDIM}} {{Cl|_PRESERVE}} array(30)
{{Cl|PRINT}} array({{Text|10|#F580B1}})
{{Cl|PRINT}} array(10)
{{Cl|REDIM}} array({{Text|10|#F580B1}})
{{Cl|REDIM}} array(10)
{{Cl|PRINT}} array({{Text|10|#F580B1}})
{{Cl|PRINT}} array(10)
 
{{CodeEnd}}
{{CodeEnd}}


Line 121: Line 111:




{{KW|_PRESERVE}} also allows the lowest index to be changed. The old starting index data value will always be in the lowest new index when the index range limits are changed.
[[_PRESERVE]] also allows the lowest index to be changed. The old starting index data value will always be in the lowest new index when the index range limits are changed.




''Example 5:'' Changing the starting index number using the {{KW|_PRESERVE}} action moves the data.  
''Example 5:'' Changing the starting index number using the [[_PRESERVE]] action moves the data.


{{CodeStart}}
{{CodeStart}}
 
{{Cl|REDIM}} Array$({{Text|1|#F580B1}} {{Cl|TO}} {{Text|50|#F580B1}})
{{Cl|REDIM}} Array$(1 TO 50)
Array$({{Text|1|#F580B1}}) = {{Text|<nowiki>"I'm number one!"</nowiki>|#FFB100}}
Array$(1) = "I'm number one!"
Array$({{Text|50|#F580B1}}) = {{Text|<nowiki>"I'm 50..."</nowiki>|#FFB100}}
Array$(50) = "I'm 50..."
{{Cl|REDIM}} {{Cl|_PRESERVE}} Array$({{Text|51|#F580B1}} {{Cl|TO}} {{Text|100|#F580B1}})
{{Cl|REDIM}} {{Cl|_PRESERVE}} Array$(51 TO 100)
{{Cl|PRINT}} Array$({{Text|51|#F580B1}}) {{Text|<nowiki>' display new start index data</nowiki>|#919191}}
PRINT Array$(51)             ' display new start index data
{{Cl|PRINT}} Array$({{Text|100|#F580B1}}) {{Text|<nowiki>' display new end data</nowiki>|#919191}}
PRINT Array$(100)             ' display new end data
 
{{CodeEnd}}
{{CodeEnd}}


Line 144: Line 132:




''Example 6:'' The memory segment address of the array is defined in {{KW|DEF SEG}}.
''Example 6:'' The memory segment address of the array is defined in [[DEF SEG]].


{{CodeStart}}
{{CodeStart}}
 
{{Cl|DEF SEG}} = {{Cl|VARSEG}}(array({{Text|0|#F580B1}}))
{{Cl|DEF SEG}} = {{Cl|VARSEG}}(array(0))
offset = {{Cl|VARPTR}}(array({{Text|0|#F580B1}})) {{Text|<nowiki>'program designated offset element</nowiki>|#919191}}
offset = {{Cl|VARPTR}}(array(0)) 'program designated offset element  
{{CodeEnd}}
{{CodeEnd}}


NOTE: If {{KW|OPTION BASE}} 1 is used change the 0 to 1. The array start index can be changed when some other data is indexed in the array.
NOTE: If [[OPTION BASE]] 1 is used change the 0 to 1. The array start index can be changed when some other data is indexed in the array.




<center>[[#toc|Return to Top]]</center>
<center>[[#toc|Return to Top]]</center>


===Multi-Dimensional Arrays===
=== Multi-Dimensional Arrays ===


Multiple dimensions are possible to create tables of values. QuickBASIC can use up to 60 dimensions. In '''QB64''' the number of dimensions possible depends on your system memory (a lot more than 60 dimensions). Array data can be saved and restored using file data.  
Multiple dimensions are possible to create tables of values. QuickBASIC can use up to 60 dimensions. In '''QB64''' the number of dimensions possible depends on your system memory (a lot more than 60 dimensions). Array data can be saved and restored using file data.


<center>'''Otherwise the data is lost when a program closes.'''</center>
<center>'''Otherwise the data is lost when a program closes.'''</center>
Line 167: Line 154:


     Setting up a car sales Database: The sales for each month as represented in an array.
     Setting up a car sales Database: The sales for each month as represented in an array.
             
 
                     DIM Vehicle%(12, 4)      ' Vehicle%(month%, type%)
                     DIM Vehicle%(12, 4)      ' Vehicle%(month%, type%)
 
 
                       Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
                       Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
                     '''    1  2  3  4  5  6  7  8  9  10  11  12  ← Month index'''
                     '''    1  2  3  4  5  6  7  8  9  10  11  12  ← Month index'''
         '''Type index ↓'''  -----------------------------------------------
         '''Type index ↓'''  -----------------------------------------------
           Cars    '''1:'''  5  10  15  20  30  19  17  12  24  20  33  30
           Cars    '''1:'''  5  10  15  20  30  19  17  12  24  20  33  30
           Trucks  '''2:'''  3  8  7  10  15    9  11  8  15  10  16  11
           Trucks  '''2:'''  3  8  7  10  15    9  11  8  15  10  16  11
           Vans    '''3:'''  4  6  8  9  7  10  9  7  9  8  10  7  
           Vans    '''3:'''  4  6  8  9  7  10  9  7  9  8  10  7
           SUV      '''4:''' 10  8  8  5  10    8  6  8  10  11  9  8
           SUV      '''4:''' 10  8  8  5  10    8  6  8  10  11  9  8


             To find monthly and yearly totals you could do something like this:
             To find monthly and yearly totals you could do something like this:


                 FOR month% = 1 TO 12
                 FOR month% = 1 TO 12
Line 186: Line 173:
                   YearlySales% = YearlySales% + MonthlySales%
                   YearlySales% = YearlySales% + MonthlySales%
                   PRINT "Monthly =", MonthlySales%; " Yearly ="; YearlySales%; "  "
                   PRINT "Monthly =", MonthlySales%; " Yearly ="; YearlySales%; "  "
                   INPUT$(1)              'stop to view each month  
                   INPUT$(1)              'stop to view each month
                   MonthlySales% = 0      'zero month sales for next months total
                   MonthlySales% = 0      'zero month sales for next months total
                 NEXT
                 NEXT
Line 197: Line 184:


{{CodeStart}}
{{CodeStart}}
 
{{Cl|DIM}} Array({{Text|12|#F580B1}}, {{Text|10|#F580B1}}) {{Text|<nowiki>' 2 dimensions can hold 143 data values</nowiki>|#919191}}
  {{Cl|DIM}} Array(12, 10)           ' 2 dimensions can hold 143 data values  
 
{{CodeEnd}}
{{CodeEnd}}


Line 207: Line 192:


{{CodeStart}}
{{CodeStart}}
 
{{Cl|DIM}} Array({{Text|1|#F580B1}} {{Cl|TO}} {{Text|12|#F580B1}}, {{Text|1|#F580B1}} {{Cl|TO}} {{Text|10|#F580B1}}) {{Text|<nowiki>' 2 dimensions can hold 120 data values</nowiki>|#919191}}
  {{Cl|DIM}} Array(1 TO 12, 1 TO 10) ' 2 dimensions can hold 120 data values
 
{{CodeEnd}}
{{CodeEnd}}


Line 215: Line 198:
<center>[[#toc|Return to Top]]</center>
<center>[[#toc|Return to Top]]</center>


===Working with the Array Elements===
=== Working with the Array Elements ===


Once an array is created, you have to put something in it. As you may have noticed, each element or index has an integer value associated with it. Array(number%) refers to just one element of the array no matter what type it is. '''Arrays CAN have negative numbered elements!'''
Once an array is created, you have to put something in it. As you may have noticed, each element or index has an integer value associated with it. Array(number%) refers to just one element of the array no matter what type it is. '''Arrays CAN have negative numbered elements!'''


You can place data into an array using several methods. The slowest method is directly placing data from the user. You can even use the array as the [[INPUT]] variable. It is recommended that ANY program user entries be limited to text as INPUT will give Redo from start errors if a user enters a string value when a numerical input was desired. Numerical string data can be converted from strings simply by using [[VAL]]. This creates less user errors! NOTE: '''QB64''' does not return a "Redo from start" error as [[INPUT]] monitors entries.
You can place data into an array using several methods. The slowest method is directly placing data from the user. You can even use the array as the [[INPUT]] variable. It is recommended that ANY program user entries be limited to text as INPUT will give Redo from start errors if a user enters a string value when a numerical input was desired. Numerical string data can be converted from strings simply by using [[VAL]]. This creates less user errors! NOTE: '''QB64''' does not return a "Redo from start" error as [[INPUT]] monitors entries.
{{CodeStart}}  
{{CodeStart}}
{{Cl|DO}}
    {{Cl|INPUT}} {{Text|<nowiki>"Enter your age: "</nowiki>|#FFB100}}, howold$
    age% = {{Cl|VAL}}(howold$)
{{Cl|DO...LOOP|LOOP UNTIL}} age% > {{Text|0|#F580B1}}


DO
Playerage%(user%) = age% {{Text|<nowiki>'saves the players age to an indexed player number</nowiki>|#919191}}
{{Cl|INPUT}} "Enter your age: ", howold$
age% = {{cl|VAL}}(howold$)
LOOP UNTIL age% > 0


Playerage%(user%) = age%  'saves the players age to an indexed player number
{{Cl|PRINT}} Playerage%(user%) {{Text|<nowiki>'print array element to screen to verify entry</nowiki>|#919191}}
 
PRINT Playerage%(user%)   'print array element to screen to verify entry
 
user% = user% + 1          'increment user number when all data has been entered


user% = user% + {{Text|1|#F580B1}} {{Text|<nowiki>'increment user number when all data has been entered</nowiki>|#919191}}
{{CodeEnd}}
{{CodeEnd}}


Line 240: Line 221:
'''To pass array data to a [[SUB]] or [[FUNCTION]] parameter, an empty element bracket passes all elements while a number only passes one specified element of the array.'''
'''To pass array data to a [[SUB]] or [[FUNCTION]] parameter, an empty element bracket passes all elements while a number only passes one specified element of the array.'''


===Array Indexing===
=== Array Indexing ===


Arrays can be set up to hold more than one kind of data, by indexing the two or more kinds of data. To do this, the programmer reserves one set of element or index values for each kind of data. The type of values MUST be the same except when using a [[TYPE]] definition value.
Arrays can be set up to hold more than one kind of data, by indexing the two or more kinds of data. To do this, the programmer reserves one set of element or index values for each kind of data. The type of values MUST be the same except when using a [[TYPE]] definition value.
Line 247: Line 228:
<center>[[#toc|Return to Top]]</center>
<center>[[#toc|Return to Top]]</center>


===Sorting Array Data===
=== Sorting Array Data ===


Arrays can be sorted numerically or alphabetically using various sorting routines. Commonly [[SWAP]] is used to trade element values in descending or ascending order.
Arrays can be sorted numerically or alphabetically using various sorting routines. Commonly [[SWAP]] is used to trade element values in descending or ascending order.
Line 254: Line 235:
<center>[[#toc|Return to Top]]</center>
<center>[[#toc|Return to Top]]</center>


===Saving Array Data===
=== Saving Array Data ===


Since variables and arrays exist in memory, data is lost when a program closes. To preserve program data you must either create a permanent [[DATA]] field or save the data to files.
Since variables and arrays exist in memory, data is lost when a program closes. To preserve program data you must either create a permanent [[DATA]] field or save the data to files.
Line 263: Line 244:
<center>[[#toc|Return to Top]]</center>
<center>[[#toc|Return to Top]]</center>


===Image Arrays===
=== Image Arrays ===


[[INTEGER]] arrays are used to hold image information when using the following graphic procedures: [[GET (graphics statement)|GET]], [[PUT (graphics statement)| PUT]], [[BSAVE]] and [[BLOAD]].  
[[INTEGER]] arrays are used to hold image information when using the following graphic procedures: [[GET (graphics statement)|GET]], [[PUT (graphics statement)| PUT]], [[BSAVE]] and [[BLOAD]].




Line 271: Line 252:


{{CodeStart}}
{{CodeStart}}
wide& = 20: deep& = 20 'change the sizes for any image area
wide& = {{Text|20|#F580B1}}: deep& = {{Text|20|#F580B1}} {{Text|<nowiki>'change the sizes for any image area</nowiki>|#919191}}
{{Cl|DIM}} array(wide& * deep&) AS {{Cl|INTEGER}}
{{Cl|DIM}} array(wide& * deep&) {{Cl|AS}} {{Cl|INTEGER}}
{{Cl|LINE}} (0, 0)-(wide& - 1, deep& - 1), 12, B 'the box border is all that you need to color.
{{Cl|LINE}} ({{Text|0|#F580B1}}, {{Text|0|#F580B1}})-(wide& - {{Text|1|#F580B1}}, deep& - {{Text|1|#F580B1}}), {{Text|12|#F580B1}}, B {{Text|<nowiki>'the box border is all that you need to color.</nowiki>|#919191}}
{{Cl|GET (graphics statement)|GET}} (0, 0)-(wide& - 1, deep& - 1), array(0)
{{Cl|GET (general)|GET}} ({{Text|0|#F580B1}}, {{Text|0|#F580B1}})-(wide& - {{Text|1|#F580B1}}, deep& - {{Text|1|#F580B1}}), array({{Text|0|#F580B1}})
{{Cl|FOR...NEXT|FOR}} s& = wide& * deep& {{Cl|TO}} 0 {{Cl|STEP}} -1
{{Cl|FOR}} s& = wide& * deep& {{Cl|TO}} {{Text|0|#F580B1}} {{Cl|STEP}} {{Text|-1|#F580B1}}
  {{Cl|IF...THEN|IF}} array(s&) {{Cl|THEN}} arraysize& = s&: {{Cl|EXIT}} {{Cl|FOR...NEXT|FOR}}
    {{Cl|IF}} array(s&) {{Cl|THEN}} arraysize& = s&: {{Cl|EXIT FOR}}
{{Cl|NEXT}}
{{Cl|NEXT}}
{{Cl|PRINT}} arraysize&
{{Cl|PRINT}} arraysize&
{{Cl|END}} '' ''
{{Cl|END}}
{{CodeEnd}}
{{CodeEnd}}
<center>'''Note: QB64 can [[GET (graphics statement)|GET]] the entire SCREEN 12 area into one array!'''</center>
<center>'''Note: QB64 can [[GET (graphics statement)|GET]] the entire SCREEN 12 area into one array!'''</center>


See also: [[Creating Sprite Masks]]
See also: [[Creating Sprite Masks]]
Line 289: Line 269:
<center>[[#toc|Return to Top]]</center>
<center>[[#toc|Return to Top]]</center>


===SHARED Arrays===
=== SHARED Arrays ===


When array data is used with [[SUB]] or [[FUNCTION]] procedures they can be passed as parameters. When passed as parameters, a specific index or the entire array can be used. To specify an index, the array is passed with the element number. If the entire array is passed, the element brackets should be empty. Example: '''{{text|SUB SubName (ArrayName() AS INTEGER)|green}}'''
When array data is used with [[SUB]] or [[FUNCTION]] procedures they can be passed as parameters. When passed as parameters, a specific index or the entire array can be used. To specify an index, the array is passed with the element number. If the entire array is passed, the element brackets should be empty. Example: '''{{Text|SUB SubName (ArrayName() AS INTEGER)|green}}'''




Arrays can also be [[SHARED]] by all procedures by using [[DIM]] [[SHARED]] when the array is created. This allows the array data to be used in the main procedure and all sub-procedures.  
Arrays can also be [[SHARED]] by all procedures by using [[DIM]] [[SHARED]] when the array is created. This allows the array data to be used in the main procedure and all sub-procedures.




Line 309: Line 289:




{{CodeStart}} '' ''
{{CodeStart}}
{{Cl|FUNCTION}} ScanKey% (scancode%)
{{Cl|FUNCTION}} {{Text|ScanKey%|#55FF55}} (scancode%)
{{Cl|STATIC}} Ready%, keyflags%()
    {{Cl|STATIC}} Ready%, keyflags%()
{{Cl|IF}} {{Cl|NOT}} Ready% {{Cl|THEN}} {{Cl|REDIM}} keyflags%(0 {{Cl|TO}} 127): Ready% = -1  
    {{Cl|IF}} {{Cl|NOT}} Ready% {{Cl|THEN}} {{Cl|REDIM}} keyflags%({{Text|0|#F580B1}} {{Cl|TO}} {{Text|127|#F580B1}}): Ready% = {{Text|-1|#F580B1}}
i% = {{Cl|INP}}({{Cl|&H}}60) 'read keyboard states
    i% = {{Cl|INP}}({{Text|&H60|#F580B1}}) {{Text|<nowiki>'read keyboard states</nowiki>|#919191}}
{{Cl|IF}} (i% {{Cl|AND (boolean)|AND}} 128) {{Cl|THEN}} keyflags%(i% {{Cl|XOR (boolean)|XOR}} 128) = 0
    {{Cl|IF}} (i% {{Cl|AND (boolean)|AND}} {{Text|128|#F580B1}}) {{Cl|THEN}} keyflags%(i% {{Cl|XOR}} {{Text|128|#F580B1}}) = {{Text|0|#F580B1}}
{{Cl|IF}} (i% {{Cl|AND (boolean)|AND}} 128) = 0 {{Cl|THEN}} keyflags%(i%) = -1
    {{Cl|IF}} (i% {{Cl|AND (boolean)|AND}} {{Text|128|#F580B1}}) = {{Text|0|#F580B1}} {{Cl|THEN}} keyflags%(i%) = {{Text|-1|#F580B1}}
K$ = {{Cl|INKEY$}}
    K$ = {{Cl|INKEY$}}
ScanKey% = keyflags%(scancode%)
    {{Text|ScanKey%|#55FF55}} = keyflags%(scancode%)
{{Cl|IF}} scancode% = 0 {{Cl|THEN}} Ready% = 0 'allows program to reset all values to 0 with a REDIM
    {{Cl|IF}} scancode% = {{Text|0|#F580B1}} {{Cl|THEN}} Ready% = {{Text|0|#F580B1}} {{Text|<nowiki>'allows program to reset all values to 0 with a REDIM</nowiki>|#919191}}
{{Cl|END FUNCTION}} '' ''
{{Cl|END FUNCTION}}
{{CodeEnd}}
{{CodeEnd}}
:''Explanation:'' The STATIC ''Ready%'' value is always 0 when a procedure is first run. [[NOT]] zero makes the IF statement True so the array is created. The ''Ready%'' value is then changed to anything but zero to make NOT ''Ready%'' False when the procedure is called again. The FUNCTION is referenced just like an array would be. The value it returns is either 0 or -1 to verify that a certain key was released or pressed respectively. The keyboard status is also updated in the array each call. If the ''scancode%'' sent is 0(a key scan code that does not exist), the array is reset(re-dimensioned) on the next call as ''Ready%'' is reset to zero.
:''Explanation:'' The STATIC ''Ready%'' value is always 0 when a procedure is first run. [[NOT]] zero makes the IF statement True so the array is created. The ''Ready%'' value is then changed to anything but zero to make NOT ''Ready%'' False when the procedure is called again. The FUNCTION is referenced just like an array would be. The value it returns is either 0 or -1 to verify that a certain key was released or pressed respectively. The keyboard status is also updated in the array each call. If the ''scancode%'' sent is 0(a key scan code that does not exist), the array is reset(re-dimensioned) on the next call as ''Ready%'' is reset to zero.
Line 326: Line 306:
<center>[[#toc|Return to Top]]</center>
<center>[[#toc|Return to Top]]</center>


 
=== Preserving Data ===
===Preserving Data===


[[_PRESERVE]] can preserve data when [[REDIM]] or [[$DYNAMIC]] is used to create dynamic arrays. The current array data can be preserved while changing the array element size. Increasing the size will preserve data inside of existing indices in the resized array. If the size is decreased, only the existing indices values will be preserved. '''The array [[TYPE]] and number of array dimensions cannot be changed!'''
[[_PRESERVE]] can preserve data when [[REDIM]] or [[$DYNAMIC]] is used to create dynamic arrays. The current array data can be preserved while changing the array element size. Increasing the size will preserve data inside of existing indices in the resized array. If the size is decreased, only the existing indices values will be preserved. '''The array [[TYPE]] and number of array dimensions cannot be changed!'''




<center>'''{{text|REDIM _PRESERVE ArrayName(1 TO 100)|green}}'''</center>
<center>'''{{Text|REDIM _PRESERVE ArrayName(1 TO 100)|green}}'''</center>




<center>[[#toc|Return to Top]]</center>
<center>[[#toc|Return to Top]]</center>


===See Also===


{{PageNavigation}}
{{PageReferences}}

Latest revision as of 12:24, 19 November 2024

What are Arrays?

Arrays are simply variables with a number of elements that can each hold data in memory. To designate a certain element, integers denote the value's position in memory. Don't let talk about memory scare you! Basic does all of the work for you just by using the simple commands in this tutorial. Besides that, you have already been using memory since you created your first variable!


Arrays can store element bytes of information like any other variable depending on the type of the variable. The total memory bytes used by an array type can be determined using the table below multiplied by the number of array elements:

Standard QBasic/QuickBASIC types
  • STRING = 1 byte per character
  • INTEGER = 2 bytes (signed Integer values from -32768 to 32767)
  • LONG = 4 bytes (signed Integer values from -2147483648 to 2147483647)
  • SINGLE = 4 bytes (up to 7 digit floating decimal point values)
  • DOUBLE = 8 bytes (up to 15 digit floating point values)
New types introduced by QB64
  • _BIT * 8 = 1 byte(signed Integer values of -1 or 0)
  • _BYTE = 1 byte (signed Integer values from -128 to 127)
  • _INTEGER64 = 8 bytes (signed values from -9223372036854775808 to 9223372036854775807
  • _FLOAT = 10 bytes (better than Double accuracy)


While QBasic uses signed values QB64 can use signed or _UNSIGNED values for _BIT, _BYTE, INTEGER, LONG or _INTEGER64 variable type values.

The array's variable type must be determined when the array is created. If no type is used, the default type is SINGLE.


Return to Top

When do I need an Array?

When you find yourself creating several variables with numbers in their names. This may seem simplistic, but normally programmers tend to use similar names to denote similar value types. This makes arrays perfect in many cases. You can get several values of the same type simply by referring to the element positions in an array. Plus you can have thousands of possibilities when needed.

Arrays can be created to hold values until they are needed. They can hold image or file data too! There are many possible uses!

The only drawback is that the data is lost when the program ends, but array data can be permanently stored in files when you want to save the data. All that you need is a simple loop to transfer the data sequencially or save the entire array to a BINARY file using QB64 with a simple PUT statement. You also can retrieve the array data using one GET.


Return to Top

Creating Array Variables

First we need to create a place in memory for the array. To do that we have to tell Basic the array's name, type of values it will hold and how many values we need to access. This is called dimensioning an array.

How good are you at counting from zero? This might seem like a simple question, but think about this. How many elements would we have if they were numbered 0 through 10? If you said 11, then you were correct. Some people have problems counting when 0 is involved so Basic has an option to allow all arrays to start at 1.


OPTION BASE 1 will cause all array dimensions to begin at 1, OPTION BASE 0 will cause all dimensions to begin at 0. The default when just using the maximum array size is 0. Use whatever option you are comfortable with.


Arrays in QuickBASIC 4.5 and QBasic are limited to 32767 elements, while arrays in QB64 are limited to 2147483647 elements (over 2 billion). When the 64-bit version of QB64 is implemented 9223372036854775807 elements will be the limit (but only on 64-bit systems).


DIM reserves the array's name, variable type and number of elements in memory before the array is used. DIM reserves a STATIC (unchangeable) array unless the $DYNAMIC (changeable) metacommand is used at the program's start or REDIM was used to dimension the array originally.


Example 1: Dimensions an array named 'Array' that is capable of holding 101 integer values including element 0. 

DIM Array(100) AS INTEGER

An array starts at element 0 unless changed by OPTION BASE 1 (which can set the start at 1), you can also define the start and end area by DIMensioning within a range.


DIMensioning with a range is possible also by using TO between the minimum and highest elements. Arrays can start and end at any element(index) value up to 32767. QB64 allows larger array sizes!

Example 2: dimensions an Integer array that can hold 100 values in indices 1 to 100. 

DIM Array%(1 TO 100)

Note: The array type can also be designated by variable suffixes as % designates Integers above.


REDIM can be used to redimension a dynamic array. Any information contained in the array before the REDIM will be lost...however. In order to use REDIM, the variable must have originally been dimensioned using REDIM, or a $DYNAMIC metacommand must be placed at the top of the program.

Example 3: 

OPTION BASE 1 ' placed before any arrays are dimensioned
REDIM Array$(1000) ' REDIM creates a dynamic array


QB64 has a REDIM _PRESERVE action which can be used in a REDIM statement in order to preserve the data information in the array.


Example 4: REDIM without the _PRESERVE action erases the array contents 

REM $DYNAMIC
DIM array(20)
array(10) = 24
PRINT array(10)
REDIM _PRESERVE array(30)
PRINT array(10)
REDIM array(10)
PRINT array(10)

24
24
0


_PRESERVE also allows the lowest index to be changed. The old starting index data value will always be in the lowest new index when the index range limits are changed.


Example 5: Changing the starting index number using the _PRESERVE action moves the data. 

REDIM Array$(1 TO 50)
Array$(1) = "I'm number one!"
Array$(50) = "I'm 50..."
REDIM _PRESERVE Array$(51 TO 100)
PRINT Array$(51) ' display new start index data
PRINT Array$(100) ' display new end data

I'm number one!
I'm 50...


Example 6: The memory segment address of the array is defined in DEF SEG. 

DEF SEG = VARSEG(array(0))
offset = VARPTR(array(0)) 'program designated offset element

NOTE: If OPTION BASE 1 is used change the 0 to 1. The array start index can be changed when some other data is indexed in the array.


Return to Top

Multi-Dimensional Arrays

Multiple dimensions are possible to create tables of values. QuickBASIC can use up to 60 dimensions. In QB64 the number of dimensions possible depends on your system memory (a lot more than 60 dimensions). Array data can be saved and restored using file data.

Otherwise the data is lost when a program closes.
                              TWO DIMENSIONAL ARRAY TABLES

    Setting up a car sales Database: The sales for each month as represented in an array.

                     DIM Vehicle%(12, 4)       ' Vehicle%(month%, type%)

                       Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
                        1   2   3   4   5   6   7   8   9   10  11  12  ← Month index
         Type index ↓  -----------------------------------------------
           Cars     1:  5  10  15  20  30   19  17  12  24  20  33  30
           Trucks   2:  3   8   7  10  15    9  11   8  15  10  16  11
           Vans     3:  4   6   8   9   7   10   9   7   9   8  10   7
           SUV      4: 10   8   8   5  10    8   6   8  10  11   9   8

             To find monthly and yearly totals you could do something like this:

                FOR month% = 1 TO 12
                   FOR type% = 1 TO 4
                      MonthlySales% = MonthlySales% + Vehicle%(month%, type%)
                   NEXT
                   YearlySales% = YearlySales% + MonthlySales%
                   PRINT "Monthly =", MonthlySales%; " Yearly ="; YearlySales%; "   "
                   INPUT$(1)               'stop to view each month
                   MonthlySales% = 0       'zero month sales for next months total
                NEXT


Example 7: Creating a two-dimensional array. A comma separates each dimension size. 

DIM Array(12, 10) ' 2 dimensions can hold 143 data values

One dimension could hold the month number and the other the number of items sold in 10 categories.

Example 8: Dimensioning using index ranges. 

DIM Array(1 TO 12, 1 TO 10) ' 2 dimensions can hold 120 data values


Return to Top

Working with the Array Elements

Once an array is created, you have to put something in it. As you may have noticed, each element or index has an integer value associated with it. Array(number%) refers to just one element of the array no matter what type it is. Arrays CAN have negative numbered elements!

You can place data into an array using several methods. The slowest method is directly placing data from the user. You can even use the array as the INPUT variable. It is recommended that ANY program user entries be limited to text as INPUT will give Redo from start errors if a user enters a string value when a numerical input was desired. Numerical string data can be converted from strings simply by using VAL. This creates less user errors! NOTE: QB64 does not return a "Redo from start" error as INPUT monitors entries. 

DO
    INPUT "Enter your age: ", howold$
    age% = VAL(howold$)
LOOP UNTIL age% > 0

Playerage%(user%) = age% 'saves the players age to an indexed player number

PRINT Playerage%(user%) 'print array element to screen to verify entry

user% = user% + 1 'increment user number when all data has been entered

You could use several arrays to hold the player's name, high scores, etc. Once the data is in the array, it can be used until the program ends. Then the data is lost, but you can store the data to a file before closing the program simply by using a loop. See next section.


To pass array data to a SUB or FUNCTION parameter, an empty element bracket passes all elements while a number only passes one specified element of the array.

Array Indexing

Arrays can be set up to hold more than one kind of data, by indexing the two or more kinds of data. To do this, the programmer reserves one set of element or index values for each kind of data. The type of values MUST be the same except when using a TYPE definition value.


Return to Top

Sorting Array Data

Arrays can be sorted numerically or alphabetically using various sorting routines. Commonly SWAP is used to trade element values in descending or ascending order.


Return to Top

Saving Array Data

Since variables and arrays exist in memory, data is lost when a program closes. To preserve program data you must either create a permanent DATA field or save the data to files.

The next time a program is used, it can OPEN that file and quickly restore all of the array data using a loop or QB64 can GET the entire file's data in one GET. Use LINE INPUT # to set the array sizes by counting the number of data rows in a file if you used a WRITE CSV(comma separated values) or a PRINT # sequencial file. The number of records in a TYPE or FIELD defined RANDOM access file can be found by dividing the record size into the LOF. You may want to make the array slightly larger for new entries.


Return to Top

Image Arrays

INTEGER arrays are used to hold image information when using the following graphic procedures: GET, PUT, BSAVE and BLOAD.


The INTEGER array size can be estimated by multiplying the height by the width of the image area. To find the actual size needed you can use the following routine to count backwards until something is found in the array. The example below returns the array size required to create a 20 by 20 image: 

wide& = 20: deep& = 20 'change the sizes for any image area
DIM array(wide& * deep&) AS INTEGER
LINE (0, 0)-(wide& - 1, deep& - 1), 12, B 'the box border is all that you need to color.
GET (0, 0)-(wide& - 1, deep& - 1), array(0)
FOR s& = wide& * deep& TO 0 STEP -1
    IF array(s&) THEN arraysize& = s&: EXIT FOR
NEXT
PRINT arraysize&
END
Note: QB64 can GET the entire SCREEN 12 area into one array!

See also: Creating Sprite Masks


Return to Top

SHARED Arrays

When array data is used with SUB or FUNCTION procedures they can be passed as parameters. When passed as parameters, a specific index or the entire array can be used. To specify an index, the array is passed with the element number. If the entire array is passed, the element brackets should be empty. Example: SUB SubName (ArrayName() AS INTEGER)


Arrays can also be SHARED by all procedures by using DIM SHARED when the array is created. This allows the array data to be used in the main procedure and all sub-procedures.


COMMON allows Array data to be shared between program modules when used with CHAIN. The two modules can share any variable values in a list of variables. The lists can use different variable names, but the types of values MUST be listed in the SAME order in both modules.


COMMON SHARED allows data to be shared between both modules and SUB or FUNCTION procedures.


Arrays can be created inside of SUB or FUNCTION procedures by using DIM or REDIM. Also SHARED(without DIM) can be used inside of a sub-procedure to share variable data with the Main program module ONLY. Other sub-procedures cannot reference the data. To share array data with other sub-procedures, array FUNCTIONS can be created that use the internal array elements as a parameter. QB64 may allow sub-procedures to share values with other procedures soon!


Arrays can be set as STATIC to retain the values when a sub-procedure is exited. The values will be retained until changed inside of the procedure. If the procedure creates it's own array, you can use a STATIC True or False variable to determine when to DIM or REDIM a STATIC array so that values are not lost every call. The Ready% variable below DIMs the array when the function is first used: 


FUNCTION ScanKey% (scancode%)
    STATIC Ready%, keyflags%()
    IF NOT Ready% THEN REDIM keyflags%(0 TO 127): Ready% = -1
    i% = INP(&H60) 'read keyboard states
    IF (i% AND 128) THEN keyflags%(i% XOR 128) = 0
    IF (i% AND 128) = 0 THEN keyflags%(i%) = -1
    K$ = INKEY$
    ScanKey% = keyflags%(scancode%)
    IF scancode% = 0 THEN Ready% = 0 'allows program to reset all values to 0 with a REDIM
END FUNCTION
Explanation: The STATIC Ready% value is always 0 when a procedure is first run. NOT zero makes the IF statement True so the array is created. The Ready% value is then changed to anything but zero to make NOT Ready% False when the procedure is called again. The FUNCTION is referenced just like an array would be. The value it returns is either 0 or -1 to verify that a certain key was released or pressed respectively. The keyboard status is also updated in the array each call. If the scancode% sent is 0(a key scan code that does not exist), the array is reset(re-dimensioned) on the next call as Ready% is reset to zero.


Return to Top

Preserving Data

_PRESERVE can preserve data when REDIM or $DYNAMIC is used to create dynamic arrays. The current array data can be preserved while changing the array element size. Increasing the size will preserve data inside of existing indices in the resized array. If the size is decreased, only the existing indices values will be preserved. The array TYPE and number of array dimensions cannot be changed!


REDIM _PRESERVE ArrayName(1 TO 100)


Return to Top


QB64 Programming References

Wiki Pages
Main Page with Articles and Tutorials
QB64 specific keywords (alphabetical)
Original QBasic keywords (alphabetical)
QB64 OpenGL keywords (alphabetical)
Keywords by Usage
Got a question about something?
Frequently Asked Questions about QB64
QB64 Phoenix Edition Community Forum
Links to other QBasic Sites:
Pete's QBasic Forum
Pete's QBasic Downloads
Retrieved from "https://qb64phoenix.com/qb64wiki/index.php?title=Arrays&oldid=9218"