[Canonical page](<https://docs.dhtmlx.com/planning-engine/java/api/support/vec/>)
[Full documentation index](<https://docs.dhtmlx.com/planning-engine/llms.txt>)


# Vec

`Vec<T>` is an `ArrayList<T>` with extra helper methods. Every list field in the API has this type, for example [`ProjectData.tasks`](<https://docs.dhtmlx.com/planning-engine/java/api/data/project-data.md>). Create one with a constructor, or pass any `java.util.Collection` to a setter or constructor that takes a list (`withTasks(List.of(...))`).

## Declaration

```java
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`](<https://docs.dhtmlx.com/planning-engine/java/api/support/value-record.md>) 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

```java
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

```java
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

```java
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

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

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

#### distinct

```java
public Vec<T> distinct()
```

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

#### concat

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

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

#### toList

```java
public Vec<T> toList()
```

Returns a shallow copy.

#### toHashSet

```java
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

```java
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

```java
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

```java
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

```java
public void reverse()
```

Reverses the list in place.

#### binarySearch

```java
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

```java
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

```java
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

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

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

#### sum

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

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

#### find, findIndex

```java
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

```java
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

```java
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

```java
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

```java
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

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

Appends every element of `other`, in order.

#### insert

```java
public void insert(int i, T value)
```

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

#### removeAt

```java
public void removeAt(int i)
```

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

#### removeAll

```java
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

```java
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
  }
}
```

## Related

- [`ValueRecord`](<https://docs.dhtmlx.com/planning-engine/java/api/support/value-record.md>) - record equality over list fields
- [`ProjectData`](<https://docs.dhtmlx.com/planning-engine/java/api/data/project-data.md>) - a record with list fields
- [Records, ids and dates](<https://docs.dhtmlx.com/planning-engine/java/records-ids-and-dates.md#lists>) - list fields and `List.of(...)` setters