Primitive-Collections/features.md

Quality Of Life Features

New Specialized functions/classes that were added to increase performance and/or reduce allocations and/or for Quality of life.

Functions

Functions that increase performance or are quality of life in their nature.

Iterable

Functional Functions

Java adds themselves a lot of functional functions like,

• Stream:
  • Map/FlatMap
  • Filter/Distinct/Limit/Sorted
  • Count/FindFirst/Collect
  • Peek/ForEach/Reduce
  • anyMatch/allMatch/NoneMatch

that allows to process a collection in a functional way.
But these require streams which have a lot of Overhead in their nature.

Luckly Primitive Collections adds replacement functions that provide the same functionality but with minimal overhead.
Here are some examples:

public ObjectIterable<Path> toPath(ObjectIterable<String> iterable) {
	return iterable.map(Paths::get).filter(Files::exist);
}

public Iterable<Path> toPath(Iterable<String> iterable) {
	return ObjectIterables.map(iterable, Paths::get).filter(Files::exist);
}

public int sum(IntIterable iterable) {
	return iterable.reduce(Integer::sum);
}

AsyncAPI

The AsyncAPI is a Feature that simplifies the processing of Collections on a separate thread.
It uses the same concept as Javas Stream API but uses the light weight Functions from Primitive Collections to achieve the same thing.
Unlike Javas StreamAPI the AsyncAPI is always singleThreaded and more like Javas CompletableFuture, which you can await or let run Asynchronous.

The Goal is it to simplify the processing of Collections asynchronous.
Especially on tasks which don't have to be finished instantly but can be processed on the side.

Here is a example of how the API works.

public void processFiles(ObjectCollection<String> potentialFiles) {
     potentialFiles.asAsync()
         .map(Paths::get).filter(Files::exists) //Modifies the collection (Optional)
         .forEach(Files::delete) //Creates the action (Required)
         .callback(T -> {}} //Callback on completion, still offthread (Optional)
         .execute() //Starts the task. (Required)
}

Collection

These are functions specific to the Collections interface, stuff that everyone wished it was present to be in the first place.

AddAll (Array)

Adding Elements to a Collection usually requires either a for loop or a Arrays.wrap().
This isn't an issue with Primitive Collections.

public void addMonths(ObjectCollection<String> months) {
	months.addAll("January", "February", "March", "April", "May", "June", "July", "August", "September, "October", November", "December");
}

public void addElements(ObjectCollection<String> result, String[] elements) {
	result.addAll(elements, 0, 5); //elements, offset, length
}

containsAny

Everyone hates comparing if 2 collections have part of each other included.
The solution usually requires for loops and keeping track if things were found or not.
And every Java Developer had this issue at least once and wished for a clean solution.

public boolean hasMonths(ObjectCollection<Month> target, Collection<Month> toFind) {
	return target.containsAny(toFind);
}

Copy

Collections get copied every now and then. There is only 2 ways that this happens.
Javas Clone API or using Constructor that supports collections.
Javas Clone API is kinda in a Zombie state, where it is supported or not. Its not really clear if you should use it or not.
The Clone CloneNotSupportedException isn't helping either, causing more janky code.
While a Constructor can only support so much and testing for every case isn't really viable.

So the decision was made to straight out not support clone and instead add a copy function which doesn't use a checked exception.
It works exactly like the clone function. In a sense where it creates a shallow copy. (SubCollections do not work for obvious reasons)

public IntCollection copy(IntCollection original) {
	return original.copy();
}

Primitive Streams

Since Javas Stream API is still really useful, even at its shortcomings, Primitive Collections provides easy access to it.
Generic Streams and the closest Primitive Stream will be provided. So a FloatCollection goes to a DoubleStream.

public IntStream createStream(IntCollection source) {
	return source.primitiveStream();
}

RemoveAll/RetainAll with listener

Ever wanted use removeAll or retainAll and wanted to know what elements actually got deleted?
The usual solution is to create a copy and then apply it to the original and cross reference them.
Which leads to really messy code and just hasn't a clean solution.
Luckly Primitive Collections got you covered.

public void removeInvalidFiles(ObjectCollections<Path> files, ObjectCollection<Path> toRemove) {
	files.removeAll(toRemove, T -> System.out.println(T));
}

public void removeInvalidFiles(ObjectCollections<Path> files, ObjectCollection<Path> toKeep) {
	files.retainFiles(toKeep, T -> System.out.println(T));
}

ToArray

Primitive Collections supports primitive/generic toArray functions for its Primitive Collections.
On top of that the Object side gets a Java9 function ported back to java8, which uses a functional Interface to create the backing array.

public Integer[] toArray(IntCollection c) {
	return c.toArray(new Integer[c.size]);
}

public int[] toArray(IntCollection c) {
	return c.toIntArray();
}

public String[] toArray(ObjectCollection<String> c) {
	return c.toArray(String::new);
}

List

These functions are List specific functions, a couple of these are from FastUtil.

add/get/remove/extractElements

These functions really useful helper functions. 3 of which are copied from FastUtil. (extract is from Primitive Collections)
They are basically array forms of addAll, getAll, removeRange and removeAndGetRange. This is the simplest way to describe it.

Here some example:

public void addAll(DoubleList list) {
	list.addElements(0D, 12.2D, 3.5D, 4.2D);
}

public double[] getAll(DoubleList list, int amount) {
	double[] result = new double[amount];
	list.getElements(0, result);
	return result;
}

public void removeRange(FloatList list) {
	list.removeElements(5, 14);
}

public float[] extractRange(FloatList list) {
	return list.extractElements(5, 14); //Returns the removed elements
}

addIfPresent/addIfAbsent

These two functions are simple helper functions that check internally if a element is present or absent before adding them to the List.
Removing the need for a contains or indexOf check every time you want to add a element. While it is of course better to use a set, there is cases where this is still useful.

public void addElements(IntList list, int... numbersToAdd) {
	for(int e : numbersToAdd) {
		list.addIfAbsent(e);
	}
}

public void addExisting(ObjectList<String> list, String... textToAdd) {
	for(String s : textToAdd) {
		list.addIfPresent(s);
	}
}

SwapRemove

Lists when removing a Element shift usually the backing array to the left based to shrink the elements.
While that isn't computational expensive with LinkedLists, it is with ArrayLists.
Here comes swapRemove into play, which just removes the desired elements and instead of shifting left puts the last element in its place. This reduces the data copying required down to 1 element instead of an array.

public int remove(IntList elements, int indexToRemove) {
	return elements.swapRemove(indexToRemove);
}

Unstable Sort (From FastUtil)

Unstable Sort uses a Faster but not as stable sorting algorithm to sort the Collection.
Stable doesn't mean crashing, but more like that the result isn't exactly perfectly sorted.

public void sort(List<Month> list, Comparator<Month> sorter) {
	list.unstableSort(sorter);
}

Map

These functions are based on the Map interface. Useful functions you really would want.

addTo/subFrom

addTo (from FastUtil) and subFrom are mathematically functions that either add or subtract from the value of a given key.
And if the key isn't present or would result in the default value it will either add or remove the entry from the Map. Given the circumstance.
This is a really useful function and I wish FastUtil made it accessible by default but sadly it isn't.
To simplify the explanation:

• addTo if no element is present puts in the desired number, otherwise it sums up the two values.
• subFrom if a element is present subtracts from it, if the element reaches the default value it removes the element from the map. If not present it will be ignored.

public void addTo(Object2DoubleMap<Month> map, Month key, double averageTrainsRepaired) {
	map.addTo(key, averageTrainsRepaired);
}

public void subFrom(Long2IntMap map, long key, double amount) {
	map.subFrom(key, amount);
}

addToAll

Simple bulk version of the addTo function since sometimes you want to merge 2 maps for summing.
Especially if your work is multi-threaded this can become useful.

public void addTo(Object2DoubleMap<Month> map, Object2DoubleMap<Month> trainsRepaired) {
	map.addToAll(trainsRepaired);
}

mergeAll

This is a simple bulk version of merge since merging 2 maps is more frequent then people might think and leads to cleaner code too.

public void merge(Long2ByteMap result, Long2ByteMap toMerge) {
	result.mergeAll(toMerge);
}

putAll (Array)

This allows to put keys and values as arrays instead of requiring a WrapperMap to insert the elements.
Not as useful as the Collections.addAll variant but still really useful.

public void putAll(Int2DoubleMap map, int[] keys, double[] values) {
	map.put(keys, values, 2, 15);
}

putAllIfAbsent

putAll has this usual quirk where if a element is present it will replace the value, and sometimes this is not wanted.
While putIfAbsent exists it has no real mass form and makes iterative solutions really uneasy to use.
Here comes the helper function that gets rid of that problem.

public void merge(Long2ObjectMap<String> regionFiles, Long2ObjectMap<String> toAdd) {
	regionFiles.putAllIfAbsent(toAdd);
}

removeOrDefault

getOrDefault is a really useful function that find use cases all the time.
Sadly by default there is no variant of removeOrDefault, while it has less cases still could be used every now and then.
This function basically tries to remove a element, if it is not present it will just return your desired default.

public Path removeCache(Long2ObjectMap<Path> caches, long key) {
	return caches.removeOrDefault(key, Paths.get("nuclearFun"));
}

supplyIfAbsent

This one is one of my favorites. computeIfAbsent is a really useful function.
But in 90% of the cases I use it the value is a collection.
This becomes really annoying since methodReferences are faster/cleaner then Lambdas in my opinion.
supplyIfAbsent is basically computeIfAbsent but without a key, perfect for the default constructor of a collection.
This is the whole reason it exists.

public void example(Int2ObjectMap<List<String>> map, Int2ObjectMap<String> toAdd) {
	for(Entry<String> entry : toAdd.entrySet()) {
		map.supplyIfAbsent(entry.getKey(), ObjectArrayList::new).add(entry.getValue());
	}
}

Interfaces

Interfaces that provide essential or quality of life features.

ITrimmable

The ITrimmable is Accessor interface that allows you to access a couple helper functions to control the size of your collections.
This was created for the constant casting requirement to implementations just to shrink collections which get annoying over time.

trim

This function basically trims down the backing implementation to use as little memory as required to store the elements in the collection.
Optionally a desired minimum size can be provided as of how low it should go at worst.

clearAndTrim

when you want to reset a Collection completely you have 2 options. Clear it and then call trim, or recreate the collection.
clearAndTrim solves this problem by clearing the collection and trimming it in one go, reducing overhead to achieve such a thing.

IArray

IArray is a Accessor interface that provides more access to collections by providing tools to grow your collection as needed.
While putAll/addAll try to ensure that you have enough room for your elements, this is not really a solution for all cases.
Sometimes you need to ensure the Collection is pre-initialized.
IArray grants you that control.

There is also a type specific that provides you access to the backing array implementation of Lists for faster Iteration but that is a really specific case.

ensureCapacity

Ensures that your collection has enough storage for the elements you want to insert.

elements (ITypeSpecificArray)

Allows you access to the backing array of a List which is for people who know what they are doing.
There is a lambda version of this function too which makes sure for synchronizedLists that you are the only one accessing the array.

OrderedMap

The OrderedMap is a real edge case interface that was born for a need.
FastUtil added functions that were like moveToFirst which were hardcoded to the implementation.
They didn't fit into something like a SortedMap because the Set wasn't sorted.
So OrderedMap was born, which isn't random but ordered in a specific way that can be changed.

getAndMoveToFirst/getAndMoveToLast

Returns a desired element and removing it to the first/last spot in the Map. Moving the element that was at its spot after/before it.

moveToFirst/moveToLast

Moves the element if present to the first/last spot in the Map. Moving the element that was at its spot after/before it.
Returns true if the element was actually moved.

putAndMoveToFirst/putAndMoveToLast

Adds the desired element and moves it to first/last spot in the Map. Moving the element that was at its spot after/before it.

firstKey/lastKey (Optional poll)

Provides access to the current first/last key of the Map.
Optionally can be polled if desired.

firstValue/lastValue

Provides access to the current first/last value of the Map.

OrderedSet

The OrderedSet is a real edge case interface that was born for a need.
FastUtil added functions that were like moveToFirst which were hardcoded to the implementation.
They didn't fit into something like a SortedSet because the Set wasn't sorted.
So OrderedSet was born, which isn't random but ordered in a specific way that can be changed.

addAndMoveToFirst/addAndMoveToLast

Adds the desired element and moves it to first/last spot in the Collection. Moving the element that was at its spot after/before it.

moveToFirst/moveToLast

Moves the element if present to the first/last spot in the Collection. Moving the element that was at its spot after/before it.
Returns true if the element was actually moved.

first/last (Optional poll)

Provides access to the current first/last element of the set.
Optionally can be polled if desired.