Reference > Classes

List¶

Definition¶

1	`List var = .... ;`

Extends¶

Extended By¶

None

Description¶

An ordered collection of data used for random access based on position. Entries are stored in the order added (Backed by Java ArrayList).

Method Summary¶

Owner	Name	Return Type	Description
List	constructor(list_elements)	Object	Initialize a list containing the specified elements in the order they were supplied.
List	add(values)	Object	Adds the value(s) to the end of the list.
Collection	addAll(valuesToAdd)	Object	Adds all elements contained in the iterable to this collection
List	batch(batchSize)	List	Divides the list into batches (a list of lists), based on the supplied batch size.
Collection	clear()	Boolean	Removes all elements in this collection. Returns "true" if this operation removed at least 1 element, returns "false" if it was empty.
List	contains(value)	Boolean	Returns "true" if the element is in the list, "false" if not.
List	get(index)	Object	Returns the value found at the supplied index, or "null" if the index is null or out of bounds.
Object	getClassName()	String	Returns the string name of this object's class type.
List	indexOf(value)	Integer	Returns the index of the first occurrence of the specified element in this list; returns -1 if no such index exists.
Iterable	iterator()	Iterator	Returns an iterator over this container's objects. Methods are defined in the Iterator class.
List	jsonPath(jsonPath)	Object	For lists with nested elements, returns the json at the supplied element path. Use dot (.) to delimit the path. If supplied null, the object is returned. Use numbers to traverse list elements and keys to traverse maps
List	remove(index)	Object	Removes the value at the supplied index. Returns the removed element.
List	set(index, element)	Object	Replaces the element at the specified position in this list with the specified element. Returns the original value of the replaced element.
Collection	size()	Integer	Returns the size of this collection
Collection	sort()	List	Returns a sorted list of the specified collection. Sorting is done according to the elements' type's natural ordering. This sort is guaranteed to be stable, equal elements will not be reordered as a result of the sort.
List	splice(index, howmany, values)	Integer	Inserts or overwrites elements in a list based on the supplied index and number of elements to replace. Returns ths size of the resulting list.
Object	toJson()	String	Returns a string of a json representation of this object.

Method Definitions¶

constructor(list_elements)¶

List list = new List(Object ... list_elements)

Description¶

Initialize a list containing the specified elements in the order they were supplied.

Parameter Definition¶

Name	Type	Description
list_elements	Object ...	element to be added in list construction

Example 1¶

List l = new List("a", "b", "c");

// l = [a, b, c]

Example 2¶

List l = new List("a", null, 1);

// l = [a, null, 1]

Example 3¶

List py_list = ["a", "b", "c"];

// py_list = [a, b, c]

Python-style syntax for initiating lists in AMI

add(values)¶

Object List::add(Object ... values)

Description¶

Adds the value(s) to the end of the list.

Parameter Definition¶

Name	Type	Description
values	Object ...	ordered list of values

Example 1¶

List l = new List("a");
l.add("b");

// l = [a, b]

addAll(valuesToAdd)¶

Object Collection::addAll(Iterable valuesToAdd)

Description¶

Adds all elements contained in the iterable to this collection

Parameter Definition¶

Name	Type	Description
valuesToAdd	Iterable	The values to add to this collection

Example 1¶

List l1 = new List("a","b");
List l2 = new List("c","d");
List l = l1.addAll(l2);

// l = [a, b, c, d]

batch(batchSize)¶

List List::batch(Integer batchSize)

Description¶

Divides the list into batches (a list of lists), based on the supplied batch size.

Parameter Definition¶

Name	Type	Description
batchSize	Integer	the maximum size of each batch

Example 1¶

List l = new List("a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m");
List l_batched = l.batch(5);

// l_batched = [[a, b, c, d, e], [f, g, h, i, j], [k, l, m]]

For this example containing a list of 13 elements (the alphabet) batched using 5 would result in these three lists:

A list containing elements 1-5
A list containing elements 6-10
A list containing the remaining elements 11-13

clear()¶

Boolean Collection::clear()

Description¶

Removes all elements in this collection. Returns "true" if this operation removed at least 1 element, returns "false" if it was empty.

Example 1¶

List l = new List("a","b","c");
l.clear();

// l = []

contains(value)¶

Boolean List::contains(Object value)

Description¶

Returns "true" if the element is in the list, "false" if not.

Parameter Definition¶

Name	Type	Description
value	Object	value of element to check is in the list

Example 1¶

List l = new List("a", "b", "c");
l.contains("a");

// l.contains("a") = true

Example 2¶

List l = new List("a", "b", "c");
l.contains("d");

// l.contains("d") = false

get(index)¶

Object List::get(Integer index)

Description¶

Returns the value found at the supplied index, or "null" if the index is null or out of bounds.

Parameter Definition¶

Name	Type	Description
index	Integer	zero based index

Example 1¶

List l = new List("a","b","c");
l.get(0);

// l.get(0) = a

Example 2¶

List l = new List("a", "b", "c");
l.get(3);

// l.get(3); = null

getClassName()¶

String Object::getClassName()

Description¶

Returns the string name of this object's class type.

Example 9¶

List l = new List("a", "b", "c");
l.getClassName();

// l.getClassName() = List

indexOf(value)¶

Integer List::indexOf(Object value)

Description¶

Returns the index of the first occurrence of the specified element in this list; returns -1 if no such index exists.

Parameter Definition¶

Name	Type	Description
value	Object	element to get index of

Example 1¶

List l = new List("a","b","c");
l.indexOf("a");

// l.indexOf("a") = 0

Example 2¶

List l = new List("a","b","c");
l.indexOf("d");

// l.indexOf("d") = -1

iterator()¶

Iterator Iterable::iterator()

Description¶

Returns an iterator over this container's objects. Methods are defined in the Iterator class.

Example 3¶

List l = new List("3","f","o","r","g","e");
Iterator i = l.iterator();
string temp = "";
while(i.hasNext()) { 
    temp += i.next();
}
// i.hasNext() = false
// temp = 3forge

jsonPath(jsonPath)¶

Object List::jsonPath(String jsonPath)

Description¶

For lists with nested elements, returns the json at the supplied element path. Use dot (.) to delimit the path. If supplied null, the object is returned. Use numbers to traverse list elements and keys to traverse maps

Parameter Definition¶

Name	Type	Description
jsonPath	String	dot(.) delimited path

Example 1¶

List l = new List(new Map("Crouton", "Dog"), new Map("Artemis", "Cat"));
String pet = l.jsonPath("1.Artemis");

// l.jsonPath("1.Artemis") = Cat
// pet = Cat

The list "l" is a nested list containing maps as its nested elements. In this example, jsonPath() is used to extract the corresponding value (the type of pet) of the 1st nested map with the key "Artemis".

Example 2¶

List l = new List(new Map("Crouton", "Dog"), new Map("Artemis", "Cat"));
String pet = l[1]["Artemis"];

// l[1]["Artemis"] = Cat

You can access nested list elements using Python-like syntax instead by supplying each key/index in a series of square brackets.

Example 3¶

List l = new List(new Map("Crouton", "Dog"), new Map("Artemis", "Cat"));
String q1 = l.jsonPath(null);
String q2 = l.jsonPath("");

// l.jsonPath(null) = [{Crouton=Dog}, {Artemis=Cat}]
// l.jsonPath("") = null

remove(index)¶

Object List::remove(Integer index)

Description¶

Removes the value at the supplied index. Returns the removed element.

Parameter Definition¶

Name	Type	Description
index	Integer	position of value to remove

Example 1¶

List l = new List(1, 2, 3, "four");
String r = l.remove(3);

// l = [1, 2, 3]
// r = four

set(index,element)¶

Object List::set(Integer index, Object element)

Description¶

Replaces the element at the specified position in this list with the specified element. Returns the original value of the replaced element.

Parameter Definition¶

Name	Type	Description
index	Integer	position
element	Object	new value

Example 1¶

List l = new List("one", 2, 3);
l.set(0,1);

// l = [1, 2, 3]

size()¶

Integer Collection::size()

Description¶

Returns the size of this collection

Example 1¶

List l = new List("a","b","c");
l.size();

// l.size() = 3

sort()¶

List Collection::sort()

Description¶

Returns a sorted list of the specified collection. Sorting is done according to the elements' type's natural ordering. This sort is guaranteed to be stable, equal elements will not be reordered as a result of the sort.

Example 1¶

List l1 = new List("c","b","a");
List l2 = new List(3,1,2);
l1.sort();
l2.sort();

// l1.sort() = [a, b, c]
// l2.sort() = [1, 2, 3]

splice(index,howmany,values)¶

Integer List::splice(Integer index, Integer howmany, Object ... values)

Description¶

Inserts or overwrites elements in a list based on the supplied index and number of elements to replace. Returns ths size of the resulting list.

Parameter Definition¶

Name	Type	Description
index	Integer	zero based index
howmany	Integer	number of items to replace
values	Object ...	values to use in replacement

Example 1¶

List l = new List("Crooton", "Reggie");
l.splice(0,1,"Crouton", "Artemis");

// l = [Crouton, Artemis, Reggie]

This example replaces one element at index 0 with the first supplied new element, and adds the second element after.

Example 2¶

List l = new List("Crouton", "Reggie");
l.splice(1,0,"Artemis");

// l = [Crouton, Artemis, Reggie]

This example does not replace any element, essentially acting as an insertion at index 1 with the supplied string "Artemis".

toJson()¶

String Object::toJson()

Description¶

Returns a string of a json representation of this object.

Example 9¶

List l = new List("a", "b", "c");
l.toJson();

// l.toJson() = ["a","b","c"]