Keyword
# Dim
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
## Description
Creates a local variable or array with the name and size (in the case of an array) and data type specified.
## Usage
The Dim statement has two forms:
``` xojo
Dim variableName [, variableNameN ] As [ New ] DataType [ = InitialValue ]
```
| Part | Type | Description |
|---------------|-------------------------|------------------------------------------------------------------------------------|
| variableName | Variable name | The name of the new variable. |
| variableNameN | Variable name | Optional: The names of other variables you wish to create with the same data type. |
| DataType | Data type or class | The data type or class of the variable being declared. `New` is optional. |
| InitialValue | Same type as *DataType* | Optional: Initial value for *variableName*. |
**or**
``` xojo
Dim arrayName(size [, size2,... sizeN]) As DataType
```
| Part | Type | Description |
|-----------|------------------------------------|-------------------------------------------------------------------------------------------------------------|
| arrayName | Variable name | The name of the new array. |
| size | `Integer` | The upper bound of the array. Size must be a number or a `constant`. |
| sizeN | `Integer` | Optional. The upper bound of the next dimension of the array if you are creating a multi-dimensional array. |
| DataType | Data type or class | The data type or class of the array. |
## Notes
In the first syntax, the Dim statement is used to create new variables. Variable names can be any length but must begin with a letter and can contain only alphanumeric characters (A-Z, a-z, 0-9) or an underscore. A user-defined variable cannot begin with an underscore. You can, however, use Unicode characters in variable names. Variable names are case-insensitive so x and X are considered the same variable.
A variable is an object stored in RAM that can hold a value. In the second syntax, the Dim statement is used to create a new array of the size specified. An array is a variable that can contain multiple values that are all the same data type. Passing more than one size parameter creates a multi-dimensional array, with the number of dimensions equal to the number of size parameters passed.
You can optionally provide an initial value to a variable declared with a Dim statement. Here are some examples:
``` xojo
Dim a As Integer = 5
Dim b As Double = 87.87
Dim s As String = "Howdy"
Dim c As Color = &cFF4B51
Dim myAttributes() As Introspection.AttributeInfo = Introspection.GetType(Window1).GetAttributes
```
The following statement initializes three variables to an initial value:
``` xojo
Dim x, y, z As Integer = 10
```
After the statement, all three variables have the same initial value.
If the data type is an object, you can optionally instantiate the object with the `New` keyword in the Dim statement.This code declares and instantiates a `FolderItem` object.
``` xojo
Dim f As New FolderItem
```
Otherwise, you need a second line of code to instantiate the variable, d, as in the following:
``` xojo
Dim f As FolderItem
f = New FolderItem
```
If you use the `New` keyword, then you cannot declare more than one variable in a single Dim statement.
If the call to the object's constructor takes parameters, you can pass the parameters as well. Here is an example:
``` xojo
Dim mb As New FolderItem("file.txt", FolderItem.PathModes.Native)
```
You can use a `constant` or an `enum` as an initial value. Suppose you add a global constant, InitialValue=-1, in a module. You than can dimension a variable with the statement:
``` xojo
Dim testConstant As Integer = InitialValue
```
Suppose you add a global enum named "SecurityLevel" in a module with values None, Minimum, Maximum, and Forced. You can then use any of the enums in a declaration statement such as:
``` xojo
Dim testEnum As Integer = SecurityLevel.Maximum
```
The Dim statement can be placed anywhere in a method or function, including inside a conditional structure (an `If` or `Select Case` statement).
Variables created with the Dim statement are local in scope. This means that they are created each time the method is called and are destroyed when the method is finished. The value of a local variable can be accessed only from within the method.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Arrays
Arrays are created by specifying the size. All arrays are indexed starting at position 0. Arrays can have a maximum index value of 2,147,483,646.
This creates an array with 5 elements:
``` xojo
Dim aNames(4) As String
```
Array indices start at 0, so the above array can contain values in index 0, 1, 2, 3 and 4:
``` xojo
aNames(0) = "Bob"
aNames(2) = "Tom"
```
If you don't know the size of the array you need at the time you declare it, you can declare it as a null array, i.e., an array with no elements, and use the `Redim` command to resize it later. You do this by giving it an index of -1 or by leaving the parentheses empty. This means "an array of no elements." For example, the statement:
``` xojo
Dim aNames (-1) As String
```
creates the array aNames with no elements. If your program needs to load a list of names that the user enters, you can wait to size the array until you know how many names the user has entered. You can also accomplish this by leaving out the -1. The following statement is equivalent:
``` xojo
Dim aNames() As String
```
You can also use a constant to specify the array size:
``` xojo
Const size = 3
Dim aNames(size)
```
When you assign values to an array variable, such as with the `String.Split` function, you don't need to know the number of elements ahead of time.
You can also assign an array to another array. For example, the following is valid:
``` xojo
Dim myArray(3) As String
Dim newArray() As String
myArray(0) = "Anthony"
myArray(1) = "Aardvark"
myArray(2) = "Accountant"
newArray() = myArray //newArray set equal to myArray
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Multi-dimensional arrays
Multi-dimensional arrays require some special treatment, and most of the usual array functions are not supported.
To create a 2D array:
``` xojo
Dim my2Darray( -1,-1 ) As String
```
You cannot Dim a multidimensional array with a variable, but you can do the following:
``` xojo
Dim numberOfRows As Integer = someOtherArray.LastIndex
Dim my2Darray( -1,-1 ) As String
Redim my2Darray(NumberOfRows, 9)
```
To pass a multi-dimensional array to a method you use the following in the method declaration:
``` xojo
Sub MyMethod(param(,) As String)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Dim vs. Static
The `Static` statement provides an alternative to Dim. `Static` creates a local variable or local array with the name and size (in the case of an array) and data type specified. A variable declared with the `Static` statement and assigned a value retains its value from one invocation of the method to the next. In contrast, variables declared with the Dim statement are completely local to the method and are destroyed when each invocation of the method goes out of scope.
## Sample code
This example uses the Dim statement to create an `integer` variable called "age" and assigns it the value 33.
``` xojo
Dim age As Integer
age = 33
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
This example uses the Dim statement to create two `String` variables.
``` xojo
Dim FirstName, LastName As String
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
This example uses the Dim statement to create an array called aNames with 11 elements (remember, arrays have a zero element).
``` xojo
Dim aNames(10) As String
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
This example uses the Dim statement to create an array called aNames with one element.
``` xojo
Dim aNames(0) As String
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
This example uses the Dim statement to create a two-dimensional array called aNames with 11 rows and 4 columns.
``` xojo
Dim aNames(10, 3) As String
```
## Compatibility
| | |
|-----------------------|-----|
| **Project Types** | All |
| **Operating Systems** | All |
`Arrays.Add
`, `Arrays.AddAt`, `Arrays.ResizeTo`, `Arrays.RemoveAt`, `Arrays.Sort` methods; `Arrays.LastIndex` function; `Collection`, `Dictionary` classes; `Arrays` concept; `Static` statement; `A Var Statement creates only one new object at a time` error.