Documentation gap: Array.Insert()

bgrommes

Array.Insert() accepts any index from zero to Count, such that myArray.Insert(value, myArray.Count) is a synonym for myArray.Append(value). This IMO is great, as if I want to append in any valid position, I don't have to special-case Append vs Insert if an insert amounts to an Append.

However, it should be documented as such.

Garry

Thanks for the report, and you're right, the docs were silent on this. Array.Insert() accepts any index from 0 to Count, and an index equal to Count appends the item, exactly as you describe:

Var items() As Integer = [1, 2]
items.Insert(items.Count, 99)
# items = [1, 2, 99] — same as items.Append(99)

As you say, this means you can use Insert unconditionally without special-casing an append at the end. Out-of-range indices (negative, or greater than Count) raise an IndexOutOfRangeException at runtime.

The Array reference page will document the valid range and the append-at-Count behaviour, and the method's tooltip in the Studio code editor now reads "Inserts an item at the specified index (0 to Count)." in the next release docs.