Module StableArray
This class provides an array from which elements may be removed without upsetting the positions of other elements, while also maintaining the ability to iterate the elements.
To use the plugin, add the following in build.settings:
plugins = {
["plugin.stablearray"] = { publisherId = "com.xibalbastudios" } -- note: "stablearray" is all lowercase here
}
Sample code is available here.
Functions
| New () | Factory for stable array objects. |
| StableArray:Clear () | Removes all elements from the array. |
| StableArray:Find (elem) | Finds elem in the array. |
| StableArray:FindAndRemove (elem) | Removes elem from the array, cf. |
| StableArray:Get (index) | Getter. |
| StableArray:GetArray (null, nil_elem) | Gets the elements as an array. |
| StableArray:Insert (elem) | Inserts elem into the array. |
| StableArray:InUse (index) | Predicate. |
| StableArray:Ipairs () | Iterator. |
| StableArray:__len () | Metamethod. |
| StableArray:RemoveAt (index) | Removes an element from the array. |
| StableArray:SetArray (arr, null, nil_elem) | Clears the stable array and loads elements from a stock Lua array. |
| StableArray:Update (index, elem) | Updates the element at a slot. |
Functions
- New ()
-
Factory for stable array objects.
Returns:
-
StableArray
A new stable array instance.
- StableArray:Clear ()
- Removes all elements from the array.
- StableArray:Find (elem)
-
Finds elem in the array.
If the array contains multiple instances of elem, only one is found.
Parameters:
- elem Element to find.
Returns:
-
uint or nil
Slot index, or nil if elem was not found.
- StableArray:FindAndRemove (elem)
-
Removes elem from the array, cf. StableArray:RemoveAt.
If the array contains multiple instances of elem, only one is found and removed.
Parameters:
- elem Element to remove.
Returns:
-
uint or nil
Slot index of elem, or nil if it was not found.
- StableArray:Get (index)
-
Getter.
Parameters:
- index uint Slot index.
Returns:
-
If the slot is in use, element in the slot; otherwise, nil.
N.B. When nil elements might have been inserted, StableArray:InUse can be used to distinguish missing values from nil elements.
- StableArray:GetArray (null, nil_elem)
-
Gets the elements as an array.
Parameters:
- null
Value to mark unused slots.
If this is callable, the value is instead the result of
null(element), element being whatever occupies the slot. - nil_elem Value to mark nil elements.
Returns:
-
array
Copy of the stable array's elements.
N.B. The array can contain holes if one of null or nil_elem is missing.
See also:
- null
Value to mark unused slots.
- StableArray:Insert (elem)
-
Inserts elem into the array.
Parameters:
- elem Element to add.
Returns:
-
uint
Slot index at which elem was inserted.
- StableArray:InUse (index)
-
Predicate.
Parameters:
- index uint Slot index.
Returns:
-
boolean
Slot contains an element?
- StableArray:Ipairs ()
-
Iterator.
ipairs-style iterator over the in-use slots of the array.
Returns:
-
iterator
Supplies slot index, element in slot.
- StableArray:__len ()
-
Metamethod.
Returns:
-
uint
Array size (element count + free slots).
- StableArray:RemoveAt (index)
-
Removes an element from the array.
Parameters:
- index
uint
Slot index of element.
If the slot is not in use, this is a no-op.
See also:
- index
uint
Slot index of element.
- StableArray:SetArray (arr, null, nil_elem)
-
Clears the stable array and loads elements from a stock Lua array.
Parameters:
- arr array Array used to populate the stable array.
- null If non-nil, instances of null will be removed from the array generated by arr, leaving those slots unused.
- nil_elem If non-nil, instances of nil_elem will be replaced by nil.
See also:
- StableArray:Update (index, elem)
-
Updates the element at a slot.
If the slot is not in use, this is a no-op.
Parameters:
- index uint Slot index of element.
- elem Element to add.
Returns:
- boolean Was the element updated?
- If the element was updated, the previous value.
See also: