Module org.jhotdraw8.icollection

Package org.jhotdraw8.icollection.impl.redblack

Interface RedBlackTree<K,V>

Type Parameters:

K - the key type

V - the value type

All Superinterfaces:

Iterable<Node<K,V>>

All Known Implementing Classes:

Empty, Node

public interface RedBlackTree<K,V>
extends Iterable<Node<K,V>>

Purely functional Red/Black Tree, inspired by Kazu Yamamoto's Haskell implementation.

Based on

Chris Okasaki, "Red-Black Trees in a Functional Setting", Journal of Functional Programming, 9(4), pp 471-477, July 1999

Stefan Kahrs, "Red-black trees with types", Journal of functional programming, 11(04), pp 425-432, July 2001

This class has been derived from 'vavr' RedBlackTree.java.

RedBlackTree.java. Copyright 2023 (c) vavr. MIT License.

github.com

Method Summary

Modifier and Type	Method	Description
@NonNull RedBlackTree<K,V>	ceiling(K e, @NonNull Comparator<? super K> comparator)	Returns the least Node in this tree greater than or equal to the given element, or Empty if there is no such element.
boolean	color()	Return the Color of this Red/Black Tree node.
boolean	contains(K key, Comparator<? super K> comparator)	Checks, if this RedBlackTree contains the given key.
default RedBlackTree<K,V>	delete(K key, Comparator<? super K> comparator)	Deletes a value from this RedBlackTree.
static <K, V> RedBlackTree<K,V>	empty()
@Nullable Map.Entry<K,V>	entryOrNull()	Returns the map entry of this RedBlackTree or null if it is empty.
default boolean	equals(@NonNull RedBlackTree<K,V> tree)	Returns true if the given tree has the same size and the same elements in the same sequence as this tree.
RedBlackTree<K,V>	find(K key, Comparator<? super K> comparator)	Finds the value stored in this tree, if exists, by applying the underlying comparator to the tree elements and the given element.
@NonNull RedBlackTree<K,V>	floor(K e, @NonNull Comparator<? super K> comparator)	Returns the greatest Node in this tree less than or equal to the given element, or Empty if there is no such element.
K	getKey()	Returns the key of the current tree node or throws if this is empty.
V	getValue()	Returns the value of the current tree node or throws if this is empty.
@NonNull RedBlackTree<K,V>	higher(K e, @NonNull Comparator<? super K> comparator)	Returns the least Node in this tree strictly greater than the given element, or Empty if there is no such element.
default RedBlackTree<K,V>	insert(K key, V value, Comparator<? super K> comparator)	Inserts a new value into this tree.
boolean	isEmpty()	Checks if this RedBlackTree is empty, i.e.
boolean	isRed()
default @NonNull Iterator<Node<K,V>>	iterator()	Returns an Iterator that iterates elements in the order induced by the underlying Comparator.
@Nullable K	keyOrNull()	Returns the key of this RedBlackTree or null if it is empty.
RedBlackTree<K,V>	left()	Returns the left child if this is a non-empty node, otherwise throws.
@NonNull RedBlackTree<K,V>	lower(K e, @NonNull Comparator<? super K> comparator)	Returns the greatest Node in this tree strictly less than the given element, or Empty if there is no such element.
<E> @Nullable E	mapOrNull(@NonNull BiFunction<K,V,E> f)
default @NonNull RedBlackTree<K,V>	max()	Returns the maximum element of this tree according to the underlying comparator.
default @NonNull RedBlackTree<K,V>	min()	Returns the minimum element of this tree according to the underlying comparator.
static <K, V> RedBlackTree<K,V>	of(@NonNull Comparator<? super K> comparator, K... keys)
static <K, V> RedBlackTree<K,V>	of(@NonNull Comparator<? super K> comparator, K key, V value)
static <K, V> RedBlackTree<K,V>	ofAll(@NonNull Comparator<? super K> comparator, Iterable<? extends K> keys)
RedBlackTree<K,V>	orElse(RedBlackTree<K,V> other)	Returns this RedBlackTree if it is nonempty, otherwise return the alternative.
default Iterator<Node<K,V>>	reverseIterator()	Returns an Iterator that iterates elements in the order induced by the underlying Comparator.
@NonNull RedBlackTree<K,V>	right()	Returns the right child if this is a non-empty node, otherwise throws.
int	size()	Returns the size of this tree.
String	toLispString()
@Nullable V	valueOrNull()	Returns the value of this RedBlackTree or null if it is empty.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Details

toLispString

String toLispString()

empty

static <K,
V> RedBlackTree<K,V> empty()

of

static <K,
V> RedBlackTree<K,V> of(@NonNull Comparator<? super K> comparator,
 K key,
 V value)

of

@SafeVarargs
static <K,
V> RedBlackTree<K,V> of(@NonNull Comparator<? super K> comparator,
 K... keys)

ofAll

static <K,
V> RedBlackTree<K,V> ofAll(@NonNull Comparator<? super K> comparator,
 Iterable<? extends K> keys)

insert

default RedBlackTree<K,V> insert(K key,
 V value,
 Comparator<? super K> comparator)

Inserts a new value into this tree.

Parameters:

key - A key.

value - A value.

comparator -

Returns:

A new tree if this tree does not contain the given value, otherwise the same tree instance.

color

boolean color()

Return the Color of this Red/Black Tree node.

An empty node is BLACK by definition.

Returns:

Either RED or BLACK.

contains

boolean contains(K key,
 Comparator<? super K> comparator)

Checks, if this RedBlackTree contains the given key.

Parameters:

key - A key.

comparator -

Returns:

true, if this tree contains the value, false otherwise.

isRed

boolean isRed()

delete

default RedBlackTree<K,V> delete(K key,
 Comparator<? super K> comparator)

Deletes a value from this RedBlackTree.

Parameters:

key - A value

comparator -

Returns:

A new RedBlackTree if the value is present, otherwise this.

find

RedBlackTree<K,V> find(K key,
 Comparator<? super K> comparator)

Finds the value stored in this tree, if exists, by applying the underlying comparator to the tree elements and the given element.

Especially the value returned may differ from the given value, even if the underlying comparator states that both are equal.

Parameters:

key - A value

comparator -

Returns:

Some value, if this tree contains a value equal to the given value according to the underlying comparator. Otherwise None.

isEmpty

boolean isEmpty()

Checks if this RedBlackTree is empty, i.e. an instance of Leaf.

Returns:

true, if it is empty, false otherwise.

left

RedBlackTree<K,V> left()

Returns the left child if this is a non-empty node, otherwise throws.

Returns:

The left child.

Throws:

UnsupportedOperationException - if this RedBlackTree is empty

max

default @NonNull RedBlackTree<K,V> max()

Returns the maximum element of this tree according to the underlying comparator.

Returns:

Node, if this is not empty, otherwise Empty

min

default @NonNull RedBlackTree<K,V> min()

Returns the minimum element of this tree according to the underlying comparator.

Returns:

Node, if this is not empty, otherwise Empty

right

@NonNull RedBlackTree<K,V> right()

Returns the right child if this is a non-empty node, otherwise throws.

Returns:

The right child.

Throws:

UnsupportedOperationException - if this RedBlackTree is empty

size

int size()

Returns the size of this tree.

Returns:

the number of nodes of this tree and 0 if this is the empty tree

equals

default boolean equals(@NonNull RedBlackTree<K,V> tree)

Returns true if the given tree has the same size and the same elements in the same sequence as this tree.

Parameters:

tree - the given tree

Returns:

true if equal

getKey

K getKey()

Returns the key of the current tree node or throws if this is empty.

Returns:

The value.

Throws:

NoSuchElementException - if this is the empty node.

getValue

V getValue()

Returns the value of the current tree node or throws if this is empty.

Returns:

The value.

Throws:

NoSuchElementException - if this is the empty node.

iterator

default @NonNull Iterator<Node<K,V>> iterator()

Returns an Iterator that iterates elements in the order induced by the underlying Comparator.

Internally an in-order traversal of the RedBlackTree is performed.

Example:

       4
      / \
     2   6
    / \ / \
   1  3 5  7
 

Iteration order: 1, 2, 3, 4, 5, 6, 7

See also Implement Iterator for BinaryTree I (In-order).

Specified by:

iterator in interface Iterable<K>

reverseIterator

default Iterator<Node<K,V>> reverseIterator()

Returns an Iterator that iterates elements in the order induced by the underlying Comparator.

Internally an in-order traversal of the RedBlackTree is performed.

Example:

       4
      / \
     2   6
    / \ / \
   1  3 5  7
 

Iteration order: 7, 6, 5, 4, 3, 2, 1

See also Implement Iterator for BinaryTree I (In-order).

ceiling

@NonNull RedBlackTree<K,V> ceiling(K e,
 @NonNull Comparator<? super K> comparator)

Returns the least Node in this tree greater than or equal to the given element, or Empty if there is no such element.

floor

@NonNull RedBlackTree<K,V> floor(K e,
 @NonNull Comparator<? super K> comparator)

Returns the greatest Node in this tree less than or equal to the given element, or Empty if there is no such element.

higher

@NonNull RedBlackTree<K,V> higher(K e,
 @NonNull Comparator<? super K> comparator)

Returns the least Node in this tree strictly greater than the given element, or Empty if there is no such element.

lower

@NonNull RedBlackTree<K,V> lower(K e,
 @NonNull Comparator<? super K> comparator)

Returns the greatest Node in this tree strictly less than the given element, or Empty if there is no such element.

orElse

RedBlackTree<K,V> orElse(RedBlackTree<K,V> other)

Returns this RedBlackTree if it is nonempty, otherwise return the alternative.

keyOrNull

@Nullable K keyOrNull()

Returns the key of this RedBlackTree or null if it is empty.

valueOrNull

@Nullable V valueOrNull()

Returns the value of this RedBlackTree or null if it is empty.

entryOrNull

@Nullable Map.Entry<K,V> entryOrNull()

Returns the map entry of this RedBlackTree or null if it is empty.

mapOrNull

<E> @Nullable E mapOrNull(@NonNull BiFunction<K,V,E> f)