com.fitbur.guava.common.collect.TreeTraverser Maven / Gradle / Ivy
/*
* Copyright (C) 2012 The Guava Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.fitbur.guava.common.collect;
import static com.fitbur.guava.common.base.Preconditions.checkNotNull;
import com.fitbur.guava.common.annotations.Beta;
import com.fitbur.guava.common.annotations.GwtCompatible;
import java.util.ArrayDeque;
import java.util.Deque;
import java.util.Iterator;
import java.util.Queue;
/**
* Views elements of a type {@code T} as nodes in a tree, and provides methods to traverse the trees
* induced by this traverser.
*
* For example, the tree
*
*
{@code
* h
* / | \
* / e \
* d g
* /|\ |
* / | \ f
* a b c }
*
* can be iterated over in preorder (hdabcegf), postorder (abcdefgh), or breadth-first order
* (hdegabcf).
*
*
Null nodes are strictly forbidden.
*
* @author Louis Wasserman
* @since 15.0
*/
@Beta
@GwtCompatible(emulated = true)
public abstract class TreeTraverser {
// TODO(lowasser): make this GWT-compatible when we've checked in ArrayDeque emulation
/**
* Returns the children of the specified node. Must not contain null.
*/
public abstract Iterable children(T root);
/**
* Returns an unmodifiable iterable over the nodes in a tree structure, using pre-order
* traversal. That is, each node's subtrees are traversed after the node itself is returned.
*
* No guarantees are made about the behavior of the traversal when nodes change while
* iteration is in progress or when the iterators generated by {@link #children} are advanced.
*/
public final FluentIterable preOrderTraversal(final T root) {
checkNotNull(root);
return new FluentIterable() {
@Override
public UnmodifiableIterator iterator() {
return preOrderIterator(root);
}
};
}
// overridden in BinaryTreeTraverser
UnmodifiableIterator preOrderIterator(T root) {
return new PreOrderIterator(root);
}
private final class PreOrderIterator extends UnmodifiableIterator {
private final Deque> stack;
PreOrderIterator(T root) {
this.stack = new ArrayDeque>();
stack.addLast(Iterators.singletonIterator(checkNotNull(root)));
}
@Override
public boolean hasNext() {
return !stack.isEmpty();
}
@Override
public T next() {
Iterator itr = stack.getLast(); // throws NSEE if empty
T result = checkNotNull(itr.next());
if (!itr.hasNext()) {
stack.removeLast();
}
Iterator childItr = children(result).iterator();
if (childItr.hasNext()) {
stack.addLast(childItr);
}
return result;
}
}
/**
* Returns an unmodifiable iterable over the nodes in a tree structure, using post-order
* traversal. That is, each node's subtrees are traversed before the node itself is returned.
*
* No guarantees are made about the behavior of the traversal when nodes change while
* iteration is in progress or when the iterators generated by {@link #children} are advanced.
*/
public final FluentIterable postOrderTraversal(final T root) {
checkNotNull(root);
return new FluentIterable() {
@Override
public UnmodifiableIterator iterator() {
return postOrderIterator(root);
}
};
}
// overridden in BinaryTreeTraverser
UnmodifiableIterator postOrderIterator(T root) {
return new PostOrderIterator(root);
}
private static final class PostOrderNode {
final T root;
final Iterator childIterator;
PostOrderNode(T root, Iterator childIterator) {
this.root = checkNotNull(root);
this.childIterator = checkNotNull(childIterator);
}
}
private final class PostOrderIterator extends AbstractIterator {
private final ArrayDeque> stack;
PostOrderIterator(T root) {
this.stack = new ArrayDeque>();
stack.addLast(expand(root));
}
@Override
protected T computeNext() {
while (!stack.isEmpty()) {
PostOrderNode top = stack.getLast();
if (top.childIterator.hasNext()) {
T child = top.childIterator.next();
stack.addLast(expand(child));
} else {
stack.removeLast();
return top.root;
}
}
return endOfData();
}
private PostOrderNode expand(T t) {
return new PostOrderNode(t, children(t).iterator());
}
}
/**
* Returns an unmodifiable iterable over the nodes in a tree structure, using breadth-first
* traversal. That is, all the nodes of depth 0 are returned, then depth 1, then 2, and so on.
*
* No guarantees are made about the behavior of the traversal when nodes change while
* iteration is in progress or when the iterators generated by {@link #children} are advanced.
*/
public final FluentIterable breadthFirstTraversal(final T root) {
checkNotNull(root);
return new FluentIterable() {
@Override
public UnmodifiableIterator iterator() {
return new BreadthFirstIterator(root);
}
};
}
private final class BreadthFirstIterator extends UnmodifiableIterator
implements PeekingIterator {
private final Queue queue;
BreadthFirstIterator(T root) {
this.queue = new ArrayDeque();
queue.add(root);
}
@Override
public boolean hasNext() {
return !queue.isEmpty();
}
@Override
public T peek() {
return queue.element();
}
@Override
public T next() {
T result = queue.remove();
Iterables.addAll(queue, children(result));
return result;
}
}
}