API docs state that Arrays are fixed size, but they aren't

> From my understanding it is by creating a new array of a different size then copying the items inside the array. Which makes them expensive operations.

This was my initial take.

However, regardless of how it’s actually implemented, the *API documentation* says that items can be added and removed to existing Arrays:

add(): Add an Object to the end of an Array.

remove(): Remove an Object from an Array.

If it’s the case that some (or all of these) operations are actually creating a new array with the previous contents copied over, it would be nice if this was documented, otherwise this does create an understandable confusion given that the summary says Array objects are fixed size.

I assume that regardless of the actual implementation, the array object itself is mutated by these methods, meaning that after calling add() or remove() on an instance of an Array, a new instance is not created but the same instance is updated, so that all references to the original instance will see the changes. Perhaps this is why the documentation simply says “Add an Object to the end of an array”, rather than “Copy the contents of the current array to a new array, with the new Object added at the end” — the latter text would give the false impression that a new instance is created, when it’s actually the existing instance that is updated. [Ofc, in order for the hypothetical “create new instance implementation” to work in practice, methods like add() would have to return an Array, but obviously they don’t]

If I’m understanding the situation properly, there are actually *two* concepts at play when we’re talking about the “array”.

- The Array object [instance of the Toybox.Lang.Array class]. This object presumably contains a pointer to the actual array on the heap (for lack of a better term, I’ll call this the ‘underlying array’.) When methods like Array.add() are called, a new underlying array is created, and existed items are copied from the old underlying array, which is then discarded.

- The underlying array on the heap: *It’s the underlying array which is fixed size, not the Array object.*

So it does seem that the literal text “*Array objects* are fixed size…” is wrong. Without any assumption or knowledge about the underlying implementation, it’s clear that an instance of the Array class is *not* fixed size. Array.size() can change after the Array is created.

Here’s the existing summary:

”Array objects are fixed size, numerically indexed, single dimensional, and take any Objects [including Arrays] as members. Array keys must be Numbers, but Array values may be any type of Object.”

Perhaps this could be rewritten as something like:

”Array objects are variable size, numerically indexed, single dimensional, and take any Objects [including Arrays] as members. Array keys must be Numbers, but Array values may be any type of Object.

The Array class is implemented with a fixed-size underlying array, which means that methods such as add() and addAll() are expensive: when elements are added, a new underlying array is created and existing elements are copied over from the existed underlying array. ”

> From my understanding it is by creating a new array of a different size then copying the items inside the array. Which makes them expensive operations.

This was my initial take.

However, regardless of how it’s actually implemented, the *API documentation* says that items can be added and removed to existing Arrays:

add(): Add an Object to the end of an Array.

remove(): Remove an Object from an Array.

If it’s the case that some (or all of these) operations are actually creating a new array with the previous contents copied over, it would be nice if this was documented, otherwise this does create an understandable confusion given that the summary says Array objects are fixed size.

I assume that regardless of the actual implementation, the array object itself is mutated by these methods, meaning that after calling add() or remove() on an instance of an Array, a new instance is not created but the same instance is updated, so that all references to the original instance will see the changes. Perhaps this is why the documentation simply says “Add an Object to the end of an array”, rather than “Copy the contents of the current array to a new array, with the new Object added at the end” — the latter text would give the false impression that a new instance is created, when it’s actually the existing instance that is updated. [Ofc, in order for the hypothetical “create new instance implementation” to work in practice, methods like add() would have to return an Array, but obviously they don’t]

If I’m understanding the situation properly, there are actually *two* concepts at play when we’re talking about the “array”.

- The Array object [instance of the Toybox.Lang.Array class]. This object presumably contains a pointer to the actual array on the heap (for lack of a better term, I’ll call this the ‘underlying array’.) When methods like Array.add() are called, a new underlying array is created, and existed items are copied from the old underlying array, which is then discarded.

- The underlying array on the heap: *It’s the underlying array which is fixed size, not the Array object.*

So it does seem that the literal text “*Array objects* are fixed size…” is wrong. Without any assumption or knowledge about the underlying implementation, it’s clear that an instance of the Array class is *not* fixed size. Array.size() can change after the Array is created.

Here’s the existing summary:

”Array objects are fixed size, numerically indexed, single dimensional, and take any Objects [including Arrays] as members. Array keys must be Numbers, but Array values may be any type of Object.”

Perhaps this could be rewritten as something like:

”Array objects are variable size, numerically indexed, single dimensional, and take any Objects [including Arrays] as members. Array keys must be Numbers, but Array values may be any type of Object.

The Array class is implemented with a fixed-size underlying array, which means that methods such as add() and addAll() are expensive: when elements are added, a new underlying array is created and existing elements are copied over from the existed underlying array. ”