MATLAB COM Builder

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])
• Property Item([i0], [i1], ..., [i31]) As MWField
• Property NumberOfFields As Long
• Property NumberOfDims As Long
• Property Dims As Variant
• Property FieldNames As Variant
• Sub Clone(ppStruct As MWStruct)

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 since 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. Also note:

• 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
  

Class MWFlags

Class MWField