Vec#

Vec<T> is an ArrayList<T> with extra helper methods. Every list field in the API has this type, for example ProjectData.tasks. Create one with a constructor, or pass any java.util.Collection to a setter or constructor that takes a list (withTasks(List.of(...))).

Declaration#

package org.dhtmlx.plen;

public class Vec<T> extends ArrayList<T>

All ArrayList and List methods work as usual. equals and hashCode come from ArrayList: two lists are equal when they hold equal elements in the same order. That's why a record's ValueRecord equality compares list fields element by element. A Vec allows null elements and isn't synchronized.

Unless a method says otherwise, methods that return a Vec return a new shallow copy and leave the receiver unchanged. Callbacks are the functional interfaces Fn1<A, R> (R apply(A v0)) and Fn2<A, B, R> (R apply(A v0, B v1)), so plain lambdas work.

Constructors#

public Vec()
public Vec(int capacity)
public Vec(Collection<? extends T> c)
public Vec(Iterable<? extends T> c)
public Vec(T[] a)

Name	Type	Description
`capacity`	`int`	Initial capacity. The list starts empty. Negative values throw `IllegalArgumentException`.
`c`	`Collection<? extends T>` / `Iterable<? extends T>`	Elements to copy, in iteration order.
`a`	`T[]`	Elements to copy, in array order.

Methods#

Transform#

convertAll, select#

public <R> Vec<R> convertAll(Fn1<T, R> f)
public <R> Vec<R> select(Fn1<T, R> f)
public <R> Vec<R> select(Fn2<T, Integer, R> f)

Returns a new Vec with f applied to each element, in order. convertAll and the one-argument select are the same. The two-argument select also passes the element's index.

selectMany#

public <R> Vec<R> selectMany(Fn1<T, ? extends Iterable<R>> f)

Applies f to each element and joins the returned sequences into one Vec, in order.

where#

public Vec<T> where(Fn1<T, Boolean> f)

Returns the elements for which f returns true, in order.

distinct#

public Vec<T> distinct()

Returns the elements with duplicates removed (by equals). Each element keeps the position of its first occurrence.

concat#

public Vec<T> concat(Iterable<T> other)

Returns a new Vec with the receiver's elements followed by those of other.

toList#

public Vec<T> toList()

Returns a shallow copy.

toHashSet#

public Set<T> toHashSet()

Returns the elements as an org.dhtmlx.plen.Set<T>, a LinkedHashSet<T> subclass that keeps first-occurrence order. Assign it to java.util.Set<T> or LinkedHashSet<T> when java.util.* is also imported.

toDictionary#

public <K, V> Dict<K, V> toDictionary(Fn1<T, K> key, Fn1<T, V> val)
public <K, V> Dict<K, V> toDictionary(Fn1<T, K> key, Fn1<T, V> val, Comparator<?> cmp)

Returns a map from key(element) to val(element). Dict<K, V> is a LinkedHashMap<K, V> subclass, so entries keep the list order. On a duplicate key, the later element's value replaces the earlier one. The three-argument form ignores cmp.

Order#

sort#

public void sort()

Sorts the list in place by natural order. Elements must implement Comparable, otherwise it throws ClassCastException. sort(Comparator) from List is still available.

order, orderBy#

public Vec<T> order()
public Vec<T> order(Comparator<? super T> c)
public <R extends Comparable<? super R>> Vec<T> orderBy(Fn1<T, R> f)
public <R> Vec<T> orderBy(Fn1<T, R> f, Comparator<R> c)

Returns a sorted copy. order() uses natural order, order(c) uses c, and orderBy compares the keys that f returns, by natural order or by c. The sort is stable: equal elements keep their relative order.

reverse#

public void reverse()

Reverses the list in place.

binarySearch#

public int binarySearch(T value)

Searches the list, which must already be sorted by natural order. Returns the index of value, or -(insertion point) - 1 when it's absent. Elements must implement Comparable.

sequenceCompareTo#

public int sequenceCompareTo(Vec<T> other)

Compares two lists element by element by natural order. The first unequal pair decides. If one list is a prefix of the other, the shorter list is smaller. Returns a negative number, zero or a positive number.

Query#

any, all, trueForAll#

public boolean any()
public boolean any(Fn1<T, Boolean> f)
public boolean all(Fn1<T, Boolean> f)
public boolean trueForAll(Fn1<T, Boolean> f)

any() returns true when the list isn't empty. any(f) returns true when f holds for at least one element (false on an empty list). all(f) and trueForAll(f) are the same: true when f holds for every element (true on an empty list).

count#

public int count(Fn1<T, Boolean> f)

Returns the number of elements for which f returns true. Use size() for the total.

sum#

public double sum(Fn1<T, Double> f)

Returns the sum of f(element) over all elements, 0.0 for an empty list.

find, findIndex#

public T find(Fn1<T, Boolean> f)
public int findIndex(Fn1<T, Boolean> f)

find returns the first element for which f returns true, or null. findIndex returns its index, or -1.

first, last, firstOrDefault#

public T first()
public T last()
public T firstOrDefault()
public T firstOrDefault(Fn1<T, Boolean> f)

first and last return the first and last element and throw IndexOutOfBoundsException on an empty list. firstOrDefault() returns the first element or null when the list is empty. firstOrDefault(f) is the same as find(f).

sequenceEqual#

public boolean sequenceEqual(Iterable<T> other)
public boolean sequenceEqual(T[] other)
public boolean sequenceEqual(Iterable<T> other, Object ignored)

Returns true when other has the same length and equal elements (Objects.equals) in the same order. The three-argument form ignores its second argument.

Slice#

take, skip#

public Vec<T> take(int n)
public Vec<T> skip(int n)

take returns the first n elements and skip returns the rest. An n larger than size() is clamped. A negative n throws IndexOutOfBoundsException.

getRange, asSpan#

public Vec<T> getRange(int start, int count)
public Vec<T> asSpan(int start, int n)
public Vec<T> asSpan()

getRange and the two-argument asSpan return a copy of count (n) elements from start. They throw IndexOutOfBoundsException when the range falls outside the list. asSpan() returns the receiver itself, not a copy.

Edit#

addRange#

public void addRange(Iterable<? extends T> other)
public void addRange(T[] other)

Appends every element of other, in order.

insert#

public void insert(int i, T value)

Inserts value at index i and shifts later elements right. Same as add(i, value).

removeAt#

public void removeAt(int i)

Removes the element at index i. Throws IndexOutOfBoundsException when i is out of range.

removeAll#

public int removeAll(Fn1<T, Boolean> f)

Removes every element for which f returns true and returns how many were removed. removeAll(Collection) from List is still available.

Example#

import org.dhtmlx.plen.*;
import java.util.List;

public class VecExample {
  public static void main(String[] args) throws Exception {
    var data = new ProjectData().withTasks(List.of(
        new TaskData(Id.num(1)).withDuration(2.0),
        new TaskData(Id.num(2)).withDuration(5.0),
        new TaskData(Id.num(3)).withDuration(1.0)));

    Vec<TaskData> tasks = data.tasks;
    double total = tasks.sum(t -> t.duration);
    Vec<Id> longIds = tasks.where(t -> t.duration > 1.5).select(t -> t.id);
    TaskData shortest = tasks.orderBy(t -> t.duration).first();

    System.out.println(total);             // 8.0
    System.out.println(longIds.size());    // 2
    System.out.println(shortest.duration); // 1.0
  }
}

ValueRecord - record equality over list fields
ProjectData - a record with list fields
Records, ids and dates - list fields and List.of(...) setters