Improve descriptions of LocalVector, recommend it when appropriate

[beicause]

The current documentation doesn't highlight the advantages of LocalVector and may lead to misunderstandings and discourage its use.
In fact I rarely noticed the differences between LocalVector and Vector before, until seeing many PRs in 4.5 replacing Vector with LocalVector. I think we should provide a clearer explanation of LocalVector in the documentation.

[smix8]

The main benefit of LocalVector, apart from no copy-on-write, is that a LocalVector keeps its allocated memory. So when you frequently edit and clear stuff and it is used internally only you want to use a LocalVector to not waste performance on all the frequent memory alloc.

[beicause]

The main benefit of LocalVector, apart from no copy-on-write, is that a LocalVector keeps its allocated memory. So when you frequently edit and clear stuff and it is used internally only you want to use a LocalVector to not waste performance on all the frequent memory alloc.

Will this be changed? Related: godotengine/godot#105928 (review)

[Ivorforce]

I prefer the new wording over the old. LocalVector is preferable to Vector whenever it's not expected that it needs to be copied around. We might actually make LocalVector the default recommended 'vector' type in the future for this.

Edit: Also, this needs a rebase after #11188.

[beicause]

The main benefit of LocalVector, apart from no copy-on-write, is that a LocalVector keeps its allocated memory. So when you frequently edit and clear stuff and it is used internally only you want to use a LocalVector to not waste performance on all the frequent memory alloc.

I updated the description to address this.

[Ivorforce]

The new description is incorrect.

Both Vector and LocalVector grow exponentially, and 'reserve' memory when resizing. The capacity thing is a quirk of Vector and pertains only to removing elements, where Vector may reduce capacity automatically if it crosses a size border.

It is actually expected that vector types do not automatically shrink their capacity (at least in c++), so this is a caveat to Vector rather than an addendum to LocalVector.
If I would document this (not sure if I would because we are planning to change this soon) I would put it this way:

Note that Vector automatically reduces its capacity when removing elements, which may lead to reduced performance due to allocations when it grows again.

Meanwhile, the main reason that LocalVector is faster than Vector is the lack of copy-on-write. The capacity reduction stuff can be significant, but isn't in most situations. I would not mention this in LocalVector's description, rather something like:

Due to a lack of copy-on-write, LocalVector is usually faster than Vector. Prefer it over Vector when copying it cheaply is not needed.

Will this be changed? Related: godotengine/godot#105928 (review)

This may change for Vector in the 4.6 dev cycle, yes.

[mhilbrunner]

Merged. Thank you, and thanks for the reviews!