Java Collections For JavaScript

This repository contains implementations of some commonly-used Java collections in JavaScript.

HashMap

Although JavaScript has a native Map object, key equality is determined by the sameValueZero algorithm, so objects with the exact same properties are not considered equal unless they are the same reference ({a: 1, b: 2} !== {a: 1, b: 2}). This cannot be customized.

HashMap.js provides fine-grained control over what objects are considered equal, so both primitives and user-defined objects may be used as keys.
It implements a Hash Table/Map with similar methods to Java's HashMap.
All objects (except primitives) used as keys must implement a hashCode method to return an integer hash code as well as an equals method that accepts another object as a parameter and returns whether or not the value of the current object is equal to parameter. Objects that are considered equal must have the same hash code, but the converse is not true.

Note that HashMap instances are iterable, so [...myHashMap] will return an array of arrays, where each inner array consists of the key and value for a mapping (in that order).

An example of usage can be found here.

$3

Include the script before code that uses HashMap. The script can be loaded via CDN or a local downloaded copy.

``

html





Or for Node.js, run

npm i java-collections4js

 to install the package, then use it like so:

js

const { HashMap, HashSet } = require("java-collections4js");



// or with ECMAScript Module imports

import JavaCollections from "java-collections4js";

import HashMap from "java-collections4js/dist/HashMap.js";





$3



The constructor accepts an optional HashMap, which will copy the contents. Alternately, it will create an empty HashMap.

js

const myMap = new HashMap(); // create empty HashMap

const myMap2 = new HashMap(myMap); // create HashMap from other HashMap





$3













































	Method Signature Description
	
		put(key, value) Associates the given key with the value. Returns the previous value associated with the key, or undefined if there was no value before.
	
	
		putIfAbsent(key, value) Associates the given key with the value only if there was no value previously associated with the key.
	
	
		get(key) Returns the value associated with the given key or undefined if there was no value.
	
	
		getOrDefault(key, defaultValue) Returns the value associated with the given key if there is one or defaultValue if not.
	
	
		containsKey(key) Returns true if the HashMap contains a mapping for the given key.
	
	
		containsValue(value) Returns true if there is at least one key mapped to the given value.
	
	
		clear() Removes all mappings in the HashMap.
	
	
		remove(key) Removes the mapping for the given key and returns its value.
	
	
		forEach(consumer) Iterates over each key-value mapping in the HashMap and passes the key and value of each one as arguments to the consumer callback function.
	
	
		isEmpty() Returns true if there are no mappings in the HashMap
	
	
		size() Returns the number of mappings in the HashMap.
	
	
		hashCode() Returns an integer hash code for this instance.
	
	
		equals(obj) Returns true if the value of obj is equal to the value of this instance.
	




HashSet

Although JavaScript has a native Set object, elements are considered equal only if they are primitives with the same value or the same reference of an object. Thus, objects with the same properties and values can be duplicated many times. 


HashSet.js provides fine-grained control over what objects are considered equal, so both primitives and user-defined objects may be inserted with uniqueness guaranteed.

It implements an unordered collection with unique elements. Similar to HashMap, each element (except primitives) stored in a HashSet must implement a hashCode and equals method. To use HashSet, HashMap must be included first. 


Note that HashSet instances are iterable, so [...myHashSet] will return an array containing the elements in the HashSet.



$3

Include HashMap.js and HashSet.js before code that uses HashSet. The scripts can be loaded via CDN or local downloaded copies.

Method Signature	Description
`put(key, value)`	Associates the given `key` with the `value`. Returns the previous value associated with the key, or `undefined` if there was no value before.
`putIfAbsent(key, value)`	Associates the given `key` with the `value` only if there was no value previously associated with the key.
`get(key)`	Returns the value associated with the given `key` or `undefined` if there was no value.
`getOrDefault(key, defaultValue)`	Returns the value associated with the given `key` if there is one or `defaultValue` if not.
`containsKey(key)`	Returns `true` if the `HashMap` contains a mapping for the given `key`.
`containsValue(value)`	Returns `true` if there is at least one key mapped to the given `value`.
`clear()`	Removes all mappings in the `HashMap`.
`remove(key)`	Removes the mapping for the given `key` and returns its value.
`forEach(consumer)`	Iterates over each key-value mapping in the `HashMap` and passes the key and value of each one as arguments to the `consumer` callback function.
`isEmpty()`	Returns `true` if there are no mappings in the `HashMap`
`size()`	Returns the number of mappings in the `HashMap`.
`hashCode()`	Returns an integer hash code for this instance.
`equals(obj)`	Returns `true` if the value of `obj` is equal to the value of this instance.

html





$3

The constructor accepts an optional iterable object, all elements of which will be initially added to the HashSet. If the first parameter is not provided, it constructs an empty HashSet.

js

const mySet = new HashSet(); // creates empty HashSet

const mySet2 = new HashSet([1, 2, 3]); // creates a HashSet containing the elements of the array





$3





























	Method Signature Description
	add(obj) Adds obj to the HashSet, if it is not already present. Returns true if the object was added, i.e. it was not already present.
	
		contains(obj)
		Returns true if the HashSet contains obj.
	
	
		remove(obj) Removes obj from the HashSet.
	
	
		clear() Removes all elements from the HashSet.
	
	
		size() Returns the number of elements in the HashSet.
	
	
		isEmpty() Returns true if there are no elements in the HashSet
	
	
		hashCode() Returns an integer hash code for this instance.
	
	
		equals(obj) Returns true if the value of obj is equal to the value of this instance.
	




ArrayList



ArrayList.js implements an dynamically-sized list with a hashCode and equals method. 


Note that ArrayList instances are iterable, so [...myArrayList] will return an array containing the elements in the ArrayList (in order).



$3

Include the script before code that uses ArrayList. The script can be loaded via CDN or a local downloaded copy.

Method Signature	Description
`add(obj)`	Adds `obj` to the `HashSet`, if it is not already present. Returns `true` if the object was added, i.e. it was not already present.
`contains(obj)`	Returns `true` if the `HashSet` contains `obj`.
`remove(obj)`	Removes `obj` from the `HashSet`.
`clear()`	Removes all elements from the `HashSet`.
`size()`	Returns the number of elements in the `HashSet`.
`isEmpty()`	Returns `true` if there are no elements in the `HashSet`
`hashCode()`	Returns an integer hash code for this instance.
`equals(obj)`	Returns `true` if the value of `obj` is equal to the value of this instance.

html





$3

The constructor accepts an optional iterable object to use to fill the list initially. If not specified, an empty ArrayList is constructed.

js

const myList = new ArrayList(); // creates an empty ArrayList

const myList2 = new ArrayList([1, 2, 3]); // creates an ArrayList containing the numbers 1, 2, 3





$3



















































	
		Method Signature Description
	
	
		add(...elems) Adds all of the arguments passed in to the ArrayList.
	
	
		addAll(obj) Adds all the elements of the iterable obj to the ArrayList.
	
	
		removeAtIndex(idx) Removes the element at the specified index.
	
	
		get(idx) Returns the element at the specified index.
	
	
		addAtIndex(idx, ...elems)
		Adds the given elements to the ArrayList starting at the specified index.
	
	
		set(idx, elem) Sets the element at the specified index to be elem.
	
	
		removeIf(predicate)
		Removes all elements in the ArrayList that match a predicate (that accepts an element as the only parameter and returns true if it should be removed).
	
	
		remove(obj)
		Removes the first occurrence of obj from the ArrayList.
	
	
		indexOf(obj)
		Returns the first index at which obj is found in the ArrayList.
	
	
		size()
		Returns the number of elements in the ArrayList.
	
	
		isEmpty()
		Returns true if there are no elements in the ArrayList.
	
	
		hashCode() Returns an integer hash code for this instance.
	
	
		equals(obj) Returns true if the value of obj is equal to the value of this instance.
	




Equals and HashCode for Objects You Cannot Modify



HashedObject.js provides a wrapper for an object that allows specifying an equals and hashCode function. This wrapped object can then be used as a key in a HashMap or stored 

in a HashSet.




$3

Include the script before code that uses HashedObject. The script can be loaded via CDN or a local downloaded copy.

Method Signature	Description
`add(...elems)`	Adds all of the arguments passed in to the `ArrayList`.
`addAll(obj)`	Adds all the elements of the iterable `obj` to the `ArrayList`.
`removeAtIndex(idx)`	Removes the element at the specified index.
`get(idx)`	Returns the element at the specified index.
`addAtIndex(idx, ...elems)`	Adds the given elements to the `ArrayList` starting at the specified index.
`set(idx, elem)`	Sets the element at the specified index to be `elem`.
`removeIf(predicate)`	Removes all elements in the `ArrayList` that match a predicate (that accepts an element as the only parameter and returns `true` if it should be removed).
`remove(obj)`	Removes the first occurrence of `obj` from the `ArrayList`.
`indexOf(obj)`	Returns the first index at which `obj` is found in the `ArrayList`.
`size()`	Returns the number of elements in the `ArrayList`.
`isEmpty()`	Returns `true` if there are no elements in the `ArrayList`.
`hashCode()`	Returns an integer hash code for this instance.
`equals(obj)`	Returns `true` if the value of `obj` is equal to the value of this instance.

html





$3

The constructor takes the object to wrap, the hash function, and the equals function as arguments. 


The equals function must take two objects as parameters and return a boolean indicating whether they are equal. If not equals function is specified, the default is strict equality comparison.


The hashCode function must take one object as input and return its hash code.

js

let wrapped = new HashedObject(myObj, hashFn, equalsFn);

$3

Method Signature	Description
`hashCode()`	Returns the hash code of the wrapped object obtained with the hashCode function passed in through the constructor.
`equals(obj)`	Returns the result of calling the equals function provided in the constructor, passing the underlying object and `obj` as arguments.
`getValue()`	Returns the underlying object that was wrapped.

$3

There are some static methods and properties provided for convenience that implement common equals or hash code functions.

Name	Description
`DEFAULT_EQUALS`	A function implementing an equals function using strict equality.
`ITERABLE_HASHCODE`	A function implementing a hash code function for an iterable object.
`STRING_HASHCODE`	A function implementing a hash code function for a string.
`ITERABLE_EQUALS`	A function implementing an equals function for iterable objects by comparing elements at corresponding indexes.
`factory(hashCodeFn, equalsFn)`	Returns a factory function from the given hash code and equals functions. The factory function accepts a single object parameter and returns a `HashedObject` from the parameter and the hash code and equals functions (provided when creating the factory).