de.mrapp.tries.Trie Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of tries Show documentation
A Java implementations of different Tries (prefix trees). These are ordered tree data structures commonly used for efficient string searches.
The newest version!
/*
 * Copyright 2017 - 2019 Michael Rapp
 *
 * 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 de.mrapp.tries;

import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.io.Serializable;
import java.util.Map;

/**
 * Defines the interface of a trie (also called prefix tree, digital tree or radix tree). A trie is
 * a tree data structure that can be used to store an associative array where the keys are sequences
 * (e.g. sequences of characters or lists of digits).
 * 
 * Tries allow to efficiently search for sequences (and their values) that share a common prefix. As
 * nodes with a common prefix share the same predecessors, tries also provide some kind of
 * compression.
 * 

 * In a trie values are only associated with the leaf nodes and with some inner nodes. As all
 * successors of a node share a common prefix of the sequence, which is associated with that node,
 * the position of a value in the trie specifies the key it is associated with. The root node
 * corresponds to an empty sequence.
 *
 * @param  The type of the sequences, which are used as the trie's keys
 * @param     The type of the values, which are stored by the trie
 * @author Michael Rapp
 * @since 1.0.0
 */
public interface Trie
        extends Map, Serializable {

    /**
     * Returns the root node of the trie. The returned object is not modifiable, i.e. an {@link
     * UnsupportedOperationException} will be thrown when attempting to change the state of the
     * returned node or one of its successors.
     *
     * @return The root node of the trie as an instance of the type {@link Node} or null, if the
     * trie is empty
     */
    @Nullable Node getRootNode();

    /**
     * Returns the subtree of the node, which corresponds to a specific sequence (must not
     * necessarily be a key, which is contained by the trie, but can also be a suffix). If the given
     * sequence corresponds to a key, the key is not included in the subtree. If the given sequence
     * is not contained by the trie, a {@link java.util.NoSuchElementException} will be thrown.
     * 
     * The nodes of the returned trie are deep copies of those of the original trie. Therefore the
     * returned trie is fully functional and can be modified without affecting the original trie.
     *
     * @param sequence The sequence as an instance of the generic type {@link SequenceType}
     * @return The subtree of the node, which corresponds to the given sequence, as an instance of
     * the type {@link Trie}. The subtree may not be null
     */
    @NotNull Trie subTrie(@Nullable SequenceType sequence);

}