Add performance note to Array.resize()

[MewPurPur]

Adds a note about resizing ahead of time instead of adding new elements one by one. This would likely help some people trying to resolve performance bottlenecks.

[AThousandShips]

Other than some style details to decide on it looks good to me and relevant suggestion IMO (can be in 4.2 if consensus is reached)

[arkology]

This is kinda obvious but ... Why not)

[AThousandShips]

It isn't to many, people might not now how data is allocated and how expanding reallocates and might have to move all the data, this is far from obvious even to non-beginners

[MewPurPur]

Should this note also be added to PackedArray classes? I haven't tested on those yet.

Edit: Doned.

[kleonc]

Note sure if such note is really helpful in the description of resize. If someone is not aware of this then they probably use append/push_back without checking the docs for resize. So it might make more sense to add some suggestion in descriptions of append/push_back instead.

[MewPurPur]

Fair point, though in my opinion it's not as practical because reasonably there are 4 places where the note is relevant. I see this note as a justification of why one would consider using resize(). If array operations are a bottleneck for your project, you'd likely look through all the array methods and see what you can do.

I'll change the "appending" wording to "adding", because it's also relevant for inserting and pushing to the front, even if not as much for obvious reasons.

[MewPurPur]

For clarity, I'm referring to: append() and push_back(), insert(), push_front().

[kleonc]

It's not just for adding though, removing (erase, pop_at, pop_back, pop_front) also resizes (and hence can lead to reallocation).

And true, adding notes to all such methods makes little sense. Having it documented at least in on place (resize) probably does make sense (if we really assume it's not common knowledge).

[MewPurPur]

Personally, I only realized this because I saw performance-sensitive areas of Godot's code utilize it. Maybe it's obvious to people familiar with data structures, but we already address things I consider way more obvious in our Array docs (e.g. how adding elements at the beginning is slower because everything must be reindexed)

Also, as for these destructive methods, I don't think they count because calling resize() first causes a truncation?

[kleonc]

Also, as for these destructive methods, I don't think they count because calling resize() first causes a truncation?

To be clear I wasn't saying that just calling resize() is enough for all of them. What should be used is case by case. Bulk pop_back is like bulk push_back/append, just a single resize() is equivalent/enough. For bulk insert, push_front, erase, pop_at, pop_back you'd also need some element shifting/manipulation before/after the resize(). What exactly depends on what's being done.

Anyway, I'm fine with the current notes. If we'd want to go into details then probably a whole separate manual page in the docs could be written about using/manipulating arrays. 🙃

[Calinou]

Anyway, I'm fine with the current notes. If we'd want to go into details then probably a whole separate manual page in the docs could be written about using/manipulating arrays.

This is probably a good idea to have, given there are many non-obvious things involving arrays:

• Array vs typed array vs packed array (performance, flexibility, etc).
• Shorthands for initializing packed arrays (implicit casting).
• How to iterate multi-dimensional arrays effectively.

This information could also just be added to Data preferences.

[akien-mga]

Thanks!

[YuriSizov]

Cherry-picked for 4.2.2.