Array_firstUnset

 Homepage Containers

Searches for the first occurrence of an unset element, and returns the index for this element.

foundAt := Array_firstUnset(ArrayObject, startIndex = 1)

Parameters

ArrayObject The Array object to use for the current operation.
startIndex The index to start searching from. If omitted, the search starts with the first item.

Return Value

The index for the first matching element, starting with startIndex.

If there is no such element, the function returns 0.


The function's return can be used as a quasi-boolean value; the statement if Array_firstUnset(...) would be true if an element is found, and false otherwise.

Remarks

If ArrayObject is NULL (0 or blank), the empty string is returned, to indicate an error.

Index values start at 1 and "wrap".

Related

Array_indexOf, Array_lastIndexOf, Array_regexIndexOf

Array_findMatch, Array_findLastMatch

Array_lastUnset, Array_findObject

Array

Examples

;Creates a new Array (of length 10).
myArray := Array_new(10)

;Creates some String objects
aString1 := String_new("Value1")
aString2 := String_new("Value2")
aString3 := String_new("Value1")

;Adds the Strings to myArray
Array_set(myArray, 1, aString1)
Array_set(myArray, 2, aString2)
Array_set(myArray, 3, aString3)

if foundAt := Array_firstUnset(myArray, 2)
{
    ;foundAt contains the index for the element.
    MsgBox, % "The element at index " foundAt " is unset."
}
else
{
    ;foundAt = 0 (i.e. not found)
    MsgBox, % "No unset element found."
}

Homepage  |  Containers