The MArray module provides array objects, meaning sequences of values. For example, an array of numbers. Each number in the array is known as an item. The number of items in an array object can be changed (the array can grow or shrink in size).

MArray is homogeneous meaning all items within an MArray instance must be the same type. For example, it is not possible to have some items be type "TUInt8" while others are "TUInt32", in the same MArray instance. Supporting the ability for items to have different sizes/types within the same instance (meaning heterogeneous) would impose substantial extra memory and processing overhead.

The maximum number of items that can be stored in an array instance is an indefinitely large amount. Storing 100 thousand items is no problem, if the items are small. Storing 100 million items is theoretically possible but would probably be slow, inefficient, and impractical. If you need to store a gigantic number of items, then MArray is the wrong solution for your particular problem; perhaps try a database instead.

Each item in an array is accessed/specified using its ordinal. The ordinal of the first item is 0. The ordinal of the second item is 1. The ordinal of the third item is 2, etc. Thus if you want to retrieve the value of the first item, then you would be required to specify that you want the item at ordinal 0. If there are 14 items in total, then the ordinal of the last item is 13.

The ordinal of the first item is not 1 because starting at 1 (as opposed to 0) tends to be awkward mathematically, requiring that 1 be subtracted from or added to various calculations. 0-based is more natural mathematically. For example, if you have the ordinal of an item, and you wish to calculate how many items from (and including) that position to the end of the array, then the formula is the total number/count of items minus the ordinal, if the ordinals are 0-based. However if the ordinals are 1-based, then the formula is the total number/count of items minus the ordinal, then plus 1. It is also slightly faster/easier to verify the validity of a 0-based ordinal than a 1-based ordinal.

Note that when a new item is inserted into the array, the ordinals of all following items automatically increase by 1. And when an item is removed from the array, the ordinals of all following items automatically decrease by 1. Thus the ordinals cannot be relied upon to always identify the same items, unless the array never changes, or unless items are only appended never inserted or removed. If this behavior is a problem for you, then MArray is probably the wrong solution for your particular problem; use one of the other modules.

After inserting a new item with value 456 at ordinal 3:

The ordinals are not literally stored with the items. Only the item values are actually stored. The ordinals are known implicitly, or calculated mathematically.

• Any existing reference in the outAry variable is removed and replaced by the reference to the new array object.
• If creation of the new object fails, the outAry variable is unchanged.
• The reference is set to be a non-subset reference (but can subsequently be changed to a subset).

• If this command fails, the reference and the object are (or appear) unchanged.
• If the object reference is a subset, this command will append to the end of the subset, not to the end of the entire array. Thus it may actually be inserting into the middle of the array, if the subset ends before the end of the array. In other words, it inserts at the subset end.
• The subset range is expanded to include the appended new item.
• Fails if the subset range starts or ends beyond the end of the array. Acceptable if is exactly at end.
• It is acceptable if the specified array or subset is empty.

• If the reference is a subset, it inserts at the start of the subset.
• It is acceptable if the specified array or subset is empty.
• See MNumArray::Insert for other details.

• The new item is inserted AT the specified ordinal, meaning BEFORE any existing item at the ordinal, not after. The existing item (and all following items) is pushed forward to the next ordinal / storage slot. Inserting at ordinal 0 means the newly inserted item will be the first item.
• Immediately after this command finishes successfully, the ordinal of the newly inserted item is always exactly equal to inAtOrdinal (until other items are inserted or removed).
• If this command fails, the reference and the object are (or appear) unchanged.
• If the object reference is a subset, then inAtOrdinal is an ordinal into the subset, and it inserts into the subset. For example, inAtOrdinal being 0 would mean that it inserts at the start of the subset.
• The subset range is expanded with the newly inserted item (it inserts into the subset).
• Fails if the subset range starts or ends beyond the end of the array. Acceptable if is exactly at end.

• If the object reference is a subset, then inOrdinal is an ordinal into the subset. For example, inOrdinal being 0 would mean the first item in the subset.
• Fails if inOrdinal specifies an item beyond the end of the subset.
• Fails if the subset range starts beyond the end of the array.
• inOrdinal is added to the subset-start-ordinal to calculate the real ordinal. If this calculation overflows, inOrdinal is considered to be invalid.

• Behavior regarding subsets is the same as MNumArray::Set.
• This command cannot be used to get the value of items outside of the subset range.