POWERARRAY Object

Purpose

The PowerArray object encapsulates the Windows SAFEARRAY structure. Each object contains exactly one SAFEARRAY, and allows you to read, write, and manipulate the elements easily.

The SAFEARRAY is generally considered to be the lowest common denominator of arrays. It's not as fast as a standard PowerBASIC array, but it serves an excellent purpose: It's a "standard" form of array data which can be used to transfer data between programs, modules, and even DLLs created with different versions of the compiler. Other than the possibility of added data types, we do not expect to see the internal format to change in the foreseeable future.

A SAFEARRAY is frequently contained in a VARIANT variable. However, you'll usually find that the array is referenced and identified by a 32-bit pointer to its array descriptor.

Remarks

All array operations are executed with METHOD and PROPERTY invocations on a PowerArray object. When you create or examine a PowerArray, the specific data type is identified by the following VT codes. All of them are predefined in the compiler. VT codes numbered above 200 are unique to PowerBASIC. Other programming languages will not recognize them, giving undefined results.

%vt_i2 = 2 %vt_ui4 = 19

%vt_i4 = 3 %vt_i8 = 20

%vt_r4 = 4 %vt_int = 22

%vt_r8 = 5 %vt_uint = 23

%vt_cy = 6 %vt_ptr = 26

%vt_date = 7 %vt_userdefined = 29

%vt_bstr = 8 %vt_filetime = 64

%vt_dispatch = 9 %vt_astr = 201

%vt_bool = 11 %vt_stringfix = 203

%vt_variant = 12 %vt_wstringfix = 204

%vt_unknown = 13 %vt_stringz = 205

%vt_decimal = 14 %vt_wstringz = 206

%vt_i1 = 16 %vt_type = 211

%vt_ui1 = 17 %vt_ext = 221

%vt_ui2 = 18 %vt_curx = 222

The array dimensions are stated at the time the array is created by executing the DIM method. The ByRef Bounds parameter refers to a PowerBounds UDT which is predefined in the compiler. Bound is a PowerBOUND UDT for use with RedimPreserve. It is also predefined in the compiler.

TYPE PowerBounds

Elements1 AS LONG

LowBound1 AS LONG

Elements2 AS LONG

LowBound2 AS LONG

Elements3 AS LONG

LowBound3 AS LONG

Elements4 AS LONG

LowBound4 AS LONG

END TYPE

TYPE PowerBound

Elements AS LONG

LowBound AS LONG

END TYPE

This class is named PowerArray, and the interface is named IPowerArray. If any of the following operations should fail, the OBJRESULT function will return a non-zero result rather than %S_OK (zero).

IPowerArray Methods/Properties

METHOD ARRAYBASE () AS DWORD <1>

This method returns the address of the first element of the array.

METHOD ARRAYDESC () AS DWORD <2>

This method returns the address of the SAFEARRAY descriptor.

PROPERTY GET ARRAYINFO () AS WString <3>

You can attach a wide text string to an array for informational or documentation. This Get Property retrieves the info string, if one is present.

PROPERTY SET ARRAYINFO () = WString <3>

You can attach a wide text string to an array for informational or documentation. This Set Property assigns a wide dynamic string to the array.

METHOD CLONE (PowerArray) <4>

The parameter PowerArray is another object of the same class as this object, which is PowerArray. An exact duplicate of the SafeArray in the parameter is created, and stored in this object.

METHOD COPYFROMVARIANT (ByRef Variant) <5>

An exact copy is made of the SafeArray contained in the parameter Variant. The array copy is stored in this PowerArray object.

METHOD COPYTOVARIANT (ByRef Variant) <6>

An exact copy is made of the SafeArray in this object. The array copy is stored in the parameter Variant. Only arrays of data items which are Automation compatible may be stored in a Variant. Data types which are PowerBASIC-Specific cannot be copied.

METHOD DIM (ByVal VT&, ByVal Subscripts&, ByRef Bounds, OPTIONAL ByVal SIZE) <9>

Dimensions (creates) a new array. The VT& parameter is specified by one of the %VT values listed in remarks. Subscripts& is the number of dimensions (1 to 4), Bounds is a PowerBounds UDT which is prefilled with the lower bound and size of each dimension. The optional parameter SIZE tells the size (in bytes) of each element. SIZE is only used with %vt_stringfix, %vt_wstringfix, %vt_stringz, %vt_wstringz, and %vt_type.

METHOD ERASE () <10>

The contained array is destroyed and the object is then considered empty.

METHOD ELEMENTPTR (ByVal Index1&, Opt ByVal Index2&, _

Opt ByVal Index3&, Opt ByVal Index4&) AS LONG <11>

Calculates and retrieves the address of the data element specified by the Index parameter(s).

METHOD ELEMENTSIZE () <12>

Retrieves the storage size (in bytes) of each data element of the array.

METHOD LBOUND (Subscript&) AS LONG <13>

Retrieves the lower bound number for the dimension specified by the Subscript& parameter. The first subscript is 1, the second is 2, etc.

METHOD LOCK () <14>

Increments the lock count of the SAFEARRAY. Locks can be nested, but there must be an equal number of Unlocks executed.

METHOD MOVEFROMVARIANT (ByRef Variant) <17>

Transfers ownership of the SafeArray contained in the variant parameter to this PowerArray object. The variant is then changed to %vt_empty.

METHOD MOVETOVARIANT (ByRef Variant) <18>

Transfers ownership of the SafeArray contained in this PowerArray object to the variant parameter. The PowerArray object is then changed to empty.

METHOD REDIM (ByVal VT&, ByVal Subscripts&, ByRef Bounds, OPTIONAL ByVal SIZE) <19>

REDIM allows the SafeArray to be erased and re-dimensioned to a new size. It is really just a shortcut for the two-step process of ERASE, followed by DIM. The VT& parameter is specified by one of the %VT values listed in remarks. Subscripts& is the number of dimensions (1 to 4), Bounds is a PowerBounds UDT which is prefilled with the lower bound and size of each dimension. The optional parameter SIZE tells the size (in bytes) of each element. SIZE is only used with %vt_stringfix, %vt_wstringfix, %vt_stringz, %vt_wstringz, and %vt_type.

METHOD REDIMPRESERVE (ByRef Bound) <20>

REDIMPRESERVE allows the least significant (rightmost) bound to be changed to a new size. The remaining data items in the array are preserved. Bound is a PowerBound UDT which is prefilled with the lower bound and size of the dimension to be changed.

METHOD RESET () <21>

All elements in the SafeArray are set back to their initial, default value. Numerics are set to zero, strings to zero-length, variants to %vt_empty, and object variables are set to nothing. The array memory is not deallocated.

METHOD SUBSCRIPTS () <22>

Retrieves the number of dimensions (subscripts) for this array.

METHOD UBOUND (Subscript&) AS LONG <23>

Retrieves the upper bound number for the dimension specified by the Subscript& parameter. The first subscript is 1, the second is 2, etc.

METHOD UNLOCK () <24>

Decrements the lock count of the SAFEARRAY. Locks can be nested, but there must be an equal number of Unlocks executed.

METHOD VALUEGET (ByRef GetVar, ByVal Index1&, Opt ByVal Index2&, _

Opt ByVal Index3&, Opt ByVal Index4&) AS LONG <25>

Calculates and retrieves the value of the array element specified by the Index parameter(s). This value is then assigned to the GetVar variable. It is the programmer's responsibility to ensure that the type of GetVar matches the type of the array precisely.

METHOD VALUESET (ByRef SetVar, ByVal Index1&, Opt ByVal Index2&, _

Opt ByVal Index3&, Opt ByVal Index4&) AS LONG <26>

Assigns the value of the SetVar variable to the array element specified by the Index parameter(s). It is the programmer's responsibility to ensure that the type of SetVar matches the type of the array precisely.

METHOD VALUETYPE () <27>

Retrieves the %VT code which describes the data contained in this array. The %VT codes are listed in the Remark section above.