Class MWStruct

The MWStruct class passes or receives a Struct type to or from a compiled class method. This class contains seven properties/methods:

Sub Initialize([varDims], [varFieldNames])

This method allocates a structure array with a specified number and size of dimensions and a specified list of field names.

Parameters

Argument	Type	Description
`varDims`	`Variant`	Optional array of dimensions
`varFieldNames`	`Variant`	Optional array of field names

Return Value

None.

Remarks

When created, an MWStruct object has a dimensionality of 1-by-1 and no fields. The Initialize method dimensions the array and adds a set of named fields to each element. Each time you call Initialize on the same object, it is redimensioned. If you do not supply the varDims argument, the existing number and size of the array's dimensions unchanged. If you do not supply the varFieldNames argument, the existing list of fields is not changed. Calling Initialize with no arguments leaves the array unchanged.

Example

The following Visual Basic^® code illustrates use of the Initialize method to dimension struct arrays.

Sub foo ()
    Dim x As MWStruct
    Dim y As MWStruct

    On Error Goto Handle_Error
    'Create 1X1 struct arrays with no fields for x, and y
    Set x = new MWStruct
    Set y = new MWStruct

    'Initialize x to be 2X2 with fields "red", "green", 
    '                                          and "blue"
    Call x.Initialize(Array(2,2), Array("red", "green", "blue"))
    'Initialize y to be 1X5 with fields "name" and "age"
    Call y.Initialize(5, Array("name", "age"))

    'Re-dimension x to be 3X3 with the same field names
    Call x.Initialize(Array(3,3))

    'Add a new field to y
    Call y.Initialize(, Array("name", "age", "salary"))

    Exit Sub
Handle_Error:
    MsgBox(Err.Description)
End Sub

Property Item([i0], [i1], ..., [i31]) As MWField

The Item property is the default property of the MWStruct class. This property is used to set/get the value of a field at a particular index in the structure array.

Parameters

Argument	Type	Description
`i0`,`i1`, ..., `i31`	`Variant`	Optional index arguments. Between 0 and 32 index arguments can be entered. To reference an element of the array, specify all indexes as well as the field name.

Remarks

When accessing a named field through this property, you must supply all dimensions of the requested field as well as the field name. This property always returns a single field value, and generates a bad index error if you provide an invalid or incomplete index list. Index arguments have four basic formats:

Field name only
This format may be used only in the case of a 1-by-1 structure array and returns the named field's value. For example:
```
x("red") = 0.2
x("green") = 0.4
x("blue") = 0.6
```
In this example, the name of the Item property was neglected. This is possible because the Item property is the default property of the MWStruct class. In this case, the two statements are equivalent:
```
x.Item("red") = 0.2
x("red") = 0.2
```
Single index and field name

This format accesses array elements through a single subscripting notation. A single numeric index n followed by the field name returns the named field on the nth array element, navigating the array linearly in column-major order. For example, consider a 2-by-2 array of structures with fields "red", "green" , and "blue" stored in a variable x. These two statements are equivalent:

y = x(2, "red")
y = x(2, 1, "red")

All indices and field name

This format accesses an array element of an multidimensional array by specifying n indices. These statements access all four of the elements of the array in the previous example:

For I From 1 To 2
       For J From 1 To 2
              r(I, J) = x(I, J, "red")
              g(I, J) = x(I, J, "green")
              b(I, J) = x(I, J, "blue")
       Next
Next

Array of indices and field name

This format accesses an array element by passing an array of indices and a field name. The next example rewrites the previous example using an index array:

Dim Index(1 To 2) As Integer

For I From 1 To 2
       Index(1) = I
       For J From 1 To 2
              Index(2) = J
              r(I, J) = x(Index, "red")
              g(I, J) = x(Index, "green")
              b(I, J) = x(Index, "blue")
       Next
Next

With these four formats, the Item property provides a very flexible indexing mechanism for structure arrays.

You can combine the last two indexing formats. Several index arguments supplied in either scalar or array format are concatenated to form one index set. The combining stops when the number of dimensions has been reached. For example:
```
Dim Index1(1 To 2) As Integer
Dim Index2(1 To 2) As Integer

Index1(1) = 1
Index1(2) = 1
Index2(1) = 3
Index2(2) = 2
x(Index1, Index2, 2, "red") = 0.5
```

The last statement resolves to

x(1, 1, 3, 2, 2, "red") = 0.5

The field name must be the last index in the list. The following statement produces an error:
```
y = x("blue", 1, 2)
```
Field names are case sensitive.

Property NumberOfFields As Long

The read-only NumberOfFields property returns the number of fields in the structure array.

Property NumberOfDims As Long

The read-only NumberOfDims property returns the number of dimensions in the struct array.

Property Dims As Variant

The read-only Dims property returns an array of length NumberOfDims that contains the size of each dimension of the struct array.

Property FieldNames As Variant

The read-only FieldNames property returns an array of length NumberOfFields that contains the field names of the elements of the structure array.

Example

The next Visual Basic code sample illustrates how to access a two-dimensional structure array's fields when the field names and dimension sizes are not known in advance.

Sub foo ()
      Dim x As MWStruct
      Dim Dims as Variant
      Dim FieldNames As Variant
	

      On Error Goto Handle_Error
      '
      '... Call a method that returns an MWStruct in x
      '
      Dims = x.Dims
      FieldNames = x.FieldNames
      For I From 1 To Dims(1)
            For J From 1 To Dims(2)
                  For K From 1 To x.NumberOfFields
                        y = x(I,J,FieldNames(K))
                        ' ... Do something with y
                  Next
            Next
      Next
Exit Sub
Handle_Error:
      MsgBox(Err.Description)
End Sub

Sub Clone(ppStruct As MWStruct)

Creates a copy of an MWStruct object.

Parameters

Argument	Type	Description
`ppStruct`	`MWStruct`	Reference to an uninitialized `MWStruct` object to receive the copy

Return Value

None

Remarks

Clone allocates a new MWStruct object and creates a deep copy of the object's contents. Call this function when a separate object is required instead of a shared copy of an existing object reference.

Example

The following Visual Basic example illustrates the difference between assignment and Clone for MWStruct objects.

Sub foo ()
    Dim x1 As MWStruct
    Dim x2 As MWStruct
    Dim x3 As MWStruct

    On Error Goto Handle_Error
    Set x1 = new MWStruct
    x1("name") = "John Smith"
    x1("age") = 35
	
   'Set reference of x1 to x2
    Set x2 = x1 
   'Create new object for x3 and copy contents of x1 into it
    Call x1.Clone(x3) 
   'x2's "age" field is 
   'also modified 'x3's "age" field unchanged
    x1("age") = 50 
        .
        .
        .
    Exit Sub
Handle_Error:
    MsgBox(Err.Description)
End Sub