Script: Class dw.util.List

Class List

An ordered collection of objects. The user of a List has precise control over where in the list each element is inserted. The user can access elements by their integer index (position in the list), and search for elements in the list. Lists are zero based similar to arrays. Unlike sets, lists allow duplicate elements.

All Known Subclasses

ArrayList

Properties

static EMPTY_LIST : List

Convenience variable, for an empty and immutable list.

Constructor Summary

This class does not have a constructor, so you cannot create it directly. To get an instance of this class, use one of the subclass constructors.

Method Summary

addAt(index : Number, value : Object) : void

Adds the specified object into the list at the specified index.

concat(values : Object...) : List

Creates and returns a new List that is the result of concatenating this list with each of the specified values.

fill(obj : Object) : void

Replaces all of the elements in the list with the given object.

get(index : Number) : Object

Returns the object at the specified index.

indexOf(value : Object) : Number

Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element.

join() : String

Converts all elements of the list to a string by calling the toString() method and then concatenates them together, with a comma between elements.

join(separator : String) : String

Converts all elements of the list to a string by calling the toString() method and then concatenates them together, with the separator string between elements.

lastIndexOf(value : Object) : Number

Returns the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element.

pop() : Object

Removes and returns the last element from the list.

push(values : Object...) : Number

Appends the specified values to the end of the list in order.

removeAt(index : Number) : Object

Removes the object at the specified index.

replaceAll(oldValue : Object, newValue : Object) : boolean

Replaces all occurrences of oldValue with newValue.

reverse() : void

Reverses the order of the elements in the list.

rotate(distance : Number) : void

Rotates the elements in the list by the specified distance.

set(index : Number, value : Object) : Object

Replaces the object at the specified index in this list with the specified object.

shift() : Object

Removes and returns the first element of the list.

shuffle() : void

Randomly permutes the elements in the list.

size() : Number

Returns the size of this list.

slice(from : Number) : List

Returns a slice, or sublist, of this list.

slice(from : Number, to : Number) : List

Returns a slice, or sublist, of this list.

sort() : void

Sorts the elements of the list based on their natural order.

sort(comparator : Object) : void

Sorts the elements of a list.

subList(from : Number, to : Number) : List

Returns a list containing the elements in this list identified by the specified arguments.

swap(i : Number, j : Number) : void

Swaps the elements at the specified positions in the list.

unshift(values : Object...) : Number

Inserts values at the beginning of the list.

Methods inherited from class Collection

add, add1, addAll, clear, contains, containsAll, getLength, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

Methods inherited from class Object

assign, create, create, defineProperties, defineProperty, entries, freeze, fromEntries, getOwnPropertyDescriptor, getOwnPropertyNames, getOwnPropertySymbols, getPrototypeOf, hasOwnProperty, is, isExtensible, isFrozen, isPrototypeOf, isSealed, keys, preventExtensions, propertyIsEnumerable, seal, setPrototypeOf, toLocaleString, toString, valueOf, values

Method Detail

addAt

addAt(index : Number, value : Object) : void

Adds the specified object into the list at the specified index.

Parameters:

index - the index to use.

value - the object to insert.

concat

concat(values : Object...) : List

Creates and returns a new List that is the result of concatenating this list with each of the specified values. This list itself is unmodified. If any of the specified values is itself an array or a Collection, then the elements of that Collection or array are appended to the new list rather than the object itself.

Parameters:

values - one or more objects to concatenate.

Returns:

a new List that is the result of concatenating this list with each of the specified values.

fill

fill(obj : Object) : void

Replaces all of the elements in the list with the given object.

Parameters:

obj - the object to use during replacement.

get

get(index : Number) : Object

Returns the object at the specified index.

Parameters:

index - the index to use.

Returns:

the object at the specified index.

indexOf

indexOf(value : Object) : Number

Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element.

Parameters:

value - the element to use.

Returns:

the index of the specified object or -1 if the passed object is not found in the list.

join

join() : String

Converts all elements of the list to a string by calling the toString() method and then concatenates them together, with a comma between elements.

Returns:

The string that results from converting each element of the list to a string and then concatenating them together, with a comma between elements.

join

join(separator : String) : String

Converts all elements of the list to a string by calling the toString() method and then concatenates them together, with the separator string between elements. If null is passed, then the comma character is used as a separator.

Parameters:

separator - The separator string. May be null in which case the comma character is used.

Returns:

The string that results from converting each element of the list to a string and then concatenating them together, with the separator string between elements.

lastIndexOf

lastIndexOf(value : Object) : Number

Returns the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element.

Parameters:

value - the element to use.

Returns:

the last index of the specified object or -1 if the passed object is not found in the list.

pop

pop() : Object

Removes and returns the last element from the list.

Returns:

The last element of the list or null if the list is already empty.

push

push(values : Object...) : Number

Appends the specified values to the end of the list in order.

Parameters:

values - One or more values to be appended to the end of the list.

Returns:

The new length of the list, after the specified values are appended to it.

removeAt

removeAt(index : Number) : Object

Removes the object at the specified index.

Parameters:

index - the index to use.

Returns:

the object that was removed.

replaceAll

replaceAll(oldValue : Object, newValue : Object) : boolean

Replaces all occurrences of oldValue with newValue.

Parameters:

oldValue - the old object.

newValue - the new object.

Returns:

true if one or more elements were replaced, false otherwise.

reverse

reverse() : void

Reverses the order of the elements in the list.

rotate

rotate(distance : Number) : void

Rotates the elements in the list by the specified distance.

Parameters:

distance - the distance to use.

set

set(index : Number, value : Object) : Object

Replaces the object at the specified index in this list with the specified object.

Parameters:

index - the index to use.

value - the object to use when replacing the existing object.

Returns:

the replaced object.

shift

shift() : Object

Removes and returns the first element of the list. If the list is already empty, this method simply returns null.

Returns:

The former first element of the list, or null is list is already empty.

shuffle

shuffle() : void

Randomly permutes the elements in the list.

size

size() : Number

Returns the size of this list.

Returns:

the size of this list.

slice

slice(from : Number) : List

Returns a slice, or sublist, of this list. The returned list contains the element specified by from and all subsequent elements up to the end of this list.

Parameters:

from - The index at which the slice is to begin. If negative, this argument specifies a position measured from the end of this list. That, -1 indicates the last element, -2 indicates the next from the last element, and so on.

Returns:

A new List that contains the elements of this list from the element specified by from up to the end of this list.

slice

slice(from : Number, to : Number) : List

Returns a slice, or sublist, of this list. The returned list contains the element specified by from and all subsequent elements up to, but not including, the element specified by to.

Parameters:

from - The index at which the slice is to begin. If negative, this argument specifies a position measured from the end of this list. That, -1 indicates the last element, -2 indicates the next from the last element, and so on.

to - The index immediately after the end of the slice. If this argument is negative, it specifies an element measured from the end of this list.

Returns:

A new List that contains the elements of this list from the element specified by from up to, but not including, the element specified by to.

sort

sort() : void

Sorts the elements of the list based on their natural order.

This sort is guaranteed to be stable: equal elements will not be reordered as a result of the sort.

sort

sort(comparator : Object) : void

Sorts the elements of a list. The order of the elements is determined with a comparator (see PropertyComparator) or with the help of the given function. The function must take two parameters and return a value <0 if the first parameter is smaller than the second, a value of 0 if both are equal and a value if >0 if the first one is greater than the second parameter.

This sort is guaranteed to be stable: equal elements will not be reordered as a result of the sort.

Parameters:

comparator - an instance of a PropertyComparator or a comparison function

subList

subList(from : Number, to : Number) : List

Returns a list containing the elements in this list identified by the specified arguments.

Parameters:

from - the beginning index of the elements to move to the new list.

to - the ending index of the elements to move to the new list.

Returns:

the new list containing the elements.

swap

swap(i : Number, j : Number) : void

Swaps the elements at the specified positions in the list.

Parameters:

i - the first element to swap.

j - the second element to swap.

unshift

unshift(values : Object...) : Number

Inserts values at the beginning of the list. The first argument becomes the new element 0; the second argument becomes element 1; and so on.

Parameters:

values - The values to insert into the list.

Returns:

The new length of the lest.