localDataStorage.pull( arrayKeyName[, valIndex] [, valIndexIsLiteral] )

This method yanks an element from arrayKeyName, an existing Array Key, performing a destructive delete operation. A sparse array will not be returned. By default, elements are removed from the end of the array.

When the optional valIndex is supplied as a value literal, the corresponding element is searched for and deleted (the data type of value must match). If valIndex is an integer, the corresponding position in the Array Key will be deleted. To eliminate ambiguity when the Array Key itself contains integer values, the valIndexIsLiteral option may be set to true (by default, it is false). This is helpful when an element must be deleted based on its value instead of its index position.

EXAMPLES:

🔹 Existing Array Key called 'nicknames' having value ['Mac', 'Will', 'Bill', 'Tom']:

Remove the last element (by default):
● localData.pull( 'nicknames' ); --> ['Mac', 'Will', 'Bill']

Alternatively, remove an element by value:
● localData.pull( 'nicknames', 'Bill' ); --> ['Mac', 'Will', 'Tom']

Alternatively, remove an element by position:
● localData.pull( 'nicknames', 2 ); --> ['Mac', 'Bill', 'Tom']

🔹 Existing Array Key called 'numbers' having value [1, 3, 5, 7, 9]:

Remove an element by value, specifying valIndexIsLiteral:
● localData.pull( 'numbers', 3, true ); --> [1, 5, 7, 9]

Alternatively, remove an element by position:
● localData.pull( 'numbers', 3 ); --> [1, 3, 7, 9]

The value of the updated arrayKeyName is returned when this method executes.

When data must be added and deleted at the same time, use poke.

🌐 This method may fire an event allowing you to monitor the key change.

✨ The complement to this is push.

📝 NOTE: This method is specific to Array Keys and will fail if used on any other key type. Only one element can be deleted at a time. If an Array Key contains duplicate elements and all of them must be removed, use pullall. Array Keys use one-based array indices.