Ar Erase

From GECK
Jump to: navigation, search


A function added by the New Vegas Script Extender.

Description

Erases the entry at the specified index, if it exists, from the specified array. The index may be specified using range notation to delete all elements with indices within the range, inclusively. Alternatively, the index argument may be omitted to erase all entries in an array. Returns the count of entries erased.

The array may be of any type, but the index must be appropriate to it (int or string). Arrays of type "array" (Ar_List) are always indexed consecutively, so any entries above the erased will have their keys shifted down.

Syntax

[help]
(int) Ar_Erase Parent:array ToErase:index-or-range 

Example

Ar_Erase SomeArray, SomeKey ; erases the entry at SomeKey from SomeArray

Additional Context

array_var aBeatles

let aBeatles := Ar_List JohnREF, PaulREF, GeorgeREF, RingoREF

Ar_Erase aBeatles, 4 ; does nothing because 4 is not a valid index

Ar_Erase aBeatles, 1:2 ; erases entries from 1 to 2

; aBeatles now contains: JohnREF, RingoREF

Ar_Erase aBeatles, 0 ; erases entry at key 0

; aBeatles now only contains: RingoREF

Notes

  • Any kind of forwards loop through an array, may or stringmap can encounter issues if you erase the element currently under iteration inside the loop. This includes any ForEach loop and forwards While loops, eg "while iSize > (iKey += 1)".For regular arrays, the best method is to do a backwards while loop, eg "While -1 < (iKey -= 1)". For maps and stringmaps, you can either use Ar_Append to add the keys that need erased to a separate array that you loop through afterwards, or merely exclude them from being added to a new map or stringmap that you intend to replace the old one with.
  • It doesn't appear necesssary to check if the key you pass actually exists in the array, although it should be of the expected type. This means that when an Ar_Find call returns a bad numeric or bad string index, passing it as a parameter to Ar_Erase will not cause an error. So you don't have to check if it is valid before calling Ar_Erase.

See Also