# MArray

Most of Maya's array classes provide a common interface with the only difference being the type of the underlying array elements: integer, float, MPoint, etc. This page describes that common interface.

The array classes which use this common interface implement their Python type objects using the MPyMArray_Type template class, which takes the following template parameters:

- The type of the Maya array class (e.g. MIntArray, MPointArray). We refer to this as ArrayType throughout this document.
- The C++ type of the array elements (e.g. int, MPoint). We refer to this as ElementType throughout this document.
- A boolean indicating whether reference semantics should be used.

### Reference Semantics

Reference semantics mean that indexing into the array returns a reference to an array element rather than a copy of its value. For example, let's say that you do the following:

    import maya.api.OpenMaya as om
    array = om.MPointArray()
    array.append(om.MPoint(1, 2, 3))
    p = array[0]
    p.x = -5

Under value semantics 'p' would contain a copy of the value in 'array[0]'. Changing one would have no effect on the other, so we would end up with 'p' containing (-5, 2, 3) and 'array[0]' containing (1, 2, 3).

Under reference semantics 'p' and 'array[0]' would refer to the same element so they would both end up with the point (-5, 2, 3).

In Maya's Python API arrays of simple types like int and float use value semantics, while arrays of class types like MPoint and MColor use reference semantics.

This is in keeping with the way that Python handles function parameters: parameters of simple type are passed by value while parameters of class types are passed by reference. More importantly, passing class type objects by reference can hugely improve performance. For example, imagine that you need to increment the X coordinate of all the points in an array. Using value semantics you'd have to copy the data twice:

    for i in range(len(array)):
        p = array[i]
        p.x += 1
        array[i] = p

Using reference semantics you can avoid the copies altogether:

    for p in array;
        p.x += 1

Without reference semantics those extra copies could easily double or triple the amount of CPU time required to process the array, which could prove crippling when dealing with complex geometries involving arrays of hundreds of thousands of points.

Unfortunately, there is a significant price to be paid for using reference semantics. Maya's array types do not provide reference counting for individual elements. This means that a Python script which holds a reference to an array element may suddenly find that reference invalid if the corresponding array element is destroyed. For example, the following could cause Maya to crash or otherwise become unstable because it is attempting to increment the 'x' member of an MPoint instance which no longer exists:

    p = array[0]
    array.clear()
    p.x += 1

It is up to the API user to ensure that the array is not destroyed, resized or overwritten while zie holds references to one or more of its elements.

Note that the same caveats apply to the C++ API and the old Python API as they also use reference semantics for arrays of class-type objects, so at least the danger is a familiar one for developers.

## Constants

None.

## Static Methods

None.

## Static Attributes

None.

## Constructors

Signature | Parameters | Description
--- | --- | ---
ArrayType() |  | Default constructor. Returns a new, empty ArrayType object.
ArrayType(src) | src - ArrayType | Copy constructor. Returns a new ArrayType object containing copies of of the elements from src.
ArrayType(size, value) | size - Int value - ElementType | Returns a new ArrayType object with size elements, all set to value.
ArrayType(seq) | seq - sequence whose elements are convertible to ElementType | Returns a new ArrayType object containing copies of the elements from seq. Raises a TypeError exception if any of the elements of seq cannot be converted to ElementType.

## Object Methods

Signature | Parameters | Returns | Description
--- | --- | --- | ---
append(value) | value - ElementType | New reference to self. | Appends value to the end of the array as a new element.
copy(src) | src - ArrayType or sequence of items convertible to ElementType | New reference to self. | Removes all existing elements and adds copies of the elements from src.
clear() |  | New reference to self. | Removes all existing elements.
insert(value, index) | value - ElementType index - Int | New reference to self. | Inserts value into the array element at index, after first shifting that and any elements which follow it down the array to make room. Raises a ValueError if there are not at least index elements in the array before insertion, or if index is negative.
remove(index) | index - Int | New reference to self. | Removes the array element at index then shifts any elements which follow it up to close the gap. Raises a ValueError if index is out of range.
setLength(newSize) | newSize - Int | New reference to self. | Sets the length of the array to newSize elements. If the new size is less than the old then the elements from newSize onward will be destroyed. If the new size is greater than the old then new elements will have undefined values which should not be used without first being initialized. Raises a ValueError if newSize is negative.

## Object Attributes

Name | Type | Access | Description
--- | --- | --- | ---
sizeIncrement | Int | RW | Number of elements to allocate space for when the array must grow. These elements do not show up in the array's length but are available for use if further elements are added to the array. A large sizeIncrement can improve performance by reducing the number of physical allocations required when an array grows, but at the cost of wasting memory on space for elements which may never be used. The default is 8.

## Sequence Support

All sequence operations are supported, including slices.

For arrays using reference semantics indexing returns what is effectively a borrowed reference to the array element rather than a copy of its value. See the discussion of Reference Semantics above for more details.

## Number Support

None.

## Comparison Support

No comparison operations are currently implemented. '==' and '!=' are planned and possibly others as well.

© 2011 Autodesk, Inc. All rights reserved.