About Getting an Element of a Safearray (AutoLISP/ActiveX)

Arrays are used to return multiple values from and pass multiple values to an ActiveX function.

Note: ActiveX support in AutoLISP is limited to Windows only.

The following functions are used to get the values assigned to the elements with in an array:

• vlax-safearray-type – Returns the data type of a safearray.
• vlax-safearray-get-dim – Returns the number of dimensions in a safearray.
• vlax-safearray-get-l-bound – Returns the lower boundary (first index) of a dimension in a safearray.
• vlax-safearray-get-u-bound – Returns the upper boundary (last index) of a dimension in a safearray.
• vlax-safearray-get-element – Returns the value for an element in a safearray.

Data Type of an Array

When working with AutoLISP functions, you need to know the type of data that you are working with. Each array is defined with a specific type of data. The vlax-safearray-type function is used to identify the type of data that an array was created to hold; and it requires one argument: the variable containing the array. This function returns an integer value that represents the data type that the array was created to hold.

For example, the following code creates a single-dimension array of three doubles:

(setq point (vlax-make-safearray vlax-vbDouble '(0 . 2)))
(vlax-safearray-fill point (list 100 100 0))
#<safearray...>

For example, the following code returns a 5 because the array was defined to hold doubles:

(vlax-safearray-type point)
5

Dimensions in an Array

Accessing the values of an array requires you to know the both number of dimensions and elements that an array was created with. The vlax-safearray-get-dim function returns an integer that represents the number of dimensions that an array was created with.

The following code creates a single-dimension array of three doubles:

(setq point (vlax-make-safearray vlax-vbDouble '(0 . 2)))
(vlax-safearray-get-dim point)
1

The following example creates a two-dimension array of strings:

(setq mat2 (vlax-make-safearray vlax-vbString '(0 . 1) '(1 . 3)))
(vlax-safearray-get-dim mat2)
2

Elements in an Array Dimension

After you know the number of dimensions in an array (using the vlax-safearray-get-dim function), you can get the lower (vlax-safearray-get-l-bound) and upper (vlax-safearray-get-u-bound) boundaries of an array. The boundaries of an array helps you to identify the number of elements in a dimension and the index range in which the elements of an array can be found at.

The number of elements in an array dimension can be calculated by subtracting the values returned by the vlax-safearray-get-u-bound and vlax-safearray-get-l-bound functions.

For example, the following returns the number of elements in a single-dimension array:

(setq point (vlax-make-safearray vlax-vbDouble '(0 . 2)))
(setq arrayRange (1+ (- (vlax-safearray-get-u-bound point 1) (vlax-safearray-get-l-bound point 1))))
3

The following returns the number of elements in the second dimension of a two-dimension array:

(setq mat1 (vlax-make-safearray vlax-vbString '(0 . 1) '(2 . 5)))
(setq arrayRange (1+ (- (vlax-safearray-get-u-bound mat1 2) (vlax-safearray-get-l-bound mat1 2))))
4

Get the Value of an Element in an Array

After you know the number of dimensions and elements in an array, you can get the value of an element with the vlax-safearray-get-element function.

For example, the following code populates a single-dimension array of three doubles:

(setq point (vlax-make-safearray vlax-vbDouble '(0 . 2)))
(vlax-safearray-fill point (list 100 50 0))
#<safearray...>

The following returns the value of the second element in the array:

(vlax-safearray-get-element point 1)
50.0

The following code populates a two-dimension array of strings, and get the second element of the first dimension:

(setq mat2 (vlax-make-safearray vlax-vbString '(0 . 1) '(1 . 3)))
(vlax-safearray-fill mat2 '(("a" "b" "c") ("d" "e" "f")))
(vlax-safearray-get-element mat2 0 2)
"b"