Vector class | vector.h[26], misc.t[2043], webui.t[73]

The Vector intrinsic class provides a varying-length array type. Vectors can be expanded dynamically, and values within a vector can be changed. (In contrast, List is a constant type: a value within a list cannot be changed, and new values can't be added to a list. Any manipulation of a List results in a new, separate List object, leaving the original unchanged. Vector allows new values to be added and existing values to be changed in place, without creating a new object.)

Modified in misc.t[2043]:
Add a couple of handy utility functions to Vector

Modified in webui.t[73]:
Some handy Vector extensions

`intrinsic class Vector : Collection`

Superclass Tree (in declaration order)

`Vector`
`Collection`
`Object`

Subclass Tree

`Vector`
`AnonFuncPtr`

Global Objects

(none)

Summary of Properties

``

``

``

(none)

Summary of Methods

`append appendAll appendUnique applyAll clear copyFrom countOf countWhich fillValue find forEach forEachAssoc getAndRemove getTop getUnique groupSort indexOf indexOfMax indexOfMin indexWhich insertAt isEmpty join lastIndexOf lastIndexWhich lastValWhich length mapAll maxVal minVal pop prepend push removeElement removeElementAt removeRange setLength shift shuffle sort splice subset toList unshift valWhich`

Inherited from `Collection` :
`createIterator createLiveIterator`

Inherited from `Object` :
`callInherited cf checkDisplay display displayAlt getPropList getPropParams getSuperclassList isClass isTransient ofKind propDefined propInherited propType valToSymbol`

Properties

(none)

Methods

`append (val)` | `vector.h[217]`

Append an element to the vector. This works just like insertAt() with a starting index one higher than the length of the vector. This has almost the same effect as the '+' operator, but treats a list value like any other value by simply inserting the list as a single new element (rather than appending each item in the list individually, as the '+' operator would).

`appendAll (val)` | `vector.h[234]`

Append all elements from a list or vector. This works like append(val), except that if 'val' is a list or vector, the elements of 'val' will be appended individually, like the '+' operator does. The difference between this method and the '+' operator is that this method modifies this Vector by adding the new elements directly to the existing Vector object, whereas the '+' operator creates a new Vector to store the result.

`appendUnique (val)` | `vector.h[148]`

append the elements of the list or vector 'val' to the elements of this vector, then remove repeated elements in the result; returns a new vector with the unique elements of the combination

`applyAll (func)` | `vector.h[74]`

Apply a callback function to each element of the vector. For each element of the vector, invokes the callback, and replaces the element with the return value of the callback. Modifies the vector in-place, and returns 'self'.

`clear ( )` | `misc.t[2048], webui.t[90]`

clear the vector

Modified in webui.t[90]:
return the popped element

`copyFrom (src, src_start, dst_start, cnt)` | `vector.h[50]`

Copy from another vector or list. Elements are copied from the source vector or list starting at the element given by 'src_start', and are copied into 'self' starting at the index given by 'dst_start'. At most 'cnt' values are copied, but we stop when we reach the last element of either the source or destination values. If either index is negative, it counts from the end of the vector: -1 is the last element, -2 is the second to last, and so on.

`countOf (val)` | `vector.h[135]`

count the number of elements with the given value

`countWhich (cond)` | `vector.h[138]`

count the number of elements for which the callback returns true

`fillValue (val, start?, cnt?)` | `vector.h[59]`

Fill with a given value, starting at the given element (the first element if not specified), and running for the given number of elements (the remaining existing elements of the vector, if not specified). The vector is expanded if necessary. A negative starting index counts backwards from the last element.

`find (ele)` | `misc.t[2169]`

find a vector element - synonym for indexOf

`forEach (func)`OVERRIDDEN | `vector.h[90]`

Invoke the callback func(val) on each element, in order from first to last. No return value.

`forEachAssoc (func)` | `vector.h[96]`

Invoke the callback func(index, val) on each element, in order from first to last. No return value.

`getAndRemove (idx)` | `webui.t[78]`

no description available

`getTop ( )` | `misc.t[2055]`

get the "top" item, treating the vector as a stack

`getUnique ( )` | `vector.h[141]`

create a new vector consisting of the unique elements of this vector

`groupSort (func)` | `misc.t[2121]`

Perform a "group sort" on the vector. This sorts the items into groups, then sorts by an ordering value within each group.

The groups are determined by group keys, which are arbitrary values. Each group is simply the set of objects with a like value for the key. Within the group, we sort by an integer ordering key.

'func' is a function that takes two parameters: func(entry, idx), where 'entry' is a list element and 'idx' is an index in the list. This returns a list, [group, order], giving the group key and ordering key for the entry.

`indexOf (val)` | `vector.h[107]`

get the index of the first match for the given value

`indexOfMax (func?)` | `vector.h[309]`

Get the index of the element the maximum value. If 'func' is missing, this simply returns the index of the element with the largest value, comparing the element values as though using the '>' and '<' operators. If 'func' is specified, it must be a function; it's called as func(x) for each element value x, and the result of the overall call is the index of the element for which func(x) returns the greatest value. For example, if you have a vector v containing string elements, v.indexOfMax({x: x.length()}) returns the index of the longest string.

`indexOfMin (func?)` | `vector.h[286]`

Get the index of the element with the minimum value. If 'func' is missing, this simply returns the index of the element with the smallest value, comparing the element values as though using the '>' and '<' operators. If 'func' is specified, it must be a function; it's called as func(x) for each element's value, and the result of the overall call is the index of the element for which func(x) returns the smallest value. For example, if you have a vector v containing string elements, v.indexOfMin({x: x.length()}) returns the index of the shortest string.

`indexWhich (cond)` | `vector.h[84]`

Find the first element for which the given condition is true. Apply the callback function (which encodes the condition to evaluate) to each element in turn, starting with the first. For each element, if the callback returns nil, proceed to the next element; otherwise, stop and return the index of the element. If the callback never returns true for any element, we'll return nil.

`insertAt (startingIndex, val, ...)` | `vector.h[188]`

Insert one or more elements at the given index. If the starting index is 1, the elements will be inserted before the first existing element. If the index is one higher than the number of elements, the elements will be inserted after all existing elements. A negative starting index counts from the end of the vector: -1 is the last element, -2 is the second to last, and so on. A zero starting index inserts after the last existing element.

Note that a list value argument will simply be inserted as a single element.

Returns 'self'.

`isEmpty ( )` | `misc.t[2045]`

is the vector empty?

`join (sep?)` | `vector.h[261]`

Combine the vector elements into a string. This converts each element into a string value using the usual default conversions (or throws an error if string conversion isn't possible), then concatenates the values together and returns the result. If 'separator' is provided, it's a string that's interposed between elements; if this is omitted, the elements are concatenated together with no extra characters in between.

`lastIndexOf (val)` | `vector.h[116]`

find the last element with the given value, and return its index

`lastIndexWhich (cond)` | `vector.h[126]`

Find the last element for which the condition is true, and return the index of the element. Applies the callback to each element in turn, starting with the last element and working backwards. For each element, if the callback returns nil, proceeds to the previous element; otherwise, stops and returns the index of the element. If the callback never returns true for any element, we'll return nil.

`lastValWhich (cond)` | `vector.h[132]`

Find the last element for which the condition is true, and return the value of the element

`length ( )` | `vector.h[39]`

get the number of elements in the vector

`mapAll (func)`OVERRIDDEN | `vector.h[104]`

Apply the callback function to each element of this vector, and return a new vector consisting of the results. Effectively maps the vector to a new vector using the given function, leaving the original vector unchanged.

`maxVal (func?)` | `vector.h[319]`

Get the maximum element value. If 'func' is missing, this returns the largest element value. If 'func' is specified, it must be a function; it's called as func(x) for each element value x, and the result of the overall method call is the element value x that maximizes func(x). For example, if v is a vector containing string elements, v.minVal({x: x.length()}) returns the longest string.

`minVal (func?)` | `vector.h[296]`

Get the minimum element value. If 'func' is missing, this simply returns the smallest element value. If 'func' is specified, it must be a function; it's called as func(x) for each element value x, and the result of the overall method call is the element value x that minimizes func(x). For example, if v is a vector containing string elements, v.minVal({x: x.length()}) returns the shortest string.

`pop ( )` | `misc.t[2061], webui.t[75]`

pop a value (remove and return the value at the end of the vector)

`prepend (val)` | `vector.h[223]`

Prepend an element. This works like insertAt() with a starting index of 1.

`push (val)` | `misc.t[2058], webui.t[74]`

push a value (append it to the end of the vector)

`removeElement (val)` | `vector.h[241]`

Remove an element by value. Each element of the vector matching the given value is removed. The vector is modified in-place. The return value is 'self'.

`removeElementAt (index)` | `vector.h[196]`

Delete the element at the given index, reducing the length of the vector by one element. If 'index' is negative, it counts from the end of the vector: -1 is the last element, -2 is the second to last, and so on. Returns 'self'.

`removeRange (startingIndex, endingIndex)` | `vector.h[207]`

Delete the range of elements starting at startingIndex and ending at endingIndex. The elements at the ends of the range are included in the deletion. If startingIndex == endingIndex, only one element is removed. If either index is negative, it counts backwards from the last element: -1 is the last element, -2 is the second to last, and so on. The length of the vector is reduced by the number of elements removed. Returns 'self'.

`setLength (newElementCount)` | `vector.h[172]`

Set the length - if this is shorter than the current length, existing items will be discarded; if it's longer, the newly added slots will be set to nil. Returns 'self'.

`shift ( )` | `misc.t[2086], webui.t[76]`

shift a value (remove and return the first value)

`shuffle ( )` | `misc.t[2172]`

shuffle the elements of the vector into a random order

`sort (descending?, comparisonFunction?)` | `vector.h[165]`

Sort the vector in place; returns 'self'. If the 'descending' flag is provided and is not nil, we'll sort the vector in descending order rather than ascending order.

If the 'comparisonFunction' argument is provided, it must be a callback function; the callback takes two arguments, and returns an integer less than zero if the first argument value is less than the second, zero if they're equal, and an integer greater than zero if the first is greater than the second. If no 'comparisonFunction' argument is provided, or it's provided and its value is nil, we'll simply compare the vector elements as ordinary values. The comparison function can be provided for caller-defined orderings, such as ordering a set of objects.

`splice (idx, del, ...)` | `vector.h[250]`

Splice new values into the vector. Deletes the 'del' elements starting at 'idx', then inserts the extra arguments in their place. Updates the vector in place. To insert items without deleting anything, pass 0 for 'del'. To delete items without inserting anything, omit any additional arguments. Returns 'self'.

`subset (func)` | `vector.h[66]`

Select a subset of the vector. Returns a new vector consisting only of the elements of this vector for which the callback function returns true.

`toList (start?, cnt?)` | `vector.h[36]`

Create a list with the same elements as the vector. If 'start' is specified, it's the index of the first element we store; we'll store elements starting at index 'start'. If 'cnt' is specified, it gives the maximum number of elements for the new list; by default, we'll store all of the elements from 'start' to the last element.

`unshift (val)` | `misc.t[2083]`

unshift a value (insert it at the start of the Vector)

`valWhich (cond)` | `vector.h[113]`

Find the first element for which the given condition is true, and return the value of the element.

Adv3Lite Library Reference Manual
Generated on 13/06/2025 from adv3Lite version 2.2.1