Difference between revisions of "Documentation/BASIC Guide/Arrays"
m (→Array Creation, value assignment and access example: +")") |
m |
||
(8 intermediate revisions by 4 users not shown) | |||
Line 8: | Line 8: | ||
{{DISPLAYTITLE:Arrays}} | {{DISPLAYTITLE:Arrays}} | ||
__NOTOC__ | __NOTOC__ | ||
− | In addition to simple variables (scalars), {{ | + | In addition to simple variables (scalars), {{AOo}} Basic also supports arrays (data fields). A data field contains several variables, which are addressed through an index. |
= Defining Arrays = | = Defining Arrays = | ||
Line 17: | Line 17: | ||
An array declaration is similar to that of a simple variable declaration. However, unlike the variable declaration, the array name is followed by parentheses which contain the specifications for the number of elements. The expression | An array declaration is similar to that of a simple variable declaration. However, unlike the variable declaration, the array name is followed by parentheses which contain the specifications for the number of elements. The expression | ||
− | < | + | <syntaxhighlight lang="oobas"> |
Dim MyArray(3) | Dim MyArray(3) | ||
− | </ | + | </syntaxhighlight> |
declares an array that has four variables of the variant data type, namely <tt>MyArray(0)</tt>, <tt>MyArray(1)</tt>, <tt>MyArray(2)</tt>, and <tt>MyArray(3)</tt>. | declares an array that has four variables of the variant data type, namely <tt>MyArray(0)</tt>, <tt>MyArray(1)</tt>, <tt>MyArray(2)</tt>, and <tt>MyArray(3)</tt>. | ||
Line 25: | Line 25: | ||
You can also declare type-specific variables in an array. For example, the following line declares an array with four integer variables: | You can also declare type-specific variables in an array. For example, the following line declares an array with four integer variables: | ||
− | < | + | <syntaxhighlight lang="oobas"> |
Dim MyInteger(3) As Integer | Dim MyInteger(3) As Integer | ||
− | </ | + | </syntaxhighlight> |
In the previous examples, the index for the array always begins with the standard start value of zero. As an alternative, a validity range with start and end values can be specified for the data field declaration. The following example declares a data field that has six integer values and which can be addressed using the indexes 5 to 10: | In the previous examples, the index for the array always begins with the standard start value of zero. As an alternative, a validity range with start and end values can be specified for the data field declaration. The following example declares a data field that has six integer values and which can be addressed using the indexes 5 to 10: | ||
− | < | + | <syntaxhighlight lang="oobas"> |
Dim MyInteger(5 To 10) As Integer | Dim MyInteger(5 To 10) As Integer | ||
− | </ | + | </syntaxhighlight> |
The indexes do not need to be positive values. The following example also shows a correct declaration, but with negative data field limits: | The indexes do not need to be positive values. The following example also shows a correct declaration, but with negative data field limits: | ||
− | < | + | <syntaxhighlight lang="oobas"> |
Dim MyInteger(-10 To -5) As Integer | Dim MyInteger(-10 To -5) As Integer | ||
− | </ | + | </syntaxhighlight> |
It declares an integer data field with 6 values that can be addressed using the indexes -10 to -5. | It declares an integer data field with 6 values that can be addressed using the indexes -10 to -5. | ||
− | There are | + | There are no practical limits on the indexes or on the number of elements in an array, so long as there is enough memory: |
− | + | <syntaxhighlight lang="oobas"> | |
− | + | Dim s(-53000 to 89000) As String | |
− | + | s(-52000) = "aa" | |
+ | s(79999) = "bb" | ||
+ | print s(-52000), s(79999) | ||
+ | </syntaxhighlight> | ||
− | {{Documentation/ | + | {{Documentation/VBAnote|Other limit values sometimes apply for data field indexes in VBA. The same also applies to the maximum number of elements possible per dimension. The values valid there can be found in the relevant VBA documentation.}} |
==Specified Value for Start Index== | ==Specified Value for Start Index== | ||
Line 55: | Line 58: | ||
The start index of a data field usually begins with the value 0. Alternatively, you can change the start index for all data field declarations to the value 1 by using the call: | The start index of a data field usually begins with the value 0. Alternatively, you can change the start index for all data field declarations to the value 1 by using the call: | ||
− | < | + | <syntaxhighlight lang="oobas"> |
Option Base 1 | Option Base 1 | ||
− | </ | + | </syntaxhighlight> |
− | The call must be included in the header of a module if you want it to apply to all array declarations in the module. However, this call does not affect the UNO sequences that are defined through the {{ | + | The call must be included in the header of a module if you want it to apply to all array declarations in the module. However, this call does not affect the UNO sequences that are defined through the {{AOo}} API whose index always begins with 0. To improve clarity, you should avoid using <tt>Option Base 1</tt>. |
The number of elements in an array is not affected if you use <tt>Option Base 1</tt>, only the start index changes. The declaration | The number of elements in an array is not affected if you use <tt>Option Base 1</tt>, only the start index changes. The declaration | ||
− | < | + | <syntaxhighlight lang="oobas"> |
Option Base 1 | Option Base 1 | ||
' ... | ' ... | ||
Dim MyInteger(3) | Dim MyInteger(3) | ||
− | </ | + | </syntaxhighlight> |
creates 4 integer variables which can be described with the expressions <tt>MyInteger(1)</tt>, <tt>MyInteger(2)</tt>, <tt>MyInteger(3)</tt>, and <tt>MyInteger(4)</tt>. | creates 4 integer variables which can be described with the expressions <tt>MyInteger(1)</tt>, <tt>MyInteger(2)</tt>, <tt>MyInteger(3)</tt>, and <tt>MyInteger(4)</tt>. | ||
− | {{Documentation/ | + | {{Documentation/VBAnote|In {{OOo}} Basic, the expression <tt>Option Base 1</tt> does not affect the number of elements in an array as it does in VBA. It is, rather, the start index which moves in {{AOo}} Basic. While the declaration <tt>MyInteger(3)</tt> creates three integer values in VBA with the indexes 1 to 3, the same declaration in {{AOo}} Basic creates four integer values with the indexes 1 to 4. By using <tt>Option Compatible</tt>, {{AOo}} Basic behaves like VBA.}} |
==Multi-Dimensional Data Fields== | ==Multi-Dimensional Data Fields== | ||
− | In addition to single dimensional data fields, {{ | + | In addition to single dimensional data fields, {{AOo}} Basic also supports work with multi-dimensional data fields. The corresponding dimensions are separated from one another by commas. The example |
− | < | + | <syntaxhighlight lang="oobas"> |
Dim MyIntArray(5, 5) As Integer | Dim MyIntArray(5, 5) As Integer | ||
− | </ | + | </syntaxhighlight> |
defines an integer array with two dimensions, each with 6 indexes (can be addressed through the indexes 0 to 5). The entire array can record a total of 6 x 6 = 36 integer values. | defines an integer array with two dimensions, each with 6 indexes (can be addressed through the indexes 0 to 5). The entire array can record a total of 6 x 6 = 36 integer values. | ||
− | You can define hundreds of dimensions in {{ | + | You can define hundreds of dimensions in {{AOo}} Basic Arrays; however, the amount of available memory limits the number of dimensions you can have. |
==Dynamic Changes in the Dimensions of Data Fields== | ==Dynamic Changes in the Dimensions of Data Fields== | ||
− | The previous examples are based on data fields of a specified dimension. You can also define arrays in which the dimension of the data fields dynamically changes. For example, you can define an array to contain all | + | The previous examples are based on data fields of a specified dimension. You can also define arrays in which the dimension of the data fields dynamically changes. For example, you can define an array to contain all the words in a text that begin with the letter A. As the number of these words is initially unknown, you need to be able to subsequently change the field limits. To do this in {{AOo}} Basic, use the following call: |
− | < | + | <syntaxhighlight lang="oobas"> |
ReDim MyArray(10) | ReDim MyArray(10) | ||
− | </ | + | </syntaxhighlight> |
− | {{Documentation/ | + | {{Documentation/VBAnote|Unlike VBA, where you can only dimension dynamic arrays by using <tt>Dim MyArray()</tt>, {{OOo}} Basic lets you change both static and dynamic arrays using <tt>ReDim</tt>.}} |
The following example changes the dimension of the initial array so that it can record 11 or 21 values: | The following example changes the dimension of the initial array so that it can record 11 or 21 values: | ||
− | < | + | <syntaxhighlight lang="oobas"> |
Dim MyArray(4) As Integer ' Declaration with five elements | Dim MyArray(4) As Integer ' Declaration with five elements | ||
' ... | ' ... | ||
Line 103: | Line 106: | ||
' ... | ' ... | ||
ReDim MyArray(20) As Integer ' Increase to 21 elements | ReDim MyArray(20) As Integer ' Increase to 21 elements | ||
− | </ | + | </syntaxhighlight> |
When you reset the dimensions of an array, you can use any of the options outlined in the previous sections. This includes declaring multi-dimensional data fields and specifying explicit start and end values. When the dimensions of the data field are changed, all contents are lost. If you want to keep the original values, use the <tt>Preserve</tt> command: | When you reset the dimensions of an array, you can use any of the options outlined in the previous sections. This includes declaring multi-dimensional data fields and specifying explicit start and end values. When the dimensions of the data field are changed, all contents are lost. If you want to keep the original values, use the <tt>Preserve</tt> command: | ||
− | < | + | <syntaxhighlight lang="oobas"> |
Dim MyArray(10) As Integer ' Defining the initial | Dim MyArray(10) As Integer ' Defining the initial | ||
' dimensions | ' dimensions | ||
Line 114: | Line 117: | ||
' data field, while | ' data field, while | ||
' retaining content | ' retaining content | ||
− | </ | + | </syntaxhighlight> |
When you use <tt>Preserve</tt>, ensure that the number of dimensions and the type of variables remain the same. | When you use <tt>Preserve</tt>, ensure that the number of dimensions and the type of variables remain the same. | ||
− | {{Documentation/ | + | {{Documentation/VBAnote|Unlike VBA, where only the upper limit of the last dimension of a data field can be changed through <tt>Preserve</tt>, {{AOo}} Basic lets you change other dimensions as well.}} |
If you use <tt>ReDim</tt> with <tt>Preserve</tt>, you must use the same data type as specified in the original data field declaration. | If you use <tt>ReDim</tt> with <tt>Preserve</tt>, you must use the same data type as specified in the original data field declaration. | ||
+ | |||
+ | ==Determining the Dimensions of Data Fields== | ||
+ | |||
+ | |||
+ | Functions <tt>LBound()</tt> and <tt>UBound()</tt> return respectively the lowest permitted index value and the highest permitted index value of an array. This is useful when an array has changed its dimensions. | ||
+ | |||
+ | <syntaxhighlight lang="oobas"> | ||
+ | Dim MyArray(10) As Integer | ||
+ | ' ... some instructions | ||
+ | Dim n As Integer | ||
+ | n = 47 ' could be the result of a computation | ||
+ | Redim MyArray(n) As Integer | ||
+ | MsgBox(LBound(MyArray)) ' displays : 0 | ||
+ | MsgBox(UBound(MyArray)) ' displays : 47 | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | For a multi-dimensional array you need to specify the position (1 to n) of the index you want to know the permitted lower and upper values: | ||
+ | |||
+ | <syntaxhighlight lang="oobas"> | ||
+ | Dim MyArray(10, 13 to 28) As Integer | ||
+ | MsgBox(LBound(MyArray, 2)) ' displays : 13 | ||
+ | MsgBox(UBound(MyArray, 2)) ' displays : 28 | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | ==Empty arrays== | ||
+ | |||
+ | In some cases, especially when dealing with the API, you need to declare an empty array. Such array is declared without dimension, but may later be filled by an API function or with a <tt>Redim</tt> statement: | ||
+ | |||
+ | <syntaxhighlight lang="oobas"> | ||
+ | Dim s() As String ' declare an empty array | ||
+ | ' --- later in the program ... | ||
+ | Redim s(13) As String | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | You cannot assign a value to an empty array, since it does not contain any elements. | ||
+ | |||
+ | The "signature" of an empty array is that <tt>UBound()</tt> returns -1 and <tt>LBound()</tt> returns 0: | ||
+ | |||
+ | <syntaxhighlight lang="oobas"> | ||
+ | Dim MyArray() As Integer | ||
+ | MsgBox(LBound(MyArray)) ' displays : 0 | ||
+ | MsgBox(UBound(MyArray)) ' displays : -1 | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | Some API functions return an array containing elements (indexed from zero) or return an empty array. Use <tt>UBound()</tt> to check if the returned array is empty. | ||
= Defining values for arrays = | = Defining values for arrays = | ||
Values for the Array fields can be stored like this: | Values for the Array fields can be stored like this: | ||
− | + | <syntaxhighlight lang="oobas"> | |
MyArray(0) = "somevalue" | MyArray(0) = "somevalue" | ||
− | + | </syntaxhighlight> | |
= Accessing Arrays = | = Accessing Arrays = | ||
Accessing values in an array works like this: | Accessing values in an array works like this: | ||
− | + | <syntaxhighlight lang="oobas"> | |
MsgBox("Value:" & MyArray(0)) | MsgBox("Value:" & MyArray(0)) | ||
− | + | </syntaxhighlight> | |
= Array Creation, value assignment and access example = | = Array Creation, value assignment and access example = | ||
And example containing all steps that show real array usage: | And example containing all steps that show real array usage: | ||
− | + | <syntaxhighlight lang="oobas"> | |
Sub TestArrayAxess | Sub TestArrayAxess | ||
Dim MyArray(3) | Dim MyArray(3) | ||
Line 142: | Line 190: | ||
MsgBox("Value:" & MyArray(0)) | MsgBox("Value:" & MyArray(0)) | ||
End Sub | End Sub | ||
− | + | </syntaxhighlight> | |
Latest revision as of 11:06, 30 January 2021
In addition to simple variables (scalars), Apache OpenOffice Basic also supports arrays (data fields). A data field contains several variables, which are addressed through an index.
Defining Arrays
Arrays can be defined as follows:
Simple Arrays
An array declaration is similar to that of a simple variable declaration. However, unlike the variable declaration, the array name is followed by parentheses which contain the specifications for the number of elements. The expression
Dim MyArray(3)
declares an array that has four variables of the variant data type, namely MyArray(0), MyArray(1), MyArray(2), and MyArray(3).
You can also declare type-specific variables in an array. For example, the following line declares an array with four integer variables:
Dim MyInteger(3) As Integer
In the previous examples, the index for the array always begins with the standard start value of zero. As an alternative, a validity range with start and end values can be specified for the data field declaration. The following example declares a data field that has six integer values and which can be addressed using the indexes 5 to 10:
Dim MyInteger(5 To 10) As Integer
The indexes do not need to be positive values. The following example also shows a correct declaration, but with negative data field limits:
Dim MyInteger(-10 To -5) As Integer
It declares an integer data field with 6 values that can be addressed using the indexes -10 to -5.
There are no practical limits on the indexes or on the number of elements in an array, so long as there is enough memory:
Dim s(-53000 to 89000) As String s(-52000) = "aa" s(79999) = "bb" print s(-52000), s(79999)
Specified Value for Start Index
The start index of a data field usually begins with the value 0. Alternatively, you can change the start index for all data field declarations to the value 1 by using the call:
Option Base 1
The call must be included in the header of a module if you want it to apply to all array declarations in the module. However, this call does not affect the UNO sequences that are defined through the Apache OpenOffice API whose index always begins with 0. To improve clarity, you should avoid using Option Base 1.
The number of elements in an array is not affected if you use Option Base 1, only the start index changes. The declaration
Option Base 1 ' ... Dim MyInteger(3)
creates 4 integer variables which can be described with the expressions MyInteger(1), MyInteger(2), MyInteger(3), and MyInteger(4).
Multi-Dimensional Data Fields
In addition to single dimensional data fields, Apache OpenOffice Basic also supports work with multi-dimensional data fields. The corresponding dimensions are separated from one another by commas. The example
Dim MyIntArray(5, 5) As Integer
defines an integer array with two dimensions, each with 6 indexes (can be addressed through the indexes 0 to 5). The entire array can record a total of 6 x 6 = 36 integer values.
You can define hundreds of dimensions in Apache OpenOffice Basic Arrays; however, the amount of available memory limits the number of dimensions you can have.
Dynamic Changes in the Dimensions of Data Fields
The previous examples are based on data fields of a specified dimension. You can also define arrays in which the dimension of the data fields dynamically changes. For example, you can define an array to contain all the words in a text that begin with the letter A. As the number of these words is initially unknown, you need to be able to subsequently change the field limits. To do this in Apache OpenOffice Basic, use the following call:
ReDim MyArray(10)
VBA : Unlike VBA, where you can only dimension dynamic arrays by using Dim MyArray(), Apache OpenOffice Basic lets you change both static and dynamic arrays using ReDim. |
The following example changes the dimension of the initial array so that it can record 11 or 21 values:
Dim MyArray(4) As Integer ' Declaration with five elements ' ... ReDim MyArray(10) As Integer ' Increase to 11 elements ' ... ReDim MyArray(20) As Integer ' Increase to 21 elements
When you reset the dimensions of an array, you can use any of the options outlined in the previous sections. This includes declaring multi-dimensional data fields and specifying explicit start and end values. When the dimensions of the data field are changed, all contents are lost. If you want to keep the original values, use the Preserve command:
Dim MyArray(10) As Integer ' Defining the initial ' dimensions ' ... ReDim Preserve MyArray(20) As Integer ' Increase in ' data field, while ' retaining content
When you use Preserve, ensure that the number of dimensions and the type of variables remain the same.
VBA : Unlike VBA, where only the upper limit of the last dimension of a data field can be changed through Preserve, Apache OpenOffice Basic lets you change other dimensions as well. |
If you use ReDim with Preserve, you must use the same data type as specified in the original data field declaration.
Determining the Dimensions of Data Fields
Functions LBound() and UBound() return respectively the lowest permitted index value and the highest permitted index value of an array. This is useful when an array has changed its dimensions.
Dim MyArray(10) As Integer ' ... some instructions Dim n As Integer n = 47 ' could be the result of a computation Redim MyArray(n) As Integer MsgBox(LBound(MyArray)) ' displays : 0 MsgBox(UBound(MyArray)) ' displays : 47
For a multi-dimensional array you need to specify the position (1 to n) of the index you want to know the permitted lower and upper values:
Dim MyArray(10, 13 to 28) As Integer MsgBox(LBound(MyArray, 2)) ' displays : 13 MsgBox(UBound(MyArray, 2)) ' displays : 28
Empty arrays
In some cases, especially when dealing with the API, you need to declare an empty array. Such array is declared without dimension, but may later be filled by an API function or with a Redim statement:
Dim s() As String ' declare an empty array ' --- later in the program ... Redim s(13) As String
You cannot assign a value to an empty array, since it does not contain any elements.
The "signature" of an empty array is that UBound() returns -1 and LBound() returns 0:
Dim MyArray() As Integer MsgBox(LBound(MyArray)) ' displays : 0 MsgBox(UBound(MyArray)) ' displays : -1
Some API functions return an array containing elements (indexed from zero) or return an empty array. Use UBound() to check if the returned array is empty.
Defining values for arrays
Values for the Array fields can be stored like this:
MyArray(0) = "somevalue"
Accessing Arrays
Accessing values in an array works like this:
MsgBox("Value:" & MyArray(0))
Array Creation, value assignment and access example
And example containing all steps that show real array usage:
Sub TestArrayAxess Dim MyArray(3) MyArray(0) = "lala" MsgBox("Value:" & MyArray(0)) End Sub
Content on this page is licensed under the Public Documentation License (PDL). |