com.anylogic.engine.UtilitiesCollection

public final class UtilitiesCollection
extends UtilitiesStream

This class provides a lot of commonly used functions for operations with collections / agent populations

Author:: AnyLogic North America, LLC https://anylogic.com

Method Summary

Modifier and Type	Method	Description
`static <T> boolean`	`addAll(Collection<? super T> c, Collection<T> elements)`	Adds all of the elements in the specified collection to this collection.
`static <T> boolean`	`addAll(Collection<? super T> c, T... elements)`	Adds all of the specified elements to the specified collection.
`static double`	`average(Iterable<? extends Number> collection)`	Returns average value in the given collection with numbers.
`static <T> double`	`average(Iterable<T> collection, ToDoubleFunction<? super T> value)`	Returns average value in the given collection. Usage examples:
`static <T> double`	`averageWhere(Iterable<T> collection, ToDoubleFunction<? super T> value, Predicate<? super T> condition)`	Returns average of values in the given collection among elements which meet the given condition. Usage examples:
`static <T> int`	`count(Iterable<T> collection, Predicate<? super T> condition)`	Returns the number of elements/agents in the given collection which meet the given condition. Usage examples:
`static <T> List<T>`	`filter(Iterable<T> collection, Predicate<? super T> condition)`	Returns new list with elements/agents from the original collection which meet the given condition. Usage examples:
`static <T> List<T>`	`filter(T[] array, Predicate<? super T> condition)`	Returns new list with elements/agents from original array which meet the given condition. Usage examples:
`static <T> List<T>`	`findAll(Iterable<T> collection, Predicate<? super T> condition)`	This function is the same as `filter(Iterable, Predicate)`
`static <T> List<T>`	`findAll(T[] array, Predicate<? super T> condition)`	This function is the same as `filter(Object[], Predicate)`
`static <T> T`	`findFirst(Iterable<T> collection, Predicate<? super T> condition)`	Returns the first element/agent from the given collection which meets the given condition. Usage example:
`static <T> T`	`findFirst(T[] array, Predicate<? super T> condition)`	Returns the first element/agent from the given array which meets the given condition. Usage example:
`static <T extends Comparable<? super T>> T`	`findMax(Iterable<T> collection)`	Returns 'maximum' element in the given collection according to natural ordering (elements should be comparable). If there are multiple elements which are the 'maximum', the first one is returned.
`static <T> T`	`findMax(Iterable<T> collection, ToDoubleFunction<? super T> value)`	Returns element having maximum value in the given collection. Usage examples:
`static <T extends Comparable<? super T>> T`	`findMin(Iterable<T> collection)`	Returns 'minimum' element in the given collection according to natural ordering (elements should be comparable). If there are multiple elements which are the 'minimum', the first one is returned.
`static <T> T`	`findMin(Iterable<T> collection, ToDoubleFunction<? super T> value)`	Returns element having minimum value in the given collection. Usage examples:
`static <T> int`	`indexOfFirst(Iterable<T> collection, Predicate<? super T> condition)`	Returns the index of the first element/agent from the given collection which meets the given condition. Usage example:
`static <T> int`	`indexOfFirst(T[] array, Predicate<? super T> condition)`	Returns the index of the first element/agent from the given array which meets the given condition. Usage example:
`static double`	`max(Iterable<? extends Number> collection)`	Returns maximum value in the given collection with numbers.
`static <T> double`	`max(Iterable<T> collection, ToDoubleFunction<? super T> value)`	Returns maximum value in the given collection. Usage examples:
`static <T> double`	`maxWhere(Iterable<T> collection, ToDoubleFunction<? super T> value, Predicate<? super T> condition)`	Returns maximum value of element in the given collection among elements which meet the given condition. Usage examples:
`static double`	`min(Iterable<? extends Number> collection)`	Returns minimum value in the given collection with numbers.
`static <T> double`	`min(Iterable<T> collection, ToDoubleFunction<? super T> value)`	Returns minimum value in the given collection. Usage examples:
`static <T> double`	`minWhere(Iterable<T> collection, ToDoubleFunction<? super T> value, Predicate<? super T> condition)`	Returns minimum value of element in the given collection among elements which meet the given condition. Usage examples:
`static <T> List<T>`	`sortAscending(Iterable<T> collection, ToDoubleFunction<? super T> value)`	Deprecated. use `sorted(Iterable, ToDoubleFunction)`
`static <T extends Comparable<? super T>> void`	`sortAscending(List<T> list)`	Sorts (modifies) the specified list into ascending order, according to the natural ordering of its elements.
`static <T> List<T>`	`sortDescending(Iterable<T> collection, ToDoubleFunction<? super T> value)`	Deprecated. use `sortedDescending(Iterable, ToDoubleFunction)`
`static <T extends Comparable<? super T>> void`	`sortDescending(List<T> list)`	Sorts (modifies) the specified list into ascending order, according to the inverted natural ordering of its elements.
`static <T extends Comparable<? super T>> List<T>`	`sorted(Iterable<T> collection)`	Returns a new list with rearranged elements from the given collection sorted ascending, according to the natural ordering.
`static <T> List<T>`	`sorted(Iterable<T> collection, ToDoubleFunction<? super T> value)`	Returns a new list with rearranged elements/agents from the given collection sorted ascending by some numeric value.
`static <T extends Comparable<? super T>> List<T>`	`sortedDescending(Iterable<T> collection)`	Returns a new list with rearranged elements from the given collection sorted descending, i.e.
`static <T> List<T>`	`sortedDescending(Iterable<T> collection, ToDoubleFunction<? super T> value)`	Returns a new list with rearranged elements/agents from the given collection sorted descending by some numeric value.
`static double`	`sum(Iterable<? extends Number> collection)`	Returns sum of values in the given collection with numbers.
`static <T> double`	`sum(Iterable<T> collection, ToDoubleFunction<? super T> value)`	Returns sum of values in the given collection. Usage examples:
`static <T> double`	`sumWhere(Iterable<T> collection, ToDoubleFunction<? super T> value, Predicate<? super T> condition)`	Returns sum of values in the given collection among elements which meet the given condition. Usage examples:
`static <T> T`	`top(Iterable<T> collection, ToDoubleFunction<? super T> value)`	Deprecated. please use `findMax(Iterable, ToDoubleFunction)`

Methods inherited from class com.anylogic.engine.UtilitiesStream

streamOfElements, streamOfElements

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

filter

public static <T> List<T> filter(Iterable<T> collection,
 Predicate<? super T> condition)

Returns new list with elements/agents from the original collection which meet the given condition.
Usage examples:

 for (Person person : filter( people, p -> p.age > 20 )) {
        traceln( person );
 }
 
 Person person = randomFrom( filter( people, p -> p.income < 5000 ) );

Parameters:: collection - the collection of elements/agents to be iterated through; condition - the condition to test
Returns:: always new instance of list, modifiable, with elements which have true value of the given condition

filter

public static <T> List<T> filter(T[] array,
 Predicate<? super T> condition)

Returns new list with elements/agents from original array which meet the given condition.
Usage examples:

 for (Person person : filter( peopleArray, p -> p.age > 20 )) {
        traceln( person );
 }
 
 Person person = randomFrom( filter( peopleArray, p -> p.income < 5000 ) );

Parameters:: array - the array of elements/agents to be iterated through; condition - the condition to test
Returns:: always new instance of list, modifiable, with elements which have true value of the given condition

findAll

public static <T> List<T> findAll(Iterable<T> collection,
 Predicate<? super T> condition)

This function is the same as filter(Iterable, Predicate)

Since:

7.2

See Also:

filter(Iterable, Predicate)

findAll

public static <T> List<T> findAll(T[] array,
 Predicate<? super T> condition)

This function is the same as filter(Object[], Predicate)

Since:

7.2

See Also:

filter(Object[], Predicate)

findFirst

public static <T> T findFirst(Iterable<T> collection,
 Predicate<? super T> condition)

Returns the first element/agent from the given collection which meets the given condition.
Usage example:

 Person person = findFirst( people, p -> p.age > 20 );

Parameters:: collection - the collection of elements/agents to be iterated through; condition - the condition to test
Returns:: the element which has true value of the given condition, or null if there is no such element or the collection is empty.
Since:: 7.2

findFirst

public static <T> T findFirst(T[] array,
 Predicate<? super T> condition)

Returns the first element/agent from the given array which meets the given condition.
Usage example:

 Person person = findFirst( peopleArray, p -> p.age > 20 );

Parameters:: array - the array of elements/agents to be iterated through; condition - the condition to test
Returns:: the element which has true value of the given condition, or null if there is no such element or the array is empty.
Since:: 7.2

indexOfFirst

public static <T> int indexOfFirst(Iterable<T> collection,
 Predicate<? super T> condition)

Returns the index of the first element/agent from the given collection which meets the given condition.
Usage example:

 int i = indexOfFirst( people, p -> p.age > 20 );

Parameters:: collection - the collection of elements/agents to be iterated through; condition - the condition to test
Returns:: the index of the first element which has true value of the given condition, or -1 if there is no such element or the collection is empty.
Since:: 8.5.0

indexOfFirst

public static <T> int indexOfFirst(T[] array,
 Predicate<? super T> condition)

Returns the index of the first element/agent from the given array which meets the given condition.
Usage example:

 int i = indexOfFirst( peopleArray, p -> p.age > 20 );

Parameters:: array - the array of elements/agents to be iterated through; condition - the condition to test
Returns:: the index of the first element which has true value of the given condition, or -1 if there is no such element or the array is empty.
Since:: 8.5.0

count

public static <T> int count(Iterable<T> collection,
 Predicate<? super T> condition)

Returns the number of elements/agents in the given collection which meet the given condition.
Usage examples:

 traceln(count( people, p -> p.income > 10000 ));

Parameters:: collection - the collection of elements/agents to be iterated through during calculation; condition - the condition to test
Returns:: the number of agents in the given collection which have true value of the given condition

max

public static double max(Iterable<? extends Number> collection)

Returns maximum value in the given collection with numbers.

Parameters:: collection - the collection of numbers to be iterated through during calculation
Returns:: maximum value in the given collection.
Returns -infinity if the collection is empty
Since:: 8.9.8

max

public static <T> double max(Iterable<T> collection,
 ToDoubleFunction<? super T> value)

Returns maximum value in the given collection.
Usage examples:

 traceln(max( people, p -> p.income ));

Parameters:: collection - the collection of elements/agents to be iterated through during calculation; value - the value function, returning numeric value for each element
Returns:: maximum value in the given collection.
Returns -infinity if the collection is empty

maxWhere

public static <T> double maxWhere(Iterable<T> collection,
 ToDoubleFunction<? super T> value,
 Predicate<? super T> condition)

Returns maximum value of element in the given collection
among elements which meet the given condition.
Usage examples:

 traceln(maxWhere( people, p -> p.income, p -> p.age > 18 ));

Parameters:: collection - the collection of elements/agents to be iterated through during calculation; value - the value function, returning numeric value for each element
Returns:: maximum value in the given collection with the given condition.
Returns -infinity if the collection is empty

min

public static double min(Iterable<? extends Number> collection)

Returns minimum value in the given collection with numbers.

Parameters:: collection - the collection of numbers to be iterated through during calculation
Returns:: minimum value in the given collection.
Returns +infinity if the collection is empty
Since:: 8.9.8

min

public static <T> double min(Iterable<T> collection,
 ToDoubleFunction<? super T> value)

Returns minimum value in the given collection.
Usage examples:

 traceln(min( people, p -> p.income ));

Parameters:: collection - the collection of elements/agents to be iterated through during calculation; value - the value function, returning numeric value for each element
Returns:: minimum value in the given collection.
Returns +infinity if the collection is empty

minWhere

public static <T> double minWhere(Iterable<T> collection,
 ToDoubleFunction<? super T> value,
 Predicate<? super T> condition)

Returns minimum value of element in the given collection
among elements which meet the given condition.
Usage examples:

 traceln(minWhere( people, p -> p.income, p -> p.age > 18 ));

Parameters:: collection - the collection of elements/agents to be iterated through during calculation; value - the value function, returning numeric value for each element
Returns:: minimum value in the given collection with the given condition.
Returns +infinity if the collection is empty

sum

public static double sum(Iterable<? extends Number> collection)

Returns sum of values in the given collection with numbers.

Parameters:: collection - the collection of numbers to be iterated through during calculation
Returns:: sum of values in the given collection
Since:: 8.9.8

sum

public static <T> double sum(Iterable<T> collection,
 ToDoubleFunction<? super T> value)

Returns sum of values in the given collection.
Usage examples:

 traceln(sum( people, p -> p.income ));

Parameters:: collection - the collection of elements/agents to be iterated through during calculation; value - the value function, returning numeric value for each element
Returns:: sum of values in the given collection

sumWhere

public static <T> double sumWhere(Iterable<T> collection,
 ToDoubleFunction<? super T> value,
 Predicate<? super T> condition)

Returns sum of values in the given collection
among elements which meet the given condition.
Usage examples:

 traceln(sumWhere( people, p -> p.income, p -> p.age > 18 ));

Parameters:: collection - the collection of elements/agents to be iterated through during calculation; value - the value function, returning numeric value for each element
Returns:: sum of values in the given collection with the given condition

average

public static double average(Iterable<? extends Number> collection)

Returns average value in the given collection with numbers.

Parameters:: collection - the collection of numbers to be iterated through during calculation
Returns:: average of elements value in the given collection, or NaN if the collection is empty
Since:: 8.9.8

average

public static <T> double average(Iterable<T> collection,
 ToDoubleFunction<? super T> value)

Returns average value in the given collection.
Usage examples:

 traceln(average( people, p -> p.income ));

Parameters:: collection - the collection of elements/agents to be iterated through during calculation; value - the value function, returning numeric value for each element
Returns:: average of elements value in the given collection, or NaN if the collection is empty

averageWhere

public static <T> double averageWhere(Iterable<T> collection,
 ToDoubleFunction<? super T> value,
 Predicate<? super T> condition)

Returns average of values in the given collection
among elements which meet the given condition.
Usage examples:

 traceln(averageWhere( people, p -> p.income, p -> p.age > 18 ));

Parameters:: collection - the collection of elements/agents to be iterated through during calculation; value - the value function, returning numeric value for each element
Returns:: average of values in the given collection with the given condition, or NaN if the collection has no matching elements

findMin

public static <T> T findMin(Iterable<T> collection,
 ToDoubleFunction<? super T> value)

Returns element having minimum value in the given collection.
Usage examples:

 traceln(findMin( people, p -> p.income ));

If there are multiple elements with the same minimum value, the first one is returned.

Parameters:: collection - the collection of elements/agents to be iterated through during calculation; value - the value function, returning numeric value for each element
Returns:: element having minimum value in the given collection.
Returns null if the collection is empty
Since:: 8.9.8

findMax

public static <T> T findMax(Iterable<T> collection,
 ToDoubleFunction<? super T> value)

Returns element having maximum value in the given collection.
Usage examples:

 traceln(findMax( people, p -> p.income ));

If there are multiple elements with the same maximum value, the first one is returned.

Parameters:: collection - the collection of elements/agents to be iterated through during calculation; value - the value function, returning numeric value for each element
Returns:: element having maximum value in the given collection.
Returns null if the collection is empty
Since:: 8.9.8

findMin

public static <T extends Comparable<? super T>> T findMin(Iterable<T> collection)

Returns 'minimum' element in the given collection according to natural ordering (elements should be comparable).
If there are multiple elements which are the 'minimum', the first one is returned.

Parameters:: collection - the collection of elements to be iterated through during calculation
Returns:: the 'minimum' element according to natural ordering.
Returns null if the collection is empty
Since:: 8.9.8

findMax

public static <T extends Comparable<? super T>> T findMax(Iterable<T> collection)

Returns 'maximum' element in the given collection according to natural ordering (elements should be comparable).
If there are multiple elements which are the 'maximum', the first one is returned.

Parameters:: collection - the collection of elements to be iterated through during calculation
Returns:: the 'maximum' element according to natural ordering.
Returns null if the collection is empty
Since:: 8.9.8

top

@Deprecated(forRemoval=false)
@AnyLogicLegacyAPI
public static <T> T top(Iterable<T> collection,
 ToDoubleFunction<? super T> value)

Deprecated.

please use findMax(Iterable, ToDoubleFunction)

Same as findMax(collection, value)

See Also:

findMax(Iterable, ToDoubleFunction)

sortAscending

public static <T extends Comparable<? super T>>
void sortAscending(List<T> list)

Sorts (modifies) the specified list into ascending order, according to the natural ordering of its elements. All elements in the list must implement the Comparable interface.

The specified list must be modifiable

Type Parameters:: T - the class of the objects in the list
Parameters:: list - the list to be sorted.
Since:: 8.0
See Also:: List.sort(Comparator)

sortDescending

public static <T extends Comparable<? super T>>
void sortDescending(List<T> list)

Sorts (modifies) the specified list into ascending order, according to the inverted natural ordering of its elements. All elements in the list must implement the Comparable interface.

The specified list must be modifiable

Type Parameters:: T - the class of the objects in the list
Parameters:: list - the list to be sorted.
Since:: 8.0
See Also:: List.sort(Comparator)

sorted

public static <T extends Comparable<? super T>>
List<T> sorted(Iterable<T> collection)

Returns a new list with rearranged elements from the given collection sorted ascending, according to the natural ordering. All elements in the list must implement the Comparable interface.

 var namesAtoZ = sorted( names );

Parameters:: collection - the collection of elements
Returns:: list sorted ascending (by the natural ordering of its elements)

sorted

public static <T> List<T> sorted(Iterable<T> collection,
 ToDoubleFunction<? super T> value)

Returns a new list with rearranged elements/agents from the given collection sorted ascending by some numeric value.

 var newList = sorted( people, p -> p.income );

Parameters:: collection - the collection of elements/agents; value - the value function, returning numeric value for each element
Returns:: list sorted ascending by the numeric value.

sortedDescending

public static <T extends Comparable<? super T>>
List<T> sortedDescending(Iterable<T> collection)

Returns a new list with rearranged elements from the given collection sorted descending, i.e. opposite to the natural ordering. All elements in the list must implement the Comparable interface.

 var namesZtoA = sorted( names );

Parameters:: collection - the collection of elements
Returns:: list sorted descending (reverse to the natural ordering of its elements)

sortedDescending

public static <T> List<T> sortedDescending(Iterable<T> collection,
 ToDoubleFunction<? super T> value)

Returns a new list with rearranged elements/agents from the given collection sorted descending by some numeric value.

 var newList = sortedDescending( people, p -> p.income ));

Parameters:: collection - the collection of elements/agents; value - the value function, returning numeric value for each element
Returns:: list sorted descending by the numeric value.

sortAscending

@Deprecated(forRemoval=false)
@AnyLogicLegacyAPI
public static <T> List<T> sortAscending(Iterable<T> collection,
 ToDoubleFunction<? super T> value)

Deprecated.

use sorted(Iterable, ToDoubleFunction)

Returns a new list with rearranged elements/agents from the given collection sorted ascending by value.

sortDescending

@Deprecated(forRemoval=false)
@AnyLogicLegacyAPI
public static <T> List<T> sortDescending(Iterable<T> collection,
 ToDoubleFunction<? super T> value)

Deprecated.

use sortedDescending(Iterable, ToDoubleFunction)

Returns a new list with rearranged elements/agents from the given collection sorted descending by value.

addAll

@SafeVarargs
public static <T> boolean addAll(Collection<? super T> c,
 T... elements)

Adds all of the specified elements to the specified collection. Elements to be added may be specified individually or as an array. The behavior of this convenience method is identical to that of c.addAll(Arrays.asList(elements)), but this method is likely to run significantly faster under most implementations.

When elements are specified individually, this method provides a convenient way to add a few elements to an existing collection:

     Collections.addAll(flavors, "Peaches 'n Plutonium", "Rocky Racoon");

Parameters:

c - the collection into which elements are to be inserted

elements - the elements to insert into c

Returns:

true if the collection changed as a result of the call

Since:

7.2

See Also:

Collections.addAll(Collection, Object...)

addAll

public static <T> boolean addAll(Collection<? super T> c,
 Collection<T> elements)

Adds all of the elements in the specified collection to this collection.

Parameters:: c - collection containing elements to be added to this collection
Returns:: true if this collection changed as a result of the call
Since:: 7.2
See Also:: Collection.addAll(Collection)

Class UtilitiesCollection

Method Summary

Methods inherited from class com.anylogic.engine.UtilitiesStream

Methods inherited from class java.lang.Object

Method Details

filter

filter

findAll

findAll

findFirst

findFirst

indexOfFirst

indexOfFirst

count

max

max

maxWhere

min

min

minWhere

sum

sum

sumWhere

average

average

averageWhere

findMin

findMax

findMin

findMax

top

sortAscending

sortDescending

sorted

sorted

sortedDescending

sortedDescending

sortAscending

sortDescending

addAll

addAll